Building from Source
Sooner or later you will want to use the latest Dune features or add new features to the Dune code modules. On this page, we try to collect the details on how to build Dune from source and how special features of the tool chain work.
The text here covers the C++ part of Dune. If you want to use the Dune Python bindings then you should read the Dune Python installation instructions as well.
Note: The process described below works for Linux/UNIX based systems. On Windows systems follow the setup of a WSL and then proceed as described below.
Dependencies
In order to build DUNE you need at least the following software:
- C++ compiler supporting c++-17 language standard, e.g. clang >= 5, g++ >= 7
- CMake >= 3.13
- pkg-config
Detailed information on supported compiler and CMake versions can be found in the release notes for releases and in the list recent changes for the development branch master. See also the FAQ section for information about how to resolve the build dependencies.
The following software is recommended but optional:
- MPI (e.g. OpenMPI or MPICH)
- Python Virtual Environment (e.g. python3-venv or virtualenv)
This will provide you with the core DUNE features.
Some DUNE modules might support further software. At the end of the configuration process of each dune module, a list of found, optional and required dependencies is listed.
Getting the sources
First you need to download the DUNE core modules to your computer in one common directory. You can either download tarballs of the last releases of the core modules or download directly from our git repositories. Note: If you download the modules directly from git make sure to checkout a release branch if you don’t want to work with the current development version.
For instance, create a directory and clone the core modules:
mkdir dune; cd dune
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-localfunctions.git
git clone https://gitlab.dune-project.org/core/dune-istl.git
git clone https://gitlab.dune-project.org/core/dune-grid.git
Building DUNE 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 utility on top of CMake, dunecontrol
. This can be found in the directory dune-common/bin/
.
The typical way to run dunecontrol
is using an options file and execute:
./dune-common/bin/dunecontrol --opts=config.opts all
This will configure and build all modules you have downloaded in the order of resolved dependencies.
The config.opts
file contains, e.g.,
CMAKE_FLAGS="-DCMAKE_BUILD_TYPE=Release"
See below for more details on the options file.
More generally, you can separately run
./dune-common/bin/dunecontrol [OPTIONS] cmake [CMAKE_FLAGS]
./dune-common/bin/dunecontrol [OPTIONS] make [MAKE_FLAGS]
in order to first configure and then build all modules with the given flags.
From now on, we assume that dunecontrol
is in your PATH
, e.g., by running
echo 'export PATH=/path/to/dune-common/bin:${PATH}' >> ${HOME}/.bashrc
source ${HOME}/.bashrc
Building other DUNE modules
Besides the core modules you can find lots of other dune modules:
If you want to use one of those modules make sure to download the module and all dependencies in the same common directory as the DUNE core modules. Building your modules is done in the same way as building the core modules by calling dunecontrol
.
Building a specific DUNE module (and its dependent modules)
You can instruct dunecontrol
to build only a certain dune module, using the --only=<module_name>
switch. Running dunecontrol
script
dunecontrol --only=<module_name> all
where <module_name>
is the name of that particular module given in the dune.module
file,
will build only the module <module_name>
.
If you want to build a module and the modules it depends on, you must run:
dunecontrol --module=<module_name> all
Changing build mode and optimization flags
The flags passed to the compiler are controlled by CMake. Thus, in order to change these flags, you have to add a CMAKE_FLAG
responsible for compiler (and/or linker) options.
One can either specify a global build mode:
dunecontrol cmake -DCMAKE_BUILD_TYPE=[Debug|MinSizeRel|RelWithDebInfo|Release]
(see CMake documentation for a more detailed description of the CMake option)
or you can specify compiler flags explicitly, e.g.,
dunecontrol cmake -DCMAKE_CXX_FLAGS="-O3 -DNDEBUG -march=native"
This is equivalent to specifying both, the release more and the additional -march=native
flag:
dunecontrol cmake -DCMAKE_BUILD_TYPE=Release -DCMAKE_CXX_FLAGS="-march=native"
Both flags can be put into an options file, see below, or can be set by specifying the CMAKE_FLAGS
environmental variable:
CMAKE_FLAGS='-DCMAKE_BUILD_TYPE=Release -DCMAKE_CXX_FLAGS="-march=native"' dunecontrol cmake
Note, if you do not specify anything, the CMake defaults are used which essentially means: no code optimization.
Speeding up the build process
Building several DUNE modules can be quiet time consuming. Using a concurrent build can speed this up. Either you can instruct make
to use multiple threads when building,
dunecontrol make -jN
or you can specify another make-system, like Ninja build, by setting a different CMake generator:
dunecontrol cmake -GNinja
dunecontrol make
If parts of the code must be rebuild multiple times, a utility like ccache might be useful and can be specified as a COMPILER_LAUNCHER
in CMake:
dunecontrol cmake -DCMAKE_CXX_COMPILER_LAUNCHER=/path/to/ccache
(see CMake documentation for a more detailed description of the CMake option)
Storing flags in an options file
As it is often not convenient to specify the desired options after the dunecontrol
call, one can pass the options via file specified by the --opts
option:
dunecontrol --opts=<file> COMMAND
Possible options for the options-file (or the environment) are
CMAKE_FLAGS
: arguments passed to thecmake
commandMAKE_FLAGS
: arguments passed to themake
commandBUILDDIR
: build directory for an out-of-source build. default:build-cmake
CMAKE
: executable to use forcmake
DUNE_CONTROL_PATH
: A PATH variable to locate dune modules in its subdirectories, directories are separated by colon:
An example of an options file is
# set build mode and compiler flags,
# install to a custom directory,
# disable the MPI library,
# add a search path for external libraries
# and use Ninja-build instead of make as the build-tool
CMAKE_FLAGS="-DCMAKE_BUILD_TYPE=Release \
-DCMAKE_CXX_FLAGS=\"-march=native\" \
-DCMAKE_INSTALL_PREFIX=/path/where/to/install/dune \
-DCMAKE_DISABLE_FIND_PACKAGE_MPI=1 \
-DCMAKE_PREFIX_PATH=\"/path/to/lib1;/path/to/lib2\" \
-GNinja"
Details about the dunecontrol
utility
The general structure of a dunecontrol
call is
dunecontrol [OPTIONS] COMMAND
Commands
The following atomic COMMAND
s can be executed:
cmake
: run the CMake system for each module and passes along the directories of the found dune modulesmake
: run make (or any other build tool that was configured) for each moduleall
: combination ofcmake
andmake
exec
: execute a command in each module directorybexec
: execute a command in each module’s build directoryupdate
: pull the latest version from the Git repositorygit
: run a specific git command in all module directories
Options
The following general OPTIONS
are available:
--help
: Show a detailed list of all options with description.--module=<mod>
,--only=<mod>
,--current
,--current-dep
: Control which modules to build, see above.--builddir=<dir>
: Make out-of-source builds in a subdir<dir>
. This directory is created inside each module. If<dir>
is an absolute path, the build directory is set to<dir>/module-name
for each module.--opts=<file>
: load default options from<file>
Creating your own DUNE project module
You can create your own dune project module by using the duneproject
script available in dune-common/bin
directory. Running the script will create a directory with supporting files (CMakeLists.txt
etc.) and a sample .cc file. After creating the module you can build this as explained above under “Building a specific DUNE module”.
The DUNE Build System Documentation will also give you an excellent introduction to the build system and how to create new modules/projects your own.
Installing DUNE in HPC Clusters
Cluster architectures often have a linux based system that is quiet different from a desktop environment, with its own package management system that needs special handling of the installation such that everything is found properly. However, often it is enough to just load the (build) dependencies and build DUNE using dunecontrol
the classical way as described above. There are also some non-official ways of building DUNE in HPC environments, e.g.
- There is a DUNE package for the Spack package management system, see https://gitlab.dune-project.org/spack/dune-spack for more information
- Installing DUNE in a system using EasyBuild is available for the DUNE core modules and DUNE-Fem and dependencies. There are also other examples how to write the required description files for the software management system, see https://gitlab.mn.tu-dresden.de/spraetor/dune-easybuild for further examples.
- Some old instructions for the BlueGene-P system can be found in the Installation Notes for Blue Gene P.
Warning: those descriptions and tools are often provided just for a single or a few DUNE releases and are sometimes outdated.
