Install

Binary Packages

Binary packages are available from our Release Page. Most users should start here; if no binary release fits your platform, build from source below.

Build from Source

If no binary release fits your platform, build Mr.Docs from source with the bootstrap script. The script provisions every dependency Mr.Docs needs (LLVM, Clang, and the other third-party libraries) into the install prefix you choose, configures the project, and runs the build. See the bootstrap walkthrough on the C++ Alliance site for the design rationale.

Already installed Mr.Docs from a binary package? Skip the rest of this section and go straight to Verification.

Prerequisites

You need Python, a recent C++ toolchain (Clang or a recent GCC), CMake, and Git on the machine. If any of those are missing, pass --install-system-deps to the bootstrap script below and it will use your system package manager to install them.

Running the script

git clone https://www.github.com/cppalliance/mrdocs.git
cd mrdocs
python bootstrap.py

The script prompts for the install directory and other settings interactively. Every prompt has an equivalent CLI flag; the --help output lists them all.

Usage patterns

Non-interactive (CI or scripted installs): --yes accepts every default without prompting.

python bootstrap.py --yes --build-type Release

Dry-run: --dry-run prints every command the script would run, fully resolved. The output is copy-paste-ready shell, useful when you want to follow the build manually:

python bootstrap.py --yes --dry-run --build-type Release

Continuous integration: point --cache-dir at a CI-cached directory of dependency installs; the script checks stamp files and skips up-to-date recipes. Pair with --skip-build if you only need the dependencies.

python bootstrap.py --yes --plain \
  --build-type Release --sanitizer address \
  --cache-dir ../third-party --skip-build

For more options and details, see the Bootstrap Options Reference section at the end of this page.

Verification

After install, confirm the binary is on PATH and reports the expected version:

mrdocs --version

If the shell reports "command not found" (or "is not recognized as an internal or external command" on Windows), Mr.Docs is installed but its bin/ directory is not on your PATH. Add it and reopen the terminal:

  • Windows

  • Linux / macOS

Append the install prefix’s bin\ to your user PATH from PowerShell:

[Environment]::SetEnvironmentVariable(
  'Path',
  $env:Path + ';C:\path\to\install\bin',
  'User')

Replace C:\path\to\install with the prefix you passed to --install-dir. Close and reopen the terminal so the new PATH takes effect.

Append the install prefix’s bin/ to PATH in your shell profile (typically ~/.zshrc, ~/.bashrc, or ~/.profile):

echo 'export PATH="/path/to/install/bin:$PATH"' >> ~/.zshrc
source ~/.zshrc

Replace /path/to/install with the prefix you passed to --install-dir (or the default expansion shown in Directories).

If mrdocs --version still fails after fixing PATH, the binary is on disk but cannot start. Run it with the full path (/path/to/install/bin/mrdocs --version) to see the actual error: missing shared library, wrong CPU architecture, or a mismatched glibc are the usual suspects, all fixable by rerunning bootstrap with the right --cc / --cxx.

Package layout

A Mr.Docs install follows the conventional Unix layout. After install, the prefix contains:

  • bin/ — the mrdocs executable.

  • share/mrdocs/ — bundled resources Mr.Docs reads at runtime

  • lib/ and include/ — the Mr.Docs core library and its public headers, for embedding Mr.Docs in another program.

Appendix: Bootstrap Options Reference

Build Configuration

Name Description
--build-type
(enum)

Selects the CMake build configuration. Release maximizes optimization; Debug disables it and enables assertions; RelWithDebInfo produces optimized binaries with debug info; MinSizeRel optimizes for size; DebugFast trades some debuggability for build speed.

Choices: Release, Debug, RelWithDebInfo, MinSizeRel, DebugFast

Default: Release

--preset
(string)

Name of the CMake preset to use. The default template expands to a value derived from build type, OS, compiler, and sanitizer; override only when you have a custom preset.

Default: a name like release-macos or debug-linux-clang-asan, derived from the build type, OS, compiler, and sanitizer

--sanitizer
(enum)

Builds Mr.Docs with a Clang/GCC sanitizer enabled. address catches out-of-bounds and use-after-free, undefined catches undefined behavior, thread catches data races, memory catches uninitialized reads. Bootstrap also rebuilds libc++ with the matching instrumentation when the sanitizer needs it.

Choices: address, undefined, thread, memory

--no-build-tests
(flag)

Skip building the test suite (golden, unit, lint, schema, self-doc). Tests are built by default; pass --no-build-tests for a leaner build that skips the Java-runtime requirement of the xml-lint step.

Compiler Options

Name Description
--cc
(string)

Path to the C compiler. Defaults to the compiler CMake discovers on the system; set this when you need to pin a specific version or pick between Clang and GCC.

