A compiler cache speeds up compilation times by caching object files and reusing them on subsequent builds. This even works for complete rebuilds (i.e. deleting the full build-directory). The compiler cache [ccache](https://ccache.samba.org) is automatically used when it is found by CMake.
A compiler cache speeds up compilation times by caching object files and reusing them on subsequent builds. This even works for complete rebuilds (i.e. deleting the full build-directory). The compiler cache [Ccache](https://ccache.samba.org) is automatically used when it is found by CMake.
@@ -22,12 +22,12 @@ CMake switches to enable / disable parts of OGS.
-`OGS_BUILD_TESTING` - Builds the test executables. *Defaults* to *ON*.
-`OGS_BUILD_UTILS` - Builds several utilities.
-`OGS_BUILD_PROCESS_X` - For enabling/disabling compilation of process `X`.
Run the CMake-Gui / ccmake to see a list of processes.
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.
### Debugging
-`CMAKE_BUILD_TYPE` - Defaults to `Debug` which builds with debugging infos, set to `Release` for an optimized build.
-`CMAKE_BUILD_TYPE` - Defaults to `Debug` which builds with debugging information, set to `Release` for an optimized build.
-`OGS_PROFILE` - Builds with profiling flags (`-pg`).
-`OGS_CMAKE_DEBUG` - Prints out the values of all defined CMake variables at CMake configuration time.
...
...
@@ -37,7 +37,7 @@ CMake switches to enable / disable parts of OGS.
### Testing
-`OGS_COVERAGE` - Enables code coverage measurements with gcov/lcov. TODO
-`OGS_COVERAGE` - Enables code coverage measurements with `gcov` / `lcov`. TODO
### Advanced options
...
...
@@ -46,7 +46,7 @@ CMake switches to enable / disable parts of OGS.
-`OGS_CPU_ARCHITECTURE` - Optimizes for the given CPU architecture see [-march](https://gcc.gnu.org/onlinedocs/gcc-4.5.3/gcc/i386-and-x86_002d64-Options.html)-flag. Defaults to `native`. For redistributable binaries set to `generic` on Linux and `core2` on Mac OS. Can be disabled when set to `OFF`.
-`CMAKE_LIBRARY_SEARCH_PATH` - Additional library installation path, e.g. `/opt/local` or `C:/libs`
-`OGS_DEPENDENCY_VERSIONS` - Overwrite individual entries in `web/data/versions.json`. Should be quoted and `;`-separated, e.g.: `-DOGS_DEPENDENCY_VERSIONS="minimum_version.petsc=3.16.2;ctest.large_runtime=120"`.
-`OGS_USE_MKL` - Enables MKL support. Requires MKL to be installed on the system.[^mkl] A CMake or environment variable `MKLROOT` or `MKL_DIR` has to point to the MKL installation directory. To enable 64-bit array indices in MKL add `-DMKL_USE_interface=ilp64` on the first CMake run (with a clean CMake cache) but this seems [not supported by Eigen](https://eigen.tuxfamily.org/dox/TopicUsingIntelMKL.html).
-`OGS_USE_MKL` - Enables MKL support. Requires MKL to be installed on the system.[^MKL] A CMake or environment variable `MKLROOT` or `MKL_DIR` has to point to the MKL installation directory. To enable 64-bit array indices in MKL add `-DMKL_USE_interface=ilp64` on the first CMake run (with a clean CMake cache) but this seems [not supported by Eigen](https://eigen.tuxfamily.org/dox/TopicUsingIntelMKL.html).
-`OGS_USE_PETSC_MKL_EIGEN_OPENMP` - Also enables OpenMP multithreading when PETSc and MKL is used. This pulls in another OpenMP implementation besides the Intel MKL OpenMP. **Experimental feature!**
[^mkl]:The`mkl_link_tool` (part of the MKL installation) is used for setting up necessary compiler flags. It is a 32-bit executable. On Arch Linux you need to enable the [multilib-repository](https://wiki.archlinux.org/title/official_repositories#Enabling_multilib) and then install the package `lib32-gcc-libs` (otherwise you may get this error when trying to run it: `mkl_link_tool: No such file or directory`) On other Linux distributions you have to install the package `lib32stdc++6` (Ubuntu / Debian) or `lib32stdc++6` (yum-based)! On Windows please also install the *Intel oneAPI Threading Building Blocks* during installation!
[^MKL]:The`mkl_link_tool` (part of the MKL installation) is used for setting up necessary compiler flags. It is a 32-bit executable. On Arch Linux you need to enable the [multilib-repository](https://wiki.archlinux.org/title/official_repositories#Enabling_multilib) and then install the package `lib32-gcc-libs` (otherwise you may get this error when trying to run it: `mkl_link_tool: No such file or directory`) On other Linux distributions you have to install the package `lib32stdc++6` (Ubuntu / Debian) or `lib32stdc++6` (yum-based)! On Windows please also install the *Intel oneAPI Threading Building Blocks* during installation!
Now you have to squash this conversion commit into your original commit which added the files as Git LFS files. In result your branch history should and **must not** have any Git LFS files! Otherwise GitLab will reject the push!
</div>
When you are done migrating your branches you need to disable Git LFS in your local repo:
When you are done migrating your branches you need to disable Git LFS in your local repository:
```bash
git lfs uninstall --local
...
...
@@ -41,9 +41,9 @@ git lfs uninstall --local
This creates a new fork under your account with the URL `https://gitlab.opengeosys.org/YOUR-USERNAME/ogs`.
## Migrate your local repos to point to GitLab
## Migrate your local repositories to point to GitLab
You have to modify your git remotes to point to the new GitLab repos. Assuming the former official git repo remote is called `upstream`:
You have to modify your git remotes to point to the new GitLab repositories. Assuming the former official git repository remote is called `upstream`:
OGS can be built on systems without internet connection when the following files can be made available on the system:
- The ogs source code. Just archive the full ogs source code directory (also containing the git repository in `.git`) and unarchive on the target system.
- The OGS source code. Just archive the full OGS source code directory (also containing the git repository in `.git`) and un-archive on the target system.
- The [CPM]({{<ref"cpm.md">}}) source cache. It can be obtained via the [OGS package registry](https://gitlab.opengeosys.org/ogs/ogs/-/packages/)(see below).
- Optional: The external dependencies (for MFront, PETSc or LIS) source cache. It can be obtained via the [OGS package registry](https://gitlab.opengeosys.org/ogs/ogs/-/packages/)
## CPM
The cpm source cache may change over time. To get the required file id check the `package_file_id` field in `web/data/versions.json`, e.g. with:
The CPM source cache may change over time. To get the required file id check the `package_file_id` field in `web/data/versions.json`, e.g. with:
On the [external dependencies package page](https://gitlab.opengeosys.org/ogs/ogs/-/packages/14) download the file `ext.tar.gz` with the specified version.
Unarchive the external dependencies cache into a directory. Configure OGS as usual but point to the extracted external dependencies cache:
Extract the external dependencies cache into a directory. Configure OGS as usual but point to the extracted external dependencies cache:
@@ -13,7 +13,7 @@ The [Windows Subsystem for Linux](https://en.wikipedia.org/wiki/Windows_Subsyste
## Setup
- Install WSL2 by following [this guide](https://docs.microsoft.com/en-us/windows/wsl/install-win10). **Important:** Choose **Ubuntu 20.04 LTS** as the Linux distribution. Other distros may not have a sufficient compiler.
- Install WSL2 by following [this guide](https://docs.microsoft.com/en-us/windows/wsl/install-win10). **Important:** Choose **Ubuntu 20.04 LTS** as the Linux distribution. Other distributions may not have a sufficient compiler.
- Optional but recommended: Install the new [Windows Terminal](https://docs.microsoft.com/en-us/windows/terminal/get-started)
- Follow the [developer guide for Linux]({{<ref"prerequisites.md">}}) from now on.
> [Continuous Integration](https://en.wikipedia.org/wiki/Continuous_integration) (short **CI**) is the practice of merging all developer working copies to a shared mainline several times a day.
So for every proposed change to the source code the following is done automatically:
For every proposed change to the source code the following is done automatically:
- Compilation of the changed code merged with the official source code is tested on a variety of platforms (Windows, Linux, Mac OS, different compilers)
- A comprehensive [test suite]({{<ref"unit-testing.md">}}) checks validity of the proposed changes
@@ -24,7 +24,7 @@ Here is a **link list** without specific order:
The steps to get things started with an IDE basically include **generating** the project files, **importing** them in the IDE and know where to **provide arguments** to the debugging binary.
I will assume, that you have the sources (eg. checked out from github) and that they lie in the **source directory**
I will assume, that you have the sources (e.g. checked out from GitHub) and that they lie in the **source directory**
```bash
/home/user/ogs6/sources
...
...
@@ -53,7 +53,7 @@ __________
cmake ../sources/
```
3. Start gdb in graphical mode, without license info (quiet) and with arguments:
3. Start GDB in graphical mode, without license info (quiet) and with arguments:
[GitLab](https://gitlab.com) is a web-based development and collaboration tool similar to [GitHub](https://github.com). We self-host GitLab at <https://gitlab.opengeosys.org> and migrated our development workflows from GitHub in June 2020. Development takes place in the [ogs-group](https://gitlab.opengeosys.org/ogs) and the authoritative repository is at [ogs/ogs](https://gitlab.opengeosys.org/ogs/ogs).
[GitLab](https://gitlab.com) is a web-based development and collaboration tool similar to [GitHub](https://github.com). We self-host GitLab at <https://gitlab.opengeosys.org> and migrated our development workflows from GitHub in June 2020. Development takes place in the [`ogs`-group](https://gitlab.opengeosys.org/ogs) and the authoritative repository is at [`ogs/ogs`](https://gitlab.opengeosys.org/ogs/ogs).
## Setup an account
- Creating a GitLab account can be done by simply using your existing GitHub account: click the GitHub logo (octocat) on the [Gitlab sign-in page](https://gitlab.opengeosys.org/users/sign_in)
- Creating a GitLab account can be done by simply using your existing GitHub account: click the GitHub logo on the [GitLab sign-in page](https://gitlab.opengeosys.org/users/sign_in)
- You will be redirected to GitHub (please login there) and asked for authorization.
- Your new user account will be blocked at first, please let us know we will unblock it
## Setup a password for cloning over https
## Setup a password for cloning over HTTPS
To clone a repository via `https://`-protocol you need to [set up an account password](https://gitlab.opengeosys.org/-/profile/password/edit) and use this during `git clone https://...`.
@@ -22,15 +22,19 @@ Git is very flexible in organizing a distributed development team. We use a so c
The following explanation is taken from an [in-depth article](https://www.atlassian.com/git/tutorials/comparing-workflows#!workflow-forking) on that model:
<!-- vale off -->
> Instead of using a single server-side repository to act as the *central* codebase, it gives every developer a server-side repository. This means that each contributor has not one, but two Git repositories: a private local one and a public server-side one.
>
> The main advantage of the Forking Workflow is that contributions can be integrated without the need for everybody to push to a single central repository. Developers push to their own server-side repositories, and only the project maintainer can push to the official repository. This allows the maintainer to accept commits from any developer without giving them write access to the official codebase.
>
> The result is a distributed workflow that provides a flexible way for large, organic teams (including untrusted third-parties) to collaborate securely. This also makes it an ideal workflow for open source projects.
> The result is a distributed workflow that provides a flexible way for large, organic teams (including not trusted third-parties) to collaborate securely. This also makes it an ideal workflow for open source projects.
The workflow is summarized in the following image from the [GitHub blog](https://github.com/blog/2042-git-2-5-including-multiple-worktrees-and-triangular-workflows):
@@ -71,7 +75,7 @@ This creates a new folder `ogs` in your current working directory with the OGS s
<divclass='note'>
The `--filter=blob:limit=100k`-parameter instructs git to only fetch files which are smaller than 100 Kbyte. Larger files (e.g. benchmark files, images, PDFs) are fetched on-demand only. This happens automatically and [is a replacement for the previous Git LFS tracked files](https://github.com/ufz/ogs/issues/2961). Requires at least **git 2.22**!
The `--filter=blob:limit=100k`-parameter instructs git to only fetch files which are smaller than 100 Kilobyte. Larger files (e.g. benchmark files, images, PDFs) are fetched on-demand only. This happens automatically and [is a replacement for the previous Git LFS tracked files](https://github.com/ufz/ogs/issues/2961). Requires at least **git 2.22**!
</div>
...
...
@@ -188,6 +192,10 @@ If your work is done submit a [merge request](https://gitlab.opengeosys.org/ogs/
Again this triangular workflow is summarized with this picture:
> […] the Forking Workflow requires two remotes—one for the official repository, and one for the developer’s personal server-side repository. While you can call these remotes anything you want, a common convention is to use origin as the remote for your forked repository […] and upstream for the official repository.
> Docker containers wrap up a piece of software in a complete filesystem that contains everything it needs to run: code, runtime, system tools, system libraries – anything you can install on a server. This guarantees that it will always run the same, regardless of the environment it is running in.
See the [docs](https://docs.docker.com) for installation instructions (if you are on Windows we highly recommend the [Docker Desktop WSL 2 backend](https://docs.docker.com/docker-for-windows/wsl/)).
## Images
Docker images can be created by [Dockerfiles](https://docs.docker.com/reference/builder/) which can be stacked and thus form a directed graph. OGS-6 image definitions are created with [ufz/ogs-container-maker](https://github.com/ufz/ogs-container-maker). Built images can be found at the [GitLab Container Registry](https://gitlab.opengeosys.org/ogs/ogs/container_registry). You can also [create images from your local source code](https://github.com/ufz/ogs-container-maker#build-ogs-from-local-git-repo).
Docker images can be created by [Dockerfiles](https://docs.docker.com/reference/builder/) which can be stacked and thus form a directed graph. OGS-6 image definitions are created with [`ufz/ogs-container-maker`](https://github.com/ufz/ogs-container-maker). Built images can be found at the [GitLab Container Registry](https://gitlab.opengeosys.org/ogs/ogs/container_registry). You can also [create images from your local source code](https://github.com/ufz/ogs-container-maker#build-ogs-from-local-git-repo).
To build an image by yourself create a Dockerfile:
@@ -34,17 +34,17 @@ If a binary runs on a different machine depends on a lot of factors. The followi
### Default compiler flags
-`-march=native`: Optimizes for current cpu
-`-march=native`: Optimizes for current CPU
### CMake options
#### For redistribution
-`OGS_CPU_ARCHITECTURE`: set to `generic` for good balance between optimization and portability; set to `core2` for maximum portability, more info on [gcc docs](https://gcc.gnu.org/onlinedocs/gcc/x86-Options.html#index-mtune-15)
-`OGS_CPU_ARCHITECTURE`: set to `generic` for good balance between optimization and portability; set to `core2` for maximum portability, more info on [GCC docs](https://gcc.gnu.org/onlinedocs/gcc/x86-Options.html#index-mtune-15)
#### For optimization
-`OGS_CPU_ARCHITECTURE`: tot to `native` for best optimization for your current cpu, possible values are [listed here](https://stackoverflow.com/a/25095818/80480), more info on [gcc docs](https://gcc.gnu.org/onlinedocs/gcc/x86-Options.html#index-mtune-15)
-`OGS_CPU_ARCHITECTURE`: tot to `native` for best optimization for your current CPU, possible values are [listed here](https://stackoverflow.com/a/25095818/80480), more info on [GCC docs](https://gcc.gnu.org/onlinedocs/gcc/x86-Options.html#index-mtune-15)
</div>
...
...
@@ -56,7 +56,7 @@ See Linux-tab!
Try to use static libraries as much as possible. For OGS itself use `BUILD_SHARED_LIBS=OFF`, which already defaults to `OFF`.
Third-party libraries installed via the systems package package manager are often provided as shared libraries. You may want to use [Conan]({{<ref"conan-package-manager.md">}}) which provides lots of libraries (e.g. VTK) as static libs.
package manager are often provided as shared libraries. You may want to use [Conan]({{<ref"conan-package-manager.md">}}) which provides lots of libraries (e.g. VTK) as static libraries.
This starts the container, mounts your home directory inside the container, passes the current working directory and runs the ogs executable (which is in your home directory which is mounted inside the container) with the passed project file. Everything works as expected and is transparent to the user. When ogs finishes the container stops and you returns to the host system.
This starts the container, mounts your home directory inside the container, passes the current working directory and runs the OGS executable (which is in your home directory which is mounted inside the container) with the passed project file. Everything works as expected and is transparent to the user. When OGS finishes the container stops and you returns to the host system.
Eve has [Singularity](https://www.sylabs.io/singularity) container runtime installed so you can simply download a prebuilt container and run OGS inside it. See the [user guide]({{<ref"container">}}) for more infos.
Eve has [Singularity](https://www.sylabs.io/singularity) container runtime installed so you can simply download a prebuilt container and run OGS inside it. See the [user guide]({{<ref"container">}}) for more information.
@@ -37,6 +39,8 @@ We provide CMake configuration presets defined in [CMakePresets.json](https://gi
| PETSc Release | release-petsc | - |
| PETSc Debug | debug-petsc | - |
<!-- vale on -->
[^1]:Requires the `ninja`-tool. See [install instructions]({{<ref"prerequisites.md#optional-install-ninja">}}).
### Configure with a preset
...
...
@@ -98,7 +102,7 @@ cmake --preset=release
#### <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:
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 configurations would be initialized as follows:
```bash
cmake --preset=msvc-release
...
...
@@ -148,7 +152,7 @@ CMake comes with a graphical tool called **cmake-gui**. You can find it in the *
<divclass='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` instead of `cmake`:
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`:
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.
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.
#### About Visual Studio startup projects
...
...
@@ -25,7 +25,7 @@ The reason for this is that you can have only one sub-project of your Visual Stu
### How to work with CMake and Visual Studio
You can work normally in Visual Studio but remember that you have to make project changes in the `CMakeLists.txt`-file and not inside Visual Studio. So you can add a new source file within Visual Studios File menu but you have to add that file also to the CMake file. Every time you change a `CMakeLists.txt` and you build the project a new CMake run is automatically invoked. After that Visual Studio informs you that the project files were changed and it reloads them.
You can work normally in Visual Studio but remember that you have to make project changes in the `CMakeLists.txt`-file and not inside Visual Studio. You can add a new source file within Visual Studios File menu but you have to add that file also to the CMake file. Every time you change a `CMakeLists.txt` and you build the project a new CMake run is automatically invoked. After that Visual Studio informs you that the project files were changed and it reloads them.
</div>
<divclass='linux'>
...
...
@@ -70,7 +70,7 @@ See Linux-tab!
## Waiting
So now the build process is running... This can take some time because maybe there are external libraries which get automatically downloaded and compiled. This step is only done once per build directory, so subsequent builds will be much faster. See [this]({{<ref"cpm.md">}}) for more.
Now the build process is running... This can take some time because maybe there are external libraries which get automatically downloaded and compiled. This step is only done once per build directory, so subsequent builds will be much faster. See [this]({{<ref"cpm.md">}}) for more.
The `--filter=blob:limit=100k`-parameter instructs git to only fetch files which are smaller than 100 Kbyte. Larger files (e.g. benchmark files, images, PDFs) are fetched on-demand only. This happens automatically and [is a replacement for the previous Git LFS tracked files](https://github.com/ufz/ogs/issues/2961). Requires at least **git 2.22**!
The `--filter=blob:limit=100k`-parameter instructs git to only fetch files which are smaller than 100 Kilobyte. Larger files (e.g. benchmark files, images, PDFs) are fetched on-demand only. This happens automatically and [is a replacement for the previous Git LFS tracked files](https://github.com/ufz/ogs/issues/2961). Requires at least **git 2.22**!
