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 15 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
181 changes: 105 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,108 @@ 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. To set a specific Python, set install path. |
stinebuu marked this conversation as resolved.
Show resolved Hide resolved
| | [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] |
+---------------------------------------------+----------------------------------------------------------------+

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

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

+---------------------------------------------+----------------------------------------------------------------+
| -Dwith-mpi=[OFF|ON|</path/to/mpi>] | Request compilation with MPI. Optionally give directory with |
stinebuu marked this conversation as resolved.
Show resolved Hide resolved
| | MPI installation. [default=OFF] |
+---------------------------------------------+----------------------------------------------------------------+
| -Dwith-openmp=[OFF|ON|<OpenMP-Flag>] | Enable OpenMP multi-threading. Optional: set OMP flag. |
stinebuu marked this conversation as resolved.
Show resolved Hide resolved
+---------------------------------------------+----------------------------------------------------------------+

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

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

+---------------------------------------------+----------------------------------------------------------------+
| -Dwith-gsl=[OFF|ON|</path/to/gsl>] | Find a gsl library. To set a specific library, set install |
stinebuu marked this conversation as resolved.
Show resolved Hide resolved
| | path. [default=ON] |
+---------------------------------------------+----------------------------------------------------------------+
| -Dwith-readline=[OFF|ON|</path/to/readline>]| Find a GNU Readline library. To set a specific library, set |
stinebuu marked this conversation as resolved.
Show resolved Hide resolved
| | 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-boost=[OFF|ON|</path/to/boost>] | Find a Boost library. To set a specific Boost installation, |
stinebuu marked this conversation as resolved.
Show resolved Hide resolved
| | set install path. [default=ON] |
+---------------------------------------------+----------------------------------------------------------------+
| -Dwith-libneurosim= | Request the use of libneurosim. Optionally give the directory, |
stinebuu marked this conversation as resolved.
Show resolved Hide resolved
| [OFF|ON|</path/to/libneurosim>] | where libneurosim is installed. [default=OFF] |
+---------------------------------------------+----------------------------------------------------------------+
| -Dwith-music=[OFF|ON|</path/to/music>] | Request the use of MUSIC. Optionally give the directory, where |
| | MUSIC is installed. [default=OFF] |
+---------------------------------------------+----------------------------------------------------------------+
| -Dwith-sionlib=[OFF|ON|</path/to/sionlib>] | Request the use of sionlib. Optionally give the directory, |
| | where sionlib is installed. [default=OFF] |
+---------------------------------------------+----------------------------------------------------------------+

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

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

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. Separate multiple flags by |
| | ';'. [default OFF, when ON, defaults to '-O3'] |
stinebuu marked this conversation as resolved.
Show resolved Hide resolved
+---------------------------------------------+----------------------------------------------------------------+
| -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'] |
stinebuu marked this conversation as resolved.
Show resolved Hide resolved
+---------------------------------------------+----------------------------------------------------------------+
| -Dwith-libraries=[<list;of;libraries>] | Link additional libraries. Give full path. Separate multiple |
| | libraries by ';'. [default OFF] |
stinebuu marked this conversation as resolved.
Show resolved Hide resolved
+---------------------------------------------+----------------------------------------------------------------+
| -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] |
+---------------------------------------------+----------------------------------------------------------------+
| -Dwith-version-suffix=[string] | Set a user defined version suffix. [default ''] |
heplesser marked this conversation as resolved.
Show resolved Hide resolved
+---------------------------------------------+----------------------------------------------------------------+


.. _compile-with-mpi:
Expand All @@ -111,10 +149,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 +187,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