Skip to content

Commit 3491224

Browse files
alandefreitasalandefreitas
committed
docs: installation instructions are relative to enclosing directory
1 parent ba63ed0 commit 3491224

File tree

2 files changed

+164
-72
lines changed

2 files changed

+164
-72
lines changed

‎CMakeLists.txt

Lines changed: 47 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -65,7 +65,31 @@ endif()
6565

6666
set(CMAKE_FOLDER Dependencies)
6767

68-
# LLVM
68+
# LLVM + Clang
69+
if (LLVM_ROOT)
70+
# LLVM_ROOT is absolute
71+
get_filename_component(LLVM_ROOT "${LLVM_ROOT}" ABSOLUTE)
72+
set(LLVM_ROOT "${LLVM_ROOT}" CACHE PATH "Root of LLVM install." FORCE)
73+
if (NOT EXISTS "${LLVM_ROOT}")
74+
message(FATAL_ERROR
75+
"LLVM_ROOT (${LLVM_ROOT}) provided does not exist.\n"
76+
"Please set LLVM_ROOT to the root of LLVM install.\n")
77+
endif()
78+
if (NOT EXISTS "${LLVM_ROOT}/lib/cmake/llvm")
79+
message(FATAL_ERROR
80+
"LLVM_ROOT (${LLVM_ROOT}) provided is invalid.\n"
81+
"No <LLVM_ROOT>/lib/cmake/llvm found.\n"
82+
"Please set LLVM_ROOT to the root of LLVM install.\n")
83+
endif()
84+
endif()
85+
if (Clang_ROOT)
86+
# Clang_ROOT is absolute
87+
get_filename_component(Clang_ROOT "${Clang_ROOT}" ABSOLUTE)
88+
set(LLVM_ROOT "${LLVM_ROOT}" CACHE PATH "Root of Clang install." FORCE)
89+
elseif (LLVM_ROOT)
90+
# Clang_ROOT matches LLVM_ROOT by default
91+
set(Clang_ROOT "${LLVM_ROOT}" CACHE PATH "Root of Clang install." FORCE)
92+
endif()
6993
find_package(LLVM REQUIRED CONFIG)
7094
find_package(Clang REQUIRED CONFIG)
7195
list(APPEND CMAKE_MODULE_PATH "${LLVM_CMAKE_DIR}")
@@ -83,6 +107,17 @@ if (NOT DUKTAPE_SOURCE_ROOT)
83107
"Please set DUKTAPE_SOURCE_ROOT to the root of the Duktape source tree.\n"
84108
"https://github.com/svaarala/duktape/releases/download/v2.7.0/duktape-2.7.0.tar.xz\n")
85109
endif()
110+
if (NOT EXISTS "${DUKTAPE_SOURCE_ROOT}")
111+
message(FATAL_ERROR
112+
"DUKTAPE_SOURCE_ROOT (${DUKTAPE_SOURCE_ROOT}) does not exist.\n")
113+
endif()
114+
if (NOT EXISTS "${DUKTAPE_SOURCE_ROOT}/src/duktape.c")
115+
message(FATAL_ERROR
116+
"DUKTAPE_SOURCE_ROOT (${DUKTAPE_SOURCE_ROOT}) is invalid.\n"
117+
"No /src/duktape.c found.\n"
118+
"Please set DUKTAPE_SOURCE_ROOT to the root of the Duktape source tree.\n")
119+
endif()
120+
get_filename_component(DUKTAPE_SOURCE_ROOT "${DUKTAPE_SOURCE_ROOT}" ABSOLUTE)
86121
add_library(duktape ${DUKTAPE_SOURCE_ROOT}/src/duktape.c ${DUKTAPE_SOURCE_ROOT}/src/duktape.h)
87122
target_include_directories(
88123
duktape PUBLIC
@@ -159,12 +194,13 @@ if (WIN32)
159194
-D_SILENCE_CXX20_CISO646_REMOVED_WARNING
160195
-DFMT_HEADER_ONLY # because of _ITERATOR_DEBUG_LEVEL
161196
)
162-
get_target_property(LLVM_CONFIGURATION_TYPE LLVMCore IMPORTED_CONFIGURATIONS)
163-
if (LLVM_CONFIGURATION_TYPE STREQUAL RELWITHDEBINFO)
164-
target_compile_definitions(mrdox-core PUBLIC -D_ITERATOR_DEBUG_LEVEL=0)
165-
target_compile_options(mrdox-core PUBLIC /MD)
166-
endif()
167197
if(MSVC)
198+
get_target_property(LLVM_CONFIGURATION_TYPE LLVMCore IMPORTED_CONFIGURATIONS)
199+
if (LLVM_CONFIGURATION_TYPE STREQUAL RELWITHDEBINFO)
200+
# Handle Debug/RelWithDebInfo mismatch between mrdox and LLVM
201+
target_compile_definitions(mrdox-core PUBLIC $<$<CONFIG:Debug>:-D_ITERATOR_DEBUG_LEVEL=0>)
202+
target_compile_options(mrdox-core PUBLIC $<$<CONFIG:Debug>:/MD>)
203+
endif()
168204
if("${CMAKE_GENERATOR_PLATFORM}" STREQUAL "Win64") # 64-bit
169205
target_compile_options(mrdox-core PUBLIC /arch:AMD64)
170206
endif()
@@ -343,8 +379,12 @@ if (MRDOX_BUILD_DOCS)
343379
if (MRDOX_GENERATE_REFERENCE AND MRDOX_GENERATE_ANTORA_REFERENCE)
344380
add_dependencies(generate_docs generate_antora_reference)
345381
endif()
382+
elseif (NOT NPM_EXECUTABLE AND NPX_EXECUTABLE)
383+
message(WARNING "NPM not found. Unable to generate documentation.")
384+
elseif (NPM_EXECUTABLE AND NOT NPX_EXECUTABLE)
385+
message(WARNING "NPX not found. Unable to generate documentation.")
346386
else()
347-
message(WARNING "NPM or NPX not found. Unable to generate documentation.")
387+
message(WARNING "NPM and NPX not found. Unable to generate documentation.")
348388
endif()
349389
endif ()
350390

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

