The bootstrap script available in the repository provides an alternative way to install MrDocs and its dependencies from source. Just run the script from the root of the MrDocs repository:

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

Or if you just want to install MrDocs without cloning the repository, you can run the script directly from the web:

Windows PowerShell
Unix Variants

python -c "$(Invoke-WebRequest -Uri 'https://raw.githubusercontent.com/cppalliance/mrdocs/refs/heads/develop/bootstrap.py' -UseBasicParsing | Select-Object -ExpandProperty Content)"

python -c "$(curl -fsSL https://raw.githubusercontent.com/cppalliance/mrdocs/refs/heads/develop/bootstrap.py)"

This method automates the download, configuration, and build steps for MrDocs and all required third-party libraries. It is especially useful for developers and for users who prefer a streamlined, interactive setup or need to install MrDocs in custom environments.

The script will prompt you for the installation directory and all other options. Every option can be defined in the command line directly instead of being prompted. All options can be listed with the --help option.

The --non-interactive option allows you to run the script without any prompts, using values specified in the command line and default values for other options. In the default case, the script will download the source code to the current directory and install MrDocs system-wide.

Windows PowerShell
Unix Variants

python -c "$(Invoke-WebRequest -Uri 'https://raw.githubusercontent.com/cppalliance/mrdocs/refs/heads/develop/bootstrap.py' -UseBasicParsing)" --non-interactive

python -c "$(curl -fsSL https://raw.githubusercontent.com/cppalliance/mrdocs/refs/heads/develop/bootstrap.py)" --non-interactive

The script handles tool checks, repository cloning, patching, and CMake configuration, reducing manual intervention and potential errors. This approach is recommended for developers, advanced users, or those integrating MrDocs into larger projects.

Manually Install from Source

The following instructions assume we are at a parent directory that’s going to contain both the MrDocs and the third-party dependencies directories.

+ <parent-directory>
  + mrdocs
  + third-party

Clone the MrDocs repository with:

git clone https://github.com/cppalliance/mrdocs

Also create and go to the third-party directory, where we are going to download and install our dependencies:

mkdir third-party
cd third-party

These instructions assume all dependencies are installed in the third-party directory for simplicity. Feel free to install them anywhere you want and adjust the main MrDocs configuration command later.

Fmt

MrDocs uses the fmt library for formatting strings. From the third-party directory, you can clone the fmt repository and install it with the following commands:

git clone https://github.com/fmtlib/fmt --branch 10.2.1 --depth 1 (1)
cd fmt
cmake -S . -B ./build -DCMAKE_BUILD_TYPE=Release -D FMT_DOC=OFF -D FMT_TEST=OFF (2)
cmake --build ./build --config Release (3)
cmake --install ./build --prefix ./install (4)
cd ..

1	Shallow clones the fmt repository.
2	Configure the fmt library with CMake, excluding the documentation and tests.
3	Builds the fmt library in the `build` directory.
4	Installs the fmt library in the `install` directory.

All instructions in this document assume you are using a CMake version above 3.26. Binaries are available at CMake’s official website.

Duktape

MrDocs uses the duktape library for JavaScript parsing. From the third-party directory, you can download the duktape source code from the official release:

Windows PowerShell
Unix Variants

Invoke-WebRequest -Uri "https://github.com/svaarala/duktape/releases/download/v2.7.0/duktape-2.7.0.tar.xz" -OutFile "duktape-2.7.0.tar.xz" (1)

1	Downloads the `duktape` source code.

curl -LJO https://github.com/svaarala/duktape/releases/download/v2.7.0/duktape-2.7.0.tar.xz (1)

1	Downloads the `duktape` source code.

Then patch the Duktape source code to provide CMake support.

tar -xf duktape-2.7.0.tar.xz (1)
cp ../mrdocs/third-party/duktape/CMakeLists.txt ./duktape-2.7.0/CMakeLists.txt (2)
cp ../mrdocs/third-party/duktape/duktapeConfig.cmake.in ./duktape-2.7.0/duktapeConfig.cmake.in (3)
cd duktape-2.7.0

1	Extracts the `duktape` source code.
2	Patches the source code with a `CMakeLists.txt` file to the `duktape-2.7.0` directory so that we can build it with CMake.
3	Copies the `duktapeConfig.cmake.in` file to the `duktape-2.7.0` directory so that we can install it with CMake and find it later from other CMake projects.

Now adjust the duk_config.h file to indicate we are statically building Duktape.

