Merge pull request #3045 from JanVogelsang/clion-ide

Add CLion IDE developer documentation

doc/htmldoc/developer_space/workflows/nest_with_ides.rst

@@ -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
 
@@ -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
 
@@ -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
 
@@ -327,7 +327,7 @@ Install NEST
       - build/
       - install/
 
-1. Build NEST
+2. Build NEST
 
    .. code-block:: sh
 
@@ -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:
 
@@ -377,26 +377,26 @@ Also add the generated files:
     <somebase>/NEST/build/libnestutil/config.h
     <somebase>/NEST/build/libnestutil/sliconfig.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::
 
@@ -409,7 +409,53 @@ 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
+-----
+
+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 configuration 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.
+
+.. note::
+
+   `CLion <https://www.jetbrains.com/clion/>`_ is a commercial product. It is *your responsibility* to ensure that you have a valid
+   license permitting you to use CLion (or any software product) for your work on the    
+   NEST Simulator. 
+
+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 (Go to :menuselection:`Build,Execution,Deployment --> CMake`) to make more changes at a later point.
+
+    * 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 selecting :menuselection:`Edit configurations` in the dropdown in the top right corner.
+4. Add a :menuselection:`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 selecting :menuselection:`Configure custom build targets` and give it a name of your choice
+7. Add an external build tool by selecting the three dots next to the :menuselection:`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).

doc/htmldoc/static/css/custom.css

@@ -96,6 +96,10 @@ section#kernel-attributes-nest-nestmodule dd {
         border-bottom: 1px solid #ddd;
 }
 
+.menuselection {
+   font-weight: bold;
+}
+
 /*************************************************************
  * Rules for  mermaid diagrams
  *************************************************************/
@@ -106,7 +110,6 @@ section#kernel-attributes-nest-nestmodule dd {
 	stroke-width: None !important;
 }
 
-
 rect.basic.label-container {
 	fill: #e2e2e200; !important
 	stroke: #ff6633;
@@ -123,7 +126,6 @@ figure.align-default {
 	outline-style: groove;
 }
 
-
 /**************************************************************************************
  Settings for overriding material design theme 
  Setting nest colors to override sphinx material "orange" and other default colors