Skip to content
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.

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

Add CLion IDE developer documentation #3045

Merged
merged 13 commits into from
Jan 10, 2024
75 changes: 58 additions & 17 deletions doc/htmldoc/developer_space/workflows/nest_with_ides.rst
jessica-mitchell marked this conversation as resolved.
Show resolved Hide resolved
Original file line number Diff line number Diff line change
Expand Up @@ -277,7 +277,7 @@ Homebrew
^^^^^^^^

1. Follow the install instructions for Homebrew (`short <http://brew.sh/>`_) or `long <https://github.com/Homebrew/homebrew/blob/master/share/doc/homebrew/Installation.md#installation>`_)
1. Open up the Terminal and execute the following lines:
2. Open up the Terminal and execute the following lines:

.. code-block:: sh

Expand All @@ -289,7 +289,7 @@ MacPorts
(We recommend using the Homebrew workflow, since there you can use a more current OpenMPI version for NEST, but we leave the MacPorts instructions for legacy purposes.)

1. Follow the install instructions for `MacPorts <https://www.macports.org/install.php>`_.
1. Open up the Terminal and execute the following lines:
2. Open up the Terminal and execute the following lines:

.. code-block:: sh

Expand All @@ -298,8 +298,8 @@ MacPorts
sudo port install gsl +gcc48
sudo port install cmake # build tools

1. NEST on Mac requires OpenMPI 1.6 from MacPorts to work properly, so we have to get this older version for MacPort. Download the portsfile `Portfile-openmpi-1.6.4.txt <http://www.nest-simulator.org/wp-content/uploads/2014/12/Portfile-openmpi-1.6.4.txt>`_ and save it under the name ``Portfile`` in an arbitraty directory.
1. In Terminal, move to the directory containing Portfile and run
3. NEST on Mac requires OpenMPI 1.6 from MacPorts to work properly, so we have to get this older version for MacPort. Download the portsfile `Portfile-openmpi-1.6.4.txt <http://www.nest-simulator.org/wp-content/uploads/2014/12/Portfile-openmpi-1.6.4.txt>`_ and save it under the name ``Portfile`` in an arbitraty directory.
4. In Terminal, move to the directory containing Portfile and run

.. code-block:: sh

Expand Down Expand Up @@ -327,7 +327,7 @@ Install NEST
- build/
- install/

1. Build NEST
2. Build NEST

.. code-block:: sh

Expand Down Expand Up @@ -368,7 +368,7 @@ Get Xcode working with NEST
~~~~~~~~~~~~~~~~~~~~~~~~~~~

1. Create a new project, which we will call ``NEST-fork`` in this article. In the menu select File -> New -> Project... . Then select OS X -> Other -> External Build System (with build tool ``/usr/bin/make``)
1. Add the NEST sources to the project. There is a ``+`` in the left-bottom corner. Click ``Add Files to "NEST-fork"...``. Then select the ``<somebase>/NEST/src/`` folder (do not copy items and use groups).
2. Add the NEST sources to the project. There is a ``+`` in the left-bottom corner. Click ``Add Files to "NEST-fork"...``. Then select the ``<somebase>/NEST/src/`` folder (do not copy items and use groups).

Also add the generated files:

Expand All @@ -378,26 +378,26 @@ Also add the generated files:
<somebase>/NEST/build/libnestutil/sliconfig.h
<somebase>/NEST/build/nest/static_modules.h

1. On the left panel select the newly created project ``NEST-fork``, then select the created target.
3. On the left panel select the newly created project ``NEST-fork``, then select the created target.

Here you set set Directory to ``<somebase>/NEST/build``. This will be the directory, in which the ``make`` command is executed. Also check ``Pass build settings in environment``.

1. Next select the ``Build Settings`` panel.
4. Next select the ``Build Settings`` panel.

Here you ``Add User-Defined Setting`` and name it ``PATH``. In the ``NEST-fork`` column (the second) you copy the content of your ``PATH`` variable (do ``echo $PATH`` in the Terminal).

1. The build system (CMD+B) should work from now on.
5. The build system (CMD+B) should work from now on.

Running NEST from Xcode
~~~~~~~~~~~~~~~~~~~~~~~

We have to edit the Targets Scheme:

