Developer Build Guide

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.

To start a build, simply run scons from within the trunk directory; this will build all Chaste components and run their continuous tests (NB: it does not build user projects). "scons -c ." will do a clean build (note the '.' - this is necessary to do a full clean).

Other build targets can be selected, rather than just running the default.

  • scons <component> build and tests the specified component.
  • scons projects/<project_name> build and tests the specified user project.
  • scons core will build and test the core components. As of the time of writing this means global, io, linalg, mesh, ode and pde.
  • scons . will build all the Chaste components and currently checked out user projects.
  • scons build=<whatever> chaste_libs=1 exe=1 apps will build any executables contained in the apps folder.

Various options can be passed to customise the build. Some also have short forms, shown in brackets.

  • Common options:
    • build=<x> (b=<x>) sets what type of build to perform; see 'Build Classes' below.
    • test_suite=<path> (ts=<path>) can be used to specify the paths to specific test suites to run, instead of running all tests in the default test pack(s). A single test suite may be given, or multiple paths may be separated by commas. The paths should be relative to the top level directory of Chaste (e.g. test_suite=global/test/TestException.hpp) or be an absolute path (see MakeEclipseBuildTheTestThatIsOpen).
      • As an alternative to using test_suite=, test .hpp files may also be specified directly as arguments to scons, e.g. "scons global/test/TestException.hpp global/test/TestCwd.hpp". This makes it easier to use tab completion to specify multiple tests to run.
      • Subfolders may also be given to select tests therein. For instance "scons heart/test/ionicmodels" will run all the Continuous tests in that folder.
    • compile_only=1 (co=1) will just compile test executables without running them. This is useful for fixing build failures.
    • all_tests=1 (at=1) will select all tests for running. This is most useful in conjunction with compile_only=1 to avoid breaking the nightly builds.
    • chaste_libs=1 (cl=1) to compile Chaste as libraries, rather than using fine-grained dependencies for linking (see #244 and #614).
    • update_provenance=0 (up=0) to not update the provenance information (see #1026 and Version.hpp) - useful to avoid rebuilding if you don't want accurate provenance while developing a feature.
    • brief=1 (br=1) to reduce the length of C++ compilation lines printed by scons.
    • exe=1 enables building of Chaste executables.
  • Rarer options:
    • debug=1 will turn on some limited build script debugging. It is particularly useful to check your hostconfig configuration.
    • static=1 to compile the Chaste libraries statically rather than making them shared libraries. Requires chaste_libs=1 to be useful.
    • run_time_flags="<x>" will pass a list of flags to the executables in the build. For example, run_time_flags="-get_total_flops" will enable PETSc flop logging. ​More PETSc flags
    • acceptance_suite=weekly will switch the acceptance tests run (used with exe=1 and the apps target).
    • test_summary=0 will prevent the build summarising the output of any tests run. By default it produces an index.html file in the output directory (the name of which will be printed to stdout in case you are unsure).
    • no_store_results=1 will avoid taking a copy of test output, hence removing the buffering so you see output lines as they are generated, at the cost of making the results parser think the test failed since no output was produced.
  • Experimental options:
    • install_prefix can be used to specify where to install the Chaste headers and libraries, if the install target is given. See #1467.
  • Some options exist for the benefit of the build system:
    • revision=<n> is used by the integration machines to specify what revision of the code is being built.
    • dyn_libs_only=1 is used by the run-time CellML converter to only compile the cell model.
    • do_inf_tests=0 will turn off "infrastructure tests" (checking for orphaned tests and duplicate file names). Passing 1 will turn on extra checks, including checking copyright notices.
    • check_failing_tests=1 will try running tests in the Failing test pack.
    • force_test_runs=1 will force re-running of all (selected) tests even if the source is unchanged.

Build Classes

The build argument is used to control what type of build to perform. The different possible values for this option correspond to classes defined in the source:trunk/python/BuildTypes.py file. The GetBuildType function in this module will always have the most up-to-date information on what is available, but a summary is also given here for convenience.

Some of the classes (and hence valid values for the build=<x> parameter) are:

  • BuildType: This is the base class, and uses gcc with lots of warnings turned on.
  • GccDebug: Use gcc with debugging turned on (-g flag). This is currently the default.
  • MemoryTesting: Use valgrind to check for memory leaks when running tests.
  • Coverage: Do coverage testing. Runs the continuous test pack on both 1 and 2 processors. Note that you can evaluate the coverage of a single test by adding a test_suite= option, or of a component or project by giving it as a target (e.g. scons b=Coverage global).
  • DoxygenCoverage: Test whether every class, method, parameter, etc. have some documentation. By default it checks the main Chaste components; you can test a project by giving it as a build target (e.g. scons b=DoxygenCoverage projects/ProjectFolder).
  • GccOpt: Use gcc with some optimisations.
  • GccOptP4: Use gcc optimised for Pentium 4.
  • GccOptNative: Use gcc optimised for the machine the compilation is performed on. This may yield better performance than GccOpt, but may not work on older versions of gcc.
  • Intel: Use the Intel C++ compiler, linker, etc.
  • IntelNonopt: Use the Intel compiler with no optimisation.
  • IntelP4 Use the Intel compiler optimised for Pentium 4.
  • IntelProduction: The fastest build (in terms of run time, not compile time) available; requires extra libraries.
  • Parallel: Use mpirun with 2 processors. The Parallel TestPack is default.
  • Profile: Same as GccDebug but uses the gprof CPU profiler and the Profile test pack.
  • LineProfile: Same as Profile but generates line-by-line profiling info.
  • GoogleProfile: Use the Google Profiler.

Build Options

A build type string can be just a class name `build=<x>, in which case that class is used (as above). Certain options can also be specified, separated by an underscore '_'. Some valid values for the build=<x>_<WhateverOption1>_<WhateverOption2> options parameters are:

  • ndebug to define NDEBUG, turning off assert()s and speeding up ublas,
  • report to turn on extra reporting with the Intel compiler,
  • fpe to enable specific floating point exception traps in PETSc-enabled tests (currently tests for FE_DIVBYZERO like x/0.0 and FE_INVALID like 0.0/0.0),
  • onlytests to disable the default testpack,
  • n (a positive integer) to run tests in parallel using n processes,
  • TestPackName to specify an extra set of tests to run (see also TestingStrategy).
  • traceksp to enable linear system solution tracing: # iterations, residual evolution,...
  • barriers to turn on MPI barriers within BeginEvent and EndEvent calls.
  • warn to stop compiler warnings being treated as errors.
  • 32bit - see Compile32bit
  • hostconfig,... - can be used to select different library versions, etc. if your machine configuration supports this.

The various classes specify such things as what compiler and flags to use for building C++ code, and also what tests to run by default. They also contain methods which the build (and test summary) scripts use to determine whether a test passed or failed, and where to store the output of tests. Unless you're working on the infrastructure you shouldn't have to worry about that. All methods contain documentation on their function.

Note that different build types, if they use different compilation flags, cause the compiled object files to be stored in different directories. Doing a clean build (scons -c . build=<whatever>) will only remove object files in the directories corresponding to the given build type.

See Also