Merge pull request #234 from tammoippen/cmake_docu_updates

Update documentation to `cmake` build infrastructure.
nest · Apr 5, 2016 · ee9d6d4 · ee9d6d4
2 parents 1e2ca71 + a1f9b38
commit ee9d6d4
Show file tree

Hide file tree

Showing 3 changed files with 50 additions and 80 deletions.
diff --git a/eclipse_workflow.md b/eclipse_workflow.md
@@ -110,7 +110,7 @@ If you have longer-running branches for major changes, you may want to create on
 
 ### Preparations
 
-You should bootstrap and configure NEST as usual. In this document,
+You should configure NEST as usual. In this document,
 we will first set up the NEST production build
 `bld_master_nompi`. Handling further configurations will be described
 in a later section.
@@ -123,14 +123,16 @@ We thus assume the following directory layout:
 
 You should configure, build and install NEST manually once (note that
 I want to build NEST with gcc 5.1 from Homebrew, therefore the
-`CC=gcc-5 CXX=g++-5` arguments to `configure`; NB: Make sure that you
-have checked out the master branch in the `src` directory):
+`-DCMAKE_C_COMPILER=gcc-5 -DCMAKE_CXX_COMPILER=g++-5` arguments to `cmake`; 
+NB: Make sure that you have checked out the master branch in the `src` directory):
 
     cd $NEST_ROOT/bld_master_nompi
-    ../src/configure --prefix=$NEST_ROOT/bld_master_nompi/install CC=gcc-5 CXX=g++-5
-	make -j4
-	make install
-	make installcheck
+    cmake -DCMAKE_INSTALL_PREFIX=$NEST_ROOT/bld_master_nompi/install -DCMAKE_C_COMPILER=gcc-5 -DCMAKE_CXX_COMPILER=g++-5 -Dwith-debug=ON ../src
+    make -j4
+    make install
+    make installcheck
+
+__Note:__ With `cmake` you can also generate the Eclipse project files yourself by adding the option `-G "Eclipse CDT4 - Unix Makefiles"`. The following section assumes, that you do not use this option.
 
 ### Project setup
 
@@ -246,14 +248,14 @@ each build directory you create.
 ### Configuring and additional build directory
 
 Create and configure the build directory as usual and build and
