Verified Commit 0c24dc2c authored by Lars Bilke's avatar Lars Bilke
Browse files

[markdownlint] web/content/docs/devguide.

parent 51415e20
......@@ -43,7 +43,7 @@ brew install ccache
<div class='win'>
Windows support in ccache is not yet in the main ccache development line. Please install ccache from https://github.com/cristianadam/ccache/releases.
Windows support in ccache is not yet in the main ccache development line. Please install [ccache](https://github.com/cristianadam/ccache/releases).
Just extract the archive and put the `ccache.exe` into the `PATH`.
......
......@@ -26,7 +26,7 @@ $ jq -r '.cpm.package_file_id' web/data/versions.json
Now simply download the file with:
```
```bash
curl https://gitlab.opengeosys.org/ogs/ogs/-/package_files/[insert ID here]/download --output cpm.tar.gz
```
......
......@@ -45,7 +45,7 @@ The current style is defined in [.cmake-format.yaml](https://gitlab.opengeosys.o
On installation make sure to install with the yaml option:
```
```bash
pip install cmakelang[YAML]
```
......
......@@ -35,4 +35,4 @@ If you do not want a reviewer to have a look, e.g. because you are currently wor
On the merge request page in the first box which contains information on the MR author and branch name there is button labelled `Check out branch` which will show you instructions on how to locally checkout this MR:
![](checkout-branch.png)
![The checkout branch button in the GitLab web interface](checkout-branch.png)
......@@ -128,7 +128,6 @@ brew install clang-format
</div>
## Optional: Working on a new feature
You only have to follow the above steps once. From then on, whenever you want to work on a new feature, you can more easily interact with the remote repositories.
......
......@@ -27,6 +27,7 @@ If a binary runs on a different machine depends on a lot of factors. The followi
### Optimization CMake options
- `OGS_CPU_ARCHITECTURE`: possible values `AMD64` or `INTEL64` (sets `/favor:{AMD64 | INTEL64}` flag)
</div>
<div class='linux'>
......@@ -44,6 +45,7 @@ If a binary runs on a different machine depends on a lot of factors. The followi
#### 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)
</div>
<div class='mac'>
......
......@@ -40,11 +40,13 @@ Singularity per default mounts your home directory and also passes your current
- *CentOS 6/7 / RedHat*: Install via [EPEL](https://sylabs.io/guides/3.0/user-guide/installation.html#install-the-centos-rhel-package-using-yum).
- *Ubuntu 20.04 / Debian Sid*:
```
```bash
wget http://ftp.us.debian.org/debian/pool/main/s/singularity-container/singularity-container_3.9.6+ds1-1_amd64.deb
sudo apt install containernetworking-plugins squashfs-tools
sudo dpkg -i singularity-container_3.9.6+ds1-1_amd64.deb
```
- **OR** install [Homebrew](https://docs.brew.sh/Homebrew-on-Linux) package `singularity`.
- If you do not have one of the above OS versions [install Singularity from source](https://sylabs.io/guides/3.5/user-guide/quick_start.html#quick-installation-steps).
......
......@@ -86,7 +86,7 @@ You can create a `CMakeUserPresets.json` file in the root source directory with
<div class='note'>
### Windows notes:
### Windows notes
#### <i class="far fa-check"></i> Ninja requirement: Use the Visual Studio command line
......
......@@ -18,6 +18,7 @@ To compiled OGS with PETSc, MPI c++ compiler wrappers like OpenMPI, MPICH (
has many derivatives, e.g intelMPI), and PETSc have to be installed as prerequisites.
## Install MPI
MPI c++ compiler wrappers are essentially installed on most of Linux clusters
and supercomputers, and they are usually managed by the environment module of operating system.
What you have to do on that platforms is just to load a proper MPI wrapper module.
......@@ -25,15 +26,18 @@ On Linux powered laptop, PC, or work station, you can install OpenMPI or MPICH v
the package manager of the Linux distribution, e.g. RPM of RedHat, pacman of Arch.
## Install PETSc
If PETSc is not installed on your system, you can download the PETSc source code
(https://petsc.org/release/download/), compile it
(<https://petsc.org/release/download/>), compile it
and install by yourself according to the PETSc's installation instruction on
https://petsc.org/release/install/.
<https://petsc.org/release/install/>.
Here is an example of PETSc configuration:
```
```bash
./configure PETSC_ARCH=linux-fast COPTFLAGS='-O3 --prefix=/home/me/opt/petsc --with-debugging=0 -march=native -mtune=native' CXXOPTFLAGS='-O3 -march=native -mtune=native' --with-cc=mpicc --with-cxx=mpicxx --with-fc=mpif90 --download-fblaslapack --download-metis --download-parmetis --download-superlu_dist --download-scalapack --download-mumps --download-hypre --with-c2html=0 --with-cxx-dialect=C++11 --with-cuda=0`
```
With that configuration, PETSc will be compiled without PETSc debugging model (`--with-debugging=0`),
and installed to `opt` directory of the home directory. For Arch Linux, if you
install PETSc package from AUR repository, please keep in mind that
......@@ -42,22 +46,23 @@ With that configuration, PETSc will be compiled without PETSc debugging model (`
PETSc debugging model gives low performance. You can manually edit PKGBUILD of PETSc from AUR by
adding the option of `--with-debugging=0` before installation.
Please note that the PETSc package is preferred to build in release model regardless of
OGS being built with release or debug preset because that you may not like to debug the
source code of PETSc and want to have a better computational performance.
PESTSc is recommended to use on Linux. On Windows, it only runs on
UNIX emulator Cygwin. A detailed description about how to use PETSc on Windows
is available on this PETSc site: https://petsc.org/main/install/windows/.
is available on this PETSc site: <https://petsc.org/main/install/windows/>.
One the frontends of EVE cluster of UFZ, your can load specified MPI, PETSc and
other modules by command:
```
```bash
source [path to ogs source code]/scripts/env/eve/petsc.sh
```
## Build configuration of OGS
For CMake configuration, the option of `OGS_USE_PETSC` must be set to true.
It is `-DOGS_USE_PETSC=ON` for command line.
......@@ -71,9 +76,11 @@ when `OGS_USE_PETSC` is switched on, the compilation will fail with missed
library error.
For simplicity, you can first run cmake with MPI C/C++ compiler specified. For example:
```
```bash
cmake [path to source code] [-GNinja] -DOGS_USE_PETSC=ON -DCMAKE_C_COMPILER=/usr/bin/mpicc -DCMAKE_CXX_COMPILER=/usr/bin/mpic++
```
and then use *ccmake* or *cmake-gui* to configure further more CMake options.
The other basic build configurations are the same as that described in [Build configuration]({{<ref
......
......@@ -19,7 +19,7 @@ weight = 1003
To get the latest source code simply download it from [repository website](https://gitlab.opengeosys.org/ogs/ogs) and extract the archive:
![](zip-download.png)
![Getting the zip download URL from the GitLab web interface](zip-download.png)
You can also download and extract with the command line:
......@@ -27,12 +27,14 @@ You can also download and extract with the command line:
wget https://gitlab.opengeosys.org/ogs/ogs/-/archive/master/ogs-master.tar.gz
tar xf ogs-master.tar.gz
```
----
## Option: Clone the source code repository with Git
First you need to get the clone url:
![](git-url.png)
![Getting the git clone URL from the GitLab web interface](git-url.png)
Then clone the repository with `git`:
......
......@@ -199,6 +199,7 @@ git config --global http.proxy http://yourproxy.example.com
- Download the installer, at the [CMake download page](http://www.cmake.org/cmake/resources/software.html) choose the **Windows (Win32 Installer)**.
- Execute the installer, please check the **Add CMake to the system path for all users**-option
</div>
<div class='linux'>
......@@ -218,7 +219,6 @@ brew install cmake
</div>
## Optional: Install Ninja
We recommend [`ninja`](https://ninja-build.org) as a cross-platform build tool (`make`-replacement).
......
......@@ -31,10 +31,10 @@ weight = 1080
- `# ogs-doxygen-v[TAG (- separated instead of .)]`
- Create branch from `master` with name `v[TAG]` and push
- Create a discourse announcement post
- DOI badge
- Software heritage badge
- Link to release page on opengeosys.org
- Link to GitLab release
- Link to Zenodo release
- Link to archive on Software Heritage
- DOI badge
- Software heritage badge
- Link to release page on opengeosys.org
- Link to GitLab release
- Link to Zenodo release
- Link to archive on Software Heritage
- Set milestone on expired issues and merge requests
......@@ -16,9 +16,9 @@ We use the workflow manager [Snakemake](https://snakemake.readthedocs.io) to tes
## Requirements
- [Snakemake](https://snakemake.readthedocs.io/en/stable/getting_started/installation.html) >= {{< dataFile "versions.minimum_version.snakemake" >}}
- If you use `OGS_USE_PIP=ON` then `snakemake` is installed in your virtual environment in your build-directory automatically. You can then call it via `.venv/bin/snakemake ...` (inside your build directory).
- If you use `OGS_USE_PIP=ON` then `snakemake` is installed in your virtual environment in your build-directory automatically. You can then call it via `.venv/bin/snakemake ...` (inside your build directory).
- On Windows only:
- The `tee`-utility in the `PATH` (can be installed from https://sourceforge.net/projects/unxutils)
- The `tee`-utility in the `PATH` (can be installed from <https://sourceforge.net/projects/unxutils>)
## Examples
......
......@@ -18,7 +18,7 @@ This page describes errors you get at runtime of OGS, e.g. when executing the `o
Typical error message:
```
```bash
error while loading shared libraries: libXX.so: cannot open shared object file: No such file or directory
```
......@@ -28,10 +28,11 @@ A shared library which was linked to OGS could not be found during runtime. The
export LD_LIBRARY_PATH=/path/to/missing/lib:$LD_LIBRARY_PATH
./ogs
```
More information can be found here:
- https://tldp.org/HOWTO/Program-Library-HOWTO/shared-libraries.html
- https://amir.rachum.com/blog/2016/09/17/shared-libraries/#runtime-search-path
- <https://tldp.org/HOWTO/Program-Library-HOWTO/shared-libraries.html>
- <https://amir.rachum.com/blog/2016/09/17/shared-libraries/#runtime-search-path>
If you use Conan you want to activate its [runtime environment]({{< relref "conan-package-manager.md#conan-environment" >}}).
......@@ -41,7 +42,7 @@ One can see with the `ldd` (macOS: `otool -L`) tool which dynamic libraries will
Typical error message:
```
```bash
XX.dll could not be found.
```
......
Supports Markdown
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment