[web] Finished devguide/getting-started.

web/content/docs/devguide/development-workflows/branching-model.pandoc

@@ -0,0 +1,36 @@
++++
+date = "2018-02-23T15:28:13+01:00"
+title = "Branching model"
+author = "Lars Bilke"
+weight = 1011
+
+[menu]
+  [menu.devguide]
+    parent = "development-workflows"
++++
+
+## Forking workflow
+
+Git is very flexible in organizing a distributed development team. We use a so called **Forking workflow**.
+
+The following explanation is taken from an [in-depth article](https://www.atlassian.com/git/workflows#!workflow-forking) on that model:
+
+> 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.
+> <cite> https://www.atlassian.com/git/workflows#!workflow-forking </cite>
+>
+
+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):
+
+![](https://cloud.githubusercontent.com/assets/1319791/8943755/5dcdcae4-354a-11e5-9f82-915914fad4f7.png)
+
+You always **fetch** changes from official repository (called **upstream**), develop on your **local** repository and **push** changes to your server-side repository (called **origin**).
+
+First thing to do when you start working on your local repository is to create a topic branch (based on the current master branch of the official repository) specific to a well defined feature or bugfix you are about to implement. **Never** work on the **master**-branch (it is reserved for the official version)! See also [this tutorial](https://www.atlassian.com/git/tutorial/git-branches#!overview) on branching.
+
+Start committing changes in logical chunks. After you are happy with your implementation push your topic branch to your forked repository on GitHub.
+
+Open a *Pull Request* which will initiate the code review process.

web/content/docs/devguide/getting-started/build-configuration.pandoc

@@ -0,0 +1,106 @@
++++
+date = "2018-02-23T15:28:13+01:00"
+title = "Build configuration"
+author = "Lars Bilke"
+weight = 1004
+
+[menu]
+  [menu.devguide]
+    parent = "getting-started"
++++
+
+## Overview
+
+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 should **not** be placed inside the source code. 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-release`
+- `build-debug`
+- `build-release-mpi`
+
+So just go ahead and create a build-directory along your source code directory.
+
+
+## Install required libraries with Conan
+
+It is preferred to use Conan package manager to install required third-party libraries. To use Conan add the CMake option `OGS_USE_CONAN=ON` to the CMake run (see below). This will run Conan automatically downloading either prebuilt binaries of required libraries or building them locally if a binary for your setup (operating system, compiler, ..) is not available. [Check this]({entry:674:url}) for advanced Conan usage.
+
+*Note:* Instead of using Conan you can optionally [install the required libraries manually]({entry:81:url}).
+
+::: {.win}
+Add `-DOGS_USE_CONAN=ON` to the CMake-run (see below).
+
+::: {.note}
+### 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 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:
+
+```bash
+$ [assuming you are at the same directory where the source code directory is located]
+$ mkdir ogs-build && cd ogs-build
+$ mkdir debug && cd debug
+$ cmake ../../ogs -G "Visual Studio 14 2015 Win64" -DOGS_USE_CONAN=ON -DCMAKE_BUILD_TYPE=Debug
+$ cd .. && mkdir release && cd release
+$ cmake ../../ogs -G "Visual Studio 14 2015 Win64" -DOGS_USE_CONAN=ON -DCMAKE_BUILD_TYPE=Release
+```
+
+`..\..\ogs` represents the relative path to the source code (please adapt if you have a different directory layout).
+
+Please also note that in Visual Studio you have to choose the correct configuration (i.e. when opening the solution-file in the release-folder you have to switch the Visual Studio configuration to **Release**)!
+:::
+:::
+
+::: {.linux}
+Add `-DOGS_USE_CONAN=ON` to the CMake-run (see below).
+:::
+
+::: {.mac}
+Add `-DOGS_USE_CONAN=ON` to the CMake-run (see below).
+:::
+
+
+## Configure with CMake
+
+For configuring a build the open source [CMake](http://www.cmake.org) tool is used. CMakeLists.txt files replace traditional Makefiles or IDE project files. The CMake tool is run inside the build-directory with a reference to the source code-directory of the project and user-chosen options. CMake then generates either Makefiles or project files for IDE such as Visual Studio or Eclipse inside the build directory. 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.
+
+Because of the separation of the source code and all stuff that is generated as a part of the build process it is no problem to have several build configurations (e.g. a serial configuration and a parallelized MPI-enabled configuration) all referring to the same source code.
+
+When you want to start over with a new configuration simply delete the build-directory, create a new one and reconfigure.
+
+For a list of available options see the {entry:devguide/configuration-options:link}.
+
+## Option: Configure from the command line
+
+CMake can be run from the shell by invoking the cmake command inside a build directory. You can pass any CMake variable or option with `-DVARIABLE_NAME=VALUE` (note the `-D` in front!). You can also pass the generator you want to use (e.g. `Unix Makefiles` or `Visual Studio 14 2015 Win64`-project files) with the `-G` parameter (to see all available generators just run `cmake --help`), although in most cases the appropriate generator will be chosen automatically. The last parameter to the CMake command is the path to the source code directory. A typical call would look like this:
+
+```bash
+$ cmake -G "Visual Studio 14 2015 Win64" -DCMAKE_BUILD_TYPE=Release ../ogs
+```
+
+CMake tries to autodetect your compiler so in most cases this should be enough:
+
+```bash
+$ cmake ../ogs
+```
+
+## Option: Configure with a visual tool
+
+::: {.win}
+CMake comes with a graphical tool called **cmake-gui**. You can find it in the **Windows Start Menu**. First you need to set the source and build directory. Then click **Configure**. Now choose the generator to be used (e.g. **Visual Studio 14 2015 Win64** for Visual Studio 2015 64-bit). Now choose your desired configuration options by toggling the corresponding checkboxes. Click **Configure** again. Click **Configure** often enough until the **Generate**-button becomes visible. Pressing **Generate** will finally generate the project files inside the chosen build directory.
+:::
+
+::: {.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` inside your build directory with the path to the source code (and optionally the generator you want to use) as parameter:
+
+```bash
+$ ccmake ../ogs
+```
+
+First press <kbd>C</kbd> to **Configure**. You are now presented the available configuration options. You can navigate in the list with the cursor keys and toggle / alter options with <kbd>Enter</kbd>. You may also press <kbd>T</kbd> to toggle (previously hidden) advanced options. Press <kbd>C</kbd> again until the **Generate**-option becomes visible. Press <kbd>G</kbd> to generate the project files and exit `ccmake`.
+
+There is also the tool `cmake-gui` available, please see the Win-Tab for a description.
+:::
+
+::: {.mac}
+Please see the Linux instructions!
+:::

web/content/docs/devguide/getting-started/build.pandoc

@@ -0,0 +1,112 @@
++++
+date = "2018-02-23T15:28:13+01:00"
+title = "Build"
+author = "Lars Bilke"
+weight = 1005
+
+[menu]
+  [menu.devguide]
+    parent = "getting-started"
++++
+
+## Build the project
+
+::: {.win}
+# Step: Build with Visual Studio
+
+Open the OGS.sln 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.
+
+## About Visual Studio startup projects
+
+The reason for this is that you can have only one sub-project of your Visual Studio Solution activated for debugging (e.g. by pressing <kbd>F5</kbd>). Per default this is the first sub-project (in the case of a CMake-generated project this is `ALL_BUILD`). This must be manually set to a sub-project which generates an executable (a library sub-project cannot be started). And because this setting is stored in user specific project file it cannot be set via CMake.
+
+# 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.
+:::
+
+::: {.linux}
+# Option: Make
+
+To build with the `make` tool on the shell go to your previously created build directory and type `make`:
+
+```bash
+$ cd build
+$ make
+```
+
+To speedup the compilation process append the number of cores of your cpu to the make command. E.g. for 8 cores:
+
+```bash
+$ make -j 8
+```
+
+# Option: Eclipse
+
+To let CMake generate the Eclipse project files change the generator argument to the CMake run:
+
+```bash
+$ cmake [your configuration options] -G"Eclipse CDT4 - Unix Makefiles" ../sources
+```
+
+Or with ccmake
+
+```bash
+$ ccmake -G"Eclipse CDT4 - Unix Makefiles" ../sources
+```
+
+Start the Eclipse ide. From the menu choose **File / Import**. In the import dialog choose **General / Existing projects into workspace** and click **Next**. In **Select root directory** select your build directory and make sure that **Copy project into workspace** is unchecked. Click **Finish**.
+:::
+
+::: {.mac}
+# Option: Make
+
+To build with the `make` tool on the shell go to your previously created build directory and type `make`:
+
+```bash
+$ cd build
+$ make
+```
+
+To speedup the compilation process append the number of cores of your cpu to the make command. E.g. for 8 cores:
+
+```bash
+$ make -j 8
+```
+
+# Option: Xcode
+
+To let CMake generate the Xcode project files change the generator argument on the CMake run:
+
+```bash
+$ cmake [your configuration options] -G Xcode ../sources
+```
+
+Or with ccmake
+
+```bash
+$ ccmake -G Xcode ../sources
+```
+
+Then load the generated project file by either clicking the **OGS.xcodeproj** or via
+
+```bash
+$ open OGS.xcodeproj
+```
+
+In Xcode choose `ogs` or `ogs-gui` from the drop-down menu on the top right and then hit the Run-button.
+:::
+
+
+## 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 {entry:devguide/third-party-libraries:link} for more.
+
+
+## Finished!
+
+Congratulations you have finished the **Getting Started**-section!
+
+Have a look at the other sections of this guide. Maybe check out {entry:devguide/development-workflows:link} if you are interested in actively contributing to the project. The {entry:devguide/configuration-options:link}-page shows you all available build customizations. Or do you want to build the {entry:devguide/data-explorer:link}? Go ahead!

web/content/docs/devguide/getting-started/get-the-source-code.pandoc

@@ -0,0 +1,85 @@
++++
+date = "2018-02-23T15:28:13+01:00"
+title = "Get the source code"
+author = "Lars Bilke"
+weight = 1003
+
+[menu]
+  [menu.devguide]
+    parent = "getting-started"
++++
+
+::: {.note}
+### Attribution
+
+The content of this page is largely taken from the [GitHub-blog](https://github.com/blog/2042-git-2-5-including-multiple-worktrees-and-triangular-workflows).
+:::
+
+
+## Create a fork
+
+Go to the [official OGS-6 repository](https://github.com/ufz/ogs) and click the "Fork"-button. This creates a new fork under your account with the URL `https://github.com/YOUR-USERNAME/ogs`.
+
+
+## Setup your local clone
+
+You can use the git command line tool to clone the remote repository on GitHub to your PC:
+
+```bash
+$ git clone https://github.com/YOUR-USERNAME/ogs
+$ cd ogs
+$ git config remote.pushdefault origin
+$ git config push.default current
+```
+
+**Note:** We use `git lfs clone` instead of the regular `git clone` to significantly speed up the cloning of the repo and its test data files. See [this for more information](https://github.com/ufz/ogs/pull/1978).
+
+This creates a new folder `ogs` in your current working directory with the OGS source code. After this step, the remote called `origin` refers to your fork on GitHub. It also sets the default remote for pushes to be `origin` and the default push behavior to `current`. Together this means that if you just type `git push`, the current branch is pushed to the `origin` remote (git version >= 2.5 required).
+
+Create a second remote called `upstream` that points at the main OGS repository and fetch from it:
+
+```bash
+$ git remote add upstream https://github.com/ufz/ogs
+$ git [lfs] fetch upstream # The lfs-equivalent of the fetch command is more efficient
+```
+
+
+## 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.
+
+Make sure that your local repository is up-to-date with the upstream repository:
+
+```bash
+$ git fetch upstream
+```
+
+Create a branch `feature-name` off of upstream `master`-branch to work on a new feature, and check out the branch:
+
+```bash
+git checkout -b feature-name upstream/master
+```
+
+This automatically sets up your local `new-feature`-branch to track the upstream `master`-branch. This means that if more commits are added to `master` upstream, you can merge those commits into your `feature`-branch by typing
+
+```bash
+$ git pull
+```
+
+or rebase your branch on top of the new master by typing
+
+```bash
+$ git pull --rebase
+```
+
+Now after you implemented the feature and committed your work you can push the new commits to the `feature-name`-branch on your GitHub fork:
+
+```bash
+$ git push
+```
+
+If your work is done submit a pull request.
+
+This workflow is summarized with this picture:
+
+![](https://cloud.githubusercontent.com/assets/1319791/8943755/5dcdcae4-354a-11e5-9f82-915914fad4f7.png)