Windows PowerShell
Unix Variants
MacOS

$content = Get-Content -Path "src\duk_config.h" (1)
$content = $content -replace '#define DUK_F_DLL_BUILD', '#undef DUK_F_DLL_BUILD' (2)
$content | Set-Content -Path "src\duk_config.h" (3)

1	Read the content of `duk_config.h`
2	Replace the `DUK_F_DLL_BUILD` macro with `#undef DUK_F_DLL_BUILD`
3	Write the content back to the file

sed -i 's/#define DUK_F_DLL_BUILD/#undef DUK_F_DLL_BUILD/g' "src/duk_config.h" (1)

1	Disables the `DUK_F_DLL_BUILD` macro in the `duk_config.h` file to indicate we are statically building duktape.

sed -i '' 's/#define DUK_F_DLL_BUILD/#undef DUK_F_DLL_BUILD/g' src/duk_config.h

1	Disables the `DUK_F_DLL_BUILD` macro in the `duk_config.h` file to indicate we are statically building duktape.

And finally install the library with CMake:

cmake -S . -B ./build -DCMAKE_BUILD_TYPE=Release (1)
cmake --build ./build --config Release (2)
cmake --install ./build --prefix ./install (3)

1	Configures the `duktape` library with CMake.
2	Builds the `duktape` library in the `build` directory.
3	Installs the `duktape` library with CMake support in the `install` directory.

The scripts above download the duktape source code, extract it, and configure it with CMake. The CMake scripts provided by MrDocs are copied to the duktape-2.7.0 directory to facilitate the build process with CMake and provide CMake installation scripts for other projects.

Libxml2

MrDocs uses libxml2 tools for tests. Only developers need to install this dependency. Users can skip this step.

From the third-party directory, you can clone the libxml2 repository and install it with the following commands:

git clone https://github.com/GNOME/libxml2 --branch v2.12.6 --depth 1 (1)
cd libxml2
cmake -S . -B ./build -DCMAKE_BUILD_TYPE=Release -DLIBXML2_WITH_PROGRAMS=ON -DLIBXML2_WITH_FTP=OFF -DLIBXML2_WITH_HTTP=OFF -DLIBXML2_WITH_ICONV=OFF -DLIBXML2_WITH_LEGACY=OFF -DLIBXML2_WITH_LZMA=OFF -DLIBXML2_WITH_ZLIB=OFF -DLIBXML2_WITH_ICU=OFF -DLIBXML2_WITH_TESTS=OFF -DLIBXML2_WITH_HTML=ON -DLIBXML2_WITH_C14N=ON -DLIBXML2_WITH_CATALOG=ON -DLIBXML2_WITH_DEBUG=ON -DLIBXML2_WITH_ISO8859X=ON -DLIBXML2_WITH_MEM_DEBUG=OFF -DLIBXML2_WITH_MODULES=ON -DLIBXML2_WITH_OUTPUT=ON -DLIBXML2_WITH_PATTERN=ON -DLIBXML2_WITH_PUSH=ON -DLIBXML2_WITH_PYTHON=OFF -DLIBXML2_WITH_READER=ON -DLIBXML2_WITH_REGEXPS=ON -DLIBXML2_WITH_SAX1=ON -DLIBXML2_WITH_SCHEMAS=ON -DLIBXML2_WITH_SCHEMATRON=ON -DLIBXML2_WITH_THREADS=ON -DLIBXML2_WITH_THREAD_ALLOC=OFF -DLIBXML2_WITH_TREE=ON -DLIBXML2_WITH_VALID=ON -DLIBXML2_WITH_WRITER=ON -DLIBXML2_WITH_XINCLUDE=ON -DLIBXML2_WITH_XPATH=ON -DLIBXML2_WITH_XPTR=ON (2)
cmake --build ./build --config Release (3)
cmake --install ./build --prefix ./install (4)
cd ..

1	Shallow clones the libxml2 repository.
2	Configure the libxml2 with CMake, excluding the documentation, tests, and unwanted dependencies.
3	Builds libxml2 in the `build` directory.
4	Installs libxml2 in the `install` directory.

LLVM

MrDocs uses LLVM to parse C++ code and extract documentation from it. It depends on a recent version of LLVM: dd7a3d4

Download:

You can shallow-clone the project from the official repository. From the third-party directory, run the following commands:

