Skip to content

docs: add documentation on how to debug embedded app in linux using vscode #1574

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
dipinknair wants to merge 7 commits into
base: main
Choose a base branch
from
Open

docs: add documentation on how to debug embedded app in linux using vscode #1574

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
7 commits
Select commit Hold shift + click to select a range
d93f68d
add docs for mechanical-env debug in linux
dipinknair Mar 28, 2026
f2ac749
Merge branch 'main' into doc/add-debug-mech-env
dipinknair Apr 6, 2026
56081f7
chore: adding changelog file 1574.documentation.md [dependabot-skip]
pyansys-ci-bot Apr 6, 2026
491634e
merge main
dipinknair Apr 6, 2026
f698183
move to troubleshooting
dipinknair Apr 6, 2026
e1d69d6
fix deleted
dipinknair Apr 6, 2026
9bcdd28
Apply suggestions from code review
dipinknair Apr 8, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
1 change: 1 addition & 0 deletions doc/changelog.d/1574.documentation.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1 @@
Add documentation on how to debug embedded app in linux using vscode
2 changes: 1 addition & 1 deletion doc/source/getting_started/running_mechanical.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -20,7 +20,7 @@
In remote session mode, Mechanical runs as a separate server process and
uses gRPC to communicate with Python.

Launch from Python

Check warning on line 23 in doc/source/getting_started/running_mechanical.rst

View workflow job for this annotation

GitHub Actions / Documentation Style Check 

[vale] reported by reviewdog 🐶
[Google.Headings] 'Launch from Python' should use sentence-style capitalization.

Raw Output:
{"message": "[Google.Headings] 'Launch from Python' should use sentence-style capitalization.", "location": {"path": "doc/source/getting_started/running_mechanical.rst", "range": {"start": {"line": 23, "column": 1}}}, "severity": "WARNING"}
~~~~~~~~~~~~~~~~~~

Use the
Expand Down Expand Up @@ -121,4 +121,4 @@

.. seealso::

:doc:`troubleshooting` — executable not found, licensing, VPN, and debug tips.
:doc:`troubleshooting` — executable not found, licensing, VPN, and debug tips.
46 changes: 46 additions & 0 deletions doc/source/getting_started/troubleshooting.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -46,6 +46,52 @@
- Running behind a VPN
- Missing dependencies

.. _debug-embedding-vscode-linux:

Debug with Visual Studio Code on Linux
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

On Linux, the Python debugger must see the same environment that ``mechanical-env`` sets when
Copy link
Copy Markdown
Collaborator

@klmcadams klmcadams Apr 8, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
On Linux, the Python debugger must see the same environment that ``mechanical-env`` sets when

On Linux, the Python debugger must see the same environment that the ``mechanical-env`` variable sets when
Copy link
Copy Markdown
Collaborator

@klmcadams klmcadams Apr 8, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
On Linux, the Python debugger must see the same environment that the ``mechanical-env`` variable sets when
On Linux, the Python debugger must see the same environment that the ``mechanical-env`` script sets when

you run ``mechanical-env python``. You can capture that environment once, store it in a file, and
point Visual Studio Code at it.

#. Install the `Python extension`_ for Visual Studio Code (provides the Debuggy debugger).

Check failure on line 59 in doc/source/getting_started/troubleshooting.rst

View workflow job for this annotation

GitHub Actions / Documentation Style Check 

[vale] reported by reviewdog 🐶
[Vale.Spelling] Did you really mean 'Debuggy'?

Raw Output:
{"message": "[Vale.Spelling] Did you really mean 'Debuggy'?", "location": {"path": "doc/source/getting_started/troubleshooting.rst", "range": {"start": {"line": 59, "column": 73}}}, "severity": "ERROR"}

#. From your project root, write the prepared environment to ``.vscode/.env``. Use the same
``-r`` or ``-p`` options you use for normal runs:

.. code:: shell

$ mechanical-env -r 261 env > .vscode/.env

#. Create ``.vscode/launch.json`` with a launch configuration that loads that file:

.. code-block:: json

{
"version": "0.2.0",
"configurations": [
{
"name": "Python Debugger: Current File",
"type": "debugpy",
"request": "launch",
"program": "${file}",
"console": "integratedTerminal",
"envFile": "${workspaceFolder}/.vscode/.env"
}
]
}

#. Start **Run and Debug**, choose **Python Debugger: Current File**, and run your script.
Copy link
Copy Markdown
Member

@PipKat PipKat Apr 7, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Bold is used only to indicate UI options--is that the case here?


.. note::

Regenerate ``.vscode/.env`` if you change the Ansys version, installation path, or ``mechanical-env``
options. Consider adding ``.env`` to ``.gitignore`` if the file should not be shared.

.. _`Python extension`: https://marketplace.visualstudio.com/items?itemName=ms-python.python


Licensing issues
-----------------
Expand Down
7 changes: 7 additions & 0 deletions doc/source/user_guide/cli/mechanical-env.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -50,3 +50,10 @@ Run a Python script using a specific version:
.. code-block:: bash
mechanical-env -r 261 python my_script.py
Debugging with Visual Studio Code
---------------------------------

To debug embedded PyMechanical scripts in VS Code on Linux, export the environment that
Copy link
Copy Markdown
Member

@PipKat PipKat Apr 7, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
To debug embedded PyMechanical scripts in VS Code on Linux, export the environment that
To debug embedded PyMechanical scripts in Visual Studio Code on Linux, export the environment that

``mechanical-env`` would set and attach the debugger to it. See
Copy link
Copy Markdown
Member

@PipKat PipKat Apr 7, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
``mechanical-env`` would set and attach the debugger to it. See
``mechanical-env`` variable would set and attach the debugger to it. See

Copy link
Copy Markdown
Collaborator

@klmcadams klmcadams Apr 8, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

maybe "mechanical-env script" instead

Copy link
Copy Markdown
Member

@PipKat PipKat Apr 9, 2026 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@klmcadams I was just trying to put a noun after to indicate what type of entity it was. Script is fine with me. I do think I made the same "variable" change elsewhere though so I'd recommend a search. (I can make to see that you found that edit of mine and also recommended script there. Way to go!)

:ref:`debug-embedding-vscode-linux` in :doc:`/getting_started/running_mechanical`.
Loading