cmake: export targets, allow building mechanisms via CMake, part 1

[JCGoran]

Split off from #2746 since that PR was getting a bit too large.

Needs #3674.

Context

Currently we build mechanisms (mod files) using a hand-written Makefile. As a result, we need to ship a bunch of Make-specific tools with NEURON. This also does not work (or at least, not without a lot of workarounds) in a cross-platform manner.

This PR allows one to build NEURON mechanisms with CMake, using any generator we want. The way it achieves this is by exposing the create_nrnmech CMake function, which works as follows:

cmake_minimum_required(VERSION 3.15)
project(modfile_test)

find_package(neuron REQUIRED)

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

Note that the NEURON, CORENEURON, and SPECIAL toggle whether one builds libnrnmech, libcorenrnmech, and the special executable (enabling CORENEURON and SPECIAL together enables the special-core executable as well).

One can then build the targets via:

cmake -B build
cmake --build build

which can then be loaded into NEURON as usual:

nrniv -dll build/libnrnmech.so

Additional notes

• the NEURON config file must be visible to CMake, i.e. it must be added to CMAKE_PREFIX_PATH, and the nmodl executable must be in PATH nmodl is now installed as a NEURON target so we only need CMAKE_PREFIX_PATH. Additionally, until NOCMODL fails to run from build directory without setting MODLUNIT #3470 is resolved, MODLUNIT must also be set issue fixed!
• at build-time, internal mechanisms are still built with make, but this can be fixed later (nrnivmodl touches a lot of the internal code as well, so the changeset would be much larger)
• when shipping wheels, the CMAKE_PREFIX_PATH should include {NEURON_WHEEL_DIR}/.data/lib/cmake, though I am not sure how to obtain it without running any external utilities
• CMake and any of the generators should be available on the user machine. We could update the Python requirements to include cmake and ninja, but since this feature is a bit experimental, I'm not sure how useful it is
• I've not tested anything on Windows, so I'm not sure how cross-platform it really is (i.e. we ship NEURON with msys2 or whatever else is there, but CMake would probably try to use MSVC if it's installed)
• for NVHPC, we are hardcoding some of the CLI options for now, which means that one should build NEURON from source, and then use the same installation for building mechanisms (otherwise I cannot guarantee that the mechanism-building will work) looks like it works without too much hardcoding
• running special when building from a wheel currently does not work OOTB because of the fact that NEURON hardcodes the path to nrnpyenv.sh. The workaround is to add NEURONHOME=${NEURON_WHEEL_DIR}/.data/share/nrn" to the env added the same workaround as we use for wheels so now it works
• I manually tried testing special-core with NVHPC 25.3 and it works without issues. I did not want to add too many new tests since that will be tested anyway once the CMake build itself starts using create_nrnmech instead of calling nrnivmodl (that's planned for part 2)
• since this PR introduces a public API, I documented it here
• this also works with wheels (provided NEURON is inCMAKE_PREFIX_PATH)

[azure-pipelines]

✔️ d0f8f46 -> Azure artifacts URL

[github-actions]

✔️ d0f8f46 -> artifacts URL

[JCGoran]

After a bunch of tweaking, I think this actually works now, albeit it's a bit of a large changeset. I also added the nrnivmodl-cmake and nrnivmodl-all-cmake convenience scripts, that build mechanisms for NEURON and NEURON + coreNEURON respectively, and do the same thing as nrnivmodl and nrnivmodl -coreneuron, but using CMake. Since the script is quite minimal, one can tweak it using various CMAKE_* env vars, such as:

• want to use Ninja? Use CMAKE_GENERATOR=Ninja
• want parallelization? Use CMAKE_BUILD_PARALLEL_LEVEL=<#cpus> (usually the nproc CLI utility can be used for retrieving this automatically)
• want more verbosity? Use VERBOSE=1
• want to cache compilation results? Use CMAKE_C_COMPILER_LAUNCHER=ccache and CMAKE_CXX_COMPILER_LAUNCHER=ccache

On my machine with 24 cores this is about 3x faster than via nrnivmodl when compiled from scratch, and is basically instantaneous when re-using a cache.

Usage is same as nrnivmodl, i.e.:

nrnivmodl[-all]-cmake <mod1> <mod2> ... <modN>

The only difference of using the convenience script(s) w.r.t. the "original" nrnivmodl is that NEURON reports strange paths to mod files like:

loading membrane mechanisms from x86_64/libnrnmech.so
Additional mechanisms from files
 "../../../../../../../../../../mod files/axial.mod" "../../../../../../../../../../mod files/axial_pp.mod"

This is due to the fact that the CMakeLists.txt file is shipped with NEURON, and the convenience script basically calls it via:

cmake -S /some/long/path/to/neuron_install/lib/cmake -B $(uname -m)

so the relative path between the mod file(s) and where the source is can be quite long. This has no impact whatsoever on the loading of mechanisms since the loading procedure only cares about where libnrnmech.so is, not any path to the original mod files.

TODO (either in this PR or another one):

• add docs about usage of nrnivmodl-cmake and nrnivmodl-all-cmake
• decide if the Python requirements should be updated to include cmake and ninja (I am personally mildly for it, while on Linux we may have make pre-installed, and sometimes CMake as well, making all the platforms have consistent requirements would be nice)

[sonarqubecloud]

Quality Gate passed

Issues
0 New issues
0 Accepted issues

Measures
0 Security Hotspots
0.0% Coverage on New Code
0.0% Duplication on New Code

See analysis details on SonarQube Cloud

[azure-pipelines]

✔️ 5d59350 -> Azure artifacts URL

[azure-pipelines]

✔️ 52728a8 -> Azure artifacts URL

[azure-pipelines]

✔️ 94081a3 -> Azure artifacts URL

[sonarqubecloud]

Quality Gate passed

Issues
0 New issues
0 Accepted issues

Measures
0 Security Hotspots
0.0% Coverage on New Code
0.0% Duplication on New Code

See analysis details on SonarQube Cloud

[azure-pipelines]

✔️ 504d229 -> Azure artifacts URL

[D-McDougall]

I reviewed this PR and I think it looks good to merge. I read through the changes and I checked that the tests run and pass.

Someday we're going to want more documentation. This is a complicated change to the program, and I feel like a few flow-charts would go a long way towards explaining how each file fits into the program. But that is an issue for later, after we're done fixing up the build system.