BuildingOpenMalaria

OpenMalaria uses the CMake build system. Windows builds currently rely on Cygwin.

Install the required dependencies:

# Ubuntu:
apt-get install build-essential git cmake libgsl-dev libxerces-c-dev xsdcxx

# Mac OS:
brew install git coreutils cmake gcc gsl xerces-c xsd

# Windows (Cygwin): 
apt-get install p7zip gcc-g++ git cmake make zlib-devel libgsl-devel xsd libxerces-c-devel

The easiest way to build OpenMalaria is to use the provided build.sh script. To build OpenMalaria from the source, run the tests and create the release archive, first either clone the git repository:

git clone https://github.com/OpenMalaria-Org/openmalaria.git

or download the code: https://github.com/OpenMalaria-Org/openmalaria/archive/refs/heads/main.zip

Then inside the folder that you have downloaded, run:

./build.sh -t -r

This will create the release archive.

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_BINARY

Enable testing using the binary output format of OpenMalaria instead of the standard txt format (see below to enable tests).

• OM_BOXTEST_ENABLE

Enables 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.

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

Note that newer versions of OpenMalaria don't rely on Boost anymore.

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