mkdir -p llvm-project (1)
cd llvm-project
git init (2)
git remote add origin https://github.com/llvm/llvm-project.git (3)
git fetch --depth 1 origin dd7a3d4d798e30dfe53b5bbbbcd9a23c24ea1af9 (4)
git checkout FETCH_HEAD (5)

1	Create a directory for the llvm-project instead of cloning it
2	Initialize a git repository
3	Add the official LLVM repository as a remote
4	Fetch the commit we want to use: this allows us to shallow-clone the repository at this commit
5	Checkout the commit we want to use

Configure:

The mrdocs/third-party/llvm directory provides CMake presets to build LLVM. We recommend using preset files as they contain a replicable set of CMake configuration values that can be used for a project. From third-party/llvm-project, you can copy the CMakePresets.json and CMakeUserPresets.json files to the llvm-project/llvm directory.

cp ../../mrdocs/third-party/llvm/CMakePresets.json ./llvm
cp ../../mrdocs/third-party/llvm/CMakeUserPresets.json ./llvm/CMakeUserPresets.json

Run a command such as the following to configure LLVM:

Windows PowerShell
Unix Variants

cd llvm
cmake -S . -B ./build --preset=release-win -DLLVM_ENABLE_RUNTIMES=libcxx

cd llvm
cmake -S . -B ./build --preset=release-unix -DLLVM_ENABLE_RUNTIMES=libcxx;libcxxabi;libunwind

In the example above, we configure a Release version of LLVM for MrDocs. Choose one of the presets from CMakePresets.json or edit the variants in CMakeUserPresets.json to customize the configurations.

Developers might also want to build a custom Debug LLVM configuration including optimizations, which allows for faster execution of tests. The relwithdebinfo and debwithopt presets are provided for this purpose. Or if you prefer using the command line, set CMAKE_CONFIGURATION_TYPES or CMAKE_BUILD_TYPE to Debug and manually include the optimization flags to -D CMAKE_CXX_FLAGS="/O2 /Zi" (MSVC) or -D CMAKE_CXX_FLAGS="-Og -g".

This should give you an optimized build with all debug features and flags, such as an appropriate _ITERATOR_DEBUG_LEVEL and the /MDd flag in MSVC. In other platforms, this should give you a release somewhat equivalent to RelWithDebInfo optimized for debugging experience. -Og offers a reasonable level of optimization while maintaining fast compilation and a good debugging experience.

Build:

Build and install the configured version of LLVM with:

cmake --build ./build --config Release --parallel 4
cmake --install ./build --prefix ../install

Replace 4 with the number of cores you want to use for building LLVM.

Return from ./third-party/llvm-project/llvm to the LLVM project directory:

cd ../..

MrDocs

Return to the parent directory of third-party (the one containing the mrdocs directory) to build and install MrDocs:

cd ../..

Configure:

The MrDocs repository also includes a CMakePresets.json file that contains the parameters to configure MrDocs with CMake.

To specify the installation directories, you can use the LLVM_ROOT, DUKTAPE_ROOT, FMT_ROOT, and LIBXML2_ROOT environment variables. To specify a generator (-G) and platform name (-A), you can use the CMAKE_GENERATOR and CMAKE_GENERATOR_PLATFORM environment variables.

You can also customize the presets by duplicating and editing the CMakeUserPresets.json.example file in the mrdocs directory. This is typically more convenient than using environment variables.

For instance, to build MrDocs with the default Release preset, you can run the following command:

Windows PowerShell
Unix Variants

cd mrdocs
cmake -S . --preset=release-win

cd mrdocs
cmake -S . --preset=release-unix

To list the available presets, you can run:

cmake --list-presets

Build:

Then build and install MrDocs with:

cd build
cmake --build .
cmake --install .

To customize the installation directory, use the CMAKE_INSTALL_PREFIX option or use the --prefix option for the cmake --install . command. To customize the C and C++ compilers, use the CMAKE_C_COMPILER and CMAKE_CXX_COMPILER options.

Developers should also enable -D BUILD_TESTING=ON.

Package layout

The MrDocs installation directory follows the "Filesystem Hierarchy Standard" (FHS) layout:

bin: the MrDocs executable intended to be used by users or invoked from the command line.
share: resource files installed by MrDocs
doc: the MrDocs documentation
include: the MrDocs headers
lib: the MrDocs library

The FHS layout provides a directory structure that also serves as a widely accepted convention for organizing files and directories in Unix-like systems, but that can be used in any operating system.