Lines changed: 117 additions & 65 deletions
Original file line numberDiff line numberDiff line change
@@ -6,41 +6,39 @@ Binary packages are available from our https://github.com/cppalliance/mrdox/rele
66

77
== Source
88

9-
For consistency, these instructions assume you are using the `SRC_DIR` variable to refer to the directory where you are going to clone MrDox and any other requirements.
10-
Please create an environment variable with that directory and adjust it accordingly.
11-
For instance:
9+
=== Cloning MrDox
1210

13-
Windows (Command Prompt):
14-
15-
[source,commandline]
16-
----
17-
set SRC_DIR=C:\Users\%USERNAME%\src
18-
echo %SRC_DIR%
19-
----
20-
21-
Windows (PowerShell):
11+
Clone the MrDox repository with:
2212

2313
[source,bash]
2414
----
25-
$env:SRC_DIR = "C:\Users\$env:USERNAME\src"
26-
echo $env:SRC_DIR
15+
git clone https://github.com/cppalliance/mrdox
2716
----
2817

29-
Unix-variants (Linux, macOS, etc.):
18+
=== Requirements
19+
20+
Create and go to the `third-party` directory, where we are going to download and install our custom dependencies:
3021

3122
[source,bash]
3223
----
33-
export SRC_DIR="$HOME/src"
34-
echo $SRC_DIR
24+
mkdir third-party
25+
cd third-party
3526
----
3627

37-
=== Requirements
28+
[NOTE]
29+
====
30+
These instructions assume all dependencies are installed in the `third-party` directory for simplicity.
31+
Fell free to install them anywhere you want and adjust the main MrDox configuration command later.
32+
====
33+
34+
=== LLVM
3835

39-
==== LLVM
36+
MrDox depends on a specific recent version of LLVM: https://github.com/llvm/llvm-project/tree/731264b0c2af7aa46bd39625202a99e06cfccff9[731264b0]
4037

41-
MrDox depends on a recent version of LLVM.
38+
Because building LLVM may take many hours to complete, we provide pre-built binaries for Windows and Linux: https://mrdox.com/llvm+clang/[LLVM Releases].
39+
You can download the binaries and uncompress them in the `./third-party/llvm+clang` directory.
4240

43-
Here are the instructions to clone LLVM version required by this project.
41+
Alternatively, if building LLVM from source, you can clone the project from the official repository:
4442

4543
[source,bash]
4644
----
@@ -49,107 +47,161 @@ cd llvm-project
4947
git checkout 731264b0c2af7aa46bd39625202a99e06cfccff9
5048
----
5149

52-
Here are the instructions to build and install LLVM with the settings required by this project.
50+
Configure LLVM with the settings required by MrDox:
5351

54-
Windows:
52+
Windows (from administrator `cmd.exe`, after running `vcvars64.bat`):
5553

