From d93f68df82788e92e64f09284890aad51987639f Mon Sep 17 00:00:00 2001 From: dkunhamb Date: Sat, 28 Mar 2026 16:19:45 -0500 Subject: [PATCH 1/5] add docs for mechanical-env debug in linux --- .../getting_started/running_mechanical.rst | 45 +++++++++++++++++++ doc/source/user_guide/cli/mechanical-env.rst | 7 +++ 2 files changed, 52 insertions(+) diff --git a/doc/source/getting_started/running_mechanical.rst b/doc/source/getting_started/running_mechanical.rst index 1fa14937ba..8faf661acd 100644 --- a/doc/source/getting_started/running_mechanical.rst +++ b/doc/source/getting_started/running_mechanical.rst @@ -265,6 +265,51 @@ script which is part of PyMechanical $ mechanical-env python +.. _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 +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 VS Code (provides the **debugpy** debugger). + +#. 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. + +.. note:: + + Regenerate ``.vscode/.env`` if you change 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 ---------------- diff --git a/doc/source/user_guide/cli/mechanical-env.rst b/doc/source/user_guide/cli/mechanical-env.rst index c4845453a2..638aa803f2 100644 --- a/doc/source/user_guide/cli/mechanical-env.rst +++ b/doc/source/user_guide/cli/mechanical-env.rst @@ -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 +``mechanical-env`` would set and attach the debugger to it. See +:ref:`debug-embedding-vscode-linux` in :doc:`/getting_started/running_mechanical`. From 56081f739bae6d611986c34ddf588dfe87c48891 Mon Sep 17 00:00:00 2001 From: pyansys-ci-bot <92810346+pyansys-ci-bot@users.noreply.github.com> Date: Mon, 6 Apr 2026 13:47:50 +0000 Subject: [PATCH 2/5] chore: adding changelog file 1574.documentation.md [dependabot-skip] --- doc/changelog.d/1574.documentation.md | 1 + 1 file changed, 1 insertion(+) create mode 100644 doc/changelog.d/1574.documentation.md diff --git a/doc/changelog.d/1574.documentation.md b/doc/changelog.d/1574.documentation.md new file mode 100644 index 0000000000..2eacc88e16 --- /dev/null +++ b/doc/changelog.d/1574.documentation.md @@ -0,0 +1 @@ +Add documentation on how to debug embedded app in linux using vscode From f6981830fd3b6ebbc9716831cd70507257ef3454 Mon Sep 17 00:00:00 2001 From: dkunhamb Date: Mon, 6 Apr 2026 10:19:49 -0500 Subject: [PATCH 3/5] move to troubleshooting --- .../getting_started/running_mechanical.rst | 66 +------------------ .../getting_started/troubleshooting.rst | 45 +++++++++++++ 2 files changed, 46 insertions(+), 65 deletions(-) diff --git a/doc/source/getting_started/running_mechanical.rst b/doc/source/getting_started/running_mechanical.rst index c7744cbd4d..268ad06bec 100644 --- a/doc/source/getting_started/running_mechanical.rst +++ b/doc/source/getting_started/running_mechanical.rst @@ -113,68 +113,4 @@ Use the ``mechanical-env`` script shipped with PyMechanical: .. code:: shell - $ mechanical-env python - -.. _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 -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 VS Code (provides the **debugpy** debugger). - -#. 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. - -.. note:: - - Regenerate ``.vscode/.env`` if you change 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 ----------------- - -`PADT `_ has an `Ansys `_ -product section. Posts about licensing are common. - -If you are responsible for maintaining an Ansys license or have a personal installation -of Ansys, you likely can access the -`Licensing `_ -section of the Ansys Help, where you can view or download the *Ansys, Inc. Licensing Guide* for -comprehensive licensing information. - -VPN issues ----------- - -Sometimes, Mechanical has issues starting when VPN software is running. For more information, -access the `Mechanical Users Guide`_ -in the Ansys Help. + $ mechanical-env python \ No newline at end of file diff --git a/doc/source/getting_started/troubleshooting.rst b/doc/source/getting_started/troubleshooting.rst index 7be097a5b2..472636fed4 100644 --- a/doc/source/getting_started/troubleshooting.rst +++ b/doc/source/getting_started/troubleshooting.rst @@ -46,6 +46,51 @@ If this command doesn't launch Mechanical, common causes include: - 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 +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 VS Code (provides the **debugpy** debugger). + +#. 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. + +.. note:: + + Regenerate ``.vscode/.env`` if you change 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 ----------------- From e1d69d656cf9930eb258dca4a4b7de99543f9a23 Mon Sep 17 00:00:00 2001 From: dkunhamb Date: Mon, 6 Apr 2026 10:20:50 -0500 Subject: [PATCH 4/5] fix deleted --- doc/source/getting_started/running_mechanical.rst | 10 +++++++++- 1 file changed, 9 insertions(+), 1 deletion(-) diff --git a/doc/source/getting_started/running_mechanical.rst b/doc/source/getting_started/running_mechanical.rst index 268ad06bec..188b361137 100644 --- a/doc/source/getting_started/running_mechanical.rst +++ b/doc/source/getting_started/running_mechanical.rst @@ -113,4 +113,12 @@ Use the ``mechanical-env`` script shipped with PyMechanical: .. code:: shell - $ mechanical-env python \ No newline at end of file + $ mechanical-env python + +Then use the same Python code as on Windows. + +For more on embedding, see the :ref:`Embedding mode user guide `. + +.. seealso:: + + :doc:`troubleshooting` — executable not found, licensing, VPN, and debug tips. \ No newline at end of file From 9bcdd28803f50ed3df7245d50a01030b3f5c13bf Mon Sep 17 00:00:00 2001 From: Dipin <26918585+dipinknair@users.noreply.github.com> Date: Wed, 8 Apr 2026 08:43:45 -0500 Subject: [PATCH 5/5] Apply suggestions from code review Co-authored-by: Kathy Pippert <84872299+PipKat@users.noreply.github.com> --- doc/source/getting_started/troubleshooting.rst | 5 +++-- 1 file changed, 3 insertions(+), 2 deletions(-) diff --git a/doc/source/getting_started/troubleshooting.rst b/doc/source/getting_started/troubleshooting.rst index 472636fed4..2a60b9bc50 100644 --- a/doc/source/getting_started/troubleshooting.rst +++ b/doc/source/getting_started/troubleshooting.rst @@ -52,10 +52,11 @@ Debug with Visual Studio Code on Linux ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 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 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 VS Code (provides the **debugpy** debugger). +#. Install the `Python extension`_ for Visual Studio Code (provides the Debuggy debugger). #. From your project root, write the prepared environment to ``.vscode/.env``. Use the same ``-r`` or ``-p`` options you use for normal runs: @@ -86,7 +87,7 @@ point Visual Studio Code at it. .. note:: - Regenerate ``.vscode/.env`` if you change Ansys version, installation path, or ``mechanical-env`` + 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