Install

Binaries

Binary packages are available from our Release Page

Source

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. Fell free to install them anywhere you want and adjust the main MrDocs configuration command later.

Installing LLVM

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

Binaries:

Because building LLVM may take many hours to complete, we provide pre-built binaries for Windows and Linux:

CMake Preset CMake Build Debug Info Optimized MSVC Build

🪟 Windows-Release-29b20829.7z

🚀 Release

🚀 Release

❌

✅

🚀 Release

🪟 Windows-Debug-29b20829.7z

🐞 Debug

🐞 Debug

✅

❌

🐞 Debug

🪟 Windows-RelWithDebInfo-29b20829.7z

🕵️‍♂️ RelWithDebInfo

🕵️‍♂️ RelWithDebInfo

✅

✅

🚀 Release

🪟 Windows-DebWithOpt-29b20829.7z

🔬 DebWithOpt

🐞 Debug

✅

✅

🐞 Debug

🐧 Linux-Release-29b20829.tar.xz

🚀 Release

🚀 Release

❌

✅

N/A

🐧 Linux-Debug-29b20829.tar.xz

🐞 Debug

🐞 Debug

✅

❌

N/A

🐧 Linux-RelWithDebInfo-29b20829.tar.xz

🕵️‍♂️ RelWithDebInfo

🕵️‍♂️ RelWithDebInfo

✅

✅

N/A

🐧 Linux-DebWithOpt-29b20829.tar.xz

🔬 DebWithOpt

🐞 Debug

✅

✅

N/A
The Linux binaries are built on Ubuntu 22.04 and may not work on other distributions.

You can download the binaries and uncompress them in the ./third-party/llvm+clang directory we created in the previous step.

LLVM binaries are provided in a number of preset configurations. Here is a brief description of each preset:

  • Release: this is the preset users will typically use. It is optimized for speed and does not include debug information.

  • Debug: this is a preset developers can use. It includes debug information and no optimizations. However, using a Debug build of LLVM to debug MrDocs might be too slow. In this case, you can link MrDocs with RelWithDebInfo or DebWithOpt.

  • RelWithDebInfo: this is a release build with debug information. It is optimized for speed and includes debug information. However, if you are working with Windows+MSVC, this preset has a Release build type at the MSVC level. This means you can have conflicts with MrDocs in Debug mode because of LLVM setting flags such as the _ITERATOR_DEBUG_LEVEL and /MDd. In this case, you can use DebWithOpt instead to avoid the conflict and subsequent workarounds.

  • DebWithOpt: this is a debug build with optimizations. It includes all the default Debug flags for LLVM, it’s optimized for speed, includes debug information, and causes no conflicts with MrDocs in Debug mode.

If you chose to use the provided binaries instead of building LLVM from source, you can skip to the [duktape] section.

Download:

Alternatively, if building LLVM from source, you can clone the project from the official repository:

git clone https://github.com/llvm/llvm-project.git
cd llvm-project
git checkout 29b20829cc6ce3e6d9c3809164994c1659e0da56
cd llvm

Configure:

There are two ways to configure LLVM: using CMake presets or using CMake directly.

Configure with CMake Presets

We recommend using CMake presets to build LLVM. Preset files contain a replicable set of CMake configuration values that can be used to configure a project.

Instead of passing all CMake configuration values on the command line, a template for the CMakePresets.json and CMakeUserPresets.json files is provided in the repository’s third-party/llvm directory. Copy these files to the llvm-project/llvm directory and run a command such as the following to configure LLVM:

cmake -preset=relwithdebinfo-win

In the example above, we configure a RelWithDebInfo version of LLVM for MrDocs: a release build with debug information.

Choose one of the presets from CMakePresets.json or edit the variants in CMakeUserPresets.json to customize the configurations. The CMakeUserPresets.json file comes with presets for all the configurations described in the Binaries section.

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.

Configure with Command Line Arguments:

You can also configure LLVM directly with the settings required by MrDocs:

Windows (from administrator cmd.exe, after running vcvars64.bat):

cmake -S llvm -B build/MSVC/RelWithDebInfo -G "Ninja" -A x64 -D LLVM_ENABLE_PROJECTS="clang" -D CMAKE_CONFIGURATION_TYPES="RelWithDebInfo" -D LLVM_ENABLE_RTTI=ON -D CMAKE_INSTALL_PREFIX=../llvm+clang/RelWithDebInfo -D LLVM_ENABLE_IDE=OFF -D LLVM_ENABLE_DIA_SDK=OFF

