Prevent Python version mix and introduce NEST build option -Dwith-python=ON/OFF/2/3

INSTALL

@@ -14,6 +14,12 @@ NEST is installed with `cmake` (at least v2.8.12). In the simplest case, the com
 should build and install NEST to <install-path>. Detailed installation 
 instructions can be found below.
 
+Choice of CMake Version
+=======================
+
+We recommend to use `cmake` v3.4, even though installing NEST with
+`cmake` v2.8.12 will in most cases work properly.
+For more detailed information please see below: `Python3 Binding (PyNEST)`
 
 Choice of compiler
 ==================
@@ -76,8 +82,8 @@ Set default libraries:
                                                  ltdl, set install path. NEST uses the
                                                  ltdl for dynamic loading of external
                                                  user modules. [default=ON]
-    -Dwith-python=[OFF|ON|</path/to/python>]     Build PyNEST. To set a specific Python,
-                                                 set install path. [default=ON]
+    -Dwith-python=[OFF|ON|2|3]                   Build PyNEST. To set a specific Python
+                                                 version, set 2 or 3. [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.
@@ -116,17 +122,42 @@ Configuring NEST for Distributed Simulation with MPI
      -DMPI_C_COMPILER=myC_CompilerWrapper -Dwith-mpi=ON
   4. Sorry, you need to fix your MPI installation. 
 
-
 Disabling the Python Bindings (PyNEST)
 ======================================
 
 Please see also the file pynest/README.md in the documentation directory. If you
 are impatient, use 
 
-    --Dwith-python=OFF
+    -Dwith-python=OFF
+
+as an argument to `cmake`.
+
+Python3 Binding (PyNEST)
+=========================
+
+To force a Python3-binding in a mixed Python2/3 environment pass
+
+    -Dwith-python=3
 
 as an argument to `cmake`.
 
+`cmake` usually autodetects your Python installation.
+In some cases `cmake` might not be able to localize the Python interpreter
+and its corresponding libraries correctly. To circumvent such a problem following
+`cmake` built-in variables can be set manually and passed to `cmake`:
+
+  PYTHON_EXECUTABLE ..... path to the Python interpreter
+  PYTHON_LIBRARY ........ path to libpython
+  PYTHON_INCLUDE_DIR .... two include ...
+  PYTHON_INCLUDE_DIR2 ... directories
+
+  e.g.: Please note `-Dwith-python=ON` is the default.
+  cmake -DCMAKE_INSTALL_PREFIX=</install/path> \
+        -DPYTHON_EXECUTABLE=/usr/bin/python3 \
+        -DPYTHON_LIBRARY=/usr/lib/x86_64-linux-gnu/libpython3.4m.so \
+        -DPYTHON_INCLUDE_DIR=/usr/include/python3.4 \
+        -DPYTHON_INCLUDE_DIR2=/usr/include/x86_64-linux-gnu/python3.4m \
+        </path/to/NEST/src>
 
 Compiling for BlueGene/Q
 ========================

cmake/ProcessOptions.cmake

@@ -338,21 +338,26 @@ endfunction()
 function( NEST_PROCESS_WITH_PYTHON )
   # Find Python
   set( HAVE_PYTHON OFF PARENT_SCOPE )
-  if ( with-python )
-    if ( NOT ${with-python} STREQUAL "ON" )
-      # a path is set
-      set( PYTHON_EXECUTABLE ${with-python} )
+  if ( ${with-python} STREQUAL "ON" OR  ${with-python} STREQUAL "2" OR  ${with-python} STREQUAL "3" )
+
+    # Localize the Python interpreter
+    if ( ${with-python} STREQUAL "ON" )
+      find_package( PythonInterp )
+    elseif ( ${with-python} STREQUAL "2" )  
+      find_package( PythonInterp 2 REQUIRED )
+    elseif ( ${with-python} STREQUAL "3" )
+      find_package( PythonInterp 3 REQUIRED )
     endif ()
 
-    find_package( PythonInterp )
     if ( PYTHONINTERP_FOUND )
       set( PYTHONINTERP_FOUND "${PYTHONINTERP_FOUND}" PARENT_SCOPE )
       set( PYTHON_EXECUTABLE ${PYTHON_EXECUTABLE} PARENT_SCOPE )
       set( PYTHON ${PYTHON_EXECUTABLE} PARENT_SCOPE )
       set( PYTHON_VERSION ${PYTHON_VERSION_MAJOR}.${PYTHON_VERSION_MINOR} PARENT_SCOPE )
 
-      # need python lib and header...
-      find_package( PythonLibs )
+      # Localize Python lib/header files and make sure that their version matches 
+      # the Python interpreter version !
+      find_package( PythonLibs ${PYTHON_VERSION_STRING} EXACT )
       if ( PYTHONLIBS_FOUND )
         set( HAVE_PYTHON ON PARENT_SCOPE )
         # export found variables to parent scope
@@ -377,10 +382,12 @@ function( NEST_PROCESS_WITH_PYTHON )
             set( CYTHON_VERSION "${CYTHON_VERSION}" PARENT_SCOPE )
           endif ()
         endif ()
-
         set( PYEXECDIR "${CMAKE_INSTALL_LIBDIR}/python${PYTHON_VERSION_MAJOR}.${PYTHON_VERSION_MINOR}/site-packages" PARENT_SCOPE )
       endif ()
     endif ()
+  elseif ( ${with-python} STREQUAL "OFF" )
+  else ()
+    message( FATAL_ERROR "Invalid option: -Dwith-python=" ${with-python} )
   endif ()
 endfunction()
 

pynest/README.md

@@ -21,6 +21,14 @@ PyNEST to `$(pyexecdir)`, which is often expanded as follows:
 
     $(prefix)/lib{,64}/pythonX.Y/site-packages/nest
 
+
+To force the usage of a specific Python version pass
+
+    -Dwith-python=2  or  -Dwith-python=3
+
+as an argument to `cmake`.
+
+
 To make the PyNEST module available to the Python interpreter, add the
 PyNEST installation path (without the final '/nest') to the PYTHONPATH
 environment variable.