5654
[source,commandline]
5755
----
58-
# From Administrator CMD.EXE, after running vcvars64.bat
59-
cmake -S . -B build -G "Visual Studio 17 2022" -A x64 -D LLVM_ENABLE_PROJECTS="clang;clang-tools-extra" -D CMAKE_CONFIGURATION_TYPES="Debug;RelWithDebInfo" -D LLVM_ENABLE_RTTI=ON -D CMAKE_INSTALL_PREFIX=%SRC_DIR%/llvm+clang -D LLVM_ENABLE_IDE=OFF -D LLVM_ENABLE_DIA_SDK=OFF
60-
cd build
61-
cmake --build . --config RelWithDebInfo -j %NUMBER_OF_PROCESSORS%
62-
cmake --build . --config Debug -j %NUMBER_OF_PROCESSORS%
63-
cmake --install . --prefix "%SRC_DIR%/llvm+clang/Debug" --config Debug
64-
cmake --install . --prefix "%SRC_DIR%/llvm+clang/RelWithDebInfo" --config RelWithDebInfo
56+
cmake -S llvm -B build -G "Visual Studio 17 2022" -A x64 -D LLVM_ENABLE_PROJECTS="clang;clang-tools-extra" -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
6557
----
6658

6759
Unix variants:
6860

6961
[source,bash]
7062
----
71-
cmake -S llvm -B build -D LLVM_ENABLE_PROJECTS="clang;clang-tools-extra" -D CMAKE_BUILD_TYPE=RelWithDebInfo -D LLVM_ENABLE_RTTI=ON -D CMAKE_INSTALL_PREFIX=$SRC_DIR/llvm+clang/RelWithDebInfo
63+
cmake -S llvm -B build -D LLVM_ENABLE_PROJECTS="clang;clang-tools-extra" -D CMAKE_BUILD_TYPE=RelWithDebInfo -D LLVM_ENABLE_RTTI=ON -D CMAKE_INSTALL_PREFIX=../llvm+clang/RelWithDebInfo
64+
----
65+
66+
As you can see from the step above, we configure a `RelWithDebInfo` version of LLVM for MrDox by default.
67+
This is a release build with debug information.
68+
Other possible CMake configurations supported by LLVM are `Debug` (including debug information and no optimizations), `Release` (including optimizations and no debug information), and `MinSizeRel` (which optimizes for size).
69+
70+
[NOTE]
71+
====
72+
Developers might also want to build a custom `Debug` LLVM configuration including optimizations, which allows for faster execution of tests.
73+
To create such an installation, 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"`.
74+
75+
This should give you an optimized build with all debug features and flags, such as an appropriate https://learn.microsoft.com/en-us/cpp/standard-library/iterator-debug-level[`_ITERATOR_DEBUG_LEVEL`] and the `/MDd` flag in MSVC.
76+
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.
77+
78+
This custom configuration can be installed in an alternative directory, such as `../llvm+clang/DebWithOpt`, to be used by the MrDox `Debug` builds by developers.
79+
====
80+
81+
Then build and install it:
82+
83+
[source,bash]
84+
----
7285
cd build
73-
cmake --build . -j "$(nproc)"
74-
cmake --install .
86+
cmake --build . --config RelWithDebInfo
87+
cmake --install . --prefix ../../llvm+clang/RelWithDebInfo" --config RelWithDebInfo
88+
----
89+
90+
Return from `./third-party/llvm-project/build` to the parent `third-party` directory to install other dependencies:
91+
92+
[source,bash]
93+
----
94+
cd ../..
7595
----
7696

7797
==== Duktape
7898

7999
Duktape is a JavaScript engine that is used by MrDox to parse and evaluate JavaScript code.
80-
It provides no CMake integration scripts.
81-
The MrDox configuration script needs direct access to the installed source files for Duktape.
82100

83101
The release files can be obtained from the Duktape repository:
84102

85-
Windows:
86-
87-
[source,commandline]
103+
[source,bash]
88104
----
89105
curl -L -o "duktape-2.7.0.tar.xz" "https://github.com/svaarala/duktape/releases/download/v2.7.0/duktape-2.7.0.tar.xz"
90-
duktape_dir="%SRC_DIR%\duktape"
91-
mkdir "%duktape_dir%"
92-
tar -xvf "duktape-2.7.0.tar.xz" -C "%duktape_dir%"
106+
tar -xvf "duktape-2.7.0.tar.xz"
93107
----
94108

95-
Unix variants:
109+
Duktape provides no CMake integration scripts.
110+
The MrDox configuration script needs direct access to the installed source files for Duktape so that's all you need to do.
111+
112+
==== VcPkg dependencies
113+
114+
These other dependencies provide CMake integration scripts and can be obtained from https://www.vcpkg.io/[vcpkg] or installed manually.
115+
These instructions assume you are using VcPkg.
116+
117+
* `fmt` >= 10
118+
* `zlib`
119+
120+
For development builds, which include tests, you will also need:
121+
122+
* `libxml2[tools]`
123+
124+
To install these dependencies with VcPkg, first clone the repository:
96125

