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.