Skip to content

Commit

Permalink
docs: installation instructions are relative to enclosing directory
Browse files Browse the repository at this point in the history
  • Loading branch information
@alandefreitas
alandefreitas committed Aug 15, 2023
1 parent ba63ed0 commit 3491224
Show file tree
Hide file tree
Showing 2 changed files with 164 additions and 72 deletions.
54 changes: 47 additions & 7 deletions CMakeLists.txt
View file
Original file line number Diff line number Diff line change
Expand Up @@ -65,7 +65,31 @@ endif()

set(CMAKE_FOLDER Dependencies)

# LLVM
# LLVM + Clang
if (LLVM_ROOT)
# LLVM_ROOT is absolute
get_filename_component(LLVM_ROOT "${LLVM_ROOT}" ABSOLUTE)
set(LLVM_ROOT "${LLVM_ROOT}" CACHE PATH "Root of LLVM install." FORCE)
if (NOT EXISTS "${LLVM_ROOT}")
message(FATAL_ERROR
"LLVM_ROOT (${LLVM_ROOT}) provided does not exist.\n"
"Please set LLVM_ROOT to the root of LLVM install.\n")
endif()
if (NOT EXISTS "${LLVM_ROOT}/lib/cmake/llvm")
message(FATAL_ERROR
"LLVM_ROOT (${LLVM_ROOT}) provided is invalid.\n"
"No <LLVM_ROOT>/lib/cmake/llvm found.\n"
"Please set LLVM_ROOT to the root of LLVM install.\n")
endif()
endif()
if (Clang_ROOT)
# Clang_ROOT is absolute
get_filename_component(Clang_ROOT "${Clang_ROOT}" ABSOLUTE)
set(LLVM_ROOT "${LLVM_ROOT}" CACHE PATH "Root of Clang install." FORCE)
elseif (LLVM_ROOT)
# Clang_ROOT matches LLVM_ROOT by default
set(Clang_ROOT "${LLVM_ROOT}" CACHE PATH "Root of Clang install." FORCE)
endif()
find_package(LLVM REQUIRED CONFIG)
find_package(Clang REQUIRED CONFIG)
list(APPEND CMAKE_MODULE_PATH "${LLVM_CMAKE_DIR}")
Expand All @@ -83,6 +107,17 @@ if (NOT DUKTAPE_SOURCE_ROOT)
"Please set DUKTAPE_SOURCE_ROOT to the root of the Duktape source tree.\n"
"https://github.com/svaarala/duktape/releases/download/v2.7.0/duktape-2.7.0.tar.xz\n")
endif()
if (NOT EXISTS "${DUKTAPE_SOURCE_ROOT}")
message(FATAL_ERROR
"DUKTAPE_SOURCE_ROOT (${DUKTAPE_SOURCE_ROOT}) does not exist.\n")
endif()
if (NOT EXISTS "${DUKTAPE_SOURCE_ROOT}/src/duktape.c")
message(FATAL_ERROR
"DUKTAPE_SOURCE_ROOT (${DUKTAPE_SOURCE_ROOT}) is invalid.\n"
"No /src/duktape.c found.\n"
"Please set DUKTAPE_SOURCE_ROOT to the root of the Duktape source tree.\n")
endif()
get_filename_component(DUKTAPE_SOURCE_ROOT "${DUKTAPE_SOURCE_ROOT}" ABSOLUTE)
add_library(duktape ${DUKTAPE_SOURCE_ROOT}/src/duktape.c ${DUKTAPE_SOURCE_ROOT}/src/duktape.h)
target_include_directories(
duktape PUBLIC
Expand Down Expand Up @@ -159,12 +194,13 @@ if (WIN32)
-D_SILENCE_CXX20_CISO646_REMOVED_WARNING
-DFMT_HEADER_ONLY # because of _ITERATOR_DEBUG_LEVEL
)
get_target_property(LLVM_CONFIGURATION_TYPE LLVMCore IMPORTED_CONFIGURATIONS)
if (LLVM_CONFIGURATION_TYPE STREQUAL RELWITHDEBINFO)
target_compile_definitions(mrdox-core PUBLIC -D_ITERATOR_DEBUG_LEVEL=0)
target_compile_options(mrdox-core PUBLIC /MD)
endif()
if(MSVC)
get_target_property(LLVM_CONFIGURATION_TYPE LLVMCore IMPORTED_CONFIGURATIONS)
if (LLVM_CONFIGURATION_TYPE STREQUAL RELWITHDEBINFO)
# Handle Debug/RelWithDebInfo mismatch between mrdox and LLVM
target_compile_definitions(mrdox-core PUBLIC $<$<CONFIG:Debug>:-D_ITERATOR_DEBUG_LEVEL=0>)
target_compile_options(mrdox-core PUBLIC $<$<CONFIG:Debug>:/MD>)
endif()
if("${CMAKE_GENERATOR_PLATFORM}" STREQUAL "Win64") # 64-bit
target_compile_options(mrdox-core PUBLIC /arch:AMD64)
endif()
Expand Down Expand Up @@ -343,8 +379,12 @@ if (MRDOX_BUILD_DOCS)
if (MRDOX_GENERATE_REFERENCE AND MRDOX_GENERATE_ANTORA_REFERENCE)
add_dependencies(generate_docs generate_antora_reference)
endif()
elseif (NOT NPM_EXECUTABLE AND NPX_EXECUTABLE)
message(WARNING "NPM not found. Unable to generate documentation.")
elseif (NPM_EXECUTABLE AND NOT NPX_EXECUTABLE)
message(WARNING "NPX not found. Unable to generate documentation.")
else()
message(WARNING "NPM or NPX not found. Unable to generate documentation.")
message(WARNING "NPM and NPX not found. Unable to generate documentation.")
endif()
endif ()