97126
[source,bash]
98127
----
99-
curl -L -o "duktape-2.7.0.tar.xz" "https://github.com/svaarala/duktape/releases/download/v2.7.0/duktape-2.7.0.tar.xz"
100-
duktape_dir="$SRC_DIR/duktape"
101-
mkdir -p "$duktape_dir"
102-
tar -xvf "duktape-2.7.0.tar.xz" -C "$duktape_dir"
128+
git clone https://github.com/microsoft/vcpkg.git -b master
129+
cd vcpkg
103130
----
104131

105-
==== Other dependencies
132+
Then bootstrap it and install the required dependencies:
106133

107-
These other dependencies provide CMake integration scripts.
108-
They can be obtained from https://www.vcpkg.io/[vcpkg] or installed manually.
134+
Windows:
109135

110-
* fmt >= 10
111-
* zlib
112-
* libtinfo
136+
[source,bash]
137+
----
138+
bootstrap-vcpkg.bat
139+
vcpkg.exe fmt zlib libxml2[tools] --triplet x64-windows
140+
----
113141

114-
=== MrDox
142+
Unix variants:
143+
144+
[source,bash]
145+
----
146+
./bootstrap-vcpkg.sh
147+
./vcpkg fmt zlib libxml2[tools]
148+
----
115149

116-
Once the dependencies are available in `SRC_DIR`, you can download MrDox:
150+
Return from `./third-party/vcpkg` to the parent directory of `third-party` (the one containing the `mrdox` directory) to build and install MrDox:
117151

118152
[source,bash]
119153
----
120-
git clone https://github.com/cppalliance/mrdox
121-
cd mrdox
154+
cd ../..
122155
----
123156

124-
Configure it with:
157+
=== MrDox
158+
159+
Once the dependencies are available in `third-party`, you can configure MrDox with:
125160

126161
Windows:
127162

128-
[source,bash]
163+
[source,commandline]
129164
----
130-
git clone https://github.com/cppalliance/mrdox
131-
cd mrdox
132-
cmake -G "Visual Studio 17 2022" -A x64 -B bin64 -D CMAKE_PREFIX_PATH="%SRC_DIR%/llvm+clang/RelWithDebInfo" -D DUKTAPE_SOURCE_ROOT="%SRC_DIR%\duktape\duktape-2.7.0"
165+
cmake -S mrdox -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"
133166
----
134167

135168
Unix variants:
136169

137170
[source,bash]
138171
----
139-
git clone https://github.com/cppalliance/mrdox
140-
cd mrdox
141-
cmake -S . -B build -D CMAKE_BUILD_TYPE=Release -D LLVM_ROOT=/path/to/llvm+clang/RelWithDebInfo -D Clang_ROOT=/path/to/llvm+clang/RelWithDebInfo -D DUKTAPE_SOURCE_ROOT="$SRC_DIR/duktape/duktape-2.7.0"
172+
cmake -S mrdox -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"
142173
----
143174

175+
[TIP]
176+
====
177+
The MrDox repository also includes a `CMakePresets.json` file that contains the parameters to configure MrDox with CMake.
178+
179+
To specify the installation directories, you can use the `LLVM_ROOT`, `DUKTAPE_SOURCE_ROOT`, `CMAKE_TOOLCHAIN_FILE` environment variables.
180+
To specify a generator (`-G`) and platform name (`-A`), you can use the `CMAKE_GENERATOR` and `CMAKE_GENERATOR_PLATFORM` environment variables.
181+
182+
Alternatively, you can create a `CMakeUserPresets.json` file in the `mrdox` directory with the specific values you want to override in each configuration.
183+
This is typically more convenient than using environment variables when working on an IDE.
184+
The repository includes a `CMakeUserPresets.json.example` file that can be used as a template.
185+
====
186+
144187
Then build and install it with:
145188

146189
[source,bash]
147190
----
148191
cd build
149-
cmake --build . -j <threads>
192+
cmake --build .
150193
cmake --install .
151194
----
152195

196+
To customize the installation directory, use the `CMAKE_INSTALL_PREFIX` option or use the `--prefix` option for the `cmake --install .` command.
197+
To customize the C and C++ compilers, use the `CMAKE_C_COMPILER` and `CMAKE_CXX_COMPILER` options.
198+
199+
[NOTE]
200+
====
201+
Developers should also enable `-D BUILD_TESTING=ON`.
202+
If any custom build of LLVM is being used (such as `DebWithOpt`), the `LLVM_ROOT` variable should be set to the installation directory of that build.
203+
====
204+
153205
== Package layout
154206

155207
The MrDox installation directory follows the "Filesystem Hierarchy Standard" (FHS) layout:

0 commit comments

Comments
 (0)