From 68341799ffebc256bde871107a46ff233f0727d8 Mon Sep 17 00:00:00 2001
From: Lars Bilke <lars.bilke@ufz.de>
Date: Wed, 3 Feb 2021 13:21:18 +0100
Subject: [PATCH] [web] Updated docs on using CMake.

- Use CMake presets
- Use in-source build-directories
- Removed some old IDE descriptions
---
 .../devguide/advanced/build-with-ninja.md     |  55 --------
 .../docs/devguide/advanced/working-on-eve.md  |   2 +-
 .../getting-started/build-configuration.md    | 125 +++++++++++-------
 .../docs/devguide/getting-started/build.md    |  70 +---------
 .../devguide/getting-started/prerequisites.md |  18 ++-
 5 files changed, 98 insertions(+), 172 deletions(-)
 delete mode 100644 web/content/docs/devguide/advanced/build-with-ninja.md

diff --git a/web/content/docs/devguide/advanced/build-with-ninja.md b/web/content/docs/devguide/advanced/build-with-ninja.md
deleted file mode 100644
index 009433fbad9..00000000000
--- a/web/content/docs/devguide/advanced/build-with-ninja.md
+++ /dev/null
@@ -1,55 +0,0 @@
-+++
-date = "2018-02-26T11:00:13+01:00"
-title = "Build with ninja"
-author = "Lars Bilke"
-weight = 1031
-
-[menu]
-  [menu.devguide]
-    parent = "advanced"
-+++
-
-## Install ninja
-
-<div class='win'>
-
-Download *ninja.zip* from the [latest GitHub release](https://github.com/ninja-build/ninja/releases/latest). Unzip it and make sure that the directory containing the `ninja.exe` is the `PATH`-environment variable!
-
-</div>
-
-<div class='linux'>
-
-Install with your package manager:
-
-```bash
-sudo apt-get install ninja-build
-```
-
-</div>
-
-<div class='mac'>
-
-Install via Homebrew:
-
-```bash
-brew install ninja
-```
-
-</div>
-
-## Configure for ninja and build
-
-Run CMake with the ninja-generator:
-
-```bash
-cmake ../source/dir -G Ninja
-ninja
-```
-
-<div class='note'>
-
-### <i class="far fa-exclamation-triangle"></i> Visual Studio remarks
-
-When you configure with the Ninja generator you have to run CMake from the appropriate Visual Studio Command Prompt! From there you can both use `cmake` as well as `cmake-gui` which starts the GUI. In the GUI select the `Ninja` generator and leave the toggle `Use default native compilers` on.
-
-</div>
diff --git a/web/content/docs/devguide/advanced/working-on-eve.md b/web/content/docs/devguide/advanced/working-on-eve.md
index 3684a5d687e..66ba1d5f742 100644
--- a/web/content/docs/devguide/advanced/working-on-eve.md
+++ b/web/content/docs/devguide/advanced/working-on-eve.md
@@ -57,7 +57,7 @@ Generating Doxygen documentation:
 module load Doxygen/1.8.14
 ```
 
-You can [build with Ninja]({{< ref "build-with-ninja" >}}):
+You can build with Ninja:
 
 ```bash
 module load ninja/1.9.0
diff --git a/web/content/docs/devguide/getting-started/build-configuration.md b/web/content/docs/devguide/getting-started/build-configuration.md
index 6a0bf1b1ee4..30e55e897c8 100644
--- a/web/content/docs/devguide/getting-started/build-configuration.md
+++ b/web/content/docs/devguide/getting-started/build-configuration.md
@@ -11,36 +11,53 @@ weight = 1004
 
 ## Overview
 
-To separate source code from generated files such as compiled libraries, executables, test outputs and IDE projects we create build-directories. They can be placed arbitrarily but should **not** be placed inside the source code. You can have as many build-directories as you like for e.g. different configurations but they will all use one source code directory. A typically directory structure:
+Before compiling the developer has to choose a configuration of the software. OGS comes in lots of different flavours (e.g. serial / parallelized), can be build with optional features (e.g. with Python scripting support) or modules (e.g. MFront material models).
 
-- `ogs-source-code` (or simply `ogs`)
-- `build-release`
-- `build-debug`
-- `build-release-mpi`
+To separate source code from generated files such as compiled libraries, executables, test outputs and IDE projects we create build-directories. They can be placed arbitrarily. You can have as many build-directories as you like for e.g. different configurations but they will all use one source code directory. A typically directory structure:
 
-So just go ahead and create a build-directory along your source code directory.
+- `ogs-source-code` (or simply `ogs`)
+  - `build/release`
+  - `build/debug`
+  - `build/release-petsc`
+- `build` (can also be placed outside the source tree)
 
 ## Configure with CMake
 
-For configuring a build the open source [CMake](http://www.cmake.org) tool is used. CMakeLists.txt files replace traditional Makefiles or IDE project files. The CMake tool is run inside the build-directory with a reference to the source code-directory of the project and user-chosen options. CMake then generates based on the chosen *Generator* either Makefiles or project files for IDE such as Visual Studio or Eclipse inside the build directory. Also all the compiled files will be generated in this directory. This keeps the actual source code clean from intermediate files which are generated from the source code. Nothing inside the build directory will ever be version controlled because its contents can be regenerated anytime from the source code.
+For configuring a build the open source tool [CMake](http://www.cmake.org) is used. `CMakeLists.txt` files replace traditional Makefiles or IDE project files.
 
-Because of the separation of the source code and all stuff that is generated as a part of the build process it is no problem to have several build configurations (e.g. a serial configuration and a parallelized MPI-enabled configuration) all referring to the same source code.
+We provide CMake configuration presets defined in [CMakePresets.json](https://gitlab.opengeosys.org/ogs/ogs/-/blob/master/CMakePresets.json) for simple build configuration (**Note:** Requires CMake $\geq$ 3.19! Otherwise see [Configure manually](#option-configure-manually)). See the following table for commonly used presets:
 
-When you want to start over with a new configuration simply delete the build-directory, create a new one and reconfigure.
+### Available CMake presets
 
-[See this]({{< ref "configuration-options" >}}) for a list of available options.
+|               | Ninja[^1]     | Visual Studio    |
+| ------------- | ------------- | ---------------- |
+| CLI Release   | release       | msvc-release     |
+| CLI Debug     | debug         | msvc-debug       |
+| GUI Release   | release-gui   | msvc-release-gui |
+| GUI Debug     | debug-gui     | msvc-debug-gui   |
+| PETSc Release | release-petsc | -                |
+| PETSc Debug   | debug-petsc   | -                |
 
-<div class='win'>
+[^1]: Requires the `ninja`-tool. See [install instructions]({{< ref "prerequisites.md#optional-install-ninja" >}}).
 
-<div class='note'>
+### Configure with a preset
 
-### <i class="far fa-exclamation-triangle"></i> Supported Visual Studio Generators
+In the source directory run `cmake`:
 
-- `Visual Studio {{< dataFile "versions.minimum_version.msvc.number" >}} {{< dataFile "versions.minimum_version.msvc.year" >}}`
+```bash
+# Usage: cmake -S [path-to-source] --preset=[preset-name]
+cmake -S . --preset=release
+```
 
-</div>
+This will create a build-directory in the source tree (`build/release`) with the default CMake options and the Release configuration.
 
-</div>
+Additionally you can pass any CMake variable or option with `-DVARIABLE_NAME=VALUE` (note the `-D` in front!) to the CMake command. You can also overwrite the generator with the `-G` parameter or the build-directory with the `-B` parameter (to see all available options just run `cmake --help`)
+
+Also all the compiled files will be generated in this directory. This keeps the actual source code clean from intermediate files which are generated from the source code. Nothing inside the build directory will ever be version controlled because its contents can be regenerated anytime from the source code.
+
+When you want to start over with a new configuration simply delete the build-directory, create a new one and reconfigure.
+
+[See this]({{< ref "configuration-options" >}}) for a list of commonly used available options.
 
 ### Note: Installation of required libraries
 
@@ -48,63 +65,73 @@ It is preferred to use the Conan package manager to install required third-party
 
 Instead of using Conan you can optionally [install the required libraries manually]({{< ref "third-party-libraries.md" >}}) **before** running CMake.
 
-<div class='win'>
-
 <div class='note'>
 
-#### <i class="far fa-exclamation-triangle"></i> Multi-configuration with Conan and Visual Studio
+### User-defined presets
 
-With Conan one build directory corresponds to one configuration. If you want to have e.g. a release and a debug build you need to create two build directories. This is nothing new new to Linux / GCC user but differs to Visual Studios default behavior having just one build-folder / project with different configurations. A typical Visual Studio setup with both Release and Debug configs would be initialized as follows:
+You can create a `CMakeUserPresets.json` file in the root source directory with your own presets (this file is ignored by git):
+
+```json
+{
+  "version": 1,
+  "configurePresets": [
+    {
+      "name": "my-release",
+      "inherits": "release",
+      "cacheVariables": {
+        "OGS_USE_POETRY": "OFF"
+      }
+    }
+  ]
+}
 
-```bash
-[assuming you are at the same directory where the source code directory is located]
-mkdir ogs-build && cd ogs-build
-mkdir debug && cd debug
-cmake ../../ogs -G "Visual Studio {{< dataFile "versions.minimum_version.msvc.number" >}} {{< dataFile "versions.minimum_version.msvc.year" >}}" -DCMAKE_BUILD_TYPE=Debug
-cd .. && mkdir release && cd release
-cmake ../../ogs -G "Visual Studio {{< dataFile "versions.minimum_version.msvc.number" >}} {{< dataFile "versions.minimum_version.msvc.year" >}}" -DCMAKE_BUILD_TYPE=Release
 ```
 
-`..\..\ogs` represents the relative path to the source code (please adapt if you have a different directory layout).
+</div>
 
-Please also note that in Visual Studio you have to choose the correct configuration (i.e. when opening the solution-file in the release-folder you have to switch the Visual Studio configuration to **Release**)!
+<div class='win'>
 
-</div>
+<div class='note'>
 
-</div>
+### Windows notes:
 
-## Option: Configure from the command line
+#### <i class="far fa-check"></i> Ninja requirement: Use the Visual Studio command line
 
-CMake can be run from the shell by invoking the cmake command inside a build directory. You can pass any CMake variable or option with `-DVARIABLE_NAME=VALUE` (note the `-D` in front!). You can also pass the generator you want to use (e.g. `Unix Makefiles` or `Visual Studio {{< dataFile "versions.minimum_version.msvc.number" >}} {{< dataFile "versions.minimum_version.msvc.year" >}}`-project files) with the `-G` parameter (to see all available generators just run `cmake --help`), although in most cases the appropriate generator will be chosen automatically. The last parameter to the CMake command is the path to the source code directory. A typical call would look like this:
+To use the Ninja build tool you need to configure in the Visual Studio command line. In the Start menu under *Visual Studio {{< dataFile "versions.minimum_version.msvc.year" >}}* you find a application link to *x64 Native Tools Command Prompt for VS {{< dataFile "versions.minimum_version.msvc.year" >}}*. This starts a command line setup for Visual Studio 64-bit. Now you can use a Ninja preset:
 
 ```bash
-cmake -G "Visual Studio {{< dataFile "versions.minimum_version.msvc.number" >}} {{< dataFile "versions.minimum_version.msvc.year" >}}" -DCMAKE_BUILD_TYPE=Release ../ogs
+cmake -S . --preset=release
 ```
 
-CMake tries to autodetect your compiler so in most cases this should be enough:
+#### <i class="far fa-exclamation-triangle"></i> Multi-configuration with Conan and Visual Studio
+
+With Conan one build directory corresponds to one configuration. If you want to have e.g. a release and a debug build you need to create two build directories. This is nothing new to Linux / GCC user but differs to Visual Studios default behavior having just one build-folder / project with different configurations. A typical Visual Studio setup with both Release and Debug configs would be initialized as follows:
 
 ```bash
-cmake ../ogs
+cmake -S . --preset=msvc-release
+cmake -S . --preset=msvc-debug
 ```
 
-{{< asciinema url="https://asciinema.org/a/249004" >}}
+Please also note that in Visual Studio you have to choose the correct configuration (i.e. when opening the solution-file in the release-folder you have to switch the Visual Studio configuration to **Release**)!
 
-<div class='note'>
+#### <i class="far fa-check"></i> Pro Tip: Use a better terminal application
 
-### <i class="far fa-check"></i> Pro Tip: Use the Visual Studio command line
+Use the [Windows Terminal](https://www.microsoft.com/en-us/p/windows-terminal/9n0dx20hk701) for a better terminal experience. It offers modern terminal features such as multiple tabs and panes.
 
-In the Start menu under *Visual Studio {{< dataFile "versions.minimum_version.msvc.year" >}}* you find a application link to *x64 Native Tools Command Prompt for VS {{< dataFile "versions.minimum_version.msvc.year" >}}*. This starts a command line setup for Visual Studio 64-bit. When you run CMake commands in this command line the correct generator will be picked up automatically:
+</div>
 
-```bash
-cmake ../ogs
-```
+</div>
 
-This even allows for using [Ninja]({{< ref "build-with-ninja.md" >}}) as the build tool which can effectively utilize all CPU cores
+## Option: Configure manually
 
-### <i class="far fa-check"></i> Pro Tip 2: Use a better terminal application
+If you cannot use CMake presets (e.g. when your CMake installation does not support it) manually create a build directory and run CMake from within with all required parameters, e.g:
 
-Use the [Windows Terminal](https://www.microsoft.com/en-us/p/windows-terminal/9n0dx20hk701) for a better terminal experience. It offers modern terminal features such as multiple tabs and panes.
-</div>
+```bash
+# in ogs source-directory
+mkdir -p build/release
+cd build/release
+cmake ../.. -G Ninja -DCMAKE_BUILD_TYPE=Release
+```
 
 ## Option: Configure with a visual tool
 
@@ -116,10 +143,10 @@ CMake comes with a graphical tool called **cmake-gui**. You can find it in the *
 
 <div class='linux'>
 
-A more convenient way of running cmake on the command line is to use the `ccmake` tool. This is a shell tool but with some graphical user interface. To use it just run `ccmake` inside your build directory with the path to the source code (and optionally the generator you want to use) as parameter:
+A more convenient way of running cmake on the command line is to use the `ccmake` tool. This is a shell tool but with some graphical user interface. To use it just run `ccmake` instead of `cmake`:
 
 ```bash
-ccmake ../ogs
+ccmake -S . --preset=release
 ```
 
 First press <kbd>C</kbd> to **Configure**. You are now presented the available configuration options. You can navigate in the list with the cursor keys and toggle / alter options with <kbd>Enter</kbd>. You may also press <kbd>T</kbd> to toggle (previously hidden) advanced options. Press <kbd>C</kbd> again until the **Generate**-option becomes visible. Press <kbd>G</kbd> to generate the project files and exit `ccmake`.
diff --git a/web/content/docs/devguide/getting-started/build.md b/web/content/docs/devguide/getting-started/build.md
index 446e167c758..b8866543b59 100644
--- a/web/content/docs/devguide/getting-started/build.md
+++ b/web/content/docs/devguide/getting-started/build.md
@@ -15,7 +15,7 @@ weight = 1005
 
 ### Step: Build with Visual Studio
 
-Open the OGS.sln either by double-clicking it in the file browser or opening in Visual Studio via **File / Open / Project**.
+Open the OGS.sln (in the build directory) either by double-clicking it in the file browser or opening in Visual Studio via **File / Open / Project**.
 
 On the project explorer right-click on **ogs** or **ogs-gui** and choose **Set as startup project**. Then press <kbd>F5</kbd> or click the green arrow to build and start the project.
 
@@ -30,78 +30,20 @@ You can work normally in Visual Studio but remember that you have to make projec
 
 <div class='linux'>
 
-### Option: Make
+### With ninja
 
-To build with the `make` tool on the shell go to your previously created build directory and type `make`:
+To build with the `ninja` tool on the shell go to your previously configured build directory and type `ninja`:
 
 ```bash
-cd build
-make
+cd build/release
+ninja
 ```
-
-To speedup the compilation process append the number of cores of your cpu to the make command. E.g. for 8 cores:
-
-```bash
-make -j 8
-```
-
-{{< asciinema url="https://asciinema.org/a/249005" preload="1" >}}
-
-### Option: Eclipse
-
-To let CMake generate the Eclipse project files change the generator argument to the CMake run:
-
-```bash
-cmake [your configuration options] -G"Eclipse CDT4 - Unix Makefiles" ../sources
-```
-
-Or with ccmake
-
-```bash
-ccmake -G"Eclipse CDT4 - Unix Makefiles" ../sources
-```
-
-Start the Eclipse ide. From the menu choose **File / Import**. In the import dialog choose **General / Existing projects into workspace** and click **Next**. In **Select root directory** select your build directory and make sure that **Copy project into workspace** is unchecked. Click **Finish**.
 </div>
 
 <div class='mac'>
 
-### Option: Make
-
-To build with the `make` tool on the shell go to your previously created build directory and type `make`:
-
-```bash
-cd build
-make
-```
-
-To speedup the compilation process append the number of cores of your cpu to the make command. E.g. for 8 cores:
-
-```bash
-make -j 8
-```
-
-### Option: Xcode
-
-To let CMake generate the Xcode project files change the generator argument on the CMake run:
-
-```bash
-cmake [your configuration options] -G Xcode ../sources
-```
-
-Or with ccmake
-
-```bash
-ccmake -G Xcode ../sources
-```
-
-Then load the generated project file by either clicking the **OGS.xcodeproj** or via
-
-```bash
-open OGS.xcodeproj
-```
+See Linux-tab!
 
-In Xcode choose `ogs` or `ogs-gui` from the drop-down menu on the top right and then hit the Run-button.
 </div>
 
 ## Waiting
diff --git a/web/content/docs/devguide/getting-started/prerequisites.md b/web/content/docs/devguide/getting-started/prerequisites.md
index 2b08122f69b..2c4667ed5cc 100644
--- a/web/content/docs/devguide/getting-started/prerequisites.md
+++ b/web/content/docs/devguide/getting-started/prerequisites.md
@@ -18,6 +18,7 @@ The minimum prerequisites to build OGS are:
 - CMake (build configuration tool, at least version {{< dataFile "versions.minimum_version.cmake" >}})
 - A compiler with [C++20](http://en.wikipedia.org/wiki/C%2B%2B20)-support
 - [Conan package manager](https://www.conan.io/) (at least version {{< dataFile "versions.minimum_version.conan" >}}) **OR** install [required libraries]({{< ref "third-party-libraries.md" >}}) manually (for advanced users only!)
+- *Optional (but recommended)*: [Ninja](https://ninja-build.org) build tool
 
 <div class='note'>
 
@@ -202,12 +203,11 @@ git config --global http.proxy http://yourproxy.example.com
 
 <div class='win'>
 
-- [Download the Python 3 installer](https://www.python.org/ftp/python/3.7.2/python-3.7.2-amd64-webinstall.exe)
+- [Download the Python 3 installer](https://www.python.org/ftp/python/3.9.1/python-3.9.1-amd64.exe)
 - Install with the following options
   - Check *Add Python 3.X to PATH*
   - *Customize installation*
   - Make sure to have `pip` enabled (you may uncheck *Documentation*, *tcl/tk*, *Python test suite*)
-  - You may check *Install for all users*
   - Check *Add Python to environment variables*!
 
 </div>
@@ -267,7 +267,7 @@ Install Conan (>= {{< dataFile "versions.minimum_version.conan" >}}) with Python
 pip3 install --user conan
 ```
 
-This installed `conan` to `.local/bin` (or `C:\Users\[username]\AppData\Roaming\Python\Python37\Scripts` on Windows) in your home directory. Make sure to have this directory in your `PATH`!
+This installed `conan` to `.local/bin` (or `C:\Users\[username]\AppData\Roaming\Python\Python39\Scripts` on Windows) in your home directory. Make sure to have this directory in your `PATH`!
 
 Check on a newly opened command line if Conan was installed successfully:
 
@@ -281,3 +281,15 @@ Conan version {{< dataFile "versions.minimum_version.conan" >}}
 **Advanced usage:** You can also have Conan auto-installed when using the CMake-option `OGS_USE_CONAN=auto`. See the page on [Python environment]({{< ref "python-env.md" >}}) for details.
 
 </div>
+
+## Optional: Install Ninja
+
+We recommend [`ninja`](https://ninja-build.org) as a cross-platform build tool (`make`-replacement).
+
+Install Ninja with Python's pip:
+
+```bash
+pip3 install --user ninja
+```
+
+Make sure that `ninja` is in the path afterwards. See Conan install instructions above.
-- 
GitLab