==========================
CMake Options for NEST GPU
==========================

NEST GPU is installed with ``cmake`` (at least version 3.17). In the simplest case, the commands::

    cmake -DCMAKE_INSTALL_PREFIX:PATH=<nestgpu_install_dir> <nestgpu_source_dir>
    make
    make install

should build and install NEST GPU to ``nestgpu_install_dir``, which should be an absolute
path.


Options for configuring NEST GPU
================================

NEST GPU allows for several configuration options for custom builds:

..
    Use Cython
    ----------

    +-----------------------------------------------+----------------------------------------------------------------+
    | ``-Dcythonize-pynestpgu=[OFF|ON]``            | Use Cython to cythonize pynestgpukernel.pyx.                   |
    |                                               | If OFF, NEST GPU Python interface has to be build from a       | 
    |                                               | pre-cythonized pynestgpukernel.pyx. [default=ON]               |
    +-----------------------------------------------+----------------------------------------------------------------+

Set GPU architecture
--------------------

See `here <https://arnon.dk/matching-sm-architectures-arch-and-gencode-for-various-nvidia-cards/>`_
to choose the best NVIDIA GPU architecture for your GPU card.

+-----------------------------------------------+----------------------------------------------------------------+
| ``-Dwith-gpu-arch=[int]``                     | Specify the GPU compute architecture. [default=80]             |
+-----------------------------------------------+----------------------------------------------------------------+

Change parallelization scheme
-----------------------------

+-----------------------------------------------+----------------------------------------------------------------+
| ``-Dwith-mpi=[OFF|ON]``                       | Build with MPI parallelization. [default=ON]                   |
+-----------------------------------------------+----------------------------------------------------------------+

External libraries
------------------

+-----------------------------------------------+----------------------------------------------------------------
| ``-Dwith-ltdl=[OFF|ON]``                      | Build with ltdl library. To set a specific ltdl, give the      |
|                                               | install path. NEST GPU uses ltdl for dynamic loading of        |
|                                               | external user modules. [default=OFF]                           |
+-----------------------------------------------+----------------------------------------------------------------+

Compiler options
----------------

Explicit compiler flags can be given.

+-----------------------------------------------+----------------------------------------------------------------+
| ``-Dwith-optimize=[OFF|ON|<list;of;flags>]``  | Enable user defined optimizations. When OFF, no '-O' flag is   |
|                                               | passed to the compiler. Separate multiple flags by ';'.        |
|                                               | [default=ON (uses '-O3')]                                      |
+-----------------------------------------------+----------------------------------------------------------------+
| ``-Dwith-warning=[OFF|ON|<list;of;flags>]``   | Enable user defined warnings. Separate multiple flags by ';'.  |
|                                               | [default=ON (uses '-Wall')]                                    |
+-----------------------------------------------+----------------------------------------------------------------+
| ``-Dwith-debug=[OFF|ON|<list;of;flags>]``     | Enable user defined debug flags. Separate multiple flags       |
|                                               | by ';'. [default=OFF, when ON, defaults to '-g']               |
+-----------------------------------------------+----------------------------------------------------------------+

CUDA options
------------

+-----------------------------------------------+----------------------------------------------------------------+
| ``-Dwith-cpp-std=[OFF|ON]``                   | C++ standard to use for compilation. [default=OFF]             |
+-----------------------------------------------+----------------------------------------------------------------+
| ``-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]                |
+-----------------------------------------------+----------------------------------------------------------------+
| ``-Dwith-max-rreg-count=[int]``               | Set a maximum amount of register used when compiling.          |
|                                               | [default=55]                                                   |
+-----------------------------------------------+----------------------------------------------------------------+
| ``-Dwith-ptxas-options=[<list;of;flags>]``    | Options for ptxas compiling.                                   |
|                                               | Separate multiple flags by ';'. [default=OFF]                  |
+-----------------------------------------------+----------------------------------------------------------------+

Generic build configuration
---------------------------

+-----------------------------------------------+----------------------------------------------------------------+
| ``-Dwith-version-suffix=[str]``               | Set a user defined version suffix. [default='']                |
+-----------------------------------------------+----------------------------------------------------------------+