bamps is hosted by Hepforge, IPPP Durham
BAMPS Logo

Install BAMPS

BAMPS is developed and tested on Linux systems. In principle however, the code should be rather platform independent and should be able to e.g. run on Windows or MacOS with little to no modifications. The following software and libraries are necessary in order to build the BAMPS source code:

Prerequisites

CMake (Cross Platform Make)

Version >= 2.6br

http://www.cmake.org/

CMake is the build system used by BAMPS. It is used by many open source projects and should be available in basically any Linux distribution.

Boost library

Version >= 1.40br

http://www.boost.org/

The Boost C++ libraries provide functions that go beyond standard C++. BAMPS for example relies on Boost to generate random numbers (see random.h) in a way that allows for a flexible incorporation of different random number generators. Furthermore Boost is used to parse program options from input files or the command line, to dump data files that allow for later reconstruction of BAMPS events, etc.

There exist two types of Boost libraries, header-only libraries that require no building of libraries at all and separately-compiled libraries that need to be built (or installed via the Linux distribution). As of r218 the [source:full/trunk/ main version of BAMPS] depends on Boost libraries that need to be built. Currently the binary libraries filesystem, system, program_options, regex and serialization are required.

Most Linux distributions provide packages for the Boost libraries. Note however, that the libraries are evolving rather rapidly and thus packages provided by distributions might be outdated. Furthermore changes in the naming scheme of Boost libraries have occurred that might cause issues with the scripts of the build system trying to locate the libraries. Manual fine tuning might be necessary in these cases (should however be necessary only on rare occasions).

Obtaining and building Boost

Detailed instructions on building the Boost libraries on Linux systems (if not provided by the distribution) can be found at

http://www.boost.org/doc/libs/release/more/getting_started/unix-variants.html

What follows is a very short instruction on how to build and install the boost libraries as needed for BAMPS. It should be sufficient in most cases, but please refer to the boost homepage for more details.

Assuming that you are at the root of the directory in which the Boost source has been extracted, do the following:


  ~$ ./bootstrap.sh --prefix=$HOME/usr --with-libraries=system,filesystem,serialization,program_options,regex
  ~$ ./b2 --layout=tagged install

This will install the Boost headers to $HOME/usr/include/boost and the binary libraries to $HOME/usr/lib. Note the use of --layout=tagged that makes the naming scheme of the generated binary libraries compatible with the FindBoost.cmake scripts used by BAMPS.

User-based and system-wide Boost installations


#!div class=important style="border: 0.1pt solid; text-align: left; margin:0px 50px;"
Warning: Mixing user-based and system-wide installations can lead to problems!

When both a system-wide and a user-based installation of Boost are present, BAMPS should be configured such that the user-based installation is used. When Boost has been installed to the prefix $HOME/usr as described above, this is automatically the case. If Boost has been installed to another location in the user's home directory, the following line in the CMakeLists.txt needs to be adapted


  SET(BOOST_ROOT "$ENV{HOME}/usr")

Failing to do so might result in viscous linking errors due to version conflicts between the Boost headers and the Boost binary libraries. This happens when

    1. different versions of Boost are present in the system- and the user-based trees and
    2. another library (e.g. Cuba) is used from a user-based location with the same installation prefix (e.g $HOME/usr) as the Boost library.

In this case the Boost headers might get included from the user-based installation, while the binary libraries are taken from the system-wide installation. This cannot be easily prevented within the build system as fixing such mixtures of include and linking directories would require dirty and inflexible hacks on the level of the linking options. The scenario is therefore not supported.

LHAPDF library (optional)

Version >= 5.4, < 6.0br

http://projects.hepforge.org/lhapdf/


#!div class=important style="border: 0.1pt solid; text-align: left; margin:0px 50px;"
Warning: At the moment, the BAMPS code only supports lhapdf until v5.9. The new LHAPDF (v6.0+) is not yet supported.

> NOTE: If you want to prepare for the new v6.0 of LHAPDF, here some hints:

> * the option --disable-octave does not exists anymore

> * you probably have to install yaml-cpp. You can get it at http://code.google.com/p/yaml-cpp and compile it yourself, while switching on building of shared libraries explicitely: cmake -DBUILD_SHARED_LIBS=on ..

> * there is no lhpdf-getdata anymore

