diff --git a/Adding-New-Code-to-NEST.md b/Adding-New-Code-to-NEST.md new file mode 100644 index 0000000..fbbff7b --- /dev/null +++ b/Adding-New-Code-to-NEST.md @@ -0,0 +1,47 @@ +Adding New Code to NEST +======================= +This document assumes that the reader already knows [how to build NEST from source(Tips on Nest.md)]. + +* 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 directory ```nest/nest-2.6.0/nestgpu``` and wanted my new code to be inside the new library ```libnestgpu```. 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 a ```Makefile.am``` file of its own. This file contains instructions for the ```automake``` 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 library ```libnestgpu```. 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 function ```neststartup()``` in the file ```nest/nest-2.6.0/nest/neststartup.cpp```. For this, inside the ```cpp``` file, I added ```#include "gpudataadapter.h"``` and inside the definition of the function ```neststartup()```, I added ```nest::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 the ```nest/nest-2.6.0/nest/Makefile.am``` file as follows: + * I added ```nestgpu/libnestgpu.la``` to the existing definition of the variables ```nest_LDADD``` and ```nest_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 variable ```AM_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 file ```nest/nest-2.6.0/nest/neststartup.cpp``` and its header. Therefore, I had to specify the ```nest/nest-2.6.0/nestgpu``` directory as an include directory in the file ```nest/nest-2.6.0/pynest/Makefile.am``` as well. However, I did not need to specify the library ```libnestgpu``` because the library ```pynestkernel.la``` was already linked to the library ```libnest.la``` which was also already linked to my library ```libnestgpu.la```. + +* 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 word ```nestgpu``` 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 text ```AC_CONFIG_FILES```) inside the file ```configure.ac.in```.) +* 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 modified ```configure.ac.in``` file. To do this, just run the script ```nest/nest-2.6.0/bootstrap.sh``` which would generate a new ```configure``` 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``` and ```make install```. +* Now, when NEST runs, it does so with the modified code.