Prepare the dependencies and source checkout, then follow the build commands for your platform. This is the starting point for development and debugging.
There are three build modes:
-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.-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.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.
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.