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

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

This method automates the download, configuration, and build steps for Mr.Docs 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 Mr.Docs 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. This allows you to only customize the most common options and leave the others to their defaults. This is handy for developers to refresh dependencies:

python bootstrap.py --non-interactive --mrdocs-build-type=Release --third-party-src-dir=/path/to/dependencies

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 Mr.Docs into larger projects.

Manually Install from Source

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

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

Clone the Mr.Docs 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 Mr.Docs configuration command later.

All instructions in this document assume you are using a CMake version at or above 3.13 (project minimum). Binaries are available at CMake’s official website.

JerryScript

Mr.Docs embeds the JerryScript engine for JavaScript helpers. From the third-party directory, download the 3.0.0 source archive from the official repository:

Windows PowerShell
Unix Variants

Invoke-WebRequest -Uri "https://github.com/jerryscript-project/jerryscript/archive/refs/tags/v3.0.0.tar.gz" -OutFile "jerryscript-3.0.0.tar.gz" (1)

1	Downloads the `JerryScript` source code.

curl -LJO https://github.com/jerryscript-project/jerryscript/archive/refs/tags/v3.0.0.tar.gz (1)

1	Downloads the `JerryScript` source code.

Patch the JerryScript source with our CMake shim and install it:

tar -xf jerryscript-3.0.0.tar.gz (1)
cp ../mrdocs/third-party/patches/jerryscript/CMakeLists.txt ./jerryscript-3.0.0/CMakeLists.txt (2)
cp ../mrdocs/third-party/patches/jerryscript/jerryscriptConfig.cmake.in ./jerryscript-3.0.0/jerryscriptConfig.cmake.in (3)
cp ../mrdocs/third-party/patches/jerryscript/port.c ./jerryscript-3.0.0/port.c (4)
cd jerryscript-3.0.0

cmake -S . -B ./build -DCMAKE_BUILD_TYPE=Release \
  -DJERRY_PROFILE=es.next -DJERRY_CMDLINE=OFF -DJERRY_TESTS=OFF -DJERRY_DEBUGGER=OFF \
  -DJERRY_SNAPSHOT_SAVE=OFF -DJERRY_SNAPSHOT_EXEC=OFF -DJERRY_PORT_DEFAULT=ON \
  -DJERRY_MEM_STATS=OFF -DJERRY_PARSER_STATS=OFF -DJERRY_LINE_INFO=OFF \
  -DJERRY_LTO=OFF -DJERRY_LIBC=OFF -DCMAKE_MSVC_RUNTIME_LIBRARY=MultiThreadedDLL
cmake --build ./build --config Release
cmake --install ./build --prefix ./install

1	Extracts the `JerryScript` source code.
2	Adds CMake packaging files maintained in this repository.
3	Provides the port layer and CMake config used by MrDocs.

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: dc4cef8

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 dc4cef81d47c7bc4a3c4d58fbacf8a6359683fae (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 optimizeddebug 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, JERRYSCRIPT_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.