> * the members of the namespace LHAPDF have changed, the BAMPS code has to be changed

As of r351 BAMPS supports the usage of the LHAPDF library that provides parton distribution functions (PDF). Currently the usage of LHAPDF is optional, i.e. the code compiles and runs without it (in this case falling back to a built-in parametrization of the GRV PDFs), but this might change in the future.

Information on how to actually use the LHAPDF interface together with BAMPS can be found in the [wiki:RestrictedWiki/ManualsAndReadmes#UsageandconfigurationofLHAPDFdatasets usage manual], this section only describes the installation of LHAPDF.

Building LHAPDF

LHAPDF can be obtained from

http://projects.hepforge.org/lhapdf/

where also extensive information on the available PDF sets can be found. BAMPS has been tested to work with version 5.8.6, but in general versions >= 5.4 AND < 6.0.0 (!!!) should be fine (see comment above).

In order to install the LHAPDF library download the .tar.gz source file, extract it and run the usual


  ~$ ./configure --prefix=$HOME/usr --disable-octave --disable-pyext
  ~$ make
  ~$ make install

chain of commands to configure, build and install the library. Change the location of the installed files by adjusting the --prefix path as desired. Note the use of the --disable-octave option. The LHAPDF library provides severals modules and features that are not absolutely necessary for its usage in BAMPS, one of them being a module for octave. As this module has some dubious dependencies, it might not compile properly. It is therefore recommended to explicitly deactivate this module.

Obtaining and installing PDF sets

The LHAPDF library from version 5.7.1 on does not include any PDF sets by default. These need to be downloaded and installed separately. This can either be done manually by downloading individual sets from the LHAPDF homepage and putting the files into a folder called


  $HOME/usr/share/lhapdf/PDFsets

in the case of an installation prefix as in the above example) or by using the download script that is provided by the library (see below). The latter option is of course recommended.

The download script lhapdf-getdata is installed together with the library files into the bin-subfolder of the given installation prefix (e.g. into $HOME/usr/bin in our example). Execute this script inside the folder into which the PDF sets should be downloaded (see above) and follow the instructions. Also the script lhapdf-config can be used to configure LHAPDF paths etc. individually. This advanced setup however will not be covered here. More information can be found at http://projects.hepforge.org/lhapdf/install.

GNU Scientific Library (GSL)

Version >= 1.14 (earlier versions probably work as well)br

http://www.gnu.org/software/gsl/

BAMPS makes use of routines from the GNU Scientific Library (GSL) for numerical interpolation, sampling from given probability distributions, etc. The usage of GSL is likely to be extended in the future in order to remove the last dependencies on legacy routines from Numerical Recipies.

GSL is available from packages provided by virtually all Linux distributions. For example, when using Ubuntu, install the package libgsl0-dev. Of course GSL can also be downloaded, build and installed from source packages available at http://www.gnu.org/software/gsl/. However, this will be rarely necessary and therefore this scenario is not covered here. Please refer to instructions available on the homepage of the GNU software for details. Packages for Windows are also available.

Cuba library

Version >= 2.0br (At the moment only versions 2.0 and 2.1 are officially supported.)

http://www.feynarts.de/cuba/

The Cuba library provides routines for numerical integration based on various methods. Though currently not used it is implemented into the integration routines and can be easily switched to (see [source:lib/src/integrate.h integrate.h] and e.g. the preprocessor macros in [source:lib/src/scattering32.cpp scattering32.cpp]). Thus the current version of BAMPS requires the Cuba library to build. To do this download the package from http://www.feynarts.de/cuba/ and extract the source files. Run in the extracted folder


  ~$ ./configure
  ~$ make

In the folder is now the header file (cuba.h) and a library file (libcuba.a). Copy the header file to the include path (usually $HOME/usr/include) and the library file to the lib path (usually $HOME/usr/lib). The [source:full/trunk/cmake_modules/FindCuba.cmake custom CMake module] provided with BAMPS searches for the Cuba library in the default places (e.g. /usr/lib, /usr/local/lib) and in a home directory-based usr-tree (i.e. $HOME/usr).BR

Please note that the current version of BAMPS (as of [changeset:30 revision 30]) is not compatible with Cuba versions older than 2.0 any more.

PYTHIA event generator (optional)