Unix variants:

cmake -S llvm -B build/Linux/RelWithDebInfo -D LLVM_ENABLE_PROJECTS="clang" -D CMAKE_BUILD_TYPE=RelWithDebInfo -D LLVM_ENABLE_RTTI=ON -D CMAKE_INSTALL_PREFIX=../llvm+clang/RelWithDebInfo

Unlike the CMake presets, this command does not a number of parameters that removes features that are not required by MrDocs, thus increasing the build time and size of the installation.

Build:

Build and install the configured version of LLVM with:

cd build
cmake --build . --config RelWithDebInfo
cmake --install . --prefix ../../llvm+clang/RelWithDebInfo" --config RelWithDebInfo

If you prefer using the provided CMake presets, you can also use the --preset option for the build command:

cd build
cmake --build --preset=relwithdebinfo-win
cmake --install MSVC/RelWithDebInfo --config RelWithDebInfo

Return from ./third-party/llvm-project/build to the parent third-party directory to install other dependencies:

cd ../..

CMake dependencies

All other dependencies provide CMake integration scripts and can be obtained from vcpkg or installed manually.

  • fmt >= 10

  • duktape

For development builds, which include tests, you will also need:

  • libxml2[tools]

The instructions in this documentation will use vcpkg for these.

Installing vcpkg:

If you don’t have vcpkg installed, clone the repository:

git clone https://github.com/microsoft/vcpkg.git -b master
cd vcpkg

and bootstrap it:

Windows:

bootstrap-vcpkg.bat

Unix variants:

./bootstrap-vcpkg.sh

Installing dependencies:

vcpkg has two operation modes with which you can install these dependencies: classic mode and manifest mode.

Classic mode:

In vcpkg classic mode, vcpkg maintains a central installed tree inside the vcpkg instance built up by individual vcpkg install and vcpkg remove commands. This central set of packages can then be shared by any number of projects. However, each instance of vcpkg (a separate git clone) will have its own set of packages installed.

To install these dependencies with vcpkg in classic mode:

Windows:

vcpkg.exe fmt zlib libxml2[tools] --triplet x64-windows

Unix variants:

./vcpkg fmt zlib libxml2[tools]

Manifest mode:

In manifest mode, you declare your project’s direct dependencies in a manifest file named vcpkg.json. MrDocs includes a vcpkg.json.example file you can duplicate or create a symlink as vcpkg.json to use this mode. MrDocs is a CMake project that then already includes a vcpkg.json file, there’s nothing else you need to run to install the dependencies.

In this mode, vcpkg will create separate installed trees for each project and configuration. This is the recommended vcpkg mode for most users according to the vcpkg documentation.

MrDocs

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

cd ../..

Configure:

You can also configure MrDocs with command line arguments or CMake presets.

Configure with Command Line Arguments:

With the dependencies are available in third-party, you can configure MrDocs with:

Windows:

cmake -S mrdocs -B build -G "Visual Studio 17 2022" -A x64 -D CMAKE_CONFIGURATION_TYPES="RelWithDebInfo" -D CMAKE_EXPORT_COMPILE_COMMANDS=ON -D LLVM_ROOT="%cd%/third-party/llvm+clang/RelWithDebInfo" -D DUKTAPE_SOURCE_ROOT="%cd%/third-party/duktape-2.7.0" -D CMAKE_TOOLCHAIN_FILE="%cd%/third-party/vcpkg/scripts/buildsystems/vcpkg.cmake"

Unix variants:

cmake -S mrdocs -B build -D CMAKE_BUILD_TYPE=RelWithDebInfo -D CMAKE_EXPORT_COMPILE_COMMANDS=ON -D LLVM_ROOT="$(pwd)/third-party/llvm+clang/RelWithDebInfo" -D DUKTAPE_SOURCE_ROOT="$(pwd)/third-party/duktape-2.7.0" -D CMAKE_TOOLCHAIN_FILE="$(pwd)/third-party/vcpkg/scripts/buildsystems/vcpkg.cmake"

Configure with CMake Presets:

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_SOURCE_ROOT, CMAKE_TOOLCHAIN_FILE 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.

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. If any custom build of LLVM other than RelWithDebInfo is being used, the LLVM_ROOT variable should be set to the installation directory of that build.

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.