How to add new code

Adding new code is not as easy as creating a new file, e.g. foo.cpp. As we are using [GNU autotools ​http://wissrech.ins.uni-bonn.de/inside/autotools.html] one has to tell Autotools about it.

Below there are various different types list and how to add them.

New cpp or hpp files

The source folder of MoleCuilder molecuilder/src/ and each of its subfolders contain a Makefile.am as exemplarily shown below:

...
SOURCE = ${ANALYSISSOURCE} ${ATOMSOURCE} ${PATTERNSOURCE} ${UISOURCE} ${DESCRIPTORSOURCE} ${LEGACYSOURCE} bond.cpp bondgraph.cpp boundary.cpp config.cpp element.cpp ellipsoid.cpp errorlogger.cpp graph.cpp helpers.cpp info.cpp leastsquaremin.cpp linkedcell.cpp log.cpp logger.cpp memoryusageobserver.cpp moleculelist.cpp molecule.cpp molecule_dynamics.cpp molecule_fragmentation.cpp molecule_geometry.cpp molecule_graph.cpp molecule_pointcloud.cpp parser.cpp periodentafel.cpp tesselation.cpp tesselationhelpers.cpp vector.cpp verbose.cpp World.cpp 
HEADER = ${ANALYSISHEADER} ${ATOMHEADER} ${PATTERNHEADER} ${UIHEADER} ${DESCRIPTORHEADER} ${LEGACYHEADER} bond.hpp bondgraph.hpp boundary.hpp config.hpp defs.hpp element.hpp ellipsoid.hpp errorlogger.hpp graph.hpp helpers.hpp info.hpp leastsquaremin.hpp linkedcell.hpp lists.hpp log.hpp logger.hpp memoryallocator.hpp memoryusageobserver.hpp molecule.hpp molecule_template.hpp parser.hpp periodentafel.hpp stackclass.hpp tesselation.hpp tesselationhelpers.hpp vector.hpp verbose.hpp World.hpp 

BOOST_LIB = $(BOOST_LDFLAGS) $(BOOST_MPL_LIB)

check_PROGRAMS = $(TESTS)
noinst_LIBRARIES = libmolecuilder.a libgslwrapper.a
bin_PROGRAMS = molecuilder 
molecuilderdir = ${bindir}
#libmolecuilder_a_CXXFLAGS = -DNO_CACHING
libmolecuilder_a_SOURCES = ${SOURCE} ${HEADER}
libgslwrapper_a_SOURCES = ${LINALGSOURCE} ${LINALGHEADER}
molecuilder_DATA = elements.db valence.db orbitals.db Hbonddistance.db Hbondangle.db
molecuilder_LDFLAGS = $(BOOST_LDFLAGS)
molecuilder_CXXFLAGS = $(BOOST_CPPFLAGS)
#molecuilder_CXXFLAGS += -DNO_CACHING
molecuilder_SOURCES = builder.cpp
molecuilder_LDADD = libmolecuilder.a libgslwrapper.a $(BOOST_LIB) ${BOOST_THREAD_LIB}
...

Note the lines SOURCE and HEADER. These are variables, that list a number of source or header files, respectively. These may be used as $(SOURCE) later at various places.

There, a program is compiled called molecuilder. For the make program to know what to do, the SOURCES have to be listed (i.e. all cpp and hpp files needed for compilation), and additional compilation flags, such as CFLAGS or CXXFLAGS, and linker flags, such as LDFLAGS or LDADD may be specified. DATA gives additional files that are important to this program, here the database files. As you see we also compile two libraries, called libmolecuilder.a and libgslwrapper.a (dot is replaced by an underbar). In general libraries are just programs without a main function. Hence, they also need source files and arbitrary flags specified. As molecuilder uses these libraries, note that they are specified in the ..._LDADD statement. Dependencies (i.e. what needs to be compiled first) are automatically resolved by the make program.

Finally, all programs to be compiled (make all) and installed (make install) are given by the bin_PROGRAMS line, programs to be compiled but not installed by noinst_PROGRAMS and noinst_LIBRARIES for libs. check_PROGRAMS are tests programs that will be executed on entering make check, i.e. use these for unit tests codes.

Perl or Python scripts

Perl and python scripts have in most cases a first line, called she-bang, as follows:

#!/usr/bin/perl
...

As the exact location of the python may differ from system to system it makes sense to have this location inserted by autotools. Therefore, we need a variable @PERL@, to be filled by a line of code AC_CHECK[perl] already placed into molecuilder/configure.ac. Hence, we can modify the she-bang as:

#! @PERL@
...

In order to tell autotools to replace the above variable, you have to the following steps. We assume that the script is called foo.pl.

1. Rename the script to foo.pl.in (and have it in util/src).
2. Look at util/configure.ac, at the very end, there is a statement as with many files instead of ...

   AC_CONFIG_FILES([ src/bar.pl \
        test.pl \
        ...
        ])
   

3. Add an another line such as, note the put in the original name, with no .in suffix.

        foo.pl \
   

4. On make install, the autotools will replace the variable in foo.pl.in and put the modified version as foo.pl in the installation binary directory.

Note that for python the variable is @PYTHON@ but the procedure remains the same.