Build configuration

Overview

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 or modules (e.g. MFront material models).

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 not inside the source code directory (so called out-of-source builds). 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:

• ogs-source-code (or simply ogs)
• build (has to be placed outside the source directory)
  • release
  • debug

Configure with CMake

For configuring a build the open source tool CMake is used. CMakeLists.txt files replace traditional Makefiles or IDE project files.

We provide CMake configuration presets defined in CMakePresets.json for simple build configuration! Otherwise see Configure manually ). See the following table for commonly used presets:

Available CMake presets

Configure with a preset

In the source directory run cmake with a preset:

# Usage: cmake --preset [preset-name]
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).

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 for a list of commonly used available options.

The example below shows how to create custom presets using the OGS_USE_PIP=ON CMake-option. Enabling this option is recommended if you want to execute or develop Jupyter notebooks for more interactive benchmarks. OGS_USE_PIP=ON requires uv , a tool that handles Python dependencies and virtual environments. I.e., please install uv if you want to set OGS_USE_PIP=ON. See the Jupyter page for more info.

{
  "version": 1,
  "configurePresets": [
    {
      "name": "my-release",
      "inherits": "release",
      "cacheVariables": {
        "OGS_USE_PIP": "ON"
      }
    }
  ]
}

cmake --preset release

cmake --preset msvc-release # creates ../build/msvc-release/OGS.sln
cmake --preset msvc-debug   # creates ../build/msvc-debug/OGS.sln

Option: Configure manually

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:

# in ogs source-directory
mkdir -p ../build/release
cd ../build/release
cmake ../../ogs -G Ninja -DCMAKE_BUILD_TYPE=Release

CC=mpicc CXX=mpic++ cmake ../ogs -G Ninja -DCMAKE_BUILD_TYPE=Release -DOGS_USE_PETSC=ON

sudo apt-get install python3 python3-pip

sudo apt-get install python3-venv

cmake ../ogs -DOGS_USE_PIP=ON -DCMAKE_BUILD_TYPE="Release" -G Ninja

Option: Configure with a visual tool

cmake --preset release
ccmake ../build/release