User build guide

Using SCons

We use ​SCons to control the build process. The source:trunk/SConstruct file configures what needs to be built, and is worth a look if this document leaves unanswered questions. The file source:trunk/python/SConsTools.py also contains much of the build logic.

scons can be used to run a single test, or multiple tests, in debug or optimised mode, and with number of other options. This page lists the scons commands that users should be aware of. In order to run scons, open a terminal, cd into the main chaste directory, and run one of the following commands. Or better, create a 'Make target' in eclipse using that given command.

This runs all the tests 

scons

To run a single test, say heart/test/bidomain/TestBidomainProblem.hpp, do 

scons test_suite=heart/test/bidomain/TestBidomainProblem.hpp

The path is relative to the main chaste directory. The test_suite= is optional (see examples below).

You can also run tests on multiple processors. To do this, use a build type featuring an underscore followed by the number of processes, e.g. for running on 2 cores: 

scons build=_2 heart/test/bidomain/TestBidomainProblem.hpp

You can also call scons with the directory to run all of the tests within: 

scons          # runs all the tests - will take a while
scons global   # just runs the tests in the global folder
scons io       # just runs the tests in the io folder
scons linalg   # just runs the tests in the linalg (linear algebra) folder
scons mesh     # just runs the tests in the mesh folder
scons ode      # just runs the tests in the ode folder
scons pde      # just runs the tests in the pde folder
scons heart    # just runs the tests in the heart folder
scons cell_based crypt   # just runs the tests in the cell_based and crypt folders

By default (for developer builds; releases have this turned on by default) the build does not create library files for the Chaste code, but directly links the object files required by each test. To use libraries, which will reduce the compilation time if you are not making frequent changes to core Chaste code, use the chaste_libs=1 (cl=1) option, e.g. 

scons chaste_libs=1 ...

This is particularly suited to running whole test packs.

Optimised builds

The above all compile with debug flags. If the time it takes to run your code is significantly longer than the time it takes to build then you should probably use an optimised build. To compile optimised code you have to provide a build option, for example 

scons build=GccOpt heart/test/bidomain/TestBidomainProblem.hpp          # optimised build
scons build=GccOptNative heart/test/bidomain/TestBidomainProblem.hpp    # optimised build for the machine you are compiling on
scons build=GccOpt_ndebug heart/test/bidomain/TestBidomainProblem.hpp   # highly optimised with NDEBUG defined, recommended for longer-running simulations
scons build=GccOptNative_ndebug heart/test/bidomain/TestBidomainProblem.hpp   # highly optimised for that machine with NDEBUG defined, recommended for longer-running simulations
scons build=IntelProduction heart/test/bidomain/TestBidomainProblem.hpp # (see below)

Building with IntelProduction requires an Intel compiler and extra libraries (see InstallGuides/IntelCompiler). This provides the fastest code but the compilation time can be very long.

Other options

Other options that are worth knowing

  • compile_only=1 - just compile test executables without running them. This is useful for fixing build failures.
  • build=_warn - stop compiler warnings being treated as errors.
  • scons -c . - do a clean build (note the '.' - this is necessary to do a full clean).

The following abbreviations can be used,

  • b= instead of build=
  • ts= instead of test_suite= (or omit the test_suite= entirely, e.g. "scons global/test/TestCwd.hpp")
  • co=1 instead of compile_only=1
  • cl=1 instead of chaste_libs=1

for example: 

scons co=1 b=GccOpt_ndebug ts=heart/test/bidomain/TestBidomainProblem.hpp

See ChasteGuides/DeveloperBuildGuide for a complete list of options.

Viewing test results

If the tests compile and run, to check the results, open a web browser and go to the following (local) page: 

file:///<CHASTE_CODE_DIRECTORY>/test_summary/<NAME_OF_YOUR_COMPUTER>.default/index.html

The exact path will be printed at the end of the build. Note that this is just a file within the Chaste directory.