Install

Binary Packages

Binary packages are available from our Release Page. Most users should use these packages.

🪟 Windows

🐧 Linux

📃 Release

📦 7z

📦 msi

📦 zip

📦 tar.xz

📦 tar.gz

v0.0.2

July 10, 2024

🔗 MrDocs-0.0.2-win64.7z

(20 MB)

🔗 MrDocs-0.0.2-win64.msi

(37 MB)

🔗 MrDocs-0.0.2-win64.zip

(37 MB)

🔗 MrDocs-0.0.2-Linux.tar.xz

(52 MB)

🔗 MrDocs-0.0.2-Linux.tar.gz

(80 MB)

develop

April 4, 2024

🔗 MrDocs-0.0.1-win64.7z

(20 MB)

🔗 MrDocs-0.0.1-win64.msi

(37 MB)

🔗 MrDocs-0.0.1-win64.zip

(37 MB)

🔗 MrDocs-0.0.1-Linux.tar.xz

(52 MB)

🔗 MrDocs-0.0.1-Linux.tar.gz

(80 MB)

v0.0.1

December 1, 2023

🔗 MrDocs-0.0.1-win64.7z

(11 MB)

🔗 MrDocs-0.0.1-win64.msi

(18 MB)

-

🔗 MrDocs-0.0.1-Linux.tar.xz

(19 MB)

🔗 MrDocs-0.0.1-Linux.tar.gz

(28 MB)

master

December 1, 2023

🔗 MrDocs-0.0.1-win64.7z

(20 MB)

🔗 MrDocs-0.0.1-win64.msi

(37 MB)

🔗 MrDocs-0.0.1-win64.zip

(37 MB)

🔗 MrDocs-0.0.1-Linux.tar.xz

(52 MB)

🔗 MrDocs-0.0.1-Linux.tar.gz

(80 MB)

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. Fell 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.

If you prefer using Vcpkg to install dependencies, you can install VcPkg and fmt with the following commands from the third-party directory:

  • Windows PowerShell

  • Unix Variants

git clone https://github.com/microsoft/vcpkg.git -b master (1)
cd vcpkg
bootstrap-vcpkg.bat (2)
vcpkg.exe install fmt --triplet x64-windows (3)
1 Clones the Vcpkg repository.
2 Bootstraps Vcpkg.
3 Installs the fmt library. 
git clone https://github.com/microsoft/vcpkg.git -b master (1)
cd vcpkg
./bootstrap-vcpkg.sh (2)
./vcpkg install fmt (3)
1 Clones the Vcpkg repository.
2 Bootstraps Vcpkg.
3 Installs the fmt library.

You can also install fmt with Vcpkg in 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. This file includes all the dependencies MrDocs needs, except for LLVM.

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.

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

$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.

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 downloads the duktape source code, extracts it, and configures 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.

If you prefer using Vcpkg to install dependencies, you can install duktape with the following commands from the third-party directory:

  • Windows PowerShell

  • Unix Variants

cd vcpkg
vcpkg.exe install duktape --triplet x64-windows (1)
1 Installs the duktape library. 
cd vcpkg
./vcpkg install duktape (1)
1 Installs the duktape library.
These examples assume VcPkg is already installed in the third-party/vcpkg directory (see the Fmt section).

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.

If you prefer using Vcpkg to install dependencies, you can install libxml2 with the following commands from the third-party directory:

  • Windows PowerShell

  • Unix Variants

cd vcpkg
vcpkg.exe install libxml2[tools] --triplet x64-windows (1)
1 Installs libxml2. 
cd vcpkg
./vcpkg install libxml2[tools] (1)
1 Installs libxml2.
These examples assume VcPkg is already installed in the third-party/vcpkg directory (see the Fmt section).

LLVM

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

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 7a28a5b3fee6c78ad59af79a3d03c00db153c49f (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.example ./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
cd llvm
cmake -S . -B ./build --preset=release-unix

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 parent directory to build and install MrDocs:

cd ../../..

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 PowerShell

  • Unix Variants

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"
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.