Cmake Build Guide

This wiki page details all the available options for cmake builds.

  1. Cmake Build Guide
    1. General CMake Concepts
    2. File Layout
    3. Workflow
  2. Configure Step
    1. Chaste Configuration Options
  3. Build Step
    1. Building Specific Targets
      1. Components
      2. Test packs
      3. Intersecting components and test packs
      4. Component library without tests
      5. Specific tests
      6. Other Useful Targets
        1. Doxygen
        2. Coverage
        3. Doxygen Coverage
        4. Memory Testing
        5. Profiling
        6. Tutorials
    2. Windows
  4. Install Step
  5. Packaging your build with CPack
  6. Testing Step
  7. Building Projects
    1. Using Chaste like a standard library

General CMake Concepts

File Layout

The main CMake file is CMakeLists.txt. All the cmake macros and finder scripts (apart from those in the main CMake distribution) are in /cmake/. Most of these are kept in /cmake/Modules, and there is a base CMake Configure script for Chaste in /cmake/Config/. The remainder in /cmake/ are left over from the old CMake setup for windows (some are still in use).

Workflow

If you aren't familiar with this, perhaps start with ChasteGuides/CmakeFirstRun, and come back here for more detailed instructions...

CMake is a build system generator, so splits up the compilation process into two steps:

  1. Configure
  2. Build (or 'make')

In the first you call cmake to configure your project. During this step you can specify a Generator. By default this is a Makefile generator, so the configure step will output a bunch of Makefiles, with which you can build you project. Other Generators include one for Microsoft Visual C++, which outputs MSVC project files during the configure step.

It is standard for CMake to build your project in a separate (empty) directory to your source tree (usually this can still be in a subdirectory within the source tree, but the Chaste CMake system will prevent you from doing in-source builds to avoid making a mess of the git repository).

The standard way (for Makefile generators) to compile the Chaste project using CMake is to make a build directory, call cmake on the root of the source tree and then use make to compile. For example, 

mkdir /path/to/build/dir
cd /path/to/build/dir
cmake /path/to/source/dir
make

This will compile the Chaste libraries and all the tests. To run the tests you can either call make on the test target 

make test

Or use ctest, which is part of CMake 

ctest

Look under the Testing Step heading below for more information

Note: CMake, cmake, ccmake and ctest are general build managers, that have many more options than we have detailed in this document. For much more detailed documentation on these tools, please consult the CMake documentation here: ​https://cmake.org/documentation/

Configure Step

Run the ​CMake configuration step using 

cmake /path/to/source

This should work on (at least) Ubuntu with all required dependencies installed. Note that the ccmake graphical user interface provides a nice way to see what options are available.

If you have any problems with dependencies not being found, or if you wish to select one specific dependency when you have multiple versions installed, more information can be found on the ChasteGuides/FindingChasteDependencies page.

Chaste Configuration Options

These options can be set in the ccmake gui, or specified on the command line using -DOPTION=$option. eg. 

