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.

Sign up for GitHub

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

Jump to bottom

Restructure cmake_options.rst #2230

Merged
merged 22 commits into from
Jan 16, 2022
Merged

Restructure cmake_options.rst #2230

Changes from 19 commits
Commits
Show all changes
22 commits
Select commit Hold shift + click to select a range
d033a8a
convert to tables, add undocumented options
stinebuu Sep 3, 2021
73cd1e1
add alphabetized table
stinebuu Sep 3, 2021
d773d23
removed documentation already described
stinebuu Sep 3, 2021
6c24d59
Merge remote-tracking branch 'nest-simulator/master' into git_cmake_o…
stinebuu Dec 7, 2021
2df4eed
Restructure text
stinebuu Dec 7, 2021
bdd8914
Add cmake options
stinebuu Dec 7, 2021
c65c8dc
fix typo
stinebuu Dec 7, 2021
ed48cb0
Merge remote-tracking branch 'nest-simulator/master' into git_cmake_o…
stinebuu Dec 8, 2021
85601a3
Merge remote-tracking branch 'nest-simulator/master' into git_cmake_o…
stinebuu Dec 21, 2021
1e035cd
Convert to headings
stinebuu Dec 21, 2021
798d902
Python as its own table
stinebuu Dec 21, 2021
e492a5e
Remove unnecessary alphabetized table
stinebuu Dec 21, 2021
21b53c3
K-computer and Bluegene no longer available
stinebuu Dec 21, 2021
12ad267
Combine and restructure tables
stinebuu Dec 21, 2021
972104b
Add hyperlinks
stinebuu Dec 21, 2021
9efd00a
Apply suggestions from code review
stinebuu Jan 7, 2022
0f7dd10
Fix formatting after merge
stinebuu Jan 7, 2022
446760d
Update based on review
stinebuu Jan 10, 2022
545e9cf
Change wording
stinebuu Jan 14, 2022
12ac045
consistency in text
stinebuu Jan 14, 2022
b28790c
Update text in `CMakeLists.txt` to fit with cmake install documentation
stinebuu Jan 14, 2022
4af5540
Comments use lower-case letters
stinebuu Jan 14, 2022
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
180 changes: 104 additions & 76 deletions doc/userdoc/installation/cmake_options.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -28,70 +28,107 @@ Options for configuring NEST

NEST allows for several configuration options for custom builds:

Change NEST behavior::

-Dtics_per_ms=[number] Specify elementary unit of time. [default 1000.0]
-Dtics_per_step=[number] Specify resolution. [default 100]

Add user modules::

-Dexternal-modules=[OFF|<list;of;modules>] External NEST modules to be linked
in, separated by ';'. [default=OFF]

Connect NEST with external projects::

-Dwith-music=[OFF|ON|</path/to/music>] Request the use of MUSIC. Optionally
give the directory, where MUSIC is installed.
[default=OFF]

Change parallelization scheme::

-Dwith-mpi=[OFF|ON|</path/to/mpi>] Request compilation with MPI. Optionally
give directory with MPI installation.
[default=OFF]
-Dwith-openmp=[OFF|ON|<OpenMP-Flag>] Enable OpenMP multi-threading.
Optional: set OMP flag. [default=ON]

Set default libraries::

-Dwith-gsl=[OFF|ON|</path/to/gsl>] Find a gsl library. To set a specific
library, set install path.[default=ON]
-Dwith-readline=[OFF|ON|</path/to/readline>] Find a GNU Readline library. To set
a specific library, set install path.
[default=ON]
-Dwith-ltdl=[OFF|ON|</path/to/ltdl>] Find an ltdl library. To set a specific
ltdl, set install path. NEST uses the
ltdl for dynamic loading of external
user modules. [default=ON]
-Dwith-python=[OFF|ON] Build PyNEST. [default=ON]
-Dcythonize-pynest=[OFF|ON] Use Cython to cythonize pynestkernel.pyx.
If OFF, PyNEST has to be build from
a pre-cythonized pynestkernel.pyx.
[default=ON]

Change compilation behavior::