Version >= 8.180br

Version >= 8.2 is not tested and does not work at the moment.br

http://home.thep.lu.se/~torbjorn/Pythia.html

PYTHIA is a possible option to sample online the initial momenta of the particles. In addition, preprocessed files for PYTHIA initial conditions can also read in from a file. In this case the file has to be produced before, and PYTHIA itself must not be linked to BAMPS. However, the first option is recommended.

Furthermore, PYTHIA is used for the decay of heavy flavor mesons.

To use online PYTHIA initial conditions or heavy flavor decays download PYTHIA from http://home.thep.lu.se/~torbjorn/Pythia.html and unzip it to your desired path. You have to modify two files to link it properly to BAMPS:

    1. Open <path to PYTHIA>/src/Pythia.cc and add the following code outside the Pythia8 namespace:


// namespace to set shadowing parametrization from BAMPS
namespace Pythia8_bamps_link
{
  string shadowing_parametrization = "";
  double A = 197.0;
}

2. Replace the file <path to PYTHIA>/include/Pythia8/LHAPDFInterface.h with this file: [attachment:LHAPDFInterface.h] (tested with version PYTHIA 8.175)

3. Replace the file <path to PYTHIA>/lhapdfdummy/LHAPDFDummy.cc with this file: [attachment:LHAPDFDummy.cc] (tested with version PYTHIA 8.175)

In typical versions like 8.186 (most recent version < 8.2), shared libraries are not created by default. Use


~$ ./configure --enable-shared

before you run


  ~$ make

in the main PYTHIA folder <path to PYTHIA>. (Otherwise, 'make' will run 'configure' automatically with default settings, and does not generate the .so files.)

After compiling create some soft links in $HOME/usr to use PYTHIA in BAMPS:


  ~$ cd $HOME/usr/lib
  ~$ ln -s <path to PYTHIA>/lib/archive pythia
  ~$ cd $HOME/usr/include
  ~$ ln -s <path to PYTHIA>/include pythia
  ~$ mkdir $HOME/usr/share/pythia/
  ~$ cd $HOME/usr/share/pythia/
  ~$ ln -s <path to PYTHIA>/xmldoc
  ~$ cd $HOME/usr/bin
  ~$ ln -s <path to PYTHIA>/bin/pythia8-config

It is highly recommended to also install LHAPDF since it is needed to use a shadowing parametrization or more advanced parton distribution functions.

How to Build

Usage of CMake