cmake -DChaste_NUM_CPUS_TEST=2 /path/to/source
Variable Description
BUILD_SHARED_LIBS Standard CMake option (used by Chaste) that indicates whether to build static or shared libraries (defaults to OFF for WIN32 and CYGWIN, ON for everything else). Only the defaults currently work.
CMAKE_BUILD_TYPE Choose the type of build : None Debug Release RelWithDebInfo or MinSizeRel. Used for single build configuration generators (e.g. Makefiles). Not used for multi build configuration generators (e.g. MSVC)
CMAKE_INSTALL_PREFIX Typing make install will install Chaste to this base directory
Chaste_COVERAGE Build Chaste with coverage information
Chaste_ENABLE_TESTING Enable building of tests (defaults to ON)
Chaste_ENABLE_<component>_TESTING Enable building of tests for <component> (defaults to ON)
Chaste_INSTALL_TESTS Install source files for tests along with header files and built libraries
Chaste_MEMORY_TESTING Setup tests so they are run under valgrind
Chaste_NUM_CPUS_TEST Number of cpus to use when running tests (using mpiexec). Defaults to 1 (note that parallel tests are always run with 2 or more cpus)
Chaste_PROFILE_GPERFTOOLS Setup compile options and run all tests with Google CPU profiler (gperftools)
Chaste_PROFILE_GPROF Setup compile options and run all tests with GNU gprof profiler
Chaste_UPDATE_PROVENANCE Updates the build timestamp in the provenance (defaults to ON). Note that this will cause re-linking to the global library on every build.
Chaste_USE_CVODE Compiles Chaste with Sundials support (defaults to ON)
Chaste_USE_PETSC_HDF5 Prefer to compile Chaste with HDF5 library used by PETSc (defaults to ON)
Chaste_USE_PETSC_PARMETIS Prefer to compile Chaste with Parmetis library used by PETSc (defaults to ON)
Chaste_USE_VTK Compiles Chaste with VTK support (defaults to ON)
Chaste_USE_XERCES Compiles Chaste with Xerces and XSD support (defaults to OFF for WIN32 or CYGWIN, ON for everything else)
Chaste_VERBOSE Provide extra info when building Chaste (default OFF). Only useful for windows, sets up verbose compilation for MSVC compiler. For Makefile generators (default on linux and mac) use make VERBOSE=1
Chaste_VERSION_MAJOR Set Chaste major version (defaults to 3)
Chaste_VERSION_MINOR Set Chaste minor version (defaults to 4)
Chaste_PYCML_EXTRA_ARGS Add any extra arguments for PyCML here (need to set this *before* cellml files are converted to source)

Build Step

For Makefile generators (this is the default) the configure step will generate a bunch of Makefiles, so you just need to run 

make -jN

for N cores.

Building Specific Targets

Components

The configure step generates a number of targets which can be built. These targets can be libraries or executables (i.e. test executables). Each component (i.e. global, pde, heart etc) is compiled into a library, with a target name given by the name of the component (so the target name for global is global)

You can specify building a specific component library and all its tests by giving make the name of the component target. For example: 

make global   # builds the global library and all dependencies
make io       # builds the io library and all dependencies
make linalg   # builds the linalg (linear algebra) library and all dependencies
make mesh     # builds the mesh library and all dependencies
make ode      # builds the ode library and all dependencies
make pde      # builds the pde library and all dependencies
make heart    # builds the heart library and all dependencies
make cell_based crypt   # builds the cell_based and crypt libraries and all their dependencies
make core     # builds all the core Chaste libraries (global, io, linalg, mesh, ode, pde and continuum_mechanics)

Test packs

If you wish to build a specific test pack then just type make and then the name of the test pack, for example: 

make Continuous  # builds the Continuous test pack
make Nightly     # builds the Nightly test pack
make Weekly      # builds the Weekly test pack
make Parallel    # builds the Parallel test pack

And then run using, for example 

ctest -L Continuous

or 

ctest -L Continuous -j4

to run up to 4 tests in parallel (see below).

Intersecting components and test packs

If you want to run a test pack for just a specific component, for instance Continuous tests from cell_based, or Nightly tests from heart, you can invoke ctest with <Testpack>_<component>, for instance 

make cell_based
ctest -L Continuous_cell_based

or 

make heart
ctest -L Nightly_heart

Component library without tests

If you wish to build only the library (without tests) then you can type 

make chaste_${component}

where ${component} is the name of the component you wish to build.

Specific tests

You can build a specific test by using the target name for the test executable. The target name for a given test file TestName.hpp is given by $TestName. So for test file heart/test/mechanics/TestCardiacElectroMechanicsOnAnnulus.hpp the command will be 

make TestCardiacElectroMechanicsOnAnnulus

This will build an executable heart/test/TestCardiacElectroMechanicsOnAnnulus, which you can run directly or use ctest to call the test 

ctest -R TestCardiacElectroMechanicsOnAnnulus

