<!--
SPDX-FileCopyrightInfo: Copyright © DUNE Project contributors, see file LICENSE.md in module root
SPDX-License-Identifier: LicenseRef-GPL-2.0-only-with-DUNE-exception
-->

Installation Instructions
=========================

For a full explanation of the DUNE installation process please read
the installation notes [0]. The following introduction is meant for
the impatient.

Getting started
---------------

Suppose you have downloaded all DUNE modules of interest to your
computer and extracted then in one common directory. See [1] for a
list of available modules.

To compile the modules Dune has to check several components of
your system and whether prerequisites within the modules are met. For
the ease of users we have designed a custom build system on top of CMake.
Run

  ./dune-common/bin/dunecontrol all

to commence those tests and build all modules you have
downloaded. Don't worry about messages telling you that libraries are
missing: they are only needed for grid-self-checks we need for
developing.

You can customize the build to your specific needs by using an options file
(see below)

  ./dune-common/bin/dunecontrol --opts=/path_to/file.opts

If you did not tell dunecontrol to install with an options file you
need to run

  ./dune-common/bin/dunecontrol make install

to install Dune (you may need root-permissions for the install
part depending on the prefix set)

A more comprehensive introduction to the build system can be found in [0].

Passing options to the build process
------------------------------------

Using the dunecontrol script the following atomic commands can be
executed:

- configure (runs the CMake configuration tests for each module)
- exec (executes a command in each module source directory)
- bexec (executes a command in each module build directory)
- make (builds each module)
- update (updates the Git or Subversion version)

The composite command all simply runs configure and make for
each module.

As it is often not convenient to specify the desired options after
the duncontroll call, one can pass the options via a file specified
by the --opts=<file> option. Specify the options via the variable

  CMAKE_FLAGS=<flags>

An example of an options file is

  # use a special compiler (g++ version 5.0),
  # install to a custom directory, default is /usr/local/bin,
  # disable the external library SuperLU,
  # and use Ninja-build instead of make as the build-tool
  CMAKE_FLAGS="-DCMAKE_CXX_COMPILER=g++-5 -DCMAKE_INSTALL_PREFIX='/tmp/HuHu' -DCMAKE_DISABLE_FIND_PACKAGE_SuperLU=true -GNinja"

Links
-----

0. https://www.dune-project.org/doc/installation
1. https://www.dune-project.org/releases