From abffd6eafdfa98b552d54793a94ceb1e57b1c4d8 Mon Sep 17 00:00:00 2001 From: Sonja Kaiser Date: Fri, 13 Dec 2024 14:27:01 +0100 Subject: [PATCH 1/2] [doc] Devguide changes. --- .../advanced/configuration-options/index.md | 12 ++++++++ .../build-configuration/index.md | 28 +++++++++++++++-- .../getting-started/prerequisites/index.md | 2 ++ .../devguide/packages/python-env/index.md | 30 +++++++++++++++++++ .../devguide/troubleshooting/cmake/index.md | 22 +++++++++++++- 5 files changed, 91 insertions(+), 3 deletions(-) diff --git a/web/content/docs/devguide/advanced/configuration-options/index.md b/web/content/docs/devguide/advanced/configuration-options/index.md index 6b054bf6d26..c0cec57d9c0 100644 --- a/web/content/docs/devguide/advanced/configuration-options/index.md +++ b/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. diff --git a/web/content/docs/devguide/getting-started/build-configuration/index.md b/web/content/docs/devguide/getting-started/build-configuration/index.md index 9590c1b0712..93e4329b13c 100644 --- a/web/content/docs/devguide/getting-started/build-configuration/index.md +++ b/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 +
+ +### 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 +``` + +
+ ## Option: Configure with a visual tool
diff --git a/web/content/docs/devguide/getting-started/prerequisites/index.md b/web/content/docs/devguide/getting-started/prerequisites/index.md index 11f1a54b001..5532b981187 100644 --- a/web/content/docs/devguide/getting-started/prerequisites/index.md +++ b/web/content/docs/devguide/getting-started/prerequisites/index.md @@ -214,6 +214,8 @@ git config --global http.proxy http://yourproxy.example.com Install CMake via Kitware's APT Repository by [following their instructions](https://apt.kitware.com/). +If something goes wrong there, check, if Kitware related keyrings in /usr/share/keyrings are readable to everyone. + For other Linux distributions you want to use your distributions package manager, [pip](https://pypi.org/project/cmake/) or [snap](https://snapcraft.io/cmake).
diff --git a/web/content/docs/devguide/packages/python-env/index.md b/web/content/docs/devguide/packages/python-env/index.md index 82472e21307..fbdba5d7c91 100644 --- a/web/content/docs/devguide/packages/python-env/index.md +++ b/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 /.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 diff --git a/web/content/docs/devguide/troubleshooting/cmake/index.md b/web/content/docs/devguide/troubleshooting/cmake/index.md index c2a7e802cbf..29ba8487ddd 100644 --- a/web/content/docs/devguide/troubleshooting/cmake/index.md +++ b/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. From 3932d4473280ea7563b80706175bbc2dca860823 Mon Sep 17 00:00:00 2001 From: Dmitri Naumov Date: Fri, 13 Dec 2024 17:09:16 +0100 Subject: [PATCH 2/2] [doc] Devguide; install cmake via system pkg mgr --- .../docs/devguide/getting-started/prerequisites/index.md | 7 +++++-- 1 file changed, 5 insertions(+), 2 deletions(-) diff --git a/web/content/docs/devguide/getting-started/prerequisites/index.md b/web/content/docs/devguide/getting-started/prerequisites/index.md index 5532b981187..e949da18544 100644 --- a/web/content/docs/devguide/getting-started/prerequisites/index.md +++ b/web/content/docs/devguide/getting-started/prerequisites/index.md @@ -212,11 +212,14 @@ git config --global http.proxy http://yourproxy.example.com
-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 -If something goes wrong there, check, if Kitware related keyrings in /usr/share/keyrings are readable to everyone. +```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). +