Other Useful Targets

Doxygen

Type make doxygen to generate Doxygen documentation for the current code tree. The Doxygen documentation will be put in the doxygen sub-folder of the build folder

Coverage

Set the CMake variable Chaste_COVERAGE to ON and then re-configure Chaste. Once this is complete type make coverage. This will re-build the Continuous and Parallel test packs with coverage information, and then run these tests to collect their coverage. Once this is complete it uses Lcov to generate a html report on the coverage, placing it in the coverage sub-folder of the build directory.

Doxygen Coverage

Type make doxygen_coverage to generate a html report of the current Doxygen coverage. This report is placed in the doxygen_coverage subfolder.

Memory Testing

Set the CMake variable Chaste_MEMORY_TESTING to ON and then re-configure Chaste. Once this is complete type make memtest. This will run the Continuous test pack under valgrind and then generate a html report in the memtest sub-folder.

To run memory testing on a single test suite, set the CMake variable Chaste_MEMORY_TESTING to ON and then re-configure Chaste, then build and run the test as normal. This will generate a plain text valgrind .out file for any test suites run, in the memtest subdirectory of the build directory.

For example, if you wish to run a memory test on the test TestOdeBasedCellCycleModels, first set your build folder to compile with memory testing, and compile the test 

cmake -DChaste_MEMORY_TESTING=ON .
make TestOdeBasedCellCycleModels

Then run the test. After the test completes the valgrind output will will be in memtest/TestOdeBasedCellCycleModels.valgrind.out 

ctest -R TestOdeBasedCellCycleModels

Profiling

The CMake setup support two methods of profiling, using GNU gprof and gperftools (Google CPU profiler). To enable the former, set the CMake variable Chaste_PROFILE_GPROF to ON. To enable the latter, set Chaste_PROFILE_GPERFTOOLS to ON. To run the profiling, type make profile. This will run the Profile and ProfileAssembly? test packs using the chosen profiling tool and then generate a html report in the profile sub-folder.

Tutorials

To generate the markdown files from the tutorial source files, type make tutorials. This will create tutorials/UserTutorials and tutorials/PaperTutorials, generate the markdown files from the tutorial source files and put them in these directories.

Windows

Windows uses the MSVC project file generator, so you can't use make. Instead, you can use the CMake interface to run the build 

cmake --build . --config Debug

Note that the windows build currently only works for the Debug configuration

To build a particular target you can use the --target options. eg. 

cmake --build . --config Debug --target heart

Install Step

You can install the Chaste libraries to the CMAKE_INSTALL_PREFIX directory using 

make install

Note that this step isn't necessary, you can just use the build folder.

Packaging your build with CPack

Once you have built Chaste, you can package up your build using the cpack executable. Cpack uses a set of generators to package your build:

DEB = Debian packages
NSIS = Null Soft Installer
NSIS64 = Null Soft Installer (64-bit)
RPM = RPM packages
STGZ = Self extracting Tar GZip compression
TBZ2 = Tar BZip2 compression
TGZ = Tar GZip compression
TZ = Tar Compress compression
ZIP = ZIP file format

To use, type cpack -G <generator> to use the specified generator to generate the package. Naturally you must have the correct dependencies installed to use each generator (e.g. Normally only Debian or Ubuntu systems will be able to use the DEB generator).

Testing Step

You can run all tests using 

ctest

or 

ctest -j10

to spread the tests over 10 cpus. Note that by default, each test only uses 1 cpu (except those with target names ending in Parallel, see below). You can change this behaviour but using the Chaste_NUM_CPUS_TEST cmake variable. Set this variable to the number of cpus uses by each test. For example, if you wish to still run 10 tests in parallel using the -j10 flag, as above, but you now set Chaste_NUM_CPUS_TEST=2, then cmake -j10 will use a total of 10*2=20 cpus.

To run the continuous test pack you can use 

ctest -L Continuous

