.. meta::
    :description: Setup development PyCharm

.. _setupForDevelopmentWithPyCharm:

Setup for development with PyCharm
==================================

To develop Dragonfly extensions, we recommend using `PyCharm <https://www.jetbrains.com/pycharm/>`_ as
the environment of development. This section describes how to do the setup and debug your program.

.. _videoTutorial_SetupPyCharm:

------

.. includevideo:: SetupPyCharm

.. _videoTutorial_DebuggingWithPyCharm:

------

.. includevideo:: DebuggingWithPyCharm

Installing Dragonfly
--------------------
Install Dragonfly as usual.
The recommended installation path is *C:\\Program Files\\Dragonfly*.

.. note::
    In this documentation page, the installation path will be identified as *DRAGONFLY_INSTALLATION_PATH*.

Before getting further, make sure the application is running properly, then exit the program.

Registering DLLs
----------------
Start a Windows Command Prompt as administrator.
Set the current directory as the *DRAGONFLY_INSTALLATION_PATH*.
Execute *registerDLLs.bat*.
Close that window.

.. image:: StartWindowsCommandPrompt.jpg

\

.. image:: WindowsCommandPromptRegisterDLLs.jpg

Downloading and installing PyCharm
----------------------------------
Download and install `PyCharm <https://www.jetbrains.com/pycharm/>`_.
The free Community Edition has all the required features.

Setup to start PyCharm
----------------------
In a file browser, go to the folder *DRAGONFLY_INSTALLATION_PATH*.
Copy the file *setEVarsForPythonIDE.bat* in a folder with writing permission (example, the Desktop).
Edit that copied file with a text editor, like Notepad.
Add the path to the PyCharm executable at the end of the file.
Save and close the file.
Rename the file with a more relevant name, like *startPyCharm.bat*.

.. image:: EditSetEVarsForPythonIDE.jpg

Starting PyCharm
----------------
Execute the file created at the previous step (renamed *startPyCharm.bat*).
This will start PyCharm with specific environment variables required by Dragonfly.

.. warning::
    Executing this .bat file should **always** be done to be able to start Dragonfly from PyCharm,
    **even after the setup procedure is completed**.
    Not doing so will prevent Dragonfly to start from PyCharm:

    \

    .. image:: PyCharmConsoleErrorStartDragonflyEnvironmentVariablesNotSet.jpg

Configuring the project in PyCharm
----------------------------------
On the Welcome page, select *Open*,
and browse to *C:\\ProgramData\\ORS\\Dragonfly(version)\\python*. Click *OK*.

Go to File/Settings... to open the *Settings*.
On the left sidebar, click on *Project: python*/*Project Interpreter*.
In the field *Project Interpreter* should be found the Python interpreter
*3.6 (C:\\ProgramData\\ORS\\Dragonfly(version)\\Anaconda3\\python.exe)*.
If this is not the case, click on the cog wheel on the top-right, then select *Add Local*.
Browse to the *C:\\ProgramData\\ORS\\Dragonfly(version)\\Anaconda3* directory, select *python.exe* and
click *OK*. Make sure this is now the selection in the field *Project Interpreter*.

.. image:: PyCharmSettingsProjectInterpreter.jpg

\

.. image:: PyCharmSettingsSelectProjectInterpreter.jpg

\

.. image:: PyCharmSettingsSelectedProjectInterpreter.jpg

Still in the *Settings* window, on the left sidebar, click on *Project: python*/*Project Structure*.
On the right side, click on *Add Content Root*.
Browse to *C:\\Users\\yourusername\\AppData\\Local\\ORS\\Dragonfly(version)\\pythonUserExtensions*. Click *OK*.
Click again on *Add Content Root*.
Browse to *C:\\ProgramData\\ORS\\Dragonfly(version)\\pythonAllUsersExtensions*. Click *OK*.
Click *OK* to exit the *Settings* panel.

.. image:: PyCharmSettingsProjectStructure.jpg

PyCharm will have to run processes for the specified Python Interpreter.
Wait until the process *Updating Indices* is completed.

.. image:: PyCharmProcessesRunningPythonInterpreter.jpg

Go to Run/Edit Configurations... to open the *Run/Debug Configurations*.
Click on the *+* sign to add a new configuration and select *Python*.
Set a name in the *Name* field, like *Start Dragonfly*.
In the *Script* field, type *C:\\ProgramData\\ORS\\Dragonfly(version)\\python\\OrsMinimalStartupScript.py*.
In the *Python interpreter* field, make sure *Python 3.6*
(*C:\\ProgramData\\ORS\\Dragonfly(version)\\Anaconda3\\python.exe*) is selected.
In the *Working directory* field, type the *DRAGONFLY_INSTALLATION_PATH* directory.
Click *OK* to accept these changes and exit the *Run/Debug Configurations* panel.

\

.. image:: PyCharmRunDebugConfigurations.jpg

Removing exception breakpoints
------------------------------
Go to Run/View Breakpoints... to open the *Breakpoints* window.
Uncheck the *Python Exception Breakpoint*. Click on *Done*.

\

.. image:: PyCharmRemovingExceptionBreakpoints.jpg

Run Dragonfly from PyCharm
--------------------------
Click on the *Debug* icon to start Dragonfly in debug mode, where breakpoints are active.
Click on the *Run* icon to start Dragonfly in run mode, where breakpoints are not active,
but the application responds faster.

\

.. image:: PyCharmRunDebug.jpg

.. note::
    If the application is not starting and the exit code in the console is -760 or a message is displayed
    concerning the minimal OpenGL version,
    you may need to specify the graphic card to use when running the batch file *startPyCharm.bat*.

    \

    .. image:: PyCharmMinimalOpenGLVersion.jpg

    \

    .. image:: PyCharmMinimalOpenGLVersionExitCode760.jpg

    You may either start the batch file by specifying each time a graphic card supporting the minimal OpenGL version
    (this option is available when starting the batch file from a shortcut)
    or change the default graphics processor (in which case,
    a reboot may be required in order for the changes to take effect).

    \

    .. image:: StartPyCharmWithNVIDIA.jpg

    \

    .. image:: PyCharmWithNVIDIA.jpg

    \

    .. image:: NVIDIAChangingDefaultGraphicsProcessor.jpg

Debugging while running Dragonfly
---------------------------------
When starting in Debug, you can break the execution on specific lines.
While paused, you can use the debug console to examine and/or modify existing values.
To do so, show the Python prompt and type your commands at the prompt.

.. image:: PyCharmDebugConsoleShowingCommands.jpg

\

.. image:: PyCharmDebugConsoleShowingVariables.jpg

Using the Python console embedded in PyCharm
--------------------------------------------
It is sometimes useful to try some Python commands in a separate Python console.
In PyCharm, you can view the Python console from the View/Tool Windows/Python Console.

.. image:: PyCharmPythonConsole.jpg

When in a Python console, all the modules of the Dragonfly project are accessible
even if the application is not started.
You can also connect the debugger to break in the executed code.

.. image:: PyCharmPythonConsoleBreakingInCodeConsoleView.jpg

\

.. image:: PyCharmPythonConsoleBreakingInCodeDebugView.jpg