Merge branch 'Devguide' into 'master'

Small developer guide improvements

See merge request ogs/ogs!5174

web/content/docs/devguide/advanced/configuration-options/index.md

@@ -13,6 +13,11 @@ weight = 1060
 
 Some of these options are enabled by default ("*Defaults* to *ON*") otherwise they must be explicitly set to *ON*.
 
+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.
+
 ### General
 
 CMake switches to enable / disable parts of OGS.
@@ -25,6 +30,13 @@ CMake switches to enable / disable parts of OGS.
   Run the CMake-GUI / `ccmake` to see a list of processes.
 - `OGS_BUILD_PROCESSES` - A `;`-separated list specifying processes to build, e.g. `-DOGS_BUILD_PROCESSES="HT;LIE"`. Can be set to *ON* which means all processes are built or can be set to *OFF* to disable all processes. **Attention:** Setting this variable overrides individual `OGS_BUILD_PROCESS_X`-variables! This option is mainly used for CI and automation. Also the value of this variable is not cached.
 
+### Python virtual environment
+
+- `OGS_USE_PIP` - Creates a python virtual environment in the .venv-directory
+  inside the build directory, that includes useful packages like ogstools,
+  Jupyter and more. Defaults to *OFF*. See also
+  https://www.opengeosys.org/docs/devguide/packages/python-env/.
+
 ### Debugging
 
 - `CMAKE_BUILD_TYPE` - Defaults to `Debug` which builds with debugging information, set to `Release` for an optimized build.

web/content/docs/devguide/getting-started/build-configuration/index.md

@@ -55,7 +55,7 @@ cmake --preset release
 
 This will create a build-directory outside the source tree (`../build/release`) with the default CMake options and the Release configuration.
 
-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`)
+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.
 
@@ -67,7 +67,7 @@ When you want to start over with a new configuration simply delete the build-dir
 
 ### User-defined presets
 
-You can create a `CMakeUserPresets.json` file in the root source directory with your own presets (this file is ignored by git):
+You can also create a `CMakeUserPresets.json` file in the root source directory with your own presets (this file is ignored by git):
 
 ```json
 {
@@ -143,6 +143,30 @@ CC=mpicc CXX=mpic++ cmake ../ogs -G Ninja -DCMAKE_BUILD_TYPE=Release -DOGS_USE_P
 
 </div>
 
+<div class='note'>
+
+### Using a python virtual environment
+
+Additionally to
+
+```bash
+sudo apt-get install python3 python3-pip
+```
+
+(from https://www.opengeosys.org/docs/devguide/getting-started/prerequisites/), do
+
+```bash
+sudo apt-get install python3-venv
+```
+
+and then you can use the `-DOGS_USE_PIP=ON` option:
+
+```bash
+cmake ../ogs -DOGS_USE_PIP=ON -DCMAKE_BUILD_TYPE="Release" -G Ninja
+```
+
+</div>
+
 ## Option: Configure with a visual tool
 
 <div class='win'>

web/content/docs/devguide/getting-started/prerequisites/index.md

@@ -212,9 +212,14 @@ git config --global http.proxy http://yourproxy.example.com
 
 <div class='linux'>
 
-Install CMake via Kitware's APT Repository by [following their instructions](https://apt.kitware.com/).
+Install CMake using system package manager, *e.g.* on Ubuntu
+
+```bash
+sudo apt install cmake
+```
 
 For other Linux distributions you want to use your distributions package manager, [pip](https://pypi.org/project/cmake/) or [snap](https://snapcraft.io/cmake).
+
 </div>
 
 <div class='mac'>

web/content/docs/devguide/packages/python-env/index.md

@@ -24,6 +24,36 @@ Python packages are usually installed via `pip` inside an isolated environment (
 
 When configuring OGS with `OGS_USE_PIP=ON` Python creates a new virtual environment in the `.venv`-directory inside your build directory. It will also install required Python packages into this environment. You can see the current environment definition in the file `requirements.txt` inside your build-directory.
 
+Make sure, that you did
+
+```bash
+sudo apt-get install python3 python3-pip
+sudo apt-get install python3-venv
+```
+
+then you can use the `-DOGS_USE_PIP=ON` option:
+
+```bash
+cmake ../ogs -DOGS_USE_PIP=ON -DCMAKE_BUILD_TYPE="Release" -G Ninja
+```
+
+When configuring OGS with `OGS_USE_PIP=ON`, Python creates a new virtual
+environment in the .venv-directory inside your build directory.
+It will also install required Python packages into this environment.
+For example, ogstools or Jupyter will this way be available ready-made in a
+consistent configuration.
+You can see the current environment definition with all the included packages in
+the file requirements.txt inside your build-directory.
+
+When you want to use the python packages in this virtual environment, you need
+to activate it by
+
+```bash
+source <your-build-dir>/.envrc
+```
+
+where `.envrc` is a little script including `source .venv/bin/activate` as well as some path settings.
+
 To manually add Python packages run the following inside your build-directory:
 
 ```bash

web/content/docs/devguide/troubleshooting/cmake/index.md

@@ -15,7 +15,9 @@ If something goes wrong when running CMake please try again with an **empty** or
 
 Please read the CMake output carefully. Often it will tell you what went wrong.
 
-Also consider using the command line for CMake configuration as lots of CMake options (which modify requirements on third-party libraries) have to be set via the command line **before** CMake ran for the first time. E.g. when building with PETSc the following fails:
+Also consider using the command line for CMake configuration as lots of CMake options (which modify requirements on third-party libraries) have to be set via the command line **before** CMake ran for the first time.
+
+For example when building with PETSc the following fails:
 
 - Creating build directory
 - Starting CMake GUI
@@ -39,3 +41,21 @@ The following options are affected by this behavior and **should not be changed*
 - `OGS_USE_PETSC`
 - `CMAKE_BUILD_TYPE`
 - `BUILD_SHARED_LIBS`
+
+If the errors are related to TFEL, HDF5, PETSc or VTK, you may delete `~/.cache/CPM/_ext` and try again.
+
+If there are incompatibilities to a system-installed library, e.g. HDF5, you can also use the additional cmake options, e.g. `-DOGS_BUILD_HDF5=ON`, to force a local library (in this case HDF5) build. These options are available:
+
+- `OGS_BUILD_HDF5`
+- `OGS_BUILD_TFEL`
+- `OGS_BUILD_PETSC`
+- `OGS_BUILD_VTK`
+
+External dependencies are cached in `~/.cache/CPM/`.
+If something goes wrong during the first build, then ogs will pick up the failed
+build during subsequent cmake-runs without showing any error messages from the
+dependency.
+In that case you need to delete the corresponding folder in the CPM cache,
+usually something like `~/.cache/CPM/_ext/TFEL/[some long hash]`.
+Then the next cmake-run will retrigger a build of the dependency. This applies
+to TFEL, HDF5, PETSc and VTK.