Document cmake option: NRN_INSTALL_PYTHON_PREFIX (#3747)

* Make option NRN_INSTALL_PYTHON_PREFIX easier to user
* Bump minimum cmake version from 3.19 to 3.20

Author: D-McDougall

.github/workflows/coverage.yml

@@ -66,7 +66,7 @@ jobs:
       - name: Setup cmake
         uses: jwlawson/actions-setup-cmake@v2
         with:
-          cmake-version : '3.19'
+          cmake-version : '3.20'
 
       - name: Setup Caliper profiler
         run: |

.github/workflows/neuron-ci.yml

@@ -36,8 +36,8 @@ jobs:
       SDK_ROOT: $(xcrun --sdk macosx --show-sdk-path)
       SKIP_WHEELHOUSE_REPAIR: true
       BUILD_TYPE: Release
-      DESIRED_CMAKE_VERSION: 3.19
-      DYNAMIC_PYTHON_CMAKE_VERSION: 3.19
+      DESIRED_CMAKE_VERSION: '3.20'
+      DYNAMIC_PYTHON_CMAKE_VERSION: '3.20'
       PY_MIN_VERSION: ${{ matrix.config.python_min_version || '3.10' }}
       PY_MAX_VERSION: ${{ matrix.config.python_max_version || '3.14' }}
       MUSIC_INSTALL_DIR: /opt/MUSIC

.github/workflows/release.yml

@@ -159,7 +159,7 @@ jobs:
       - name: Setup cmake
         uses: jwlawson/actions-setup-cmake@v2
         with:
-          cmake-version : '3.19'
+          cmake-version : '3.20'
 
       - name: Set up Python
         id: setup-python

CMakeLists.txt

@@ -1,4 +1,4 @@
-cmake_minimum_required(VERSION 3.19 FATAL_ERROR)
+cmake_minimum_required(VERSION 3.20 FATAL_ERROR)
 # Note that this needs to happen **before** the call to project(...). This is because CMake reads
 # the CRAYPE_LINK_TYPE environment variable inside the call to project(...) and sets various flags
 # and properties based on its value. Because we are so early in the CMake processing, we have to
@@ -39,7 +39,7 @@ if(POLICY CMP0177)
   cmake_policy(SET CMP0177 NEW)
 endif()
 
-# customizable install path to Python components. Mostly useful for Spack builds
+# customizable install path to Python components. Mostly useful for Spack & venv builds
 set(NRN_INSTALL_PYTHON_PREFIX
     "lib/python/neuron/"
     CACHE STRING
@@ -65,6 +65,11 @@ else()
   set(NRN_INSTALL_DATA_PREFIX)
 endif()
 
+# Make python install path relative to CMAKE_INSTALL_PREFIX
+if(IS_ABSOLUTE "${NRN_INSTALL_PYTHON_PREFIX}")
+  cmake_path(RELATIVE_PATH NRN_INSTALL_PYTHON_PREFIX BASE_DIRECTORY "${CMAKE_INSTALL_PREFIX}")
+endif()
+
 # =============================================================================
 # CMake common project settings
 # =============================================================================

docs/cmake_doc/options.rst

@@ -306,6 +306,30 @@ NRN_ENABLE_PYTHON:BOOL=ON
   Enable Python interpreter support
   (default python, fallback to python3, but see PYTHON_EXECUTABLE below)
 
+NRN_INSTALL_PYTHON_PREFIX:STRING="lib/python/neuron/"
+-----------------------------------------------------
+  Path where NEURON Python components will be installed, relative to CMAKE_INSTALL_PREFIX. Must end with a directory named "neuron"
+
+  Environment variable PYTHONPATH must contain the real path to NRN_INSTALL_PYTHON_PREFIX in order for python to find neuron.
+
+  This path must end with a directory named "neuron"
+
+  For venv's, configure cmake with:
+
+  .. code-block:: shell
+
+    -DCMAKE_INSTALL_PREFIX=$(python -c "import sysconfig; print(sysconfig.get_path('data', 'venv'))") \
+    -DNRN_INSTALL_PYTHON_PREFIX=$(python -c "import sysconfig; print(sysconfig.get_path('platlib', 'venv') + '/neuron')")
+
+  To install to your home directory, configure cmake with:
+
+  .. code-block:: shell
+
+    -DCMAKE_INSTALL_PREFIX=$(python3 -m site --user-base) \
+    -DNRN_INSTALL_PYTHON_PREFIX=$(python3 -m site --user-site)/neuron
+
+  This option is ignored when building a wheel, in which case the value is forced to "neuron/"
+
 .. _cmake_nrn_enable_python_dynamic:
 NRN_ENABLE_PYTHON_DYNAMIC:BOOL=OFF
 ----------------------------------
@@ -544,7 +568,7 @@ NRN_ENABLE_TESTS:BOOL=OFF
     python3 -m pytest test_currents.py
 
 NRN_ENABLE_COVERAGE:BOOL=OFF
----------------------------
+----------------------------
   Enable code coverage
 
   Requires ``lcov`` (e.g. ``sudo apt install lcov``).
@@ -677,7 +701,7 @@ NRN_ENABLE_DIGEST:BOOL=OFF
   Requires libcrypto
 
 NRN_ENABLE_ARCH_INDEP_EXP_POW:BOOL=OFF
----------------------------------
+--------------------------------------
   Provides \ :func:`use_exp_pow_precision` function so that exp and pow produce
   same results on all platforms.
 

src/nmodl/pybind/CMakeLists.txt

@@ -120,7 +120,7 @@ file(COPY ${NMODL_PROJECT_PURELIB_SOURCE_DIR}/ext DESTINATION ${NMODL_PROJECT_PU
 if(NOT NRN_LINK_AGAINST_PYTHON)
   install(TARGETS pywrapper DESTINATION ${NRN_INSTALL_DATA_PREFIX}lib)
   if(NMODL_ENABLE_PYTHON_BINDINGS)
-    install(TARGETS _nmodl DESTINATION ${NRN_INSTALL_PYTHON_PREFIX}nmodl)
+    install(TARGETS _nmodl DESTINATION ${NRN_INSTALL_PYTHON_PREFIX}/nmodl)
   endif()
 else()
   install(