Installation of 3rd party libraries and programs
================================================

On Debian GNU/Linux
-------------------

All necessary libraries are included in Debian Stretch and most are included
in jessie-backports. They can be installed via

    apt install git cmake libboost-dev libug-dev libsuitesparse-dev

Using Homebrew on MacOS
-----------------------

cmake installation (it requires the previous installation of autoconf, automake and libtool):
    brew install autoconf
    brew install automake
    brew install libtool
    brew install cmake

The installation of pkg-config is recommended:
    brew install pkg-config

boost installation:
    brew install --c++11 boost

umfpack installation:
    brew tap /hombrew/science/
    brew install /hombrew/science/suite-sparse

### Installation of UG

Download release 3.12.1 of UG from

    http://conan.iwr.uni-heidelberg.de/download/ug-3.12.1.tar.gz

and unpack it.

Remark: The latest release 3.13.0 is incompatible with Dune 2.4.1.
        (see https://gitlab.dune-project.org/core/dune-grid/issues/13)

In the UG folder, run

    autoreconf -is
    ./configure --enable-dune --without-x CXX=g++
    make
    make install

Installation and compilation of dune and dune-dpg
=================================================

We give detailed installation guidelines using GCC and the UG grid manager.
The URLs that are given below were still active on July 2016. We apologize
for possible future inconsistencies in the links and hope that the user
will nevertheless find his way.

1) Create a directory to harbor the source code of the Dune modules.
   We will call this directory $DUNEDIR.

   Remark: Make sure that there are no whitespaces in the $DUNEDIR path
           as our build-system might not be able to cope with them.
           (Make is known to handle spaces in filenames quite badly and
            other CMake backends might have similar problems.)

Installation of Dune on Debian GNU/Linux
----------------------------------------

2) If you are using Debian Stretch, the Dune 2.4.1 core libraries can be
   installed from the Debian repositories with

    apt install libdune-common-dev libdune-geometry-dev libdune-grid-dev \
                libdune-istl-dev libdune-localfunctions-dev \
                libdune-functions-dev libdune-typetree-dev

   Alternatively, you can download the sources of the Dune core modules
   into $DUNEDIR like it is explained below in the MacOS instructions.
   This is necessary if you are using an older Debian release like Jessie.

Installation of Dune on MacOS
-----------------------------

2) Download the following dune sources in $DUNEDIR:
 2.a) - Version >= 2.4.1 of the following Dune source modules:
        dune-common, dune-geometry, dune-grid, dune-istl, dune-localfunctions
      - Link: https://dune-project.org/releases/2.4.1/

 2.b) Download dune-functions and dune-typetree by cloning the 2.4 release
      branches of their GitLab repositories

        git clone -b releases/2.4-compatible \
                  https://gitlab.dune-project.org/staging/dune-functions
        git clone -b releases/2.4 \
                  https://gitlab.dune-project.org/pdelab/dune-typetree

      Remark: In the future, these modules might be associated with more
              stable releases and found in https://dune-project.org/releases/

Preparing dune-dpg
------------------

3) If the dune-dpg directory is not in $DUNEDIR move it there now.

Building and compiling dune and dune-dpg
----------------------------------------

4) Create a file dune.opts in $DUNEDIR and specify
the C and C++ compiler in it. In our case, we have used gcc and g++ so
the file reads

CMAKE_FLAGS="-DCMAKE_C_COMPILER='gcc' -DCMAKE_CXX_COMPILER='g++'"
CMAKE_FLAGS+=" -DCMAKE_CXX_FLAGS='-pedantic -Wall -Wno-deprecated-declarations'"

Remarks:
 - In MacOS, the C compiler is set to clang by default so the previous
   configuration option cannot be omitted.
 - The use of clang and clang++ is in principle also possible here although
   this compiler has not been tested.
 - The second line adds some compile flags to give more warnings and
   disable deprecation warnings. Otherwise dune-grid 2.4.1 will spill a lot
   of deprecation warnings when using UG.
 - If you have installed UG into a non-standard prefix $UGPREFIX, you can
   specify it by adding a line
   CMAKE_FLAGS+=" -DUG_ROOT=$UGPREFIX"
   to your dune.opts file.

5) In $DUNEDIR, run

     $DUNEDIR/dune-common/bin/dunecontrol --opts=$DUNEDIR/dune.opts all

The command dunecontrol creates makefiles and compiles the sources. It
creates a directory build_cmake inside each Dune module where the
executables are built. As a consequence, the user should cd into
$DUNEDIR/dune-dpg/build_cmake to run the examples of the paper.

Remark: If there were any problems with the build system it might be
        helpful to remove all build_cmake directories by running

            rm -rf */build-cmake

        in $DUNEDIR. This removes all build products and old CMake
        configuration files that might cause conflicts.

For more information and options on dunecontrol, run

    $DUNEDIR/dune-common/bin/dunecontrol --help

More information on the build system of Dune can be found under
https://dune-project.org/doc/installation/
https://dune-project.org/buildsystem/

Generating API documentation with Doxygen
-----------------------------------------

We have some (rudimentary) API documentation for our classes and function
that can be generated from special comments in our source code with the
[Doxygen](http://doxygen.org) documentation generator by calling

    make doc

in $DUNEDIR/dune-dpg/build-cmake. The generated html files of the
API documentation can then be read by opening

    $DUNEDIR/dune-dpg/build-cmake/doc/doxygen/html/index.html

in your favorite browser.


Troubleshooting
---------------

On MacOS it might be possible that the following linker error appears:
```
Undefined symbols for architecture x86_64:
"__gfortran_st_write", referenced from:
_xerbla_ in libf77blas.a(xerbla.o)
"__gfortran_st_write_done", referenced from:
_xerbla_ in libf77blas.a(xerbla.o)
"__gfortran_stop_string", referenced from:
_xerbla_ in libf77blas.a(xerbla.o)
"__gfortran_transfer_character_write", referenced from:
_xerbla_ in libf77blas.a(xerbla.o)
"__gfortran_transfer_integer_write", referenced from:
_xerbla_ in libf77blas.a(xerbla.o)
```
In that case, adding the lines
```
target_link_libraries("plot_solution" "gfortran")
target_link_libraries(${convergence_test} "gfortran")
```
to $DUNEDIR/dune-dpg/src/CMakeLists.txt should help to correctly
link the example programs.
