Compilation Guide

This page is a guide to compiling OpenMalaria steb by step, using cmake. This is the recommended approach for contributors.

Clone the git repository

First make sure you have installed the required dependencies, as explained in the User Guide.

The first step is to clone OpenMalaria:

cd WORKSPACE
git clone https://github.com/SwissTPH/openmalaria.git
cd openmalaria

Select the version (or tag)

By default, this will check out the "main" branch, which tracks the latest release. To use something else,

git checkout develop   # the development version — this might not be ready for use!
git tag --list   # show tags
git checkout schema-34.0   # use release 34
git branch -a    # show branches
git checkout main   # go back to the latest stable version

Building

To keep the generated files out of the way of the source code, its best to create a separate build directory under the source code directory:

mkdir build
cd build

The build directory (WORKSPACE/openmalaria/build/) will initially be empty. cmake is a makefile generator. It reads the configuration file CMakeLists.txt and can take additional parameter on the command line to configure the makefiles that will be used to compile and link the source code and libraries. Configuration is a two step process.

First run the configuration program to create the makefiles. Run cmake, passing the path of the OpenMalaria directory you checked out. Assuming you are in the build directory, run:

cmake .. -DCMAKE_BUILD_TYPE=RELEASE

-DCMAKE_BUILD_TYPE=RELEASE will enable optimizations flags to get better performance. You should always set it unless you are debugging the code.

Then, compile OpenMalaria:

# from WORKSPACE/openmalaria/build ...
make -j4    # build on 4 CPU cores
ctest -j4   # run the tests, in parallel (tests are generated by default)

Generate the release artifact

To create the OpenMalaria folder with all the files needed to run a scenario, you can now go back to the User Guide. In the OpenMalaria directory (not the build directory), run:

./build.sh -r

Because you have already completed the compilation, build.sh will skip it and create the OpenMalaria-X.Y folder, where X and Y are major and minor version number, respectively.

Use a different Boost version (REQUIRED FOR OpenMalaria < 42)

If your system ships Boost version > 1.61, there is a bug in OpenMalaria version < 42 that will cause an inifinite loop. You need to download Boost 1.61 and pass the right parameters to OpenMalaria.

First, Download Boost 1.61 from https://sourceforge.net/projects/boost/files/boost/1.61.0/boost_1_61_0.zip

Once the download is complete, unzip the files and note the path to the directory, e.g. in my case it is:

/home/acavelan/Downloads/boost_1_61_0

Open a terminal, and go to the OpenMalaria build directory. make sure the build directory is empty, be very careful when deleting files!!

cd WORKSPACE/openmalaria/build/ && rm -rf * # will only rm files if cd is successful

Export the path to the Boost directory you have previously extracted (make sure the path is correct)

export MYBOOST=/home/username/path/to/boost/boost_1_61_0

Finally, run cmake again, specifying the right Boost directory and version:

cmake -DCMAKE_INSTALL_PREFIX=$MYBOOST -DBoost_NO_BOOST_CMAKE=TRUE -DBoost_NO_SYSTEM_PATHS=TRUE -DBOOST_ROOT:PATHNAME=$MYBOOST     -DBoost_LIBRARY_DIRS:FILEPATH=${MYBOOST}/lib -DCMAKE_BUILD_TYPE=Release ..

If the command is successful, you should see in the output of cmake, something similar to:

...
-- Found Boost: /home/acavelan/Downloads/boost_1_61_0 (found suitable version "1.61.0", minimum required is "1.54.0")
...

You can now proceed to the compilation step:

make -j4
ctest -j4

General configuration settings

• CMAKE_BUILD_TYPE

Options: * None (CMAKE_CXX_FLAGS or CMAKE_C_FLAGS used) * Debug (compile in debugging symbols) * Release (compile with optimizations) * RelWithDebInfo (both optimize and compile in debugging symbols; but if debugging note that code may not execute in the order expected due to optimizations)

• OM_BOXTEST_ENABLE

Enables what I refer to as OpenMalaria's "black-box" tests in ctest: full scenarios which are run and who's output is checked. These are the primary tests that everything is working, though when they fail it is not always clear why. Can be run with and without checkpointing to also test the checkpointing system (ctest normally runs them with checkpointing). Sometimes during development these get broken, so if they fail it is not necessarily your build that is at fault.

• OM_CXXTEST_ENABLE

Enables OpenMalaria's (few) unit tests. These should test individual components of OpenMalaria, however not that many have been written.

• OM_STREAM_VALIDATOR

Tool to aid analysis of why a black-box test is failing. See note in model/util/StreamValidator.h for usage.

• OM_STATICALLY_LINK (GCC), OM_USE_LIBCMT (MSVC)

Options to control/reduce the run-time dependencies needed by the resultant binary. May be useful when compiling a binary which will be distributed to other computers (deprecated)

Further configuration settings, needed less often

• XXX_LIB, YYY_INCLUDE_DIR

Path to library XXX, include file directory for YYY. On windows it is sometimes necessary to set these paths manually, on linux they are usually found automatically when the needed packages are installed.

• OM_CXXTEST_USE_PYTHON

Use Python instead of Perl to generate the unit tests. Either can be used, and this option should be automatically selected.

• PYTHON_EXECUTABLE / PERL_EXECUTABLE

Path to either the perl or the python program, needed to run the unit tests (see OM_CXXTEST_ENABLE). May need to be set manually in windows (usually Python since this is also needed by the black-box tests).

• CMAKE_CXX_FLAGS

Can be used if extra build flags need to be added.

• CMAKE_VERBOSE_MAKEFILE

To try to solve build/link errors it is sometimes useful to know the full options sent to the compiler/linker. This option enables this, at the cost of a very verbose build log.

This will let you tweak a few things if need be. Normally you don't need to change anything except CMAKE_BUILD_TYPE unless dependencies are not installed in standard locations in which case you may need to change those. Additionally:

You can re-run cmake if necessary or proceed to compiling.