Skip to content

Commit c71a28d

Browse files
alandefreitasalandefreitas
committed
docs: update manual installation instructions
1 parent c8095b5 commit c71a28d

File tree

1 file changed

+19
-224
lines changed

1 file changed

+19
-224
lines changed

‎docs/modules/ROOT/pages/install.adoc

Lines changed: 19 additions & 224 deletions
Original file line numberDiff line numberDiff line change
@@ -26,7 +26,7 @@ Or if you just want to install MrDocs without cloning the repository, you can ru
2626
2727
[tabs]
2828
====
29-
Windows::
29+
Windows PowerShell::
3030
+
3131
--
3232
[source,powershell]
@@ -143,56 +143,6 @@ All instructions in this document assume you are using a CMake version above 3.2
143143
Binaries are available at https://cmake.org/download/[CMake's official website,window="_blank"].
144144
====
145145
146-
If you prefer using Vcpkg to install dependencies, you can install VcPkg and `fmt` with the following commands from the `third-party` directory:
147-
148-
:tabs-sync-option:
149-
150-
[tabs]
151-
====
152-
Windows PowerShell::
153-
+
154-
--
155-
[source,bash]
156-
----
157-
git clone https://github.com/microsoft/vcpkg.git -b master <.>
158-
cd vcpkg
159-
bootstrap-vcpkg.bat <.>
160-
vcpkg.exe install fmt --triplet x64-windows <.>
161-
----
162-
163-
<.> Clones the Vcpkg repository.
164-
<.> Bootstraps Vcpkg.
165-
<.> Installs the `fmt` library.
166-
--
167-
168-
Unix Variants::
169-
+
170-
--
171-
[source,bash]
172-
----
173-
git clone https://github.com/microsoft/vcpkg.git -b master <.>
174-
cd vcpkg
175-
./bootstrap-vcpkg.sh <.>
176-
./vcpkg install fmt <.>
177-
----
178-
179-
<.> Clones the Vcpkg repository.
180-
<.> Bootstraps Vcpkg.
181-
<.> Installs the `fmt` library.
182-
--
183-
====
184-
185-
[NOTE]
186-
====
187-
You can also install `fmt` with Vcpkg in _Manifest mode_.
188-
In https://learn.microsoft.com/en-us/vcpkg/users/manifests[manifest mode,windows=blank_], you declare your project's direct dependencies in a manifest file named `vcpkg.json`.
189-
MrDocs includes a `vcpkg.json.example` file you can duplicate or create a symlink as `vcpkg.json` to use this mode.
190-
This file includes all the dependencies MrDocs needs, except for LLVM.
191-
192-
In this mode, VcPkg will create separate installed trees for each project and configuration.
193-
This is the recommended vcpkg mode for most users, according to the https://learn.microsoft.com/en-us/vcpkg/users/manifests[vcpkg documentation,window=blank_].
194-
====
195-
196146
=== Duktape
197147
198148
MrDocs uses the `duktape` library for JavaScript parsing.
@@ -295,37 +245,6 @@ cmake --install ./build --prefix ./install <.>
295245
The scripts above download the `duktape` source code, extract it, and configure it with CMake.
296246
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.
297247
298-
If you prefer using Vcpkg to install dependencies, you can install `duktape` with the following commands from the `third-party` directory:
299-
300-
[tabs]
301-
====
302-
Windows PowerShell::
303-
+
304-
--
305-
[source,bash]
306-
----
307-
cd vcpkg
308-
vcpkg.exe install duktape --triplet x64-windows <.>
309-
----
310-
311-
<.> Installs the `duktape` library.
312-
--
313-
314-
Unix Variants::
315-
+
316-
--
317-
[source,bash]
318-
----
319-
cd vcpkg
320-
./vcpkg install duktape <.>
321-
----
322-
323-
<.> Installs the `duktape` library.
324-
--
325-
====
326-
327-
NOTE: These examples assume VcPkg is already installed in the `third-party/vcpkg` directory (see the <<install-fmt>> section).
328-
329248
=== Libxml2
330249
331250
MrDocs uses `libxml2` tools for tests.
@@ -349,37 +268,6 @@ cd ..
349268
<.> Builds libxml2 in the `build` directory.
350269
<.> Installs libxml2 in the `install` directory.
351270
352-
If you prefer using Vcpkg to install dependencies, you can install `libxml2` with the following commands from the `third-party` directory:
353-
354-
[tabs]
355-
====
356-
Windows PowerShell::
357-
+
358-
--
359-
[source,bash]
360-
----
361-
cd vcpkg
362-
vcpkg.exe install libxml2[tools] --triplet x64-windows <.>
363-
----
364-
365-
<.> Installs `libxml2`.
366-
--
367-
368-
Unix Variants::
369-
+
370-
--
371-
[source,bash]
372-
----
373-
cd vcpkg
374-
./vcpkg install libxml2[tools] <.>
375-
----
376-
377-
<.> Installs `libxml2`.
378-
--
379-
====
380-
381-
NOTE: These examples assume VcPkg is already installed in the `third-party/vcpkg` directory (see the <<install-fmt>> section).
382-
383271
=== LLVM
384272
385273
MrDocs uses LLVM to parse C++ code and extract documentation from it.
@@ -428,7 +316,7 @@ Windows PowerShell::
428316
[source,bash]
429317
----
430318
cd llvm
431-
cmake -S . -B ./build --preset=release-win
319+
cmake -S . -B ./build --preset=release-win -DLLVM_ENABLE_RUNTIMES=libcxx
432320
----
433321
--
434322
@@ -438,7 +326,7 @@ Unix Variants::
438326
[source,bash]
439327
----
440328
cd llvm
441-
cmake -S . -B ./build --preset=release-unix
329+
cmake -S . -B ./build --preset=release-unix -DLLVM_ENABLE_RUNTIMES=libcxx;libcxxabi;libunwind
442330
----
443331
--
444332
====
@@ -475,68 +363,26 @@ Return from `./third-party/llvm-project/llvm` to the LLVM project directory:
475363
cd ../..
476364
----
477365
478-
=== LibC++
479-
480-
In addition to LLVM, MrDocs requires a deterministic version of the C++ standard library (LibC++) to ensure consistent behavior across various environments.
481-
This step is crucial for replicating specific compiler and library configurations.
482-
483-
**Download**:
484-
485-
Continue using the same LLVM project directory.
486-
487-
**Configure**:
366+
=== MrDocs
488367
489-
Configure and build LibC++ using the existing structure:
368+
Return to the parent directory of `third-party` (the one containing the `mrdocs` directory) to build and install MrDocs:
490369
491370
[source,bash]
492371
----
493-
export CXX="./install/bin/clang++"
494-
export CC="./install/bin/clang"
372+
cd ../..
495373
----
496374
497-
These options set the C and pass:[C++] compilers to the ones previously installed by LLVM.
498-
MrDocs only depends on the pass:[LibC++] headers, so any compiler that works for this step should be fine.
499-
500-
Run a command such as the following to configure LLVM:
375+
**Configure**:
501376
502-
[tabs]
503-
====
504-
Windows PowerShell::
505-
+
506-
--
507-
[source,bash]
508-
----
509-
cmake -G Ninja \
510-
-S runtimes \
511-
-B build-libcxx \
512-
-DLLVM_ENABLE_RUNTIMES="libcxx;libcxxabi" \
513-
-DCMAKE_INSTALL_PREFIX="$(pwd)/install" \
514-
-DLIBCXXABI_USE_LLVM_UNWINDER=OFF \
515-
-DLIBCXXABI_ENABLE_SHARED=OFF \
516-
-DLIBCXXABI_ENABLE_STATIC=ON \
517-
-DLIBCXX_ENABLE_SHARED=OFF \
518-
-DLIBCXX_NO_VCRUNTIME=ON \
519-
-DCMAKE_CXX_FLAGS="-D__ORDER_LITTLE_ENDIAN__=1234 -D__ORDER_BIG_ENDIAN__=4321 -D__BYTE_ORDER__=__ORDER_LITTLE_ENDIAN__"
520-
----
521-
--
377+
The MrDocs repository also includes a `CMakePresets.json` file that contains the parameters to configure MrDocs with CMake.
522378
523-
Unix Variants::
524-
+
525-
--
526-
[source,bash]
527-
----
528-
cmake -G Ninja \
529-
-S runtimes \
530-
-B build-libcxx \
531-
-DLLVM_ENABLE_RUNTIMES="libcxx;libcxxabi;libunwind" \
532-
-DCMAKE_INSTALL_PREFIX="$(pwd)/install"
533-
----
534-
--
535-
====
379+
To specify the installation directories, you can use the `LLVM_ROOT`, `DUKTAPE_ROOT`, `FMT_ROOT`, and `LIBXML2_ROOT` environment variables.
380+
To specify a generator (`-G`) and platform name (`-A`), you can use the `CMAKE_GENERATOR` and `CMAKE_GENERATOR_PLATFORM` environment variables.
536381
537-
**Build**:
382+
You can also customize the presets by duplicating and editing the `CMakeUserPresets.json.example` file in the `mrdocs` directory.
383+
This is typically more convenient than using environment variables.
538384
539-
Build and install the configured version of LibC++ with:
385+
For instance, to build MrDocs with the default `Release` preset, you can run the following command:
540386
541387
[tabs]
542388
====
@@ -545,8 +391,8 @@ Windows PowerShell::
545391
--
546392
[source,bash]
547393
----
548-
ninja -C build-libcxx cxx
549-
ninja -C build-libcxx install-cxx
394+
cd mrdocs
395+
cmake -S . --preset=release-win
550396
----
551397
--
552398
@@ -555,69 +401,19 @@ Unix Variants::
555401
--
556402
[source,bash]
557403
----
558-
ninja -C build-libcxx cxx cxxabi unwind
559-
ninja -C build-libcxx install-cxx install-cxxabi install-unwind
404+
cd mrdocs
405+
cmake -S . --preset=release-unix
560406
----
561407
--
562408
====
563409
564-
Return from `./third-party/llvm-project` to the parent directory to build and install MrDocs:
410+
To list the available presets, you can run:
565411
566412
[source,bash]
567413
----
568-
cd ../..
414+
cmake --list-presets
569415
----
570416
571-
=== MrDocs
572-
573-
Return from `./third-party/vcpkg` to the parent directory of `third-party` (the one containing the `mrdocs` directory) to build and install MrDocs:
574-
575-
[source,bash]
576-
----
577-
cd ../..
578-
----
579-
580-
**Configure**:
581-
582-
You can also configure MrDocs with <<mrdocs-configure-cmd-line, command line arguments>> or <<mrdocs-configure-presets, CMake presets>>.
583-
584-
[#mrdocs-configure-cmd-line]
585-
_Configure with Command Line Arguments_:
586-
587-
With the dependencies are available in `third-party`, you can configure MrDocs with:
588-
589-
[tabs]
590-
====
591-
Windows PowerShell::
592-
+
593-
--
594-
[source,commandline]
595-
----
596-
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"
597-
----
598-
--
599-
600-
Unix Variants::
601-
+
602-
--
603-
[source,bash]
604-
----
605-
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"
606-
----
607-
--
608-
====
609-
610-
[#mrdocs-configure-presets]
611-
_Configure with CMake Presets_:
612-
613-
The MrDocs repository also includes a `CMakePresets.json` file that contains the parameters to configure MrDocs with CMake.
614-
615-
To specify the installation directories, you can use the `LLVM_ROOT`, `DUKTAPE_SOURCE_ROOT`, `CMAKE_TOOLCHAIN_FILE` environment variables.
616-
To specify a generator (`-G`) and platform name (`-A`), you can use the `CMAKE_GENERATOR` and `CMAKE_GENERATOR_PLATFORM` environment variables.
617-
618-
You can also customize the presets by duplicating and editing the `CMakeUserPresets.json.example` file in the `mrdocs` directory.
619-
This is typically more convenient than using environment variables.
620-
621417
**Build**:
622418
623419
Then build and install MrDocs with:
@@ -635,7 +431,6 @@ To customize the C and C++ compilers, use the `CMAKE_C_COMPILER` and `CMAKE_CXX_
635431
[NOTE]
636432
====
637433
Developers should also enable `-D BUILD_TESTING=ON`.
638-
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.
639434
====
640435
641436
== Package layout

0 commit comments

Comments
 (0)