BAMPS uses CMake as a build system, see [#depSectionId dependencies] above.

The instructions below are valid on Linux systems, the steps necessary on Windows should be similar though. "~$ " indicates the terminal prompt. Arguments given in < > are mandatory, arguments given in [ ] are optional.

Short version: In the main directory of the program (e.g. in full/trunk/ or box/trunk/), create a subdirectory called build and change into this directory


  ~$ mkdir build
  ~$ cd build

Then configure the build directory with


  ~$ cmake ../

followed by


  ~$ make

to actually compile and build the source.

General usage

In general the code should be built in a separate directory (e.g. build or debug) like this:


  ~$ cmake [build options] <path to BAMPS main folder>

Suppose the source (e.g. [source:full/trunk/]) has been extracted into a folder ~/BAMPS. Now a subfolder ~/BAMPS/build is created in which the program should be built. In order to build with the standard options, first change into the subfolder and then issue cmake followed by make.


  ~$ cd ~/BAMPS/build
  ~$ cmake ../
  ~$ make

If all goes well the executable (e.g. called cascade for the full BAMPS version) is then located in ~/BAMPS/build/src

In order to see a more detailed output of the make processes, try


  ~$ make VERBOSE=1

On a side note, a convenient option to make is -j n or --jobs=n that tells make to spawn multiple jobs for the build process. On a multi-core machine this can considerably speed up the compilation process. So, for example, on a machine with a CPU that has 4 cores, one could issue


  ~$ make -j 4

Omitting the blank also seems to work, i.e. -j4 instead of -j 4.

Build options specific to BAMPS

The most important option to CMake is usually CMAKE_BUILD_TYPE which can be set to Release, Debug or RelWithDebInfo. Options are passed to CMake from the command line via


  ~$ cmake -D<OPTION_NAME=VALUE> [further options] <path>

Without any further configuration CMake uses the default compiler of the system, which is gcc on Linux systems.

In addition to CMAKE_BUILD_TYPE a custom variable called BAMPS_BUILD_TYPE is offered that controls the build process. Setting this variable allows to select different compilers and to specify a set of build options tailored to the system. See [source:full/trunk/SetCompilersAndBuildFlags.cmake SetCompilersAndBuildFlags.cmake] on how these flags are defined. BAMPS_BUILD_TYPE can take the following values:

    • GCC
    • Intel
    • !IntelProfGen
    • !IntelProfUse
    • IntelCSC,
    • IntelLoeweCSC
    • AMD
    • AMDCSC
    • AMDLoeweCSC

The first part indicates the compiler in use, currently the GNU compiler gcc (http://gcc.gnu.org/), the Intel compiler icc (http://software.intel.com/sites/products/documentation/hpc/compilerpro/en-us/cpp/lin/compiler_c/index.htm) and AMD's variant of the open64 compiler (http://developer.amd.com/tools/open64/pages/default.aspx).

The different variants for each compiler are meant to be tailored to specific system architectures. The Intel compiler has been found to significantly outperform the other compilers in various test cases - your mileage may vary though.

See the section on [wiki:RestrictedWiki/BuildInstructions#Compiler-basedoptimization compiler-based optimization] for background information on the various optimization options available via different compilers and especially for details on using profile-guided optimization (PGO) via BAMPS_BUILD_TYPE=IntelProfGen and BAMPS_BUILD_TYPE=IntelProfUse.

BAMPS_BUILD_TYPE can (and should) be used together with CMAKE_BUILD_TYPE, e.g.


  ~$ cmake -DBAMPS_BUILD_TYPE=Intel -DCMAKE_BUILD_TYPE=Release ../

or


  ~$ cmake -DBAMPS_BUILD_TYPE=Intel -DCMAKE_BUILD_TYPE=Debug ../

Omitting CMAKE_BUILD_TYPE defaults to a Release build, omitting BAMPS_BUILD_TYPE defaults to the standard compiler of the system (gcc on most Linux systems). Omitting both options consequently leads to a default Release build, on Linux this should be gcc with the options -O3 -DNDEBUG. If in doubt, issue make VERBOSE=1 to see which compiler and which build flags are actually used.

Disabling build extras (svn info and doxygen)

By default the BAMPS build system provides some goodies:

  • provide a [#Creatingdocumentationfromthesourcecode doxygen target] for automatic generation of API documentation.
  • retrieve svn revision information and make it available to the BAMPS main routines via a preprocessor macro.

In case this is not desired, these goodies can be deactivated by virtue of the DISABLE_BUILD_EXTRAS option, e.g


  ~$ cmake -DDISABLE_BUILD_EXTRAS=TRUE ../

When the source is not a valid svn working copy, the usage of this option is currently mandatory as due to design flaws in the FindSubversion.cmake package there is no gracious way of directly dealing with non-working copy directories.

Creating a source tarball for distribution

The lines


  INCLUDE(CMakeCustomPackageOptions.cmake)
  INCLUDE(CPack)

in the main CMakeLists.txt (e.g. [source:full/trunk/CMakeLists.txt]) together with the file [source:full/trunk/CMakeCustomPackageOptions.cmake] (this file contains the setup for the packaging) offer the possibility to quickly create a .tar.gz version of the source for distribution. Simply go into a directory in which CMake has been employed to configure the build (i.e. the build directory, see [#UsageOfCMake above]) and issue


  ~$ make package_source

Creating documentation from the source code

BAMPS uses the tool [http://www.doxygen.org Doxygen] for generating documentation of the source code. Doxygen scans the source code and automatically documents classes, files, functions, etc. But in order to provide useful documentation the source code needs to be thoroughly commented - in a way that is recognized by Doxygen. See [http://www.stack.nl/~dimitri/doxygen/manual.html here] for instructions. Please always adhere to the [http://www.stack.nl/~dimitri/doxygen/docblocks.html Doxygen conventions] for commenting the source code when writing new routines and help documenting existing routines wherever possible. This will further improve the usefulness of this documentation.

Based on the Doxygen system, an up-to-date documentation of the trunk versions of [source:full/trunk/ full] and [source:box/trunk/ box] is provided in nightly builds of the source code in the trac system under [/doxygen API documentation].

In case a manual generation of the documentation is needed, simply issue


  ~$ make doxygen

in a previously configured build directory (see above). The configuration of the Doxygen documentation is based on the template file Doxyfile.in (e.g. [source:full/trunk/Doxyfile.in]). When configuring the build directory, CMake adds some information about the current revision and creates a file Doxyfile which is then used as an input file to Doxygen. In order to manually generate the documentation with options other than the default ones (e.g. to create Latex documentation in addition to the HTML documentation), either modify Doxyfile.in and let CMake handle the rest or create (copy and modify) a custom configuration file (Doxyfile, though the name is arbitrary) and execute


  ~$ doxygen Doxyfile

Compiler-based optimization

This section is meant to supplement the information on [wiki:RestrictedWiki/BuildInstructions#BuildoptionsspecifictoBAMPS BAMPS-specific build options]. While the aforementioned instructions detail how to activate certain options during the build processes of BAMPS, the present section provides background information on the capabilities of certain compilers. It is therefore meant for people that are (a) curios, (b) want to modify the BAMPS optimization flags (e.g. in [source:full/trunk/SetCompilersAndBuildFlags.cmake]) or (c) would like some hints on how to optimize other programs.BR

So, here's how to use your compiler to optimize the s* out of your code:

GNU compiler

When working on Linux (and this is the only scenario that is discussed here), the [http://gcc.gnu.org/ GNU compiler gcc] is the usual weapon of choice. For C++ the compiler is called g++ and this program actually not only compiles but also links your code. The [http://www.cmake.org CMake] build system that is used by BAMPS usually defaults to setting up your project to use gcc. When giving CMake the option CMAKE_BUILD_TYPE=Release the compiler flags for gcc are set to


  -O3 -DNDEBUG

By the way, when using gcc without CMake as a build system, these options could either be given as command line parameters when compiling or could be assigned to the environment variable CXXFLAGS that controls the default options for compiling C++ code.

  • The -DNDEBUG option deactivates some debugging symbols and is currently not really needed for BAMPS.
  • The -O3 option is currently the most aggressive optimization option available for gcc and actually comprises a whole bunch of compiler options that thoroughly mangle your code to make it perform better. It inlines functions, eliminates variables, optimizes function calls and a lot more. See the [http://gcc.gnu.org/onlinedocs/gcc-4.6.2/gcc/Optimize-Options.html manual] for details.

When gcc with -O3 is done with your code, chances are that will not recognize much of it anymore. Therefore it should (can) not be used when trying to debug code. Give the -g option in this case or simply set CMAKE_BUILD_TYPE=Debug when using CMake. Future versions of gcc are likely to include even more aggressive optimization options.

Intel compiler

The GNU compiler is an incredible piece of software. It is one of the most widely used C and C++ compilers out there, it supports virtually all platforms, it is one of the most standard-compliant compilers and it is for free! This said, commercial software might (!) beat gcc in some disciplines. The [http://en.wikipedia.org/wiki/Intel_C%2B%2B_Compiler Intel C++ compiler icc] is such a piece of commercial software. It is considered to be the C++ compiler that produces the most performant, i.e. the fastest, code. It can vectorize (parallelize) loops, use interprocedural optimization (IPO), use profile-guided optimization (PGO) and tailors the compiled code to available hardware, making excessive use of processor-specific instruction sets. The latter is of course especially true for Intel processors on which icc-compiled code performs best. Intel makes no promises as to the applicability of some optimization options on other platforms and indeed the compiler is sometimes accused of deliberately degrading performance on AMD hardware. This debate however seems to not to be really settled and tests with BAMPS seem to suggest, that it optimizes BAMPS comparatively well on both Intel and AMD processors.

This said, the [http://software.intel.com/en-us/articles/intel-compilers/ Intel C++ compiler] is the most aggressively optimizing compiler that is currently available. But this comes at a price, it is commercial software and it is indeed very expensive. The current version of icc is 12.1 contained in the [http://software.intel.com/en-us/articles/intel-composer-xe/ Intel Composer XE] package.

There are actually some ways of using icc despite of its price:

  • The ITP and CSC systems provide the Intel C++ compiler.
      • At ITP it needs to be activated by adding some stuff to the .bashrc, see [http://th.physik.uni-frankfurt.de/wiki-it/index.php?title=Intel_Compiler_Temp the IT wiki]. Note that currently only version 11.0 is provided on the ITP systems which due to a bug does not play well with the gcc headers >= 4.4, therefore BAMPS does not compile with this version of icc, see [ticket:14]. This problem will be fixed once (if) version 12.1 is purchased.
      • On the CSC systems icc needs to be activated by loading the appropriate modules, cf. the output of module avail. The LOEWE CSC features the most recent version 12.1 that works well with BAMPS.
  • For non-commercial use Intel provides the compilers free of charge. See [http://software.intel.com/en-us/articles/non-commercial-software-development/ here]. Note however, that this license does most explicitly not cover the use for development of scientific software in case you receive any monetary compensation whatsoever for this work!
  • There is a free 30-day trial available for most of the Intel development tools. See [http://software.intel.com/en-us/articles/intel-software-evaluation-center/ here]. Registration required.

Now, finally, here are some remarks on optimization features that are special to the Intel compiler:

  • Optimization option -fastBR
icc basically offers all options that are available for gcc. It also provides the option -fast that extents the -O3 level to even optimize more aggressively. It most notably tries to tailor the compiled code to the available hardware, for example by parallizing loops. This can be expected to work best on Intel CPUs. See the [http://software.intel.com/en-us/articles/intel-parallel-studio-xe-for-linux-documentation/ excessive documentation] that is available by Intel for more details. -fast comprises several options that fore some reasons (see IPO below) are explicitly given in the CXX flags in BAMPS, see [source:full/trunk/SetCompilersAndBuildFlags.cmake]. BTW, future versions of gcc are likely to feature some sort of -fast as well.
  • Interprocedural optimization (IPO)BR
While the usual optimization looks at certain functions or blocks of code, IPO analyzes the program as a whole in order to improve the performance even more. Interprocedural optimization is activated with the -ipo option that is actually comprised in the -fast option. The [wiki:RestrictedWiki/BuildInstructions#TheBAMPSSourceTree-BAMPSLibraryandMainPrograms structure of BAMPS] that contains a library that is essentially built seperatly, makes the usage of IPO somewhat more complicated. Therefore internally IPO is handled by setting the INTERPROCEDURAL_OPTIMIZATION option on the targets via set_property, see e.g. [source:full/trunk/src/CMakeLists.txt], and explicitly setting the other options of -fast
  • Profile-guided optimization (PGO)BR
Probably the most advanced optimization method provided by icc is PGO. In a nutshell this splits the build process in three steps:
      1. Compile with the option -prof-gen together with mild optimization (e.g. -O2).
2. Run the program with some typical input data. While the program is running it analyzes itself and produces profiling data on the actual program flow, function call, etc. This information is written to special files with extension .dyn 3. Compile again, this time with -prof-use and the most aggressive optimization options (e.g. -fast). The compiler then utilizes the collected profiling data to improve the performance of the compiled code. Note that more than one profile data file can be used, that all the .dyn files must be collected in one directory and that the location of that directory might be specified to icc via -prof-dir.BR In BAMPS the PGO cycle is available by using BAMPS_BUILD_TYPE=IntelProfGen for generating profiling code and BAMPS_BUILD_TYPE=IntelProfUse for compiling code based on collected profiling data. Note that for the last step the collected .dyn files need to be put a the root of the current build directory.

Combing the above mentioned optimization options, especially PGO together with IPO and the rather aggressive loop vectorization of icc, can substantially speed up your program. Some tests with BAMPS (icc v12.1 versus gcc v4.4 on Intel quad-core) show that improving the performance by roughly 30% to 40% is possible.BR Your mileage may vary though. Largely vary! In both directions! So the advice would be: test, profile and evaluate whether using the above mentioned optimizations is actually of any benefit for the specific program and hardware at hand.

The BAMPS Source Tree - BAMPS Library and Main Programs

The source code of the different BAMPS versions (i.e. [source:full/trunk/ full] and [source:box/trunk/ box]) has been split into a BAMPS library and the main programs. The library contains all parts of the source code that are common to all variants - scattering routines, integration routines, auxiliary routines etc. Seen from the root of the svn repository the source code is thus structured as follows

    • [source:lib/trunk/src/] All source files of the BAMPS library
    • [source:full/trunk/] The full (i.e. heavy ion collisions) version of BAMPS that depends on the library
    • [source:box/trunk/] The box (i.e. static) version of BAMPS that depends on the library

Now, when building either full or box from source there are two slightly different ways of integrating the library into the build:

      1. [#InPlaceBuildOfLibrary Compile and build the library files every time the main program is build (this is the default).]
2. [#ExternalLinkingOfLibrary Separately build the library, install it somewhere on the system and subsequently link build processes of the main program(s) to the installed library.]

Which of the two options is chosen clearly depends on the use case. In the development process the first alternative (the default) might be more appropriate as it guarantees that the latest version of the library files is used. Whereas the second alternative might be more appropriate in an environment where the core routines of BAMPS remain unchanged but different variants of the main programs need to make use of these core routines, e.g. on the CSC cluster.

==== Building the library together with the main program ==== #InPlaceBuildOfLibrary

As this is the default for the current trunk versions [source:full/trunk/ full] and [source:box/trunk/ box], nothing special needs to be done. A simple CMake configuration of the build directory followed by make as described [#HowToBuild above] is sufficient.

For the more curious, here's how it works:BR

For convenience the library directory is symbolically linked into the main directories of full and box as lib/, i.e. is on the same level as src/. The location of library source is controlled by the CMake variable BAMPS_LIBRARY_PATH, which can be set at configuration time via the -D option


  ~$ cmake -DBAMPS_LIBRARY_PATH=/path/to/BAMPS/lib/source ../

(assuming the build is done in a directory one level below the main directory as described [#HowToBuild above]). The library path specified on the command line takes precedence over the default value (which is ${CMAKE_SOURCE_DIR}/lib/) and thus allows to point the build to a BAMPS library source located in some arbitrary place.

==== Building the library separately and linking to it ==== #ExternalLinkingOfLibrary
Building and installing

Alternatively the library can be separately build using the very same CMake build system as all other parts of BAMPS. Simply go to [source:lib/trunk/], create a build directory, change into this directory and issue cmake ../ followed by make (or follow the [#HowToBuild instructions] for more sophisticated options). Instead of creating an executable however, this yields a static library called libbamps.a. The main BAMPS programs can now be linked against this static library, provided that the location of the library header files is given as an include directory.

To ease this configuration, the BAMPS library can be automatically installed simply by


  make install

By default this tries to install the library files into the system's standard locations (e.g. /usr/ or /usr/local/). As this would require root privileges, it is advisable to have a home directory-based usr-tree, i.e. to create a directory ~/usr in which all custom build libraries - for example the BAMPS library - are installed.

On a side note: /usr/ (or /usr/local/ or $HOME/usr/ or...) is called the installation prefix, the actual files are usually installed into subdirectories of this prefix. For example static libraries (e.g. libbamps.a) go into a "lib/" subfolder, the header files go into an "include/" subfolder and binary files (executables) go into "bin/".

The installation prefix is controlled by the CMake variable CMAKE_INSTALL_PREFIX. Thus building the BAMPS library and installing it into a home directory-based usr-tree amounts to (again assuming a build directory lib/trunk/build/):


  cmake -DCMAKE_INSTALL_PREFIX=$HOME/usr ../
  make
  make install

Linking against the BAMPS library

As described [#InPlaceBuildOfLibrary above] the default behavior of the main BAMPS programs is to always build the library. In case linking against a previously build library (i.e. libbamps.a plus header files) is desired, this behavior can be overridden by setting the CMake variable LINK_TO_BAMPS_LIB to TRUE:


  cmake -DLINK_TO_BAMPS_LIB=TRUE ../

CMake then tries to automatically find the installed version of the BAMPS library by virtue of the custom CMake module [source:full/trunk/cmake_modules/FindBAMPS.cmake FindBAMPS.cmake]. The module is able to detect and configure BAMPS library installed in the default system locations as well as in a home directory-based ~/usr/ location. If the library has been installed elsewhere, specify the location via the CMAKE_PREFIX_PATH variable, e.g. as


  cmake -DCMAKE_PREFIX_PATH=$HOME/usr/local -DLINK_TO_BAMPS_LIB=TRUE ../

No further configuration should be necessary.