adding-new-code-to-nest.md

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.