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. 3 shows the source files directory and the build directory set for user andre.
Fig. 3 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. 4 that this has happened for user andre.
Fig. 4 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. 5 shows the LibXml2_DIR variable with the value of LibXml2_DIR-NOTFOUND.
Fig. 5 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. 6 shows a successfully configured LibXml2_DIR variable) from which build files may be generated using the Generate button.
Fig. 6 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