The -L option takes a regex expression and matches against the labels for each test. Each tests has multiple lables like Continuous Nightly, Parallel, 'heart', 'lung' etc. corresponding to the tests packs and components the test belongs to. So you could run all the global tests using 

ctest -L global

To run a specific test you can use the -R option 

ctest -R TestCardiacElectroMechanicsOnAnnulus

The -R option takes a regex expression and matches against the CMake target name. Similarly, you can use the -E option to exclude a term. You also can use ^ to match the start of the string, and $ to match the end, e.g. 

ctest -R ^TestCardiacSimulation$

You can add Parallel to the end of the target name to run the parallel version of that test (if the test is in the parallel test pack).

The -V option prints the output of tests to the terminal, so to run a particular test and see the output, you can do e.g. 

ctest -V -R TestVoronoiVertexMeshGenerator

Building Projects

You can build projects as for the Scons setup, by adding a subdirectory to the projects/ folder and then adding a projects/myproject/CMakeLists.txt file with something like 

find_package(Chaste COMPONENTS ${components})
chaste_do_project(myproject)

where ${components} is a list of components your project depends on. You can use core to indicate all the core Chaste libraries, or leave off the COMPONENTS list entirely (the default is core). The build system then assumes you are using the standard Chaste layout for a project and builds your project accordingly

If you have a test subdirectory you want built, you again need to add a projects/myproject/test/CMakeLists.txt file containing something like 

chaste_do_test_project(myproject)

And if you have an apps subdirectory then you need to add a projects/myproject/apps/CMakeLists.txt file containing 

chaste_do_apps_project(myproject)

Assuming you are following the standard Chaste layout for your project, then the CMake configure step will find all your library files, tests and applications and setup build targets for them. These will be added to the default build target so they will be built along with all the other Chaste components (or you can build them individually).

You can also build projects outside the Chaste directory tree. This is useful if you are not editing the Chaste source code as part of your project and are just using Chaste as a library. Separating your project from the Chaste build tree results in a significantly faster configuration and build steps. Assuming you have already built Chaste and (optionally) installed it in a given directory, then simply add a CMakeLists.txt file in the root folder of your project as explained above, along with corresponding CMakeLists.txt files in the test and apps sub-folders. Note that if you have built (or installed) Chaste in more than one location on your computer, you might want to specify the particular build folder you wish to use. This can be done in the root CMakeLists.txt file like so: 

find_package(Chaste COMPONENTS ${components} PATHS path/to/build_folder NO_DEFAULT_PATH)
chaste_do_project(myproject)

Using Chaste like a standard library

You can also use Chaste like a standard system library. The CMake configure step will have registered Chaste on your system, so the find_package function should work from any location (if not, you can specify a path, see below). It provides the following variables once you run it

  • Chaste_LIBRARIES: This variable contains the Chaste libraries you need to link against (for the components you specified in the find_package function)
  • Chaste_INCLUDE_DIRS: This variable contains the Chaste include folders you need to include
  • Chaste_THIRD_PARTY_INCLUDE_DIRS: This variable contains the third-party include folders you need to include
  • Chaste_THIRD_PARTY_LIBRARIES: This variable contains the third-party libraries used to build Chaste (Note that unless you are using Chaste_LINK_LIBRARIES_WITH_UNRESOLVED_SYMBOLS=ON you won't need these)

So an example CMakeLists.txt script would go 

find_package(Chaste COMPONENTS ${components})
include_directories(${Chaste_INCLUDE_DIRS} ${Chaste_THIRD_PARTY_INCLUDE_DIRS})
add_executable(my_library \my\source\file.cpp)
target_link_libraries(my_library ${Chaste_LIBRARIES})

Note that if you have configured Chaste from more than one build folder, problems occur because you don't know which one CMake will give you. You can give a specific build directory to CMake by using the NO_DEFAULT_PATH option for find_package and the PATHS option to specify a path. e.g. 

find_package(Chaste COMPONENTS ${components} PATHS ${path} NO_DEFAULT_PATH)