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) |
(38 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-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 |
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.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 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 ../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 ../..
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-cxx
ninja -C build-libcxx cxx cxxabi unwind
ninja -C build-libcxx install-cxx install-cxxabi install-unwind
Return 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.