Mechanism building with CMake

This module contains helper functions for generating (core)NEURON mechanism libraries directly in CMake. The basic idea is to replicate all of the previous functionality of the Makefiles, but without having to deal with their maintenance or having to worry about managing dependencies.

Overview

What nrnivmodl and nrnivmodl -coreneuron were doing was essentially:

create a subdir equivalent to CMAKE_HOST_SYSTEM_PROCESSOR in the current working directory
translate a given list of mod files to cpp files (using either NOCMODL or NMODL)
create a file mod_func.cpp which dynamically (that is, upon running nrniv or similar) registers the mechanisms in NEURON
create a nrnmech library in the CMAKE_HOST_SYSTEM_PROCESSOR subdirectory from all of the above listed cpp files
create a special executable in the CMAKE_HOST_SYSTEM_PROCESSOR subdirectory from the nrnmain.cpp file
link the above executable to the nrnmech library

In case the -coreneuron option is given, it additionally does the following:

create a corenrnmech library in the CMAKE_HOST_SYSTEM_PROCESSOR subdirectory from all of the above listed cpp files, except with a different mod_func.cpp which correctly registers it under the coreneuron cpp namespace
create a special-core executable in the CMAKE_HOST_SYSTEM_PROCESSOR subdirectory from the coreneuron.cpp file
link the above executable to the corenrnmech library

API reference

Note

This API is experimental and subject to change.

create_nrnmech

create_nrnmech(
    [NEURON]
    [CORENEURON]
    [SPECIAL]
    [NMODL_NEURON_CODEGEN]
    [TARGET_LIBRARY_NAME lib_tgt]
    [TARGET_EXECUTABLE_NAME exe_tgt]
    [LIBRARY_OUTPUT_DIR lib_outdir]
    [EXECUTABLE_OUTPUT_DIR exe_outdir]
    [ARTIFACTS_OUTPUT_DIR art_outdir]
    [LIBRARY_TYPE type]
    [NOCMODL_EXECUTABLE path/to/nocmodl]
    [NMODL_EXECUTABLE path/to/nmodl]
    [MOD_FILES mod1 mod2 ...]
    [NMODL_NEURON_EXTRA_ARGS arg1 arg2 ...]
    [NMODL_CORENEURON_EXTRA_ARGS arg1 arg2 ...]
    [EXTRA_ENV KEY1=VAL1 KEY2=VAL2 ...]
)

Options

NEURON: (optional) whether a library compatible with NEURON should be created.
CORENEURON: (optional) whether a library compatible with coreNEURON should be created. At least one of NEURON or CORENEURON must be specified.
SPECIAL: (optional) whether a special (or special-core in case of coreNEURON) executable should be created.
NMODL_NEURON_CODEGEN: (optional) whether to use NMODL to generate files compatible with NEURON.
TARGET_LIBRARY_NAME: (optional, default: nrnmech) the name of the CMake target for the library. Note that core is prepended to the coreNEURON target.
TARGET_EXECUTABLE_NAME: (optional, default: special) the name of the CMake target for the executable. Note that -core is appended to the coreNEURON target.
LIBRARY_OUTPUT_DIR: (optional, default: CMAKE_CURRENT_BINARY_DIR) the path where the library targets will be placed at build-time.
EXECUTABLE_OUTPUT_DIR: (optional, default: CMAKE_CURRENT_BINARY_DIR) the path where the executable targets will be placed at build-time.
ARTIFACTS_OUTPUT_DIR: (optional, default: CMAKE_CURRENT_BINARY_DIR) the path where the CPP files will be placed at build-time.
LIBRARY_TYPE: (optional, default: SHARED) the type of library to build.
NOCMODL_EXECUTABLE: (optional) the path to the NOCMODL executable. If not specified, attempts to find deduce the location of the executable from the NEURON CMake configuration.
NMODL_EXECUTABLE: (optional) the path to the NMODL executable. If not specified, attempts to find deduce the location of the executable from the NEURON CMake configuration.
MOD_FILES: list of mod files to convert.
NMODL_NEURON_EXTRA_ARGS: (optional, default: None) list of additional arguments to pass to NMODL for NEURON codegen.
NMODL_CORENEURON_EXTRA_ARGS: (optional, default: passes --inline host --c if CUDA disabled, passes --inline host --c acc --oacc if CUDA enabled) list of additional arguments to pass to NMODL for coreNEURON codegen.
EXTRA_ENV: (optional, default: None) list of additional environmental variables to pass when building the targets.

Examples

Note

You need to insert the path to neuronTargets.cmake in CMAKE_PREFIX_PATH. If you installed NEURON via CMake, the usual loaction of it is CMAKE_INSTALL_PREFIX/lib/cmake. If instead you installed NEURON as a Python wheel, the usual location is WHEEL_INSTALL_DIR/neuron/.data/lib/make, where WHEEL_INSTALL_DIR is listed after Location: when calling pip show neuron.

To build a mechanism, put this in your CMakeLists.txt:

cmake_minimum_required(VERSION 3.15)
project(custom_modfiles LANGUAGES C CXX)

find_package(neuron REQUIRED)

create_nrnmech(NEURON CORENEURON SPECIAL MOD_FILES
  modfile1.mod
  path/to/modfile2.mod)

Note

If you want to enable coreNEURON’s GPU support, you need to first build NEURON itself with CORENRN_ENABLE_GPU=ON and customize the CMAKE_C_COMPILER, CMAKE_CXX_COMPILER, and CMAKE_CUDA_COMPILER variables. Currently only NVHPC is supported. You also need to add CUDA to the LANGUAGES above.

Then you can configure your mechanisms using:

cmake -B build

Any CMake option (such as the compiler, generator, etc.) can be specified. To build the mechanisms (i.e. the nrnmech library and special executable), run:

cmake --build build

The nrnmech library will then be available under build, and can be loaded in NEURON using:

nrniv -dll build/libnrnmech.so