diff --git a/docs/developer/build-environment/windows.md b/docs/developer/build-environment/windows.md
index 6d234b0fbabb7a303d7f8c4468b49f679782345a..537b474f3f89d050685faa80b90e99392d390bb4 100644
--- a/docs/developer/build-environment/windows.md
+++ b/docs/developer/build-environment/windows.md
@@ -25,12 +25,20 @@ The tools used are:
- Select all the default options and check the option to add Python to *PATH*.
+### Python Dependencies
+The only Python dependency we have is `pipenv` which is used to manage the Python environment.
+Install it by executing the following command in a terminal after you have **successfully** installed Python:
+
+```{.sh .copy}
+pip install pipenv
+```
+
---
## Install Build Tools
- Download the build tools from Microsoft: [Download Build Tools :octicons-link-external-16:](https://visualstudio.microsoft.com/downloads/?q=build+tools#build-tools-for-visual-studio-2022){:target="_blank"}
-The page should like something like this:
+The page should look something like this:
- Execute the installer and install at least these components:
diff --git a/docs/developer/build/cpp.md b/docs/developer/build/cpp.md
index 6e7b12ca203fe3bddcb09024c8bb0ba11ad9cfed..b4b93b49fb9c140014091c3ba3c542964dc790bf 100644
--- a/docs/developer/build/cpp.md
+++ b/docs/developer/build/cpp.md
@@ -46,6 +46,34 @@ Since **CMake** is independent of the used platform, it needs to figure out on w
**CMake** introduced the concept of [Presets :octicons-link-external-16:](https://cmake.org/cmake/help/latest/manual/cmake-presets.7.html){:target="_blank"} which allows to specify different sets of arguments which are passed to **CMake** when configuring the project.
We provide a basic preset file which contains a reasonable default configuration for each platform we support. You can however, create your own :octicons-file-16: `CMakeUserPresets.json` file along our preset file to override our settings. See [CMake Presets](../cmake-presets.md) for more information about that.
+### Available Presets
+We use the following naming pattern to identify the presets:
+
+```
+architecture-platform-configuration
+```
+
+Where *architecture* can be one of the following:
+
+- `x64` for 64-bit architectures (Currently the **only** one we support!)
+
+And *platform* can be one of the following:
+
+- `windows` for Windows
+- `linux` for Linux
+- `mingw` for MinGW on Windows (:warning: **Deprecated**)
+
+The *configuration* can be one of the following:
+
+- `release` for a release builds
+- `debug` for a debug builds
+
+Other configurations are possible, but not supported by our presets.
+You have to specify custom presets by [CMakeUserPresets](../cmake-presets.md).
+
+!!! note
+ In the following we always assume the **Release** configuration for building. The **Debug** configuration works analogously.
+
### Terminal
The programmers way to configure **CMake**:
@@ -55,20 +83,24 @@ The programmers way to configure **CMake**:
=== "Windows"
``` { .sh .copy }
- cmake -B build -S . --preset Windows
+ cmake -B build -S . --preset x64-windows-release
```
=== "MinGW"
``` { .sh .copy }
- cmake -B build -S . --preset MSYS2
+ cmake -B build -S . --preset x64-mingw-release
```
=== "Linux"
``` { .sh .copy }
- cmake -B build -S . --preset Linux
+ cmake -B build -S . --preset x64-linux-release
```
+!!! tip
+ The `-B` and `-S` are not needed anymore when using the preset. You can however still use them to specify the build directory and the source directory.
+ :fontawesome-solid-arrow-right: **In the following we will omit them.**
+
During this configuration, **CMake** generates a cache file which remembers some parameters which are re-used when you configure **CMake** again.
This cache files is __not__ automatically deleted/updated, which can lead to some unexpected behavior.
When this happens, you can tell **CMake** explicitly to refresh this cache by:
@@ -76,21 +108,21 @@ When this happens, you can tell **CMake** explicitly to refresh this cache by:
=== "Windows"
``` { .sh .copy }
- cmake -B build -S . --preset Windows --fresh
+ cmake --preset x64-windows-release --fresh
```
=== "MinGW"
``` { .sh .copy }
- cmake -B build -S . --preset MSYS2 --fresh
+ cmake --preset x64-mingw-release --fresh
```
=== "Linux"
``` { .sh .copy }
- cmake -B build -S . --preset Linux --fresh
+ cmake --preset x64-linux-release --fresh
```
-Alternatively, you can just delete everything inside the build directory before configuring **CMake** again.
+<!-- Alternatively, you can just delete everything inside the build directory before configuring **CMake** again.
The default build configuration of **CMake** is ^^Release^^. The build configuration can be changed, for example to ^^Debug^^, by:
@@ -109,7 +141,7 @@ The default build configuration of **CMake** is ^^Release^^. The build configura
``` { .sh .copy }
cmake -B build -S . --preset Linux -DCMAKE_BUILD_TYPE:STRING=Debug
- ```
+ ``` -->
### GUI
**CMake** also comes with a GUI which can be used for the configuration process.
@@ -119,7 +151,8 @@ The GUI looks like this:
It works the same as the command line interface.
You have to specify the path to the source files and to the build directory.
-You also see the exposed options of the project.
+Then you have to select the preset you want to use.
+You can see the exposed options of the project as well.
And as the GUI already tells you:
> Press Configure to update and display new values in red, then press Generate to generate selected build files.
@@ -148,50 +181,45 @@ So to build a specific target you call **CMake** with the following command, whe
=== "Windows"
```sh
- cmake --build build --target the-target --config build-type
+ cmake --build --preset x64-windows-release --target <target>
```
- :fontawesome-solid-arrow-right: The `build-type` can be one of the usual suspects:
-
- - **Release**
- - **Debug**
- - **MinSizeRel**
=== "MinGW"
```sh
- cmake --build build --target the-target
+ cmake --build --preset x64-mingw-release --target <target>
```
!!! tip
- Remember: the build type is already specified when configuring **CMake** :point_up:.
+ Remember: The build preset should match the one specified when configuring **CMake** :point_up:.
=== "Unix"
```sh
- cmake --build build --target the-target
+ cmake --build --preset x64-linux-release --target <target>
```
!!! tip
- Remember: the build type is already specified when configuring **CMake** :point_up:.
+ Remember: The build preset should match the one specified when configuring **CMake** :point_up:.
When you want to compile all the modules ^^at once^^, you can just omit the *target* option and call **CMake** with:
=== "Windows"
```sh
- cmake --build build --config build-type
+ cmake --build --preset x64-windows-release
```
=== "MinGW"
```sh
- cmake --build build
+ cmake --build --preset x64-mingw-release
```
=== "Unix"
```sh
- cmake --build build
+ cmake --build --preset x64-linux-release
```
You can also clean the build before re-compiling:
@@ -199,31 +227,28 @@ You can also clean the build before re-compiling:
=== "Windows"
```sh
- cmake --build build --target the-target --config build-type --clean-first
+ cmake --build --preset x64-windows-release --target <target> --clean-first
```
=== "MinGW"
```sh
- cmake --build build --target the-target --clean-first
+ cmake --build --preset x64-mingw-release --target <target> --clean-first
```
=== "Unix"
```sh
- cmake --build build --target the-target --clean-first
+ cmake --build --preset x64-linux-release --target <target> --clean-first
```
That's all folks. This should compile *UNICADO* just fine. 👌
-!!! warning
- Make sure to update your **PATH** with the new runtime libraries (when compiled as shared libraries), which are located in: /path-to-libs-submodule/unicadoRuntimeLibs/
-
### Improve Compilation Speed
You can increase the build speed by enabling parallel jobs of the build tool. This is as easy as this:
```sh
-cmake --build build --target the-target -j n-jobs
+cmake --build --preset <preset> --target <target> -j <n_jobs>
```
-This builds the project using `n-jobs` processes. You can give any number here, but it should correspond to the number of processors available on your machine.
+This builds the project using `n_jobs` processes. You can give any number here, but it should correspond to the number of processors available on your machine.
diff --git a/docs/developer/build/release-package.md b/docs/developer/build/release-package.md
new file mode 100644
index 0000000000000000000000000000000000000000..4319d8974c97d9c283a71b8742df9c87878a0200
--- /dev/null
+++ b/docs/developer/build/release-package.md
@@ -0,0 +1,58 @@
+---
+title: Building the Release Package
+summary: How to build C++ Installer packages of UNICADO.
+authors:
+ - Sebastian Oberschwendtner
+date: 2024-05-29
+---
+When all module executables are built and tested, you can create an installer package for the **UNICADO** project.
+CMake offers a convenient way to execute predefined workflow steps to build everything you need for the installer package and the installer itself.
+The **UNICADO** project has a workflow defined for creating a **Release** package for *Windows* and *Linux*.
+
+:fontawesome-solid-arrow-right: You can read more about the [workflow :octicons-link-external-16:](https://cmake.org/cmake/help/latest/manual/cmake-presets.7.html#workflow-preset){:target="_blank"} in the **CMake** documentation.
+
+## Prerequisites
+Make sure you execute **all** steps on this page in a terminal in the **root directory** of the [Unicado Package :octicons-link-external-16:](https://git.rwth-aachen.de/unicado/unicado-package){:target="_blank"} repository.
+
+### Enable Parallel Builds (optional)
+Since most machines nowadays have multiple cores, you can enable parallel builds to speed up the build process.
+In fact, the release workflow will warn you if you don't. :wink:
+
+As the release workflow invokes multiple different CMake modules, you have to enable the parallel build by setting an **environment variable** called [`CMAKE_BUILD_PARALLEL_LEVEL`](https://cmake.org/cmake/help/latest/envvar/CMAKE_BUILD_PARALLEL_LEVEL.html){:target="_blank"}:
+
+=== "Windows"
+
+ ```{.sh .copy}
+ set CMAKE_BUILD_PARALLEL_LEVEL=<number_of_cores>
+ ```
+
+=== "Linux"
+
+ ```{.sh .copy}
+ export CMAKE_BUILD_PARALLEL_LEVEL=<number_of_cores>
+ ```
+
+**Do not insert any spaces around the `=` sign!**
+
+!!! note
+ The `<number_of_cores>` should be the number of cores your machine has.
+
+## Build the Installer
+The installer with all its needed components can be built by executing the following command:
+
+=== "Windows"
+
+ ```sh
+ cmake --workflow --preset x64-windows-release
+ ```
+
+=== "Linux"
+
+ ```sh
+ cmake --workflow --preset x64-linux-release
+ ```
+
+This should also work out of the box with a freshly cloned version of the **Unicado Package** repository.
+
+!!! note
+ There is **no** *Debug* configuration for the installer package. The installer package has to always be built in **Release** mode!
\ No newline at end of file
diff --git a/docs/developer/cmake-presets.md b/docs/developer/cmake-presets.md
index 5e40b9222bf0f384538123c718fcca374e874fab..a19ee49638e050a269d5faaea80d40928cf61eb3 100644
--- a/docs/developer/cmake-presets.md
+++ b/docs/developer/cmake-presets.md
@@ -29,7 +29,7 @@ The following provides preset templates you can build your preset upon.
"configurePresets": [
{
"name": "default",
- "inherits": "Windows",
+ "inherits": "x64-windows-common",
<your custom overrides here>
}
]
@@ -45,7 +45,7 @@ The following provides preset templates you can build your preset upon.
"configurePresets": [
{
"name": "default",
- "inherits": "MSYS2",
+ "inherits": "x64-unix-common",
<your custom overrides here>
}
]
@@ -61,7 +61,7 @@ The following provides preset templates you can build your preset upon.
"configurePresets": [
{
"name": "default",
- "inherits": "Linux",
+ "inherits": "x64-linux-common",
<your custom overrides here>
}
]
diff --git a/docs/developer/including-libraries.md b/docs/developer/including-libraries.md
index 01079fb5b381db26d179daf8cf45e01d427c7296..b97c872b87169e7abf10a7eb5d47ad6a8a67c103 100644
--- a/docs/developer/including-libraries.md
+++ b/docs/developer/including-libraries.md
@@ -32,7 +32,7 @@ The default configuration when [Building with CMake](build/cpp.md) is:
When you want to decrease the binary size of the executables or want to test changes in the libraries without having to recompile the executables, you can build the libraries as **dynamic** libraries by configuring **CMake** with:
```sh
-cmake -B build -S . -G "your-generator" -DBUILD_SHARED_LIBS=ON
+cmake -B build -S . --preset <preset> -DBUILD_SHARED_LIBS=ON
```
This will build all libraries as **dynamic** libraries and link the executables against those libraries.
@@ -40,6 +40,7 @@ It does not matter where you set this option.
When you build the libraries on their own, the option does the same thing as when you build the complete project where the libraries are included as a submodule.
!!! warning
+ This is **not** recommended unless you have a specific need for it.
Do not forget to add the location of the **dynamic** libraries to your **PATH** afterwards. 😉
## Changing to the library package
@@ -47,7 +48,7 @@ When you build the libraries on their own, the option does the same thing as whe
When you want to save some compilation time or do not want to copy the libraries everywhere, you can include them as a package by:
```sh
-cmake -B build -S . -G "your-generator" -DFIND_LIBRARIES_AS_PACKAGE=ON -DCMAKE_PREFIX_PATH=path-to-libs
+cmake -B build -S . --preset <preset> -DFIND_LIBRARIES_AS_PACKAGE=ON -DCMAKE_PREFIX_PATH=path-to-libs
```
!!! important
diff --git a/mkdocs.yml b/mkdocs.yml
index 7ed2ff53428a5ab0bbca848aa6acb0381530a320..51cceb6d615933f2dbae4233f75b7e68b8d423a3 100644
--- a/mkdocs.yml
+++ b/mkdocs.yml
@@ -104,6 +104,7 @@ nav:
- 'Build':
- 'C++': 'developer/build/cpp.md'
- 'Python': 'developer/build/python.md'
+ - 'Release Package/Installer': 'developer/build/release-package.md'
- 'Libraries': 'developer/including-libraries.md'
- 'CMake Presets': 'developer/cmake-presets.md'
- 'Style Guide':