Expand Down
182 changes: 117 additions & 65 deletions docs/modules/ROOT/pages/install.adoc
View file
Original file line number Diff line number Diff line change
Expand Up @@ -6,41 +6,39 @@ Binary packages are available from our https://github.com/cppalliance/mrdox/rele

== Source

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.
Please create an environment variable with that directory and adjust it accordingly.
For instance:
=== Cloning MrDox

Windows (Command Prompt):

[source,commandline]
----
set SRC_DIR=C:\Users\%USERNAME%\src
echo %SRC_DIR%
----

Windows (PowerShell):
Clone the MrDox repository with:

[source,bash]
----
$env:SRC_DIR = "C:\Users\$env:USERNAME\src"
echo $env:SRC_DIR
git clone https://github.com/cppalliance/mrdox
----

Unix-variants (Linux, macOS, etc.):
=== Requirements

Create and go to the `third-party` directory, where we are going to download and install our custom dependencies:

[source,bash]
----
export SRC_DIR="$HOME/src"
echo $SRC_DIR
mkdir third-party
cd third-party
----

=== Requirements
[NOTE]
====
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 MrDox configuration command later.
====

=== LLVM

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

MrDox depends on a recent version of LLVM.
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].
You can download the binaries and uncompress them in the `./third-party/llvm+clang` directory.

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

[source,bash]
----
Expand All @@ -49,107 +47,161 @@ cd llvm-project
git checkout 731264b0c2af7aa46bd39625202a99e06cfccff9
----

Here are the instructions to build and install LLVM with the settings required by this project.
Configure LLVM with the settings required by MrDox:

Windows:
Windows (from administrator `cmd.exe`, after running `vcvars64.bat`):

[source,commandline]
----
# From Administrator CMD.EXE, after running vcvars64.bat
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
cd build
cmake --build . --config RelWithDebInfo -j %NUMBER_OF_PROCESSORS%
cmake --build . --config Debug -j %NUMBER_OF_PROCESSORS%
cmake --install . --prefix "%SRC_DIR%/llvm+clang/Debug" --config Debug
cmake --install . --prefix "%SRC_DIR%/llvm+clang/RelWithDebInfo" --config RelWithDebInfo
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
----

Unix variants:

[source,bash]
----
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
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
----

As you can see from the step above, we configure a `RelWithDebInfo` version of LLVM for MrDox by default.
This is a release build with debug information.
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).

[NOTE]
====
Developers might also want to build a custom `Debug` LLVM configuration including optimizations, which allows for faster execution of tests.
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"`.
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.
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.
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.
====

Then build and install it:

[source,bash]
----
cd build
cmake --build . -j "$(nproc)"
cmake --install .
cmake --build . --config RelWithDebInfo
cmake --install . --prefix ../../llvm+clang/RelWithDebInfo" --config RelWithDebInfo
----

Return from `./third-party/llvm-project/build` to the parent `third-party` directory to install other dependencies:

[source,bash]
----
cd ../..
----

==== Duktape

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

The release files can be obtained from the Duktape repository:

Windows:

[source,commandline]
[source,bash]
----
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"
duktape_dir="%SRC_DIR%\duktape"
mkdir "%duktape_dir%"
tar -xvf "duktape-2.7.0.tar.xz" -C "%duktape_dir%"
tar -xvf "duktape-2.7.0.tar.xz"
----

Unix variants:
Duktape provides no CMake integration scripts.
The MrDox configuration script needs direct access to the installed source files for Duktape so that's all you need to do.

==== VcPkg dependencies

These other dependencies provide CMake integration scripts and can be obtained from https://www.vcpkg.io/[vcpkg] or installed manually.
These instructions assume you are using VcPkg.

* `fmt` >= 10
* `zlib`

For development builds, which include tests, you will also need:

* `libxml2[tools]`

To install these dependencies with VcPkg, first clone the repository:

[source,bash]
----
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"
duktape_dir="$SRC_DIR/duktape"
mkdir -p "$duktape_dir"
tar -xvf "duktape-2.7.0.tar.xz" -C "$duktape_dir"
git clone https://github.com/microsoft/vcpkg.git -b master
cd vcpkg
----

==== Other dependencies
Then bootstrap it and install the required dependencies:

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

* fmt >= 10
* zlib
* libtinfo
[source,bash]
----
bootstrap-vcpkg.bat
vcpkg.exe fmt zlib libxml2[tools] --triplet x64-windows
----

=== MrDox
Unix variants:

[source,bash]
----
./bootstrap-vcpkg.sh
./vcpkg fmt zlib libxml2[tools]
----

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

[source,bash]
----
git clone https://github.com/cppalliance/mrdox
cd mrdox
cd ../..
----

Configure it with:
=== MrDox

Once the dependencies are available in `third-party`, you can configure MrDox with:

Windows:

[source,bash]
[source,commandline]
----
git clone https://github.com/cppalliance/mrdox
cd mrdox
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"
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"
----

Unix variants:

[source,bash]
----
git clone https://github.com/cppalliance/mrdox
cd mrdox
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"
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"
----

[TIP]
====
The MrDox repository also includes a `CMakePresets.json` file that contains the parameters to configure MrDox 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.
Alternatively, you can create a `CMakeUserPresets.json` file in the `mrdox` directory with the specific values you want to override in each configuration.
This is typically more convenient than using environment variables when working on an IDE.
The repository includes a `CMakeUserPresets.json.example` file that can be used as a template.
====

Then build and install it with:

[source,bash]
----
cd build
cmake --build . -j <threads>
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.

[NOTE]
====
Developers should also enable `-D BUILD_TESTING=ON`.
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.
====

== Package layout

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

0 comments on commit 3491224

Please sign in to comment.