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)

General CMake Concepts

CMake is a build system generator, so splits up the build process into two steps. 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 (This can still be in a subdirectory within the source tree). The Chaste CMake system will prevent you from doing in-source builds (i.e. from trying to build using the root directory of the source tree).

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

Configure Step

Run the CMake configuration step using

cmake /path/to/source

This should work on (at least) Ubuntu with all required dependencies installed

Windows

For windows (on scratch at least) you need to specify a generator (using -G) and the location of the third party libraries (using -DCHASTE_DEPS_ROOT_DIR=). So on scratch the command is

cmake -DCHASTE_DEPS_ROOT_DIR=D:\chaste_windows\build\install\third_party_libs -DChaste_USE_PETSC_HDF5=OFF -DHAVE_PARMETIS=ON -GVisual Studio 10 Win64 \path\to\source

Note you need the -DChaste_USE_PETSC_HDF5=OFF because I'm using "Petsc for Windows" for Petsc, which doesn't include hdf5 libraries.

You need -DHAVE_PARMETIS=ON to skip the step which checks that Parmetis is working, it works for the main Chaste build, so not to worry (for now).

Specifying a Compiler

You can specify a C++ compiler by setting the CXX environment variable. eg.

CXX=icpc cmake /path/to/source

Specifying PETSc

You can specify a PETSc folder and Arch by setting the PETSC_DIR and PETSC_ARCH environment variables. eg.

PETSC_DIR=/path/to/petsc PETSC_ARCH=linux-intel cmake /path/to/source

Specifying Sundials

You can specify a Sundials folder by setting the SUNDIALS_ROOT environment variables.

Specifying HDF5

You can specify a HDF5 folder by setting the HDF5_ROOT environment variables.

Specifying VTK

You can specify a VTK directory by using the VTK_DIR CMake variable (note: NOT an environment variable). eg.

cmake -DVTK_DIR=/path/to/vtk /path/to/source

Specifying Boost

You can specify a Boost directory by using the BOOST_ROOT CMake variable (note: NOT an environment variable)

Notes for CHASTE_DEPS_ROOT_DIR

(Windows only) Note that using this CMake option overwrites any specified library locations

Chaste Configuration Options

See below for a complete list of the configuration options

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

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

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 subdir/next_subdir/testname.hpp (where subdir is the first subdirectory after the component directory, is given by $testname_$subdir_$next_subdir_Runner. So for test file heart/test/mechanics/TestCardiacElectroMechanicsOnAnnulus.hpp the command will be

make TestCardiacElectroMechanicsOnAnnulus_mechanics_Runner

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

ctest -R TestCardiacElectroMechanicsOnAnnulus_mechanics_

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.

Testing Step

You can run all tests using

ctest

or

ctest -j10

to spread the tests over 10 cpus. Note that each individual test still only uses Chaste_NUM_CPUS_TEST cpus (except those with target names ending in Parallel, see below).

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_mechanics_

The -R options takes a regex expression and matches against the CMake target name. This uses a similar format as that used to make a particular test (see above), but without the Runner at the end. 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).

CMake Configuration Options

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

cmake -DChaste_NUM_CPUS_TEST=2 /path/to/source

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_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_USE_VTK

Compiles Chaste with VTK support (defaults to ON)

Chaste_USE_CVODE

Compiles Chaste with Sundials 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_USE_PETSC_PARMETIS

Prefer to compile Chaste with Parmetis library used by PETSc (defaults to ON)

Chaste_USE_PETSC_HDF5

Prefer to compile Chaste with HDF5 library used by PETSc (defaults to ON)

Chaste_LINK_LIBRARIES_WITH_UNRESOLVED_SYMBOLS

By default all component libraries are built as shared libraries with fully resolved symbols, so you should just be able to link to them without worrying about dependencies. This changes this behaviour and builds them as shared libraries, not resolving any symbols. So if you want to use them you need to link in all dependencies manually.

Note. This must be setup to ON to link against the PETSc library compiled in the bob user account (and perhaps all the lofty ones, I havn't tested this), as otherwise you will get conflicts between the HDF5 brought in by PETSc and the HDF5 brought in by VTK)

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.

RUN_TESTS

Deprecated option used for current windows testing. This runs the tests during the configuration step.

CHASTE_AUTO_INSTALL_DEPS

Deprecated option used for windows. Used to build and install the third-party libraries.

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.

ENABLE_CHASTE_TESTING

Enable building of tests (defaults to ON)

ENABLE_CHASTE_PROJECT_TESTING

Enable building of project tests (defaults to ON)

CHASTE_DEPS_ROOT_DIR

Setup up location of third-party libraries (only used in Windows)

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

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)