-Dstatic-libraries=[OFF|ON] Build static executable and libraries. [default=OFF]
-Dwith-optimize=[OFF|ON|<list;of;flags>] Enable user defined optimizations. Separate
multiple flags by ';'.
[default OFF, when ON, defaults to '-O3']
-Dwith-warning=[OFF|ON|<list;of;flags>] Enable user defined warnings. Separate
multiple flags by ';'.
[default ON, when ON, defaults to '-Wall']
-Dwith-debug=[OFF|ON|<list;of;flags>] Enable user defined debug flags. Separate
multiple flags by ';'.
[default OFF, when ON, defaults to '-g']
-Dwith-intel-compiler-flags=[<list;of;flags>] User defined flags for the Intel compiler.
Separate multiple flags by ';'.
[defaults to '-fp-model strict']
-Dwith-libraries=<list;of;libraries> Link additional libraries. Give full path.
Separate multiple libraries by ';'.
[default OFF]
-Dwith-includes=<list;of;includes> Add additional include paths. Give full
path without '-I'. Separate multiple include
paths by ';'. [default OFF]
-Dwith-defines=<list;of;defines> Additional defines, e.g. '-DXYZ=1'.
Separate multiple defines by ';'. [default OFF]

Use Python to build PyNEST
~~~~~~~~~~~~~~~~~~~~~~~~~~

+-----------------------------------------------+----------------------------------------------------------------+
| ``-Dwith-python=[OFF|ON|<path/to/Python>]`` | Build PyNEST [default=ON]. To set a specific Python, give the |
| | install path. |
+-----------------------------------------------+----------------------------------------------------------------+
| ``-Dcythonize-pynest=[OFF|ON]`` | Use Cython to cythonize pynestkernel.pyx [default=ON]. If OFF, |
| | PyNEST has to be build from a pre-cythonized pynestkernel.pyx. |
+-----------------------------------------------+----------------------------------------------------------------+

For more details, see the :ref:`Python binding <compile_with_python>` section below.

Select parallelization scheme
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

+---------------------------------------------+----------------------------------------------------------------+
| ``-Dwith-mpi=[OFF|ON|</path/to/mpi>]`` | Build with MPI parallelization [default=OFF]. Optionally give |
| | directory with MPI installation. |
+---------------------------------------------+----------------------------------------------------------------+
| ``-Dwith-openmp=[OFF|ON|<OpenMP-Flag>]`` | Build with OpenMP multi-threading [default=ON]. Optionally set |
| | OMP compiler flags. |
+---------------------------------------------+----------------------------------------------------------------+

See also the section on :ref:`building with mpi <compile-with-mpi>` below.

External libraries
~~~~~~~~~~~~~~~~~~

+-------------------------------------------------------+------------------------------------------------------------------------------------------------+
| ``-Dwith-libneurosim=[OFF|ON|</path/to/libneurosim>]``| Build with `libneurosim <https://github.com/INCF/libneurosim>`_ [default=OFF]. Optionally |
| | give the directory where libneurosim is installed. |
+-------------------------------------------------------+------------------------------------------------------------------------------------------------+
| ``-Dwith-music=[OFF|ON|</path/to/music>]`` | Build with `MUSIC <https://github.com/INCF/MUSIC>`_ [default=OFF]. Optionally give the |
| | directory where MUSIC is installed. |
+-------------------------------------------------------+------------------------------------------------------------------------------------------------+
| ``-Dwith-sionlib=[OFF|ON|</path/to/sionlib>]`` | Build with |
| | `sionlib <https://www.fz-juelich.de/ias/jsc/EN/Expertise/Support/Software/SIONlib/_node.html>`_|
| | [default=OFF]. Optionally give the directory where sionlib is installed. |
+-------------------------------------------------------+------------------------------------------------------------------------------------------------+
| ``-Dwith-boost=[OFF|ON|</path/to/boost>]`` | Build with Boost [default=ON]. To set a specific Boost installation, give the install path. |
+-------------------------------------------------------+------------------------------------------------------------------------------------------------+
| ``-Dwith-readline=[OFF|ON|</path/to/readline>]`` | Build with GNU Readline library [default=ON]. To set a specific library, give the install path.|
+-------------------------------------------------------+------------------------------------------------------------------------------------------------+
| ``-Dwith-ltdl=[OFF|ON|</path/to/ltdl>]`` | Build with ltdl library [default=ON]. To set a specific ltdl, give the install path. NEST uses|
| | ltdl for dynamic loading of external user modules. |
+-------------------------------------------------------+------------------------------------------------------------------------------------------------+
| ``-Dwith-gsl=[OFF|ON|</path/to/gsl>]`` | Build with the GSL library [default=ON]. To set a specific library, give the install path. |
+-------------------------------------------------------+------------------------------------------------------------------------------------------------+

NEST properties
~~~~~~~~~~~~~~~