1. In the menu select: Product -> Scheme -> Manage Schemes...
1. Select the ``NEST-fork`` target and hit ``Edit...``
1. Select the ``Run`` option on the left and then on the right select ``Info``.
1. As ``Executable`` select ``<somebase>/NEST/install/bin/nest``.
1. You can specify arguments in the ``Arguments`` panel.
2. Select the ``NEST-fork`` target and hit ``Edit...``
3. Select the ``Run`` option on the left and then on the right select ``Info``.
4. As ``Executable`` select ``<somebase>/NEST/install/bin/nest``.
5. You can specify arguments in the ``Arguments`` panel.

.. note::

Expand All @@ -410,7 +410,48 @@ Code Completion in Xcode
We have to create a new target and configure it appropriately:

1. In the menu select: File -> New -> Target....
1. Make the target a OS X -> Command Line Tool (Next), of type C++ in your project (preselected). We call it ``completion``
1. Remove all files and folders that are created with the new target.
1. In the tab "Build Phase" of the new target, under "Compile Sources" add all ``*.h``, ``*.hpp``, ``*.c``, ``*.cc``, ``*.cpp`` files from the list (you can use CMD+a).
1. Now Xcode generates its index and after that code completion should work.
2. Make the target a OS X -> Command Line Tool (Next), of type C++ in your project (preselected). We call it ``completion``
3. Remove all files and folders that are created with the new target.
4. In the tab "Build Phase" of the new target, under "Compile Sources" add all ``*.h``, ``*.hpp``, ``*.c``, ``*.cc``, ``*.cpp`` files from the list (you can use CMD+a).
5. Now Xcode generates its index and after that code completion should work.


CLion
JanVogelsang marked this conversation as resolved.
Show resolved Hide resolved
-----

This recipe describes how to set up CLion for editing, building, and running NEST. The description here was tested on Ubuntu 23.
All the steps below are fully optional if you don't intend to debug your code using CLion and prefer to build NEST manually from the command line.
If you just want to debug your code, you can skip steps 1-2 and only follow steps 3-7. However, it is advised to also follow steps 1-2 to inform CLion of your desired CMake configuration.
Setting up the CMake configuration in CLion has the following advantages:

* CLion's default CMake configuration creates the build directory inside the source code root directory, which easily leads to unknowingly committing build files to git.
* CLion regenerates build files when checking out a new branch, potentially overriding the build you created by manually running CMake from the command line.
* After setting up both the CMake configuaration and a run configuration, you won't need to use the command line to run ``cmake``, ``make``, ``make install``, and ``python *.py`` at all anymore. All will be done automatically by CLion and you only need to run your application without having to manually recompile.

JanVogelsang marked this conversation as resolved.
Show resolved Hide resolved

Setting up the project
~~~~~~~~~~~~~~~~~~~~~~

1. :ref:`Clone NEST <git_workflow>` onto your computer or select ``Get from VCS`` from CLion's start window
2. You will be prompted to setup CMake. You can find the CMake configuration in the settings (Build,Execution,Deployment --> CMake) to make more changes at a later point. Make the following changes and press "Ok":
jessica-mitchell marked this conversation as resolved.
Show resolved Hide resolved

* Generator: ``Let CMake decide``
* CMake options: ``-DCMAKE_INSTALL_PREFIX=[YOUR BUILD DIRECTORY]/install -DPython_ROOT_DIR=[YOUR PYTHON ENV ROOT] -Wunused-parameter -Wall -Wextra -Werror -Dwith-optimize=OFF -Dwith-debug=ON``
* Build directory: ``[YOUR BUILD DIRECTORY]``

3. Edit the run configurations by clicking on "Edit configurations" in the dropdown in the top right corner.
4. Add a ``custom build application``
5. Set the following values:

* Environment variables: ``PYTHONPATH=[YOUR BUILD DIRECTORY]/install/lib/python3.[YOUR PYTHON MINOR VERSION]/site-packages:$PYTHONPATH``
* Working directory: ``[YOUR NEST REPO ROOT]``
* Executable: ``[YOUR PYTHON ENV ROOT]/bin/python3``

6. Add a custom target by clicking on "Configure Custom Build Targets" and give it a name of your choice
7. Add an external build tool by clicking on the three dots next to the "Build" dropdown menu and give it a name of your choice again. Then set the following values:

* Program: ``[PATH TO MAKE EXECUTABLE]`` (usually /usr/bin/make)
* Arguments: ``-j $(nproc) install``
* Working directory: ``[YOUR BUILD DIRECTORY]``

You can now run any python script using NEST and debug the C++ code. To debug Python code, use Pycharm instead (does not require any setup whatsoever).
Loading