Development Workflow
Bootstrap leaves your checkout ready to build, test and debug from the terminal or from an IDE.
Basic commands
These commands cover most use cases:
python bootstrap.py # once: dependencies, presets, IDE entries
just build # build the default preset
just unit-tests # the fast check while you work
just golden-tests # the fast check while you work
just run-all-tests # every check, before you commit
just format # format the lines you changed
just lint # the checks on your changed linesBootstrap
You can run bootstrap once per preset, and it writes the IDE entries and the justfile recipes for that preset:
python bootstrap.pyTo accept the defaults for every option, run:
python bootstrap.py -yYou can also accept the defaults and customize any other option, such as the preset name, the installation directory, the compiler and the sanitizer:
python bootstrap.py -y --preset release-linux --install-dir install/release-linux --compiler clang --sanitizer addressIt builds LLVM and the other dependencies, so the first run per preset takes a while. The Build from Source page and the bootstrap reference cover all options.
Justfiles
Bootstrap creates targets for VSCode, CLion, Visual Studio, and justfile recipes so you can see all the commands in one place:
just --listIt also updates CMake presets and sets up debug visualizers.
To see what a recipe runs, ask just for a dry run:
$ just --dry-run build
test -d build/release-linux || just configure-release-linux
cmake --build build/release-linuxBuilding
just build and just unit-tests configure the preset when its build directory is missing, and just unit-tests builds the tests first.
To configure and build Mr.Docs:
just configure
just buildWhen many presets are available, you can use a suffixed recipe name to pick one, such as just build-release-linux or just unit-tests-debug-linux. The unsuffixed recipes use the preset that run_all_tests.py would pick, and the recipes below name a preset when you need another.
To configure and build a preset:
just configure-release-linux
just build-release-linuxTo build a specific target such as mrdocs:
just build-mrdocs-release-linuxLinting
lint.py/just lint runs every linting guard incrementally: each judges what changed since the merge base with upstream, and --all makes them judge the whole tree.
A generated-file guard runs only when its inputs or outputs changed, and prints <guard>: not affected otherwise.
Formatting
just format formats the C++ lines you changed since the merge base. It runs utils/format/format.py, and its --check flag only reports.
CMake offers the same through the format and format-check targets.
Formatting covers the rules.
Tests
Unit tests
To run unit tests:
just unit-testsTo run every automated check at once, run just run-all-tests, which the quickstart describes.
Documentation
The documentation renders the reference with the tool installed under install/<preset>/, and just build-local-docs builds the tool but does not install it. Install first, then build:
just build-release-linux
cmake --install build/release-linux --prefix install/release-linux
just build-local-docsThe build writes the site under docs/build/site/.
One command for everything
The command just run-all-tests runs utils/testing/run_all_tests.py.
It lints first, then configures and builds, and runs the golden tests, which stop it if they fail.
Then it runs the unit tests, the example tests, the integration tests and the docs build.
Its main flags are --preset to pick the preset, --update-golden to refresh the golden fixtures first, and --skip-docs to skip the docs build.