+-----------------------------------------------+----------------------------------------------------------------+
| ``-Dtics_per_ms=[number]`` | Specify elementary unit of time [default=1000 tics per ms]. |
+-----------------------------------------------+----------------------------------------------------------------+
| ``-Dtics_per_step=[number]`` | Specify resolution [default=100 tics per step]. |
+-----------------------------------------------+----------------------------------------------------------------+
| ``-Dexternal-modules=[OFF|<list;of;modules>]``| External NEST modules to be linked in, separated by ';' |
| | [default=OFF]. |
+-----------------------------------------------+----------------------------------------------------------------+
| ``-Dwith-detailed-timers=[OFF|ON]`` | Build with detailed internal time measurements [default=OFF]. |
| | Detailed timers can affect the performance. |
+-----------------------------------------------+----------------------------------------------------------------+
| ``-Dtarget-bits-split=["standard"|"hpc"]`` | Split of the 64-bit target neuron identifier type |
| | [default="standard"]. "standard" is recommended for most users.|
| | If running on more than 262144 MPI processes or more than 512 |
| | threads, change to "hpc". |
+-----------------------------------------------+----------------------------------------------------------------+

Generic build configuration
~~~~~~~~~~~~~~~~~~~~~~~~~~~

+------------------------------------------------------+------------------------------------------------------------------+
| ``-Dstatic-libraries=[OFF|ON]`` | Build static executable and libraries [default=OFF]. |
+------------------------------------------------------+------------------------------------------------------------------+
| ``-Dwith-optimize=[OFF|ON|<list;of;flags>]`` | Enable user defined optimizations |
| | [default=OFF (uses '-O2')]. When ON, '-O3' is used. Separate |
| | multiple flags by ';'. |
+------------------------------------------------------+------------------------------------------------------------------+
| ``-Dwith-warning=[OFF|ON|<list;of;flags>]`` | Enable user defined warnings [default=ON (uses '-Wall')]. |
| | Separate multiple flags by ';'. |
+------------------------------------------------------+------------------------------------------------------------------+
| ``-Dwith-debug=[OFF|ON|<list;of;flags>]`` | Enable user defined debug flags [default=OFF]. When ON, '-g' is |
| | used. Separate multiple flags by ';'. |
+------------------------------------------------------+------------------------------------------------------------------+
| ``-Dwith-intel-compiler-flags=[OFF|<list;of;flags>]``| User defined flags for the Intel compiler |
| | [default='-fp-model strict']. Separate multiple flags by ';'. |
+------------------------------------------------------+------------------------------------------------------------------+
| ``-Dwith-libraries=[OFF|<list;of;libraries>]`` | Link additional libraries [default=OFF]. Give full path. Separate|
| | multiple libraries by ';'. |
+------------------------------------------------------+------------------------------------------------------------------+
| ``-Dwith-includes=[OFF|<list;of;includes>]`` | Add additional include paths [default=OFF]. Give full path |
| | without '-I'. Separate multiple include paths by ';'. |
+------------------------------------------------------+------------------------------------------------------------------+
| ``-Dwith-defines=[OFF|<list;of;defines>]`` | Additional defines, e.g. '-DXYZ=1' [default=OFF]. Separate |
| | multiple defines by ';'. |
+------------------------------------------------------+------------------------------------------------------------------+
| ``-Dwith-version-suffix=[string]`` | Set a user defined version suffix [default='']. |
+------------------------------------------------------+------------------------------------------------------------------+


.. _compile-with-mpi:
Expand All @@ -111,10 +148,10 @@ following steps in order to add support for MPI:
3. If 2. does not work, but you know the correct compiler wrapper
for your installation, try adding the following to the invocation
of ``cmake``::
-DMPI_CXX_COMPILER=myC++_CompilerWrapper
-DMPI_CXX_COMPILER=myC++_CompilerWrapper \
-DMPI_C_COMPILER=myC_CompilerWrapper -Dwith-mpi=ON

When running large-scale parallel simualations and recording from many
When running large-scale parallel simulations and recording from many
neurons, writing to ASCII files might become prohibitively slow due to
the large number of resulting files. By installing the `SIONlib
library <http://www.fz-juelich.de/jsc/sionlib>`_ and supplying its
Expand Down Expand Up @@ -149,16 +186,7 @@ follwing switch for the invocation of ``cmake``. It expects either
For details on how to use the Connection Generator Interface, see the
:ref:`guide on connection management <conn_builder_conngen>`.

Disabling the Python Bindings (PyNEST)
--------------------------------------

To disable Python bindings use::

-Dwith-python=OFF

as an argument to ``cmake``.

Please see the :doc:`README <pynest_readme_link>` for details.
.. _compile_with_python:

Python Binding (PyNEST)
-----------------------
Expand Down