--cxx
(string)

Path to the C++ compiler. Defaults to the compiler CMake discovers on the system; set this to pin a specific version or to use a different toolchain from CC.

--cflags
(string)

Extra flags appended to every C compile command, both for third-party recipes and for Mr.Docs itself. Useful for linker-friendly debug info (-gz=zstd) or coverage flags.

--cxxflags
(string)

Extra flags appended to every C++ compile command, both for third-party recipes and for Mr.Docs itself.

--ldflags
(string)

Extra flags appended to every link command, both for third-party recipes and for Mr.Docs itself.

Tool Paths

Name Description
--cmake-path
(string)

Path to the CMake executable. Bootstrap discovers CMake on PATH by default; set this when multiple CMake versions are installed and the wrong one is picked up.

--ninja-path
(string)

Path to the Ninja executable. Ninja is the preferred CMake generator because it produces a compile_commands.json automatically; bootstrap discovers it on PATH by default.

--git-path
(string)

Path to Git. Required for cloning recipes and for the compilation-database CMake integration. Bootstrap discovers Git on PATH by default.

--python-path
(string)

Path to the Python interpreter recipes should use for any Python steps. Defaults to the interpreter currently running bootstrap.

--java-path
(string)

Path to a Java runtime. Required for the xml-lint test step when --build-tests is on; ignored otherwise.

Directories

Name Description
--source-dir
(string)

Root of the cloned Mr.Docs source tree. Bootstrap auto-detects this from the working directory, so you usually do not need to set it explicitly.

Default: the directory containing the cloned source

--build-dir
(string)

Where CMake places intermediate build artefacts. The default template expands per build type, OS, compiler, and sanitizer so different combinations do not clobber each other.

Default: <source-dir>/build/<preset>

--install-dir
(string)

Where the final binaries and resources are installed. The default template expands per build type, OS, compiler, and sanitizer so different combinations install side-by-side.

Default: <source-dir>/install/<preset>

Behavior Options

Name Description
-y
(flag)

Accept every default prompt without asking. Use this for CI, containers, and scripted installs where there is no human at the keyboard.

--dry-run
(flag)

Print every command bootstrap would run, fully resolved with absolute paths, without executing anything. Useful when you want to inspect the build steps or reproduce them manually.

--verbose
(flag)

Show extra log lines about each step bootstrap takes.

--debug
(flag)

Show full Python tracebacks on errors. Implies verbose.

--plain
(flag)

Disable colors and emoji in the output. Use for CI logs and any environment that does not render terminal escape codes.

--install-system-deps
(flag)

If a required system tool (CMake, a compiler, Git, etc.) is missing, attempt to install it via apt-get on Linux or brew on macOS before continuing.

Dependency Options

Name Description
--clean
(flag)

Wipe every cached third-party dependency build and start over. The Mr.Docs build itself is also cleared.

--force
(flag)

Rebuild a recipe even when its stamp file says it is up to date. Use this after an out-of-band change to a recipe's source tree.

--recipe-filter
(string)

Comma-separated list of recipe names to build (for example, llvm,jerryscript). Recipes not in the list are skipped.

--skip-build
(flag)

Install dependencies but skip the CMake configure and build of Mr.Docs itself. Useful when you only need the dependency tree populated for CI cache restoration.

--list-recipes
(flag)

Print every dependency recipe bootstrap knows about and exit.

--cache-dir
(string)

Use a shared directory of cached dependency installs. Each recipe installs to <cache-dir>/<recipe-name> instead of the per-build location. Bootstrap checks stamp files and skips recipes that are already up to date, so this directory is the natural unit of CI cache restoration.

--cache-key
(string)

Print the cache key for one recipe and exit (for example, --cache-key llvm). The key includes the recipe name, the OS, and the configuration that affects its build, so it can be used as a cache restore key in CI.

--os-key
(string)

OS or container identifier baked into cache keys (for example, ubuntu:24.04, macos-15). Required for cross-machine cache reuse so that builds from different runners do not pull each other's artefacts.

--env-file
(string)

Path where bootstrap writes computed <recipe>_ROOT paths and propagation flags in key=value format. CI uses the file to inject environment variables into the steps that follow bootstrap.

--refresh-all
(flag)

Re-run the bootstrap configuration step for every existing IDE configuration in the source tree, regenerating run configs from current options without rebuilding.

Run Configuration Options

Name Description
--no-run-configs
(flag)

Skip generating IDE run/debug configurations for CLion, VS Code, and Visual Studio. Bootstrap generates configs by default so common Mr.Docs targets are one click away; pass --no-run-configs when you do not want bootstrap to touch the IDE config directories.