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 |
|
July 10, 2024 |
(20 MB) |
(37 MB) |
(37 MB) |
(52 MB) |
(80 MB) |
|
October 24, 2024 |
(21 MB) |
(38 MB) |
(39 MB) |
(22 MB) |
(32 MB) |
|
December 1, 2023 |
(11 MB) |
(18 MB) |
- |
(19 MB) |
(28 MB) |
|
December 1, 2023 |
(20 MB) |
(37 MB) |
(37 MB) |
(52 MB) |
(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-partyClone the MrDocs repository with:
git clone https://github.com/cppalliance/mrdocsAlso 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 |
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 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: e1065370
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 e1065370aaacb1b1cb48e77d37d376bf024f4a39 (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.jsonRun a command such as the following to configure LLVM:
-
Windows PowerShell
-
Unix Variants
cd llvm
cmake -S . -B ./build --preset=release-wincd llvm
cmake -S . -B ./build --preset=release-unixIn 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 This should give you an optimized build with all debug features and flags, such as an appropriate |
Build:
Build and install the configured version of LLVM with:
cmake --build ./build --config Release --parallel 4
cmake --install ./build --prefix ../installReplace 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 ../..LibC++
In addition to LLVM, MrDocs requires a deterministic version of the C standard library (LibC) to ensure consistent behavior across various environments. This step is crucial for replicating specific compiler and library configurations.
Download:
Continue using the same LLVM project directory.
Configure:
Configure and build LibC++ using the existing structure:
export CXX="./install/bin/clang++"
export CC="./install/bin/clang"These options set the C and C++ compilers to the ones previously installed by LLVM. MrDocs only depends on the LibC++ headers, so any compiler that works for this step should be fine.
Run a command such as the following to configure LLVM:
-
Windows PowerShell
-
Unix Variants
cmake -G Ninja \
-S runtimes \
-B build-libcxx \
-DLLVM_ENABLE_RUNTIMES="libcxx;libcxxabi" \
-DCMAKE_INSTALL_PREFIX="$(pwd)/install" \
-DLIBCXXABI_USE_LLVM_UNWINDER=OFF \
-DLIBCXXABI_ENABLE_SHARED=OFF \
-DLIBCXXABI_ENABLE_STATIC=ON \
-DLIBCXX_ENABLE_SHARED=OFF \
-DLIBCXX_NO_VCRUNTIME=ON \
-DCMAKE_CXX_FLAGS="-D__ORDER_LITTLE_ENDIAN__=1234 -D__ORDER_BIG_ENDIAN__=4321 -D__BYTE_ORDER__=__ORDER_LITTLE_ENDIAN__"cmake -G Ninja \
-S runtimes \
-B build-libcxx \
-DLLVM_ENABLE_RUNTIMES="libcxx;libcxxabi;libunwind" \
-DCMAKE_INSTALL_PREFIX="$(pwd)/install"Build:
Build and install the configured version of LibC++ with:
-
Windows PowerShell
-
Unix Variants
ninja -C build-libcxx cxx
ninja -C build-libcxx install-cxxninja -C build-libcxx cxx cxxabi unwind
ninja -C build-libcxx install-cxx install-cxxabi install-unwindReturn from ./third-party/llvm-project 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 |
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.