[doc] Write introductiory text

README

-Preparing the Sources
-=========================
+# Getting and building this tutorial
 
-Additional to the software mentioned in README you'll need the
-following programs installed on your system:
+This document is work-in-progress. You should have a look at the
+excellent [getting started with Dune](http://www.math.tu-dresden.de/~osander/research/sander-getting-started-with-dune.pdf)
+text by written by Oliver Sander.
 
-  cmake >= 2.8.12
+## Prerequisites
 
-Getting started
----------------
+### Operation system
 
-If these preliminaries are met, you should run
+In order to use Dune you will need a recent Linux installation.
+People are also using Dune on OSX and it has been reported you
+can build Dune on Windows after applying some patches. Both systems
+will not be covered here. However, the following instructions
+may (or may not) in large parts also apply to OSX.
 
-  dunecontrol all
 
-which will find all installed dune modules as well as all dune modules
-(not installed) which sources reside in a subdirectory of the current
-directory. Note that if dune is not installed properly you will either
-have to add the directory where the dunecontrol script resides (probably
-./dune-common/bin) to your path or specify the relative path of the script.
+### Required tools
 
-Most probably you'll have to provide additional information to dunecontrol
-(e. g. compilers, configure options) and/or make options.
+In order to obtain Dune via the `git` version control system you must install
 
-The most convenient way is to use options files in this case. The files
-define four variables:
+* git
 
-CMAKE_FLAGS      flags passed to cmake (during configure)
-MAKE_FLAGS       flags passed to make
+on your system.
+Dune is written in modern C++, so you will need a C++-compiler which
+is not to outdated. This does in general mean that you need either
+of the following compilers:
 
-An example options file might look like this:
+* gcc (version 4.9 or newer)
+* clang (version 3.? or newer)
 
-#use this options to configure and make if no other options are given
-CMAKE_FLAGS=" \
--DCMAKE_CXX_COMPILER=g++-4.9 \
--DCMAKE_CXX_FLAGS='-Wall -pedantic' \
--DCMAKE_INSTALL_PREFIX=/install/path" #Force g++-4.9 and set compiler flags
-MAKE_FLAGS=install #Per default run make install instead of simply make
+Furthermore Dune uses the CMake build-system and requires
 
-If you save this information into example.opts you can pass the opts file to
-dunecontrol via the --opts option, e. g.
+* cmake (version 2.8.12 or newer)
 
-  dunecontrol --opts=example.opts all
+Any recent Linux distribution will contain these tools in its
+repository. Hence you should be able to install them using
+the package management system of your distribution. It is not
+recommended to install these tools manually from source or from
+binary packages unless you are an advanced user and know what
+you're doing.
 
-More info
----------
 
-See
 
-     dunecontrol --help
 
-for further options.
+## Getting Dune
+
+There are several ways to get Dune. One option is to install it
+via your distributions package management system if it provides
+Dune. This is e.g. the case for Debian and Ubuntu. Another option
+that we will follow here is to build them from source after getting
+the code directly from the central source code repository.
+First we create a directory for our Dune installation e.g. by
+
+```shell
+mkdir dune
+cd dune
+```
+
+Next we clone the repositories for the core modules
+
+```shell
+git clone https://gitlab.dune-project.org/core/dune-common.git
+git clone https://gitlab.dune-project.org/core/dune-geometry.git
+git clone https://gitlab.dune-project.org/core/dune-grid.git
+git clone https://gitlab.dune-project.org/core/dune-localfunctions.git
+git clone https://gitlab.dune-project.org/core/dune-istl.git
+```
+
+Besides the core modules we need some extension modules and this tutorial
+
+```shell
+git clone https://gitlab.dune-project.org/staging/dune-typetree.git
+git clone https://gitlab.dune-project.org/staging/dune-functions.git
+git clone https://gitlab.dune-project.org/staging/dune-uggrid.git
+```
+
+
+## Configuring and building Dune
+
+Dune uses a CMake build system. Each Dune module is build individually but
+most modules will depend on others being build before. In order to avoid
+having to do this manually Dune provides the script `dunecontrol` which
+resolves the module dependencies, builds them in an appropriate order,
+and passes options in a unified way. You can pass options to this script
+via an options file. In the following we assume that the absolute
+path of our Dune directory is `/home/john/dune`. Then you can e.g. create
+a file `/home/john/dune/debug.opts` with the following content
+
+```
+# Setup a central build directory for all modules
+BUILDDIR="/home/john/dune/build-debug"
+
+# Point cmake to dependencies
+CMAKE_PREFIX_PATH=""
+
+# Used compiler
+# for gcc use g++, for clang use clang++
+CXX=/usr/bin/g++
+
+# Use CMAKE_PREFIX_PATH to tell CMake some specific stuff, e.g. to use a Debug build
+CMAKE_FLAGS="
+    -DCMAKE_CXX_COMPILER='$CXX' \
+    -DCMAKE_CXX_FLAGS='-g -O0 -Wall -Wno-sign-compare' \
+    -DCMAKE_PREFIX_PATH='$CMAKE_PREFIX_PATH' \
+"
+```
+
+This contains a set of options suitable for a debug build.
+Now you can build Dune with the given options file by calling
+
+```shell
+./dune-common/bin/dunecontrol --opts=debug.opts all
+```
+
+This will generate a directory `build-debug` which contains
+a build folder for any Dune module. The compiled example programs
+of this tutorial are contained in `build-debug/dune-fu-tutorial/src/`.
+
+If you want to recompile after changing code you will normally not need
+to run `dunecontrol` again. Instead you can simply call `make` in the
+**build-directory** for the corresponding module.
 
 
-The full build system is described in the dune-common/doc/buildsystem (Git version) or under share/doc/dune-common/buildsystem if you installed DUNE!