Building libCellML

This document covers building libCellML from source. It is assumed that you already have the codebase downloaded and ready for building. The variable LIBCELLML_SRC shall be used to refer to the directory containing the LICENSE file for libCellML.

Build Directory

It is best to build libCellML outside of the source tree. To this end, create a build directory that is not the LIBCELLML_SRC directory. A sibling directory of LIBCELLML_SRC is a good choice, named something like build or libcellml-build. The variable LIBCELLML_BUILD shall be used to refer to the build directory.

Configuration

The libCellML library uses the CMake build configuration tool to configure the library. Version 3.2 or greater of CMake is required to configure libCellML.

The configuration options for the library are detailed in the following table. The command line options can be set with the -D flag, like so -DBUILD_TYPE=Release. Please note that in CMake GUI Configuration applications, the config variable is prefixed with LIBCELLML_

Options

Config Default Description
BUILD_TYPE Release The type of build Release, Debug etc.
BUILD_SHARED ON Build shared libraries (so, dylib, DLLs).
TWAE * ON Treat warnings as errors.
INSTALL_PREFIX /usr/lib Install path prefix (platform specific).
UNIT_TESTS ON Enable tests.
MEMCHECK ON Enable memcheck testing (if available).
COVERAGE ON Enable coverage testing (if available).

* In CMake GUI Configuration applications this option is given in full LIBCELLML_TREAT_WARNINGS_AS_ERRORS

From the command line (bash shell), libCellML can be configured to create an optimised shared object library like so:

cd $LIBCELLML_BUILD
cmake -DBUILD_TYPE=Release $LIBCELLML_SRC

Windows

When configuring libCellML on Windows, we may need to set the location of the LibXml2 library, which is dependent on the computer’s environment settings. We can set the location of the LibXml2 library when we configure libCellML. When we configure libCellML, the location of LibXml2 can be specified through the command line by adding the parameter:

-DLibXml2_DIR="C:\Program Files\libxml2 2.9.6\lib\cmake"

to the configuration command. This assumes that the recommended LibXml2 binaries have been installed to the default location C:\Program Files\libxml2 2.9.6. Please note that this method will only work with the recommended LibXml2 binaries, LibXml2 binaries from other sources will not work in this way.

Windows CMake-GUI

When we use the CMake-GUI application on Windows, we first set the location of the source files and the location for the generated build files. fig_devBuilding_windowsCMakeGUISourceBuildDirs shows the source files directory and the build directory set for user andre.

CMake-GUI with initial values for source and build directories set.

CMake-GUI with source and build directores set for user andre.

When we press the Configure button, CMake performs an initial configuration. This initial configuration is likely to encounter an error because CMake is not able to find LibXml2. We can see in fig_devBuilding_windowsCMakeConfigurationError that this has happened for user andre.

CMake-GUI on Windows showing configuration error after initial configuration attempt.

CMake-GUI showing configuration error after initial configuration attempt.

We can resolve this error easily if we set the value of the LibXml2_DIR variable to the location of the LibXml2 cmake directory. fig_devBuilding_windowsCMakeLibXml2DIRNotFound shows the LibXml2_DIR variable with the value of LibXml2_DIR-NOTFOUND.

LibXml2_DIR variable with a value of LibXml2_DIR-NOTFOUND.

LibXml2_DIR variable with a value of LibXml2_DIR-NOTFOUND.

Setting the value of LibXml2_DIR to C:\Program Files\libxml2 2.9.6\lib\cmake and configuring again will result in a successful configuration (fig_devBuilding_windowsCMakeLibXml2DirSet shows a successfully configured LibXml2_DIR variable) from which build files may be generated using the Generate button.

LibXml2_DIR variable with a value of C:\Program Files\libxml2 2.9.6\lib\cmake.

LibXml2_DIR variable with a value of C:\Program Files\libxml2 2.9.6\lib\cmake.

If LibXml2 was not installed to C:\Program Files\libxml2 2.9.6, you will need to adjust the path to match your situation.

Build

Once the build scripts have been generated by CMake, invoke the build with the appropriate command. For Makefile-based configurations, the command is simply:

make

If testing is enabled, run the tests using the test target:

make test

or using the ctest application:

ctest

For a more verbose output, run:

ctest -V