Merge branch 'master' of github.com:precice/precice.github.io

_data/sidebars/docs_sidebar.yml

@@ -89,6 +89,10 @@ entries:
             url: /installation-source-installation.html
             output: web, pdf
 
+          - title: Finding
+            url: /installation-source-finding.html
+            output: web, pdf
+
           - title: Advanced
             url: /installation-source-advanced.html
             output: web, pdf

pages/docs/dev-docs/dev-conventions.md

@@ -11,18 +11,18 @@ summary: This page describes general and coding conventions used in preCICE.
 - CamelCase notation is used, no underlines please.
 - Make sure your code compiles before you commit.
 - Pay attention to compiler generated warnings and try to fix them.
-- In case you can't fix a unused variable warning, e.g. with range based for loops, you can use std::ignore = vertex; // Silence unused variable warning.
+- In case you can't fix a unused variable warning, e.g. with range based for loops, you can use `std::ignore = vertex; // Silence unused variable warning`.
 - Use `std::vector::empty()` to check for emptiness, not `vector.size() == 0`. `empty()` is guaranteed to be O(1) for all STL container classes. Furthermore, it says what you are actually doing.
 - Use `#pragma once` as an include guard.
-- Use `std::make_shared` for creating smart pointers. Why: <a href="https://stackoverflow.com/questions/20895648/difference-in-make-shared-and-normal-shared-ptr-in-c">Difference in make_shared and normal shared_ptr in C++</a>
+- Use `std::make_shared` for creating smart pointers. Why: [Difference in make_shared and normal shared_ptr in C++](https://stackoverflow.com/questions/20895648/difference-in-make-shared-and-normal-shared-ptr-in-c).
 
 ## Indentation and formatting
 
 As a rule of thumb again: Orient yourself on the already written code!
 
-There is a settings file for `clang-format`. See the page on \ref tooling for more information on clang-format.
+There is a settings file for `clang-format`. See the page on [Tooling](dev-docs-dev-tooling.html#formatting-the-code") for more information on clang-format.
 
-Regarding indentation, we follow the BSD-style.
+Regarding indentation, we follow the [BSD-style](https://en.wikipedia.org/wiki/Indentation_style#Allman_style).
 
 We do not indent namespaces since three or so levels of nested namespaces fill the offset without adding any viable information.
 

pages/docs/dev-docs/dev-tooling.md

@@ -25,8 +25,6 @@ To keep the code-base consistent, please use `clang-format` version 8.
 Scripts will explicitly use `clang-format-8` to prevent any problems.
 Looking for precompiled binaries? Here is the [official APT repository](http://apt.llvm.org/).
 
-We also use a custom formatting tool for XML files based on python 3 and the lxml package. So make sure to install it e.g. via `pip install --user lxml`.
-
 To format the entire codebase, run our formatting tool:
 
 ```bash
@@ -73,6 +71,24 @@ void formatted_code_again;
 void formatted_code_yet_again;
 ```
 
+## Formatting preCICE configuration files
+
+To format your `precice-config.xml`, you can use the script `format_precice_config.py` which is part of the [preCICE pre-commit hooks](https://github.com/precice/precice-pre-commit-hooks) (without needing to install the pre-commit hooks) and depends on the lxml package (install it with `pip install --user lxml`). To format a file in place:
+
+```bash
+format_precice_config.py precice-config.xml
+```
+
+The script returns 0 on success, 1 on error, and 2 if a file was modified.
+
+You may want to define an alias for convenience:
+
+```bash
+function preciceConfigFormat(){
+  /path/to/format_precice_config.py "${1:-precice-config.xml}"
+}
+```
+
 ## clang-tidy
 
 The tool `clang-tidy` runs static analysis on C and C++ files and reports warnings in clang error format (i.e. editors can parse them).

pages/docs/installation/installation-source-finding.md

@@ -0,0 +1,93 @@
+---
+title: Building from source - Finding
+permalink: installation-source-finding.html
+keywords: configuration, basics, cmake, installation, building, source, bash, profile
+toc: false
+---
+
+If you installed preCICE in a custom prefix, then one still needs to make it discoverable by the system.
+
+The preCICE library needs to be discoverable in various ways:
+
+1. The location of headers needs to be available during compilation.
+   Compilers use hints from `CPATH` if no extra compilation flags were passed to them using `-I`.
+2. The shared library needs to be available during linking and execution.
+   The dynamic linker uses hints from `LD_LIBRARY_PATH` (`DYLD_LIBRARY_PATH` on MacOS X).
+3. The preCICE executables need to be in `PATH` (optional, only for additional tools).
+
+As this setup can become tedious to maintain, there are some tools that expose the above details.
+However, they also need to find preCICE in some way:
+
+* `pkg-config` and `pkgconf` use `PKG_CONFIG_PATH` to search for additional `.pc` files.
+* `CMake` uses `CMAKE_PREFIX_PATH` for additional installation prefixes.
+  Alternatively, one can specify the location of the preCICE CMake configuration file using `precice_DIR`.
+
+## Using the shell
+
+If you are using a Unix-like system, you are using a shell, which offers an easy and straight forward way to make preCICE discoverable.
+
+Let `PRECICE_PREFIX` be the installation prefix chosen during the [preparation step](installation-source-preparation#installation-prefix).
+Then add the following to your `.profile` (for bash) or `.zshrc` (for zsh).
+
+```bash
+# set this to your selected installation prefix
+PRECICE_PREFIX=~/software/prefix
+export PATH=$PRECICE_PREFIX/bin:$PATH
+export LD_LIBRARY_PATH=$PRECICE_PREFIX/lib:$LD_LIBRARY_PATH
+export CPATH=$PRECICE_PREFIX/include:$CPATH
+# Enable detection with pkg-config and CMake
+export PKG_CONFIG_PATH=$PRECICE_PREFIX/lib/pkgconfig:$PKG_CONFIG_PATH
+export CMAKE_PREFIX_PATH=$PRECICE_PREFIX:$CMAKE_PREFIX_PATH
+```
+
+After adding these variables, start a new session (open a new terminal or logout and login again).
+
+## Using systemd environment.d
+
+An alternative to the above system is to set these variables in the shell-agnostic [`environment.d`](https://www.man7.org/linux/man-pages/man5/environment.d.5.html).
+
+Create the directory if it does not yet exist:
+
+```terminal
+mkdir -p ~/.config/environment.d/
+```
+
+Let `PRECICE_PREFIX` be the installation prefix chosen during the [preparation step](installation-source-preparation#installation-prefix).
+Then create a file `~/.config/environment.d/99-precice.conf` with the content:
+
+```conf
+# set this to your selected installation prefix
+PRECICE_PREFIX=$HOME/software/prefix
+PATH=${PRECICE_PREFIX}/bin:${PATH}
+LD_LIBRARY_PATH=${PRECICE_PREFIX}/lib:${LD_LIBRARY_PATH}
+CPATH=${PRECICE_PREFIX}/include:${CPATH}
+# Enable detection with pkg-config and CMake
+PKG_CONFIG_PATH=${PRECICE_PREFIX}/lib/pkgconfig:${PKG_CONFIG_PATH}
+CMAKE_PREFIX_PATH=${PRECICE_PREFIX}:${CMAKE_PREFIX_PATH}
+```
+
+After adding the file, logout and login again. Opening a new terminal will not be sufficient.
+
+## Using directly from the binary directory
+
+{% warning %}
+This method is strongly discouraged unless you are a preCICE developer.
+Install preCICE into a prefix unless you have a very good reason not to.
+{% endwarning %}
+
+It may not always be practical to install preCICE repeatedly.
+This is especially the case for simultaneous development of preCICE and an adapter, or while profiling the internals.
+
+This method is discouraged as file layouts are fundamentally different and we make **no** guarantees on keeping them consistent between releases.
+Hence, the only reliable methods for using preCICE from the binary directory require `pkg-config` or `CMake`.
+If your adapter or solver isn't using one of these methods, then we strongly suggest to install preCICE to a prefix or port the adapter to `pkg-config`.
+
+First extend `LD_LIBRARY_PATH` with the binary directory if you don't plan to use `rpath` (which `CMake` does by default).
+For `pkg-config` users, extend `PKG_CONFIG_PATH` with the binary directory.
+For `CMake` users, either set the environment variable `precice_DIR` to the binary directory prior to calling `CMake`, or pass it as a `CMake` variable during configuration.
+
+## Next steps
+
+This concludes the preCICE installation for custom prefixes and you should have a working installation of preCICE on your system.
+
+To use preCICE in your project, see the page [Linking to preCICE](installation-linking).

pages/docs/installation/installation-source-installation.md

@@ -17,28 +17,9 @@ To test your installation please run `make test_install`.
 This will attempt to build our C++ example program against the **installed version** of the library.
 This is commonly known as _the smoke test_.
 
-## Make preCICE installation findable
-
-In case you chose a user-wide prefix installation, see preparation section on the [installation prefix](installation-source-advanced#installation-prefix), you need to extend some additional environment variables. This is needed such that other applications and preCICE adapters can find your preCICE installation. Please add the following lines your `~/.bashrc` and replace `<prefix>` with your selected prefix:
-
-```bash
-PRECICE_PREFIX=~/software/prefix # set this to your selected prefix
-export PATH=$PRECICE_PREFIX/bin:$PATH
-export LD_LIBRARY_PATH=$PRECICE_PREFIX/lib:$LD_LIBRARY_PATH
-export CPATH=$PRECICE_PREFIX/include:$CPATH
-# Enable detection with pkg-config and CMake
-export PKG_CONFIG_PATH=$PRECICE_PREFIX/lib/pkgconfig:$PKG_CONFIG_PATH
-export CMAKE_PREFIX_PATH=$PRECICE_PREFIX:$CMAKE_PREFIX_PATH
-```
-
-After adding these variables, please start a new session (open a new terminal or logout and login again).
-
-{% note %}
-On MacOS X some of the environment variables have different names. For example, you have to extend the environment variable `DYLD_LIBRARY_PATH` instead of `LD_LIBRARY_PATH`.
-{% endnote %}
-
 ## Next steps
 
-This concludes the preCICE installation and you should have a working installation of preCICE on your system.
-
+If you chose a system directory as installation prefix, then this concludes the preCICE installation and you should have a working installation of preCICE on your system.
 To use preCICE in your project, see the page [Linking to preCICE](installation-linking).
+
+For custom prefixes, the installation needs to be discoverable by the system, which leads us to the final step, [finding preCICE](installation-source-finding).