-install NEST once (`CC` and `CXX` are not set explicitly, since I
-built MPI to use the `gcc-5` and `g++-5` compilers).
+install NEST once (do not use the MPI compiler wrappers for `cmake`, as
+it will figure out the correct options itself).
 
 ```
 cd $NEST_ROOT
 mkdir bld_fixes_mpi
 cd bld_fixes_mpi
-../src/configure --prefix=$NEST_ROOT/bld_fixes_mpi/install --with-mpi
+cmake -DCMAKE_INSTALL_PREFIX=$NEST_ROOT/bld_fixes_mpi/install -DCMAKE_C_COMPILER=gcc-5 -DCMAKE_CXX_COMPILER=g++-5 -Dwith-debug=ON -Dwith-mpi=ON ../src
 make -j4
 make install
 make installcheck
@@ -297,7 +299,7 @@ Afterwards, you can select the run configuration by clicking on the little trian
 This section is very preliminary.
 
 1. Create a build directory and configure NEST with the `--with-debug` switch, then add a corresponding configuration in Eclipse as described above.
-1. Remember to also create a run configuration. Then, click the triangle next to the Bug to start debugging, chosing your debug run configuration.
+1. Remember to also create a run configuration. Then, click the triangle next to the Bug to start debugging, choosing your debug run configuration.
 1. Eclipse stops the debugger on entry to main, you probably want to click Resume here.
 
 NB: At present, I am not able to get any variable values out in gdb. This seems to be a gdb problem, I also have this problem with gdb on the command line. So on the Mac we may have to wait until Eclipse support lldb.

diff --git a/extension_modules.md b/extension_modules.md
@@ -37,17 +37,12 @@ with external modules, please join the [mailing
 list](http://www.nest-initiative.org/community) to share it with us
 and other users.
 
-## Prerquisites
+## Prerequisites
 
 1. Download, build and install NEST. NEST should be built outside the source code directory.
-2. GNU Autotools. We have tested these instructions with the following versions:
-        m4-1.4.11
-        libtool-2.4.2
-        autoconf-2.69
-        automake-1.14.1 
-3. You can use the install_autotools.sh script in the extras directory to install recent versions of the Autotools in your home directory.
-4. The NEST source code and installation directory must be accessible for building modules.
-5. Define the environment variable NEST_INSTALL_DIR to contain the path to which you have installed NEST, e.g. using bash,
+2. Install CMake version 2.8.12 or later.
+3. The NEST source code and installation directory must be accessible for building modules.
+4. Define the environment variable NEST_INSTALL_DIR to contain the path to which you have installed NEST, e.g. using bash,
 
         export NEST_INSTALL_DIR=/Users/plesser/NEST/ins
 
@@ -57,67 +52,56 @@ and other users.
 
 As a starting point, try to build MyModule as follows:
 
-1. From the NEST source directory, copy directory examples/MyModule to somewhere outside the NEST source, build or install directories.
-2. Change to the new location of MyModule and prepare by issuing
-
-        imt-b23010408:MyModule plesser$ ./bootstrap.sh
-        Bootstrapping MyModule
-          -> Removing old automake cache ...
-          -> Running aclocal ...
-          -> Installing libtool components ...
-          -> Running autoheader ...
-          -> Running automake ...
-          -> Running autoconf ...
-        Done.
-
-    You may see some more output.
-3. Leave MyModule and create a build directory for it, e.g., mmb next to it
+1. From the NEST source directory, copy directory `examples/MyModule` to somewhere outside the NEST source, build or install directories.
+2. Create a build directory for it on the same level as MyModule (e.g. mmb)
 
+        cd /path/to/MyModule
         cd ..
         mkdir mmb
         cd mmb
 
-4. Configure. The configure process uses the script nest-config.sh to find out where NEST is installed, where the source code resides, and which compiler options were used for compiling NEST. If nest-config.sh is not in your path, you need to provided it explicitly like this
+3. Configure. The configure process uses the script `nest-config` to find out where NEST is installed, where the source code resides, and which compiler options were used for compiling NEST. If `nest-config` is not in your path, you need to provided it explicitly like this
 
-        ../MyModule/configure --with-nest=${NEST_INSTALL_DIR}/bin/nest-config
+        cmake -Dwith-nest=${NEST_INSTALL_DIR}/bin/nest-config ../MyModule
 
     MyModule will then be installed to `${NEST_INSTALL_DIR}`. This ensures that NEST will be able to find initializing SLI files for the module.
 
-    You should not use the `--prefix` to select a different installation destination. If you do, you must make sure to use addpath in SLI before loading the module to ensure that NEST will find the SLI initialization file for your module.
+    You should not use the `-DCMAKE_INSTALL_PREFIX` to select a different installation destination. If you do, you must make sure to use `addpath` in SLI before loading the module to ensure that NEST will find the SLI initialization file for your module.
 
-5. Compile.
+4. Compile.
 
         make
         make install
-       
-6. The previous command installed MyModule to the NEST installation directory, including help files generated from the source code. 
+
+5. The previous command installed MyModule to the NEST installation directory, including help files generated from the source code. 
 
 ## Using MyModule
 
-1. Set your `LD_LIBRARY_PATH` to include `$NEST_INSTALL_DIR/lib/nest`, where `$NEST_INSTALL_DIR` is the root of the NEST installation directory tree. On OSX, set `DYLD_LIBRARY_PATH`.
-2. Start NEST.
-3. Load the module using
+1. Start NEST.
+2. Load the module using
 
         SLI ] (mymodule) Install
         Apr 30 17:06:11: *** Info: Install
         Apr 30 17:06:11: loaded module My NEST Module
 
-4. You should now see pif_psc_alpha in the modeldict and drop_odd_spike in the synapsedict. You can learn more about these models and the additional (meaningless) connection function supplied by the model by typing
+3. You should now see `pif_psc_alpha` in the `modeldict` and `drop_odd_spike` in the `synapsedict`. You can learn more about these models and the additional (meaningless) connection function supplied by the model by typing
 
         /pif_psc_alpha help
         /drop_odd_spike help
         /StepPatternConnect help
 
-5. In PyNest, use
+4. In PyNEST, use
 
         nest.Install("mymodule")
 
     This is available under Linux and OSX starting with NEST 1.9.8497 and later. Link the module into NEST as described below if you run into problems. 
 
 ## Creating your own module
 
-1. Start with the code from MyModule, replace anything called "mymodule" in any form of camelcasing by the name of your module, and proceed as above.
-2. When you change names of source code files or add/remove files, you need to update `Makefile.am`.
+1. Start with the code from MyModule.
+1. Follow the instructions (1. - 4.) at the top of the `CMakeLists.txt` file in the MyModule directory.
+1. Replace anything called "mymodule" in any form of camelcasing by the name of your module, and proceed as above.
+2. When you change names of source code files or add/remove files, you need to update the variable `MODULE_SOURCES` in `CMakeLists.txt` .
 3. `make dist` will roll a tarball of your module for distribution to others.
 4. `mymodule.cpp` and `sli/mymodule.sli` contain versioning information that you may want to update. It helps to keep the C++ code and SLI wrapper of your module in sync. 
 
@@ -127,16 +111,17 @@ As a starting point, try to build MyModule as follows:
 2. Change back to the NEST build directory.
 3. Reconfigure NEST informing it about your MyModule. Note that the module MUST be installed in the NEST installation directory tree!
 
-        ../src/configure --with-modules="mymodule"
+        cmake [...] -Dexternal-modules=my ../src
 
-    Several modules can be given, separated by spaces.
+    Several modules can be given, separated by semicolon.
+    <br/>__Note:__ Instead of giving the full module name `mymodule`, only give the `SHORT_NAME` `my` for the option `-Dexternal-modules=...`.
 4. Recompile and install NEST.
 5. The module should now be available as soon as NEST has started up. It will also be available in PyNEST.
 6. When you make any change to your module, you must first re-compile and re-install your module.
 7. Then move to the NEST build directory and issue
 
         make -C nest clean
         make
-        make install-exec
+        make install
 
     This rebuilds only the NEST executable. 
diff --git a/xcode_workflow.md b/xcode_workflow.md
@@ -15,10 +15,9 @@ This article contains instructions on how to develop NEST on a Mac (OSX 10.10.3
 We need several packages installed, before we can become productive with NEST:
 
 * gcc
-* openmpi 1.6
+* openmpi 1.6 (or later)
 * gsl
-* autoconf
-* automake
+* cmake
 * libtool
 * ipython, python, cython, ... The best way to install all the python requirements is to use [Anaconda](https://store.continuum.io/cshop/anaconda/).
 
@@ -34,26 +33,7 @@ We present two ways to install the rest: MacPorts and Homebrew. For both version
 1. Follow the install instructions for Homebrew ([short](http://brew.sh/) or [long](https://github.com/Homebrew/homebrew/blob/master/share/doc/homebrew/Installation.md#installation))
 1. Open up the Terminal and execute the following lines:
 
-        brew install gcc gsl autoconf automake libtool
-1. Since every package is compiled using th Mac supplied gcc, aka clang, but we want OpenMP to wrap around the Homebrew-gcc, we have to alter the openmpi-installation script. Assuming we installed Homebrew gcc 5.1.0, the executable is called `gcc-5` or `g++-5`, the script can be changed this way:
-
-        brew edit open-mpi
-In the `def install` function add the `CC` and `CXX` lines to the `args` variable like this:
-
-        args = %W[
-          --prefix=#{prefix}
-          --disable-dependency-tracking
-          --disable-silent-rules
-          --enable-ipv6
-          --with-libevent=#{Formula["libevent"].opt_prefix}
-          --with-sge
-          CC=gcc-5         # these are the
-          CXX=g++-5        # important lines
-        ]
-1. Homebrew tries to use pre-compiled packages, if possible (so-called bottles). You can disable this by setting the environment variable `HOMEBREW_BUILD_FROM_SOURCE` to some value. Install OpenMPI with the following line:
-
-        brew install pkg-config makedepend     # have open-mpi dependencies installed as bottles
-        HOMEBREW_BUILD_FROM_SOURCE=1 brew install open-mpi
+        brew install gcc gsl cmake open-mpi libtool
 
 ### MacPorts
 
@@ -65,7 +45,7 @@ In the `def install` function add the `CC` and `CXX` lines to the `args` variabl
         sudo port install gcc48
         sudo port select gcc mp-gcc48 # make gcc-48 the default compiler
         sudo port install gsl +gcc48
-        sudo port install autoconf automake libtool    # build tools
+        sudo port install cmake       # build tools
 1. NEST on Mac requires OpenMPI 1.6 from MacPorts to work properly, so we have to get this older version for MacPort. Download the portsfile [Portfile-openmpi-1.6.4.txt](http://www.nest-simulator.org/wp-content/uploads/2014/12/Portfile-openmpi-1.6.4.txt) and save it under the name `Portfile` in an arbitraty directory.
 1. In Terminal, move to the directory containing Portfile and run
 
@@ -89,23 +69,26 @@ Afterwards you should have a directory structure like:
 1. Build NEST
 
         cd src
-        ./bootstrap.sh
         cd ../build
 
         # with Homebrew infrastructure run:
-        $PWD/../src/configure --prefix=$PWD/../install --with-debug --with-mpi CC=mpicc CXX=mpicxx
+        cmake -DCMAKE_INSTALL_PREFIX=$PWD/../install -Dwith-debug=ON -Dwith-mpi=ON -DCMAKE_C_COMPILER=gcc-5 -DCMAKE_CXX_COMPILER=g++-5 $PWD/../src
         # with MacPorts infrastructure run:
-        $PWD/../src/configure --prefix=$PWD/../install --with-debug --with-mpi CC=openmpicc CXX=openmpicxx
+        cmake -DCMAKE_INSTALL_PREFIX=$PWD/../install -Dwith-debug=ON -Dwith-mpi=ON -DCMAKE_C_COMPILER=gcc-mp-4.8 -DCMAKE_CXX_COMPILER=g++-mp-4.8 $PWD/../src
 
         make -j8    # run make with 8 processes
         make install 
         make installcheck
 
-__Note:__ It is important, that the `configure` command is _not_ executed with relative paths, in order for Xcode to find source files mentioned in the build logs.
+__Note:__ It is important, that the `cmake` command is _not_ executed with relative paths, in order for Xcode to find source files mentioned in the build logs.
 
 __Note:__ If you want to debug your code with Xcode later, it has to be compiled with debug-options enabled.
 
-__Note:__ Always supply a concrete `CC` and `CXX` for the configure (if you do not use the mpi-versions, which should wrap around the correct gcc): e.g. `CC=gcc-5 CXX=g++-5` (for Homebrew) or `CC=gcc-mp-4.8 CXX=g++-mp-4.8` (for MacPorts). Otherwise Xcode will prefer to use the gcc/clang version.
+__Note:__ Always supply a concrete `CMAKE_C_COMPILER` and `CMAKE_CXX_COMPILER` for the configure: e.g. `-DCMAKE_C_COMPILER=gcc-5 -DCMAKE_CXX_COMPILER=g++-5` (for Homebrew) or `-DCMAKE_C_COMPILER=gcc-mp-4.8 -DCMAKE_CXX_COMPILER=g++-mp-4.8` (for MacPorts). Otherwise Xcode will prefer to use the gcc/clang version.
+
+__Note:__ Even if you want to build with MPI enabled, do not set the wrapper compilers for `CMAKE_*_COMPILER`, as cmake will figure out the correct compiler options on its own.
+
+__Note:__ With cmake it is also possible, to generate the XCode project files with `-G Xcode`, but this will require you to build with `gcc/clang`. The following instructions assume, that you do not use this option.
 
 ## Get Xcode working with NEST