tutorial/compilation.md

+# Compilation
+
+For compiling the SHEMAT-Suite source code inside `~/SHEMAT-Suite/`, a
+`cmake` command is used. This site explains how to build SHEMAT-Suite using `cmake`.
+
+You might want to read the [installation requirements](release/howtos/installation_requirements) first.
+
+New users, please start with [Compilation command
+cmake](#compilation-command-cmake). More advanced users, please also
+look at the [Compilation: Best
+Practices](#compilation-best-practices).
+
+Not downloaded SHEMAT-Suite source code yet? [ Learn how to clone it
+here](./checkout)!
+
+The SHEMAT-Suite executable is ready to go? Proceed to
+[Execution](./execution).
+
+If you encounter **Errors or Warnings** write an
+[Issues](https://git.rwth-aachen.de/SHEMAT-Suite/SHEMAT-Suite/issues)
+on the Gitlab page of SHEMAT-Suite.
+
+## Table of Contents ##
+
+[[_TOC_]]
+
+# Compilation command cmake
+
+The source code of SHEMAT-Suite should be located in a directory
+of the form `/path/to/SHEMAT-Suite/` . Most commonly this would be
+your home-directory `~/SHEMAT-Suite`. Go to the directory
+containing SHEMAT-Suite by executing:
+
+```
+cd /path/to/SHEMAT-Suite
+```
+
+For compiling the source code and building an executable, use the command `cmake` as described below.
+
+Create a build-directory and go there
+```
+mkdir build
+cd build
+```
+
+Run `cmake` inside the build-directory with the default configuration as follows
+```
+cmake ..
+gmake
+```
+
+In general, we want to include some information about our compilation:
+```
+cmake -Dphys_base =<phys> -DPROPS=<props> -DUSER=<user> -Domp=<ON/OFF> -Dhdf=<ON/OFF> -Ddetails=<ON/OFF> ..
+gmake <mode> -j<#>
+```
+
+-   `<mode>`
+
+1.  `fw` (forward mode)
+2.  `sm` (stochastic mode)
+3.  `ad` (inverse mode automatic differentiation)
+4.  `ad` (inverse mode divided differences)
+5.  `lib_oed` (build code as a library)
+6.  For more information see [Branches](../branches).
+
+-   `<phys>`
+
+1.  `head` (head-based flow equation)
+2.   `pres` (pressure-based flow equation) 
+
+-   `<props>`
+
+1.  `const`
+2.  `bas`
+3.  `basc`
+4.  other PROPS-directory found in
+    `/path/to/SHEMAT-Suite/props/`. Find more information on property
+    modules [here](../props).
+
+-   `<flags>`
+
+1.  `-Dvtk` (no support for VTK-Output)
+2.  `-Dhdf` (no support for [hdf5](../howtos/output)-Output)
+3.  `-Dplt` (no support for Tecplot-Output)
+4.  `-Ddebug` (Debugging flags, no optimization)
+5.  `-Domp` (no OpenMP support)
+6.  all allowed switches/flags can be found in the file
+    `/path/to/SHEMAT-Suite/cmake/Options.cmake`
+
+-   `<#>`
+
+1.  `16` (bigger number = faster compilation)
+
+**Remark**: The compiler to use is automatically detected by `cmake`. 
+SHEMAT-Suite can be compiled using `gcc` or `intel` compilers. 
+
+Alternatively, `cmake` provides a **GUI** for chosing the compilation optionas and settings. The command
+
+```
+cmake-gui .
+```
+can be run in the `build` directory of SHEMAT-Suite to visually browse the `cmake` configuration.
+
+### hdf5 support
+
+For `hdf5` support, the corresponding software has to be installed (see  [installation requirements](release/howtos/installation_requirements)).
+
+# Compilation: Best Practices
+
+The compilation shell script
+[compilequick.sh](https://git.rwth-aachen.de/SHEMAT-Suite/SHEMAT-Suite_Models/blob/master/compilequick.sh) in the Gitlab
+repository [SHEMAT-Suite_Models](https://git.rwth-aachen.de/SHEMAT-Suite/SHEMAT-Suite_Models) includes all compilation best
+practices!
+
+
+Here, some best practices for compilation are written down. There are
+two good things to do:
+
+1.  rename the executable to reflect your input (for example including
+    the branch of SHEMAT-Suite, under which the executable was compiled)
+2.  Move the compilation output to the model directory along with the
+    executable (See [Compilation Output](#compilation-output))
+3.  Write a Compilation Shell Script (for an example [Compilation
+    Shell Script](#compilation-shell-script))
+
+### Compilation Output
+
+Compilation Output generated automatically by SHEMAT-Suite includes the
+two files
+
+```
+CMakeCache.txt
+version.inc
+```
+
+These files include general information about the compilation
+(`CMakeCache.txt`) and SHEMAT-Suite version information. Both can be
+very helpful, when errors occur.
+
+### Compilation Shell Script
+
+A compilation shell script (`compilequick.sh`) can be found in
+[SHEMAT-Suite_Models](https://git.rwth-aachen.de/SHEMAT-Suite/SHEMAT-Suite_Models):
+[compilequick.sh](https://git.rwth-aachen.de/SHEMAT-Suite/SHEMAT-Suite_Models/blob/master/compilequick.sh). Another
+script wich includes more module loading options can be found in
+[SHEMAT-Suite_Models/deltasets](https://git.rwth-aachen.de/SHEMAT-Suite/SHEMAT-Suite_Models/tree/master/deltatests):
+[compilequick.sh](https://git.rwth-aachen.de/SHEMAT-Suite/SHEMAT-Suite_Models/blob/master/deltatests/compilequick.sh).
+Use the first script to compile SHEMAT-Suite. Specify your model
+directory under `model_dir`, then specify the make directory (the
+SHEMAT-Suite directory) under `make_dir` and a few more variables
+(compilation type, head or pres mode, property module, user directory,
+compiler and compiler flag). Finally you can execute it as follows
+
+```
+./compilequick.sh
+```
+
+It will compile SHEMAT-Suite in `make_dir` and afterwards move the
+executable to `model_dir` along with the files `version.inc`,
+`CMakeCache.txt`. To be noted, the local and the online git version of the `make_dir` SHEMAT repository must be equal.