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, but not 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> builds the specified component.
• scons projects/<project_name> builds 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 below.
  • test_suite=<path> (ts=<path>) can be used to specify the pathname of a single test suite to run, instead of running all tests in the default test pack(s). The path should be given relative to the top level directory of Chaste (e.g. test_suite=heart/test/TestMonodomainFitzHughNagumoWithDG0Assember.hpp) or be an absolute path (see MakeEclipseBuildTheTestThatIsOpen).
  • 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 to reduce the length of C++ compilation lines printed by scons.
  • exe=1 enables building of Chaste executables.
• Rarer options:
  • static=1 to compile the Chaste libraries statically rather than making them shared libraries. Requires chaste_libs=1 to be useful.
  • 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).
  • 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
  • debug=1 will turn on some limited build script debugging. It is particularly useful to check your hostconfig configuration.
  • acceptance_suite=weekly will switch the acceptance test (used with exe=1 and the apps target)
• 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" (e.g. checking for orphaned tests).
  • 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.
• Deprecated options:
  • test_component=<component> just tests the given component, i.e. out of the test packs in view, it only runs the tests that occur both in those test packs and the specified component. A better way to do this is to just call scons <component>, which will only build the libraries actually needed by the given component.

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.

A build type string can be just a class name, in which case that class is used. Certain options can also be specified, separated by an underscore '_'. Current options are:

• report to turn on extra reporting with the Intel compiler,
• ndebug to define NDEBUG, turning off assert()s and speeding up ublas,
• 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.

Some of the classes (and hence valid values for the build 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.