Adding New Code to NEST
This document assumes that the reader already knows how to build NEST from source.
- If you want to add a new library inside NEST, createa a new directory inside
nest/nest-2.6.0
. In my case, I created the directorynest/nest-2.6.0/nestgpu
and wanted my new code to be inside the new librarylibnestgpu
. Inside this directory, you add your new source/header files. - However, your code is still not part of the NEST build system. To have your code be built with NEST, you need to do few more things.
- First, create a file named
Makefile.am
inside this new directory. Every source directory of NEST contains aMakefile.am
file of its own. This file contains instructions for theautomake
tool so that it knows what to build, from which files, using which libraries, etc. For example, I had two source files:GpuDataAdapter.h`` and
GpuDataAdapter.cpp`` which I wanted to be built into my new librarylibnestgpu
. For this purpose, my ```nest/nest-2.6.0/nestgpu/Makefile.am``` file contained the following lines:
# Automake file for the GPU-port of the NEST simulation kernel library
#
# Saad Quader, January 2015
#
defs= @SLI_THREAD_DEFS@ $defs
MAKEFLAGS= @MAKE_FLAGS@
noinst_LTLIBRARIES=libnestgpu.la
libnestgpu_la_SOURCES=\
gpu_data_adapter.h gpu_data_adapter.cpp
# do not change anything below this line ------------------------------
libnestgpu_la_CXXFLAGS= @AM_CXXFLAGS@
libnestgpu_la_LIBADD= @LIBLTDL@ @LIBADD_DL@
AM_CPPFLAGS= -I$(top_srcdir)/libnestutil\
-I$(top_srcdir)/librandom\
-I$(top_srcdir)/sli\
-I$(top_srcdir)/nestkernel\
@INCLTDL@ @GSL_CFLAGS@ @MUSIC_INCLUDE@ @MPI_INCLUDE@
-
Suppose you want to use your code from any part of the original NEST code. In my case, I wanted to call
GpuDataAdapter::init()
from within the functionneststartup()
in the filenest/nest-2.6.0/nest/neststartup.cpp
. For this, inside thecpp
file, I added#include "gpudataadapter.h"
and inside the definition of the functionneststartup()
, I addednest::gpu::GpuDataAdapter::init();
. -
Editing the existing source code was easy. However, how does the compiler/linker know where to find the declaration/definition of the code for the
GpuDataAdapter::init()
function? This is the hard part. For this, I had to modify thenest/nest-2.6.0/nest/Makefile.am
file as follows:- I added
nestgpu/libnestgpu.la
to the existing definition of the variablesnest_LDADD
andnest_DEPENDENCIES
so that the linker knows where to find the definition of my new functions. - I also added
-I$(top_srcdir)/nestgpu
to the existing value of the variableAM_CPPFLAGS
so that the compiler knows where to look for the#include
headers for my new code. - However, it turned out that the module
nest/nest-2.6.0/pynest
also uses the filenest/nest-2.6.0/nest/neststartup.cpp
and its header. Therefore, I had to specify thenest/nest-2.6.0/nestgpu
directory as an include directory in the filenest/nest-2.6.0/pynest/Makefile.am
as well. However, I did not need to specify the librarylibnestgpu
because the librarypynestkernel.la
was already linked to the librarylibnest.la
which was also already linked to my librarylibnestgpu.la
.
- I added
-
Next, you should tell the NEST build system to actually visit this subdirectory and build your code. For this, you have to edit the
nest/nest-2.6.0/configure.ac.in
. In particular, you need to edit two things:- You have to specify that you have a new source directory. You do this by editing the existing value of the variable
SLI_CORE_LIBS
and adding the wordnestgpu
in its existing list of directories. - You have to specify that you have a new
Makefile
to be created by the configure script. You do this by adding the following line:AC_CONFIG_FILES(nestgpu/Makefile)
after the list of existing Makefiles. (Just search for the textAC_CONFIG_FILES
) inside the fileconfigure.ac.in
.)
- You have to specify that you have a new source directory. You do this by editing the existing value of the variable
-
Now that we have specified that we have new code, we need to rebuild the system, by generating a new
configure
script using our recently modifiedconfigure.ac.in
file. To do this, just run the scriptnest/nest-2.6.0/bootstrap.sh
which would generate a newconfigure
script. -
Then, reconfigure NEST by typing
cd /home/saad/nest/build && ../nest-2.6.0/configure ../nest-2.6.0/configure --prefix=/home/saad/venv/nest-dbg --with-mpi --with-openmp --with-debug --with-optimize=-O0
. -
Then, build NEST by running
make
andmake install
. -
Now, when NEST runs, it does so with the modified code.