Build BornAgain from source

Prepare the dependencies and source checkout, then follow the build commands for your platform. This is the starting point for development and debugging.

Developer options

There are three build modes:

  • The standard mode, without mode option, is meant for users who build BornAgain from source.
  • The developer mode, -DDEV=ON, is meant for work on the source code. It regenerates the files under auto/, treats compiler warnings as errors, adds the developer checks to the test suite, and skips the slow tests. It requires the dependencies listed under Developer build.
  • The maintainer mode, -DMAINTAIN=ON, is meant for CI and for preparing releases. It treats compiler warnings as errors, adds the developer checks, runs all tests, makes the Python wheel fit for distribution, and tests the wheel.

The two mode options exclude each other. The developer checks take effect only on Linux and macOS.

To change the mode of an existing build, run from its build directory:

cmake .. -DDEV=ON -DMAINTAIN=OFF

CMake retains the Python and dependency settings from that build. Add -DCMAKE_CXX_COMPILER_LAUNCHER=ccache when ccache is installed.

In standard mode, the options governed by the modes can be set one by one:

  • -DZERO_TOLERANCE=ON treats compiler warnings as errors.
  • -DDEVELOPER_CHECKS=ON adds the developer checks to the test suite.
  • -DCONFIGURE_BINDINGS=ON regenerates auto/Wrap/. This requires SWIG.
  • -DCONFIGURE_EXAMPLES=ON regenerates the examples below auto/. This requires Ruby with ERB.
  • -DCONFIGURE_DOXY=ON builds the Doxygen API reference.
  • -DEXCLUDE_XL_TESTS=ON skips the slow tests.
  • -DBA_PY_PACK=ON makes the Python wheel fit for distribution, and tests it.

Run tests

After building, run the test suite from the build directory:

ctest -j8 --output-on-failure

-jN runs up to N tests in parallel. To rerun only failed tests or select tests by name, use:

ctest --rerun-failed --output-on-failure
ctest -R 'TestNamePattern' --output-on-failure

List matching tests without running them with ctest -N -R 'TestNamePattern'.

Tests that take more than about 2 s carry the label XL. In developer mode, they are left out of the test suite; CTest ends with a note that says how many. To run them, use the maintainer mode, or reconfigure with -DDEV=OFF.

On Linux and macOS, DEVELOPER_CHECKS=ON adds CTest checks for source format, code structure, documentation, and generated examples. Use ctest -N to list them. The checks do not rewrite files.

If cpp.format fails on files you did not change, compare your clang-format version with the one used by CI.

Doxygen API reference

Configure with -DCONFIGURE_DOXY=ON, then build the doxy target:

ninja doxy

Open html/index.html from the build directory.

Continue with Contribute changes to submit code changes, or Debug and analyze for debug builds and analysis tools.