@@ -10,11 +10,11 @@ This tutorial assumes you are familiar with the process of building Mantid (with
.. contents::
:local:
.. _setting-up-pycharm-on-windows:
Setting up PyCharm on Windows
#############################
PyCharm should be opened using ``pycharm.bat`` which can be found in the build directory (this sets some additional environment variables compared with simply opening PyCharm directly).
1. Once PyCharm is open, set up the project. Go to ``File->Open`` and select the root directory in which both your source and build directories reside.
Go to ``File->Settings``, then under ``Project`` you will set two sub-menus ``Project Interpreter`` and ``Project Structure``. The interpreter defines the python executable that will be used to run your code, and the structure menu allows you to decide which folders within the project to include and index.
...
...
@@ -29,13 +29,17 @@ PyCharm should be opened using ``pycharm.bat`` which can be found in the build d
3. In the ``Project Structure`` sub menu you should see your root directory with the source/build directories both visible (if not, add them). The folder structure should be present in the centre of the window allowing you to mark folders orange (excluded) or blue (source). Source directories will be searched for python code.
Within the source directory add the following to your sources;
Within the source directory add the following to your sources:
The first folder can be replaced with the folder that contains your code, if you aren't writing code in ``scripts/``.
Additionally, in the Mantid build directory add the following as source folders:
...
...
@@ -46,10 +50,16 @@ PyCharm should be opened using ``pycharm.bat`` which can be found in the build d
here we are setting up PyCharm for the Debug build, you would use ``/bin/Release`` instead if you are building mantid in release mode.
4. The environment needs to be set up before running the configuration. Follow the instructions below to use either the EnvFile plugin (recommended) or manual path setup.
NOTE : In some cases, imports in the code will still be highlighted red when they come from folders within the ``script/`` folder, or from other folders entirely. To fix this simply add the relevant folder that contains the module you are importing in the same fashion as step 3 above.
.. _running-file-debug-with-envfile-extension:
Running Files in the Debugger with EnvFile extension
Running python code from within PyCharm which depends on the python API, or PyQt for example requires one extra step. Because the source root labelling from the previous section only affects PyCharm searching and not the run configuration, before running the file we must set up the run configuration correctly.
4. Install the EnvFile plugin by Borys Pierov. The plugin can be installed in multiple ways:
...
...
@@ -76,13 +86,16 @@ Disadvantages:
Running Files in the Debugger without EnvFile extension
Running python code from within PyCharm which depends on the python API, or PyQt for example requires one extra step. Because the source root labelling from the previous section only affects PyCharm searching and not the run configuration, before running the file we must set up the run configuration correctly.
As an example, create a new file in ``<Mantid Source Directory>/scripts/`` called ``test.py``. Copy into it the Python code below.
This can be done in two ways:
- Open PyCharm using ``pycharm.bat`` which can be found in the build directory (this sets some additional environment variables compared with simply opening PyCharm directly).
4. To edit the configurations go to ``Run->Run...`` and select ``Edit Configurations``. This should open up a sub window. Hit the green ``+`` in the top left to create a new configuration and name it. In order to tell PyCharm where to look for python modules and libraries we need to add some folders to the ``PATH`` environment variable. Click on the ``...`` next to the *Environment Variables* box, and hit the ``+`` icon. In the Name column enter "PATH", in the value column enter the following;
- This is preferred if you only have 1 repository with which PyCharm is used. If you need to use PyCharm on multiple repositories, it is recommended that you use the EnvFile extension.
- To edit the configurations go to ``Run->Run...`` and select ``Edit Configurations``. This should open up a sub window. Hit the green ``+`` in the top left to create a new configuration and name it. In order to tell PyCharm where to look for python modules and libraries we need to add some folders to the ``PATH`` environment variable. Click on the ``...`` next to the *Environment Variables* box, and hit the ``+`` icon. In the Name column enter "PATH", in the value column enter the following;
.. code-block:: sh
...
...
@@ -92,13 +105,14 @@ As an example, create a new file in ``<Mantid Source Directory>/scripts/`` calle
The semi-colon delimited list of paths should end in ``;%PATH%`` so that we prepend to the existing list of paths rather than overwriting them. The last two lines will allow imports of PyQt4 and PyQt5 modules.
The semi-colon delimited list of paths should end in ``;%PATH%`` so that we prepend to the existing list of paths rather than overwriting them.
You should now be able to run and debug the scripts using the newly created configuration, by adding the full path of the file in the ``Script path`` box at the top of the configuration window.
As an example, create a new file in ``<Mantid Source Directory>/scripts/`` called ``test.py``. Copy into it the Python code below.
Testing using PyQt
------------------
##################
To test that the above instructions have worked, you can simply create a new Python file with the following content (for PyQt5)
...
...
@@ -124,14 +138,48 @@ To test that the above instructions have worked, you can simply create a new Pyt
ui.show()
sys.exit(app.exec_())
Local Debugging of Unit Tests with PyCharm
##########################################
This **does not** require a PyCharm Professional license for debugging, but requires additional setup for running unit tests.
1. Go to your Run/Debug Configurations.
2. Open Templates > Python tests > Unittests configuration.
3. Set the working directory to ``<Mantid Build Dir>/bin/Debug``, for a Debug build, or ``<Mantid Build Dir>/bin/Release`` for a Release build.
4. Add the EnvFile to the Unittests configuration, instructions in :ref:`running-file-debug-with-envfile-extension`.
5. You should now be able to click the Run/Debug icons next to each unit test method or class to run/debug them.
Remote Debugging of Unit Tests with PyCharm
#############################
This requires a PyCharm Professional license for the Remote Debugging feature.
This approach can be used to debug unit tests. However, as the required package ``pydevd`` is not shipped with Mantid, we need to manually add it at runtime. This can be done by appending a directory that contains the installed ``pydevd`` package on the ``PYTHONPATH``. The following code does so at runtime::
PYTHON_ROOT="<Change this to point to a Python installation that has pydevd installed>"
A Remote Debugging configration needs to be setup to use the ``44444`` port (can be changed, but it needs to be reflected in the code), and running before the tests are run!
The ``pydevd`` package does not have to be installed on Python 2. As of 12/11/2018 installing ``pydevd`` on a separate installation with Python 3.7, and adding the code above successfully connects.
Setting up PyCharm on Linux
###########################
On Linux the instructions are identical to Windows except that :
- In step 1, the file is ``pycharm.sh`` rather than ``pycharm.bat``
- In step 2, use the native python interpreter (``/usr/bin/python2.7/python.exe``) rather than from ``<Mantid Source Directory>/external/src/ThirdParty/lib/python2.7/python.exe``
- In step 4, add ``<Mantid Build Directory>/bin;`` to the ``PATH`` environment variable in the new configuration (rather than ``<Mantid Build Directory>/bin/Debug;``), and remove the other three file paths.
- In step 3, add ``<Mantid Build Directory>/bin;`` to the ``PATH`` environment variable in the new configuration (rather than ``<Mantid Build Directory>/bin/Debug;``), and remove the other three file paths.
- In step 4, if you are not using the EnvFile extension, then the file is ``pycharm.sh`` rather than ``pycharm.bat``
@@ -30,7 +30,7 @@ using the cmake flag ``PACKAGE_WORKBENCH=ON``.
Developing and debugging with PyCharm on Windows
################################################
The first thing that needs to be done is creating the PyCharm project and configuring the project settings. Please follow the instructions at :ref:`GettingStartedWithPyCharm`.
The first thing that needs to be done is creating the PyCharm project and configuring the project settings. Please follow the instructions at :ref:`setting-up-pycharm-on-windows`.
After the project settings have been configured, a Run/Debug configuration needs to be created. To edit the configurations go to ``Run->Run...`` and select ``Edit Configurations``. Select ``Templates->Python``, and hit the green ``+`` in the top left.
The necessary changes to the configuration are:
...
...
@@ -90,23 +90,3 @@ For example to run the MatrixWorkspaceDisplay:
2. Set the Script Path to ``<Mantid Source Dir>/qt/python/mantidqt/widgets/matrixworkspaceviewer``. This package has a ``__main__.py`` file which makes it runnable.
3. You might have to CHANGE back the working directory to ``<Mantid Build Dir>/bin/Debug``.
4. Click OK, then running the configration should start the MatrixWorkspaceDisplay.
Remote Debugging with PyCharm
-----------------------------
This requires a PyCharm Professional license for the Remote Debugging feature.
This approach can be used to debug unit tests. However, as the required package ``pydevd`` is not shipped with Mantid, we need to manually add it at runtime. This can be done by appending a directory that contains the installed ``pydevd`` package on the ``PYTHONPATH``. The following code does so at runtime::
PYTHON_ROOT="<Change this to point to a Python installation that has pydevd installed>"
A Remote Debugging configration needs to be setup to use the ``44444`` port (can be changed, but it needs to be reflected in the code), and running before the tests are run!
The ``pydevd`` package does not have to be installed on Python 2. As of 12/11/2018 installing ``pydevd`` on a separate installation with Python 3.7, and adding the code above successfully connects.
