OilfieldToolsNet/opm-simulators
4
0
Fork 0
mirror of https://github.com/OPM/opm-simulators.git synced 2025-02-25 18:55:30 -06:00
Code Issues Packages Projects Releases Wiki Activity

Merge pull request #92 from bska/092_cmake

Browse Source 
Synchronise build system with OPM-Core
This commit is contained in:
Atgeirr Flø Rasmussen 2014-03-03 08:18:33 +01:00
commit cbee89158d
21 changed files with 954 additions and 84 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

6
cmake/Modules/FindSuperLU.cmake
View File

@ -54,7 +54,7 @@ endif()
# print message if there was still no blas found!
if(NOT BLAS_FOUND AND NOT SUPERLU_BLAS_LIBRARY)
message("BLAS not found but required for SuperLU")
message(STATUS "BLAS not found but required for SuperLU")
return()
endif()
list(APPEND CMAKE_REQUIRED_LIBRARIES "${SUPERLU_BLAS_LIBRARY}")
@ -69,7 +69,7 @@ if (NOT SUPERLU_INCLUDE_DIR)
)
endif()
if(NOT SUPERLU_INCLUDE_DIR)
message("Directory with the SuperLU include files not found")
message(STATUS "Directory with the SuperLU include files not found")
return()
endif()
list(APPEND CMAKE_REQUIRED_INCLUDES "${SUPERLU_INCLUDE_DIR}")
@ -84,7 +84,7 @@ if (NOT SUPERLU_LIBRARY)
)
endif()
if(NOT SUPERLU_LIBRARY)
message("Directory with the SuperLU library not found")
message(STATUS "Directory with the SuperLU library not found")
return()
endif()
list(APPEND CMAKE_REQUIRED_LIBRARIES "${SUPERLU_LIBRARY}")

7
cmake/Modules/Findcjson.cmake
View File

@ -31,13 +31,14 @@ if (CMAKE_SIZEOF_VOID_P)
math (EXPR _BITS "8 * ${CMAKE_SIZEOF_VOID_P}")
endif (CMAKE_SIZEOF_VOID_P)
string(REGEX REPLACE "${PROJECT_SOURCE_DIR}/?(.*)" "\\1" BUILD_DIR_SUFFIX "${PROJECT_BINARY_DIR}")
find_library (CJSON_LIBRARY
NAMES "cjson"
HINTS "${CJSON_ROOT}"
PATHS "${PROJECT_BINARY_DIR}/../opm-parser"
"${PROJECT_BINARY_DIR}/../opm-parser-build"
"${PROJECT_BINARY_DIR}/../../opm-parser/build"
"${PROJECT_BINARY_DIR}/../../opm-parser/cmake-build"
"${PROJECT_BINARY_DIR}/../opm-parser${BUILD_DIR_SUFFIX}"
"${PROJECT_BINARY_DIR}/../../opm-parser/${BUILD_DIR_SUFFIX}"
PATH_SUFFIXES "lib" "lib${_BITS}" "lib/${CMAKE_LIBRARY_ARCHITECTURE}"
"opm/json"
DOC "Path to cjson library archive/shared object files"

1
cmake/Modules/Finddune-common.cmake
View File

@ -50,6 +50,7 @@ int main (void) {
HAVE_ARRAY;
HAVE_BOOST_MAKE_SHARED_HPP;
HAVE_BOOST_SHARED_PTR_HPP;
HAVE_DUNE_BOOST;
HAVE_GMP;
HAVE_MAKE_SHARED;
HAVE_MPI;

1
cmake/Modules/Finddune-istl.cmake
View File

@ -49,6 +49,7 @@ int main (void) {
HAVE_MPI;
HAVE_PARMETIS;
HAVE_SUPERLU;
HAVE_UMFPACK;
SUPERLU_MIN_VERSION_4_3;
SUPERLU_POST_2005_VERSION
")

44
cmake/Modules/Findopm-autodiff.cmake Normal file
View File

@ -0,0 +1,44 @@
# - Find OPM automatic differentiation library
#
# Defines the following variables:
# opm-autodiff_INCLUDE_DIRS Directory of header files
# opm-autodiff_LIBRARIES Directory of shared object files
# opm-autodiff_DEFINITIONS Defines that must be set to compile
# opm-autodiff_CONFIG_VARS List of defines that should be in config.h
# HAVE_OPM_AUTODIFF Binary value to use in config.h
# Copyright (C) 2012 Uni Research AS
# This code is licensed under The GNU General Public License v3.0
# use the generic find routine
include (opm-autodiff-prereqs)
include (OpmPackage)
find_opm_package (
# module name
"opm-autodiff"
# dependencies
"${opm-autodiff_DEPS}"
# header to search for
"opm/autodiff/AutoDiff.hpp"
# library to search for
"opmautodiff"
# defines to be added to compilations
""
# test program
"#include <opm/autodiff/AutoDiff.hpp>
int main (void) {
Opm::AutoDiff<double> x = Opm::AutoDiff<double>::constant(42.);
(void) x;
return 0;
}
"
# config variables
"${opm-autodiff_CONFIG_VAR}"
)
include (UseDynamicBoost)
#debug_find_vars ("opm-autodiff")

8
cmake/Modules/Findopm-parser.cmake
View File

@ -31,6 +31,9 @@ if ((NOT OPM_PARSER_ROOT) AND OPM_ROOT)
set (OPM_PARSER_ROOT "${OPM_ROOT}/opm-parser")
endif ()
# Detect the build dir suffix or subdirectory
string(REGEX REPLACE "${PROJECT_SOURCE_DIR}/?(.*)" "\\1" BUILD_DIR_SUFFIX "${PROJECT_BINARY_DIR}")
# if a root is specified, then don't search in system directories
# or in relative directories to this one
if (OPM_PARSER_ROOT)
@ -43,9 +46,8 @@ else ()
"${PROJECT_SOURCE_DIR}/../opm-parser")
set (_opm_parser_build
"${PROJECT_BINARY_DIR}/../opm-parser"
"${PROJECT_BINARY_DIR}/../opm-parser-build"
"${PROJECT_BINARY_DIR}/../../opm-parser/build"
"${PROJECT_BINARY_DIR}/../../opm-parser/cmake-build")
"${PROJECT_BINARY_DIR}/../opm-parser${BUILD_DIR_SUFFIX}"
"${PROJECT_BINARY_DIR}/../../opm-parser/${BUILD_DIR_SUFFIX}")
endif ()
# use this header as signature

26
cmake/Modules/OpmAliases.cmake Normal file
View File

@ -0,0 +1,26 @@
# - Alias probed variables for compatibility with DUNE buildsystem
#
# DUNE build system sets some variables which have different names
# in the CMake modules we are using; this module set those variable
# so they can be exported to config.h visible to DUNE headers
function (set_aliases)
# hardcoded list of "dune-var opm-var" pairs, where the components
# are separated by space
set (aliases
"HAVE_UMFPACK HAVE_SUITESPARSE_UMFPACK_H"
"HAVE_DUNE_BOOST HAVE_BOOST"
)
foreach (alias IN LISTS aliases)
# convert entry "X Y" into a list "X;Y", then pick apart
string (REGEX REPLACE "\ +" ";" tuple "${alias}")
list (GET tuple 0 var)
list (GET tuple 1 name)
# write this alias to cache
set (${var} ${${name}} PARENT_SCOPE)
endforeach (alias)
endfunction (set_aliases)
# always call this when the module is imported
set_aliases ()

17
cmake/Modules/OpmFind.cmake
View File

@ -59,6 +59,7 @@ set (_opm_proj_exemptions
dune-istl
dune-grid
dune-geometry
opm-parser
)
# although a DUNE module, it is delivered in the OPM suite
@ -137,16 +138,22 @@ macro (find_and_append_package_to prefix name)
# using config mode is better than using module (aka. find) mode
# because then the package has already done all its probes and
# stored them in the config file for us
if (NOT (${name}_FOUND OR ${NAME}_FOUND))
if (NOT DEFINED ${name}_FOUND AND NOT DEFINED ${NAME}_FOUND)
if (${name}_DIR)
message (STATUS "Finding package ${name} using config mode")
find_package (${name} ${ARGN} NO_MODULE PATHS ${${name}_DIR} NO_DEFAULT_PATH)
else (${name}_DIR)
else ()
message (STATUS "Finding package ${name} using module mode")
find_package (${name} ${ARGN})
endif (${name}_DIR)
endif (NOT (${name}_FOUND OR ${NAME}_FOUND))
endif (CMAKE_DISABLE_FIND_PACKAGE_${name})
endif ()
endif ()
if (NOT DEFINED ${name}_FOUND)
set (${name}_FOUND "${${NAME}_FOUND}")
endif ()
if (NOT DEFINED ${NAME}_FOUND)
set (${NAME}_FOUND "${${name}_FOUND}")
endif ()
endif ()
# the variable "NAME" may be replaced during find_package (as this is
# now a macro, and not a function anymore), so we must reinitialize

3
cmake/Modules/OpmLibMain.cmake
View File

@ -89,6 +89,9 @@ endif (COMMAND prereqs_hook)
include (OpmFind)
find_and_append_package_list_to (${project} ${${project}_DEPS})
# set aliases to probed variables
include (OpmAliases)
# remove the dependency on the testing framework from the main library;
# it is not possible to query for Boost twice with different components.
list (REMOVE_ITEM "${project}_LIBRARIES" "${Boost_UNIT_TEST_FRAMEWORK_LIBRARY}")

6
cmake/Modules/OpmPackage.cmake
View File

@ -344,11 +344,11 @@ macro (find_opm_package module deps header lib defs prog conf)
if ((NOT (${module}_INCLUDE_DIR ${_and_lib_var} AND HAVE_${MODULE}))
AND (_${module}_required OR NOT _${module}_quiet))
if (DEFINED ${module}_DIR)
message ("${module}_DIR = ${${module}_DIR}")
message (STATUS "${module}_DIR = ${${module}_DIR}")
elseif (DEFINED ${module}_ROOT)
message ("${module}_ROOT = ${${module}_ROOT}")
message (STATUS "${module}_ROOT = ${${module}_ROOT}")
elseif (DEFINED ${MODULE}_ROOT)
message ("${MODULE}_ROOT = ${${MODULE}_ROOT}")
message (STATUS "${MODULE}_ROOT = ${${MODULE}_ROOT}")
endif (DEFINED ${module}_DIR)
endif ((NOT (${module}_INCLUDE_DIR ${_and_lib_var} AND HAVE_${MODULE}))
AND (_${module}_required OR NOT _${module}_quiet))

22
cmake/Modules/UseOnlyNeeded.cmake
View File

@ -4,11 +4,23 @@
# in order to get only the minimal set of dependencies.
function (prepend var_name value)
if (${var_name})
set (${var_name} "${value} ${${var_name}}" PARENT_SCOPE)
else (${var_name})
set (${var_name} "${value}")
endif (${var_name})
# only add the prefix if it is not already at the beginning. this
# prevents the same string to be added at the same place every time
# we check for reconfiguration (e.g. "--as-needed" below)
string (LENGTH "${value}" _val_len)
string (LENGTH "${${var_name}}" _var_len)
if (NOT (${_var_len} LESS ${_val_len}))
string (SUBSTRING "${${var_name}}" 0 ${_val_len} _var_pre)
else (NOT (${_var_len} LESS ${_val_len}))
set (_var_pre)
endif (NOT (${_var_len} LESS ${_val_len}))
if (NOT ("${_var_pre}" STREQUAL "${value}"))
if (${var_name})
set (${var_name} "${value} ${${var_name}}" PARENT_SCOPE)
else (${var_name})
set (${var_name} "${value}")
endif (${var_name})
endif (NOT ("${_var_pre}" STREQUAL "${value}"))
endfunction (prepend var_name value)
# only ELF shared objects can be underlinked, and only GNU will accept

4
cmake/Modules/dune-cornerpoint-prereqs.cmake
View File

@ -15,8 +15,8 @@ set (dune-cornerpoint_DEPS
# compile with C++0x/11 support if available
"CXX11Features"
# various runtime library enhancements
"Boost 1.39.0
COMPONENTS date_time filesystem system unit_test_framework REQUIRED"
"Boost 1.44.0
COMPONENTS date_time filesystem system iostreams unit_test_framework REQUIRED"
# DUNE dependency
"dune-common REQUIRED;
dune-grid REQUIRED;

30
cmake/Modules/opm-autodiff-prereqs.cmake
View File

@ -3,21 +3,21 @@
# defines that must be present in config.h for our headers
set (opm-autodiff_CONFIG_VAR
)
)
# dependencies
set (opm-autodiff_DEPS
# Compile with C99 support if available
"C99"
# Compile with C++0x/11 support if available
"CXX11Features"
# Various runtime library enhancements
"Boost 1.44.0
COMPONENTS date_time filesystem system unit_test_framework REQUIRED"
# DUNE prerequisites
"dune-common REQUIRED;
dune-istl REQUIRED;
opm-core REQUIRED"
# Eigen
"Eigen3 3.1.2 REQUIRED"
)
# Compile with C99 support if available
"C99"
# Compile with C++0x/11 support if available
"CXX11Features"
# Various runtime library enhancements
"Boost 1.44.0
COMPONENTS date_time filesystem system iostreams unit_test_framework REQUIRED"
# DUNE prerequisites
"dune-common REQUIRED;
dune-istl REQUIRED;
opm-core REQUIRED"
# Eigen
"Eigen3 3.1.2 "
)

18
cmake/Modules/opm-benchmarks-prereqs.cmake Normal file
View File

@ -0,0 +1,18 @@
# -*- mode: cmake; tab-width: 2; indent-tabs-mode: t; truncate-lines: t; compile-command: "cmake -Wdev" -*-
# vim: set filetype=cmake autoindent tabstop=2 shiftwidth=2 noexpandtab softtabstop=2 nowrap:
# defines that must be present in config.h for our headers
set (opm-benchmarks_CONFIG_VAR
)
# dependencies
set (opm-benchmarks_DEPS
# compile with C++0x/11 support if available
"CXX11Features REQUIRED"
# various runtime library enhancements
"Boost 1.44.0
COMPONENTS date_time filesystem system iostreams unit_test_framework REQUIRED"
# OPM dependency
"opm-core"
"opm-upscaling"
)

54
cmake/Modules/opm-core-prereqs.cmake
View File

@ -3,33 +3,33 @@
# defines that must be present in config.h for our headers
set (opm-core_CONFIG_VAR
HAVE_ERT
HAVE_SUITESPARSE_UMFPACK_H
)
HAVE_ERT
HAVE_SUITESPARSE_UMFPACK_H
)
# dependencies
set (opm-core_DEPS
# compile with C99 support if available
"C99"
# compile with C++0x/11 support if available
"CXX11Features REQUIRED"
# various runtime library enhancements
"Boost 1.44.0
COMPONENTS date_time filesystem system unit_test_framework REQUIRED"
# matrix library
"BLAS REQUIRED"
"LAPACK REQUIRED"
# Tim Davis' SuiteSparse archive
"SuiteSparse COMPONENTS umfpack"
# solver
"SuperLU"
# xml processing (for config parsing)
"TinyXML"
#Parser library
"opm-parser REQUIRED"
# Ensembles-based Reservoir Tools (ERT)
"ERT"
# DUNE dependency
"dune-common"
"dune-istl"
)
# compile with C99 support if available
"C99"
# compile with C++0x/11 support if available
"CXX11Features REQUIRED"
# various runtime library enhancements
"Boost 1.44.0
COMPONENTS date_time filesystem system iostreams unit_test_framework REQUIRED"
# matrix library
"BLAS REQUIRED"
"LAPACK REQUIRED"
# Tim Davis' SuiteSparse archive
"SuiteSparse COMPONENTS umfpack"
# solver
"SuperLU"
# xml processing (for config parsing)
"TinyXML"
#Parser library
"opm-parser REQUIRED"
# Ensembles-based Reservoir Tools (ERT)
"ERT"
# DUNE dependency
"dune-common"
"dune-istl"
)

21
cmake/Modules/opm-parser-prereqs.cmake
View File

@ -3,16 +3,17 @@
# defines that must be present in config.h for our headers
set (opm-parser_CONFIG_VAR
HAVE_ERT
)
HAVE_ERT
)
# dependencies
set (opm-parser_DEPS
# compile with C99 support if available
"C99"
# compile with C++0x/11 support if available
"CXX11Features REQUIRED"
# various runtime library enhancements
"Boost 1.44.0 COMPONENTS date_time filesystem system unit_test_framework REQUIRED"
"cJSON"
)
# compile with C99 support if available
"C99"
# compile with C++0x/11 support if available
"CXX11Features REQUIRED"
# various runtime library enhancements
"Boost 1.44.0
COMPONENTS date_time filesystem system iostream unit_test_framework REQUIRED"
"cJSON"
)

4
cmake/Modules/opm-polymer-prereqs.cmake
View File

@ -12,8 +12,8 @@ set (opm-polymer_DEPS
# compile with C++0x/11 support if available
"CXX11Features"
# various runtime library enhancements
"Boost 1.39.0
COMPONENTS date_time filesystem system unit_test_framework REQUIRED"
"Boost 1.44.0
COMPONENTS date_time filesystem system iostreams unit_test_framework REQUIRED"
# Ensembles-based Reservoir Tools
"ERT"
# OPM dependency

4
cmake/Modules/opm-porsol-prereqs.cmake
View File

@ -12,8 +12,8 @@ set (opm-porsol_DEPS
# compile with C++0x/11 support if available
"CXX11Features"
# various runtime library enhancements
"Boost 1.39.0
COMPONENTS date_time filesystem system unit_test_framework REQUIRED"
"Boost 1.44.0
COMPONENTS date_time filesystem system iostreams unit_test_framework REQUIRED"
# DUNE dependency
"dune-common REQUIRED;
dune-istl REQUIRED;

4
cmake/Modules/opm-upscaling-prereqs.cmake
View File

@ -13,8 +13,8 @@ set (opm-upscaling_DEPS
# compile with C++0x/11 support if available
"CXX11Features"
# various runtime library enhancements
"Boost 1.39.0
COMPONENTS date_time filesystem system unit_test_framework REQUIRED"
"Boost 1.44.0
COMPONENTS date_time filesystem system iostreams unit_test_framework REQUIRED"
# matrix library
"BLAS REQUIRED"
"LAPACK REQUIRED"

4
cmake/Modules/opm-verteq-prereqs.cmake
View File

@ -12,8 +12,8 @@ set (opm-verteq_DEPS
# compile with C++0x/11 support if available
"CXX11Features"
# various runtime library enhancements
"Boost 1.39.0
COMPONENTS date_time filesystem system unit_test_framework REQUIRED"
"Boost 1.44.0
COMPONENTS date_time filesystem system iostreams unit_test_framework REQUIRED"
# OPM dependency
"opm-core"
)

754
cmake/OPM-CMake.md Normal file
View File

@ -0,0 +1,754 @@
OPM Build System
================
This is the documentation for the build system used in various OPM modules.
In the following, `xxx` is used as a placeholder for the project name (e.g.
"core").
Unlike traditional CMake files which is highly imperative, OPM projects
sets up declarative lists of prerequisites and content and rely on convention
and pre-made modules to do the build. Its goal is to replace but be
compatible with the old autotools-based system.
## Terminology
In the build system to following abstract locations are referred to:
<table><thead><tr><th>Location<th>Description<tbody>
<tr>
<td> Source tree
<td>
This is where the source files are located. Usually this directory is created
by a `git clone`. You edit files in this directory. The build system on the
other hand will never touch these files; they could be read-only for that
matter. It should be located on a disk that is backed up. The source trees
for various OPM modules should be siblings to eachother.
<tr>
<td> Build tree
<td>
This is where you do `make` (or `ninja`), and the compiler/linker will put
its output here. It may be the same directory as the source tree (which is
then called an "in-tree build"). However, it is recommended that you keep
it separate. Do `make clean && make distclean` to remove all files that
are created by the build (if you put it in the source directory).
You don't need to backup these files (since they can be generated from the
source); instead this directory should be located somewhere with fast
write access. The build trees for various OPM modules should be siblings
(unless they are subdirectories in their source trees).
<tr>
<td> Installation tree
<td>
This is where the build system will put all the final libraries and headers
when running `make install`.
You can specify another location for the installation tree by setting the
CMake variable `CMAKE_INSTALL_PREFIX` on the command line (or use `--prefix=`
with the configure script). Notice that the portion of this path which
will become the new filesystem root should be specified with the environment
variable `DESTDIR`.
</table>
## Use Cases
This section lists some common use cases for adding new code to a project
with respect to the build system, and lists the steps that must be undertaken
to do the necessary modifications.
### Adding a Translation Unit
1. Put the file in a sub-directory of `opm/xxx`.
2. Add the file name to the `MAIN_SOURCE_FILES` list in `CMakeLists_files.txt`.
Please keep this list sorted.
3. If you are adding new interfaces that will be used by client code, add the
header to the `PUBLIC_HEADER_FILES`. Note that any `_impl` headers containing
template implementations must also be included.
### Adding a Prerequisite
1. Add the name of the prerequisite module to the `opm-xxx_DEPS` list in the file
`cmake/Modules/opm-xxx-prereqs.cmake`, where xxx is a placeholder for the module
name of your CMake project.
2. If you need any CMake configuration defines available in your public _headers_,
add these to the `opm-xxx_CONFIG_VAR` list in the same file. Please refrain
from this practice as it imposes a requirement on the clients of your code to
gather the same configuration information and make it available in the units
which uses your headers.
### Adding a Unit Test
1. Put the source code in a single translation unit in directory `tests`. The
name of this unit should start with `test_`.
2. Put any datafiles this code rely on in the same directory. The code should
assume that such datafiles are available in the current directory the program
is running from. The code should not write to these files, but rather make
a copy if it needs to modify them.
3. Add the file name to the `TEST_SOURCE_FILES` list in `CMakeLists_files.txt`.
4. Add the datafiles to the `TEST_DATA_FILES` list in the same files. The
files will be copied from the source tree into the target tree.
### Adding a New Utility Program
1. Put the source code of the utility in the `examples` directory.
2. Add the name of the translation unit to the `PROGRAM_SOURCE_FILES` list
in `CMakeLists_files.txt`.
### Creating a New Module
1. Copy the directory `cmake/` and all sub-directories from opm-core. This
directory contains the common build system, and should ideally be identical
across OPM projects. Also copy the file `configure` in the project root.
2. Create project-specific files using those from another project as a template.
The list of project specific files is in the section
[Modules Reference](#project-specific-files) below.
3. Create a new file `cmake/Modules/opm-xxx-prereqs.cmake`, using one of the
existing ones as a template.
4. Optionally, create a new file `cmake/Modules/Findopm-xxx.cmake`, using one
of the existing ones as a template.
## Options
These options regulate the behaviour of the build system. In addition to these
options, you can also set standard CMake options, or options for the
prerequisites, which is not documented here. If you run the configure script
with the `--help` option, it will print a text of what the options are called
when using the autotools-compatible wrapper.
<table><thead><tr><th>Option<th>Description<tbody>
<tr>
<td> BUILD_EXAMPLES
<td>
Include the examples when doing a build. Whenever you change something
in the library, however small, all the examples will also be rebuilt.
Default is ON.
<tr>
<td> BUILD_TESTING
<td>
Include the unit tests when doing a build. Whenever you change something
in the library, however small, all the unit tests will also be rebuilt.
Default is ON.
<tr>
<td> PRECOMPILE_HEADERS
<td>
Precompile common headers into a binary blob which is loaded on further
compilations. If your compiler supports this, it usually reduces build
time. It does not affect the running time of the code. Default is OFF.
<tr>
<td> SIBLING_SEARCH
<td>
Search for OPM/DUNE prerequisites in sibling directories of the build
tree. Default is ON.
<tr>
<td> SUITESPARSE_USE_STATIC
<td>
Link SuiteSparse/UMFPack statically. Using this option will enable you
to build an executable which has no external dependencies. The default
is to use shared libraries if those are available.
<tr>
<td> SYSTEM_DEBUG
<td>
Put debug symbols in the system debug directory (`/usr/lib/debug`) as
this seems to be the only place which is searched by default by GDB.
Default is OFF, as it requires that you have write access to that
directory. Note that if you are doing a system installation (set
CMAKE_INSTALL_PREFIX=/usr), then the libraries will be put in this
location irregardless of this option.
<tr>
<td> USE_MPI
<td>
Enable the code to use MPI for parallelization. Default is OFF.
Note: It is important that OPM and DUNE modules is either all
compiled with MPI support or that none is. The build system will
attempt to recognize inconsistencies.
<tr>
<td> USE_OPENMP
<td>
Enable the code to use OpenMP for parallelization. Default is ON.
<tr>
<td> USE_RUNPATH
<td>
Remember the directories from where the prerequisites were found
when building. Default is ON, which enables you to run without
setting PATH all over the place in your build directories. When
creating an installation package, this should be set off.
<tr>
<td> USE_UNDERSCORING
<td>
Assume that Fortran externals have an underscore suffix instead
of checking this with an actual compiler. If you set this option,
you can use Fortran libraries (notably BLAS and LAPACK) without
having a Fortran compiler installed. The default is OFF.
<tr>
<td> USE_VERSIONED_DIR
<td>
Put libraries in a directory which includes the label of the project,
e.g. `/usr/lib/opm-core/2013.10`. Default is OFF.
<tr>
<td> WITH_NATIVE
<td>
Optimize for the instruction set of the build machine. This is
a good idea if you are building the library on the same machine
as you will be using the library. Default is ON.
<tr>
<td> WHOLE_PROG_OPTIM
<td>
Perform an extra round of optimization when linking the program.
(Usually the compiler only optimizes within the translation unit).
If your compiler supports this, it usually leads to a faster runtime.
Default is OFF.
</table>
## Modules Reference
### Project-specific Files
All of these files are in the project root, except for `opm-xxx.m4`
which is in the `m4` directory. (`dunecontrol` always adds this
subdirectory for all the prerequisites listed in `dune.module`, to the
search path).
<table><thead><tr><th>File<th>Description<tbody>
<tr>
<td> CMakeLists.txt
<td>
Project-specific customizations to the build, such as filtering out source
files based on the availability of prerequisites, or adding configuration
variables only the implementation depends on.
Prefer to do customizations in the hooks available to this file rather than
adding ad-hoc code to the build system itself, to keep the `cmake/` directory
unified across projects.
<tr>
<td> CMakeLists_files.txt
<td>
List of all compilation modules in the project, test cases and public
headers that should be installed in the distribution package. The contents
of these lists are distributed to project-specific variables by the build
system.
<tr>
<td> CTestConfig.cmake
<td>
Settings for submitting result of tests to CDash. The default is setup
to submit to [the official CDash panel](http://www.opm-project.org/CDash/)
and does not need to be changed if your module has a panel there.
<tr>
<td> dune.module
<td>
Information about the project such as name, release label, link version
and maintainer. Also specify dependencies to other OPM/DUNE-projects so
that dunecontrol can build in correct order. (Note that the full list of
dependencies is taken from opm-xxx-prereqs.cmake and not from here).
Since this file must be present before the build starts (for dunecontrol),
the version information is kept here.
<tr>
<td> opm_xxx.m4
<td>
Tell the generic opm.m4 module which name it should request pkg-config
for. This module is used by autotools-projects which link to OPM.
Notice that dashes is replaced by underscore in the filename to be
compatible with M4. (The actual name of the file doesn't matter to the
autotools build system). The contents of this file is mostly boiler-plate
where the names need to be changed to the project in question. (The
DUNE build system assumes the presence of macros based on the project
name).
</table>
### Project Modules
These modules contains the dependency information for this project, so
the build system can set up the prerequisite list correctly and probe
for other modules automatically. (This replaces hard-coded calls to
find_library in the CMakeLists.txt file).
<table><thead><tr><th>File (.cmake)<th>Description<tbody>
<tr>
<td> xxx-prereqs
<td>
List prerequisite modules and defines used in public headers. Each module
must have such a "declaration", and this must be made available to every
other projects as well (which is why this is located in `cmake/Modules`).
<tr>
<td> Findxxx
<td>
CMake modules which locates module `xxx` in the system directories. As
the `opm-xxx-config.cmake` is made available together with the libraries
and headers, these modules are not really needed (for OPM modules).
</table>
### Generated Files
These files are generated by the build system and exists in the _build_ tree,
not in the source tree. They are documented here to make developers aware of
their role in the build system.
<table><thead><tr><th>File<th>Description<tbody>
<tr>
<td> config.h
<td>
Settings variables which the build system has configured and make available
to the source code. This file is **not** installed amongst the headers, so
you should never include this in a public header, even if you need the value
in one of these variables. Instead, you must rely on the client code to
configure this variable for you.
<tr>
<td> opm-xxx.pc
<td>
pkg-config information file to locate the **build** tree. This is used by
the autotools build files, but can also be handy when manually building
small test programs for which you don't generate an own build system.
<tr>
<td> opm-xxx-config.cmake
<td>
CMake information file to locate the **build** tree. This file is imported
when this project is set up as a prerequisite.
<tr>
<td> opm-xxx-install.pc
<td>
pkg-config information file to locate the **installation** tree. It is
the same as `opm-xxx.pc` except that the paths are switched. When the
project is installed, this file is installed instead (under `lib/pkgconfig`
relative to the installation root). This directory should hence be put
in the search path to pkg-config to use the installed package. Before
installation, this file is worthless and should not be included, because
it does not refer to the build tree at all. (Be careful not to mix
the build and the installation tree).
Notice that the build system will forward a bunch of public definitions
which should be available to compile code referring to this library.
<tr>
<td> opm-xxx-install.cmake
<td>
CMake information file to locate the **installation** tree. It is the
same as `opm-xxx-config.cmake` except that the paths are switched. When
the project is installed, this file is installed instead (under `share/cmake`
relative to the installation root).
<tr>
<td> opm-xxx-config-version.cmake
<td>
CMake wants to include this into the build _before_ it is determined whether
the library was found successfully (depending on the version number perhaps),
so this information is put in its own file. Since it is the same for the
build tree and the installation tree, it is shared in both those locations.
</table>
### Utility Modules
These modules consists of useful routines which is not OPM-specific and
that could be used in any projects. They don't depend on any other parts
of the build system.
<table><thead><tr><th>File (.cmake)<th>Description<tbody><tr>
<td> AddOptions
<td>
Functions to add options to compiler command line (e.g. 'CXXFLAGS').
This macro can add options to more than one language and/or configuration
at a time, and also automatically removes duplicates.
<tr>
<td> ConfigVars
<td>
Functions to write values of selected variables to `config.h`. The
advantage of using this compared to a template file, is that other
modules can add their own variables to be written (a project doesn't
need to know which variables a prerequisite wants to have in config.h).
<tr>
<td> DuneCompat
<td>
Modify `Makefile` so dunecontrol can infer source directory from it.
dunecontrol infers the source location of prerequisites from textual
analysis of the Makefile in their build tree. (dunecontrol cannot build
with Ninja anyway, so that is not a problem).
<tr>
<td> Duplicates
<td>
Functions to remove duplicate values from a list of libraries, which
must always be done from the beginning in order to link correctly.
<tr>
<td> LibtoolArchives
<td>
Write .la file which will make libtool find our library. This enables
users of our library to use libtool even if we did not do so ourselves.
</table>
### Build System Modules
These are the modules which comprises the OPM-specific parts of the
build system. The overall flow through the stages of the build is best
captured by reading through the `OpmLibMain.cmake` module.
<table><thead><tr><th>File (.cmake)<th>Description<tbody>
<tr>
<td> configure
<td>
Wrapper script which emulates an autotools front-end, making the build
system usable with dunecontrol. There is one in the project root directory
which just forwards everything to the main script in `cmake/Scripts`.
<tr>
<td> OpmAliases
<td>
Copy variables which are probed by our find modules to the names which
are expected by DUNE.
<tr>
<td> OpmCompile
<td>
Set up a compilation target for the library itself. It is assumed that
each OPM project build exactly one library file containing all its code.
The files and compiler options are passed through the project variables
(see the section [Variables Reference](#variables-reference) below).
<tr>
<td> OpmDefaults
<td>
If optimization and debugging settings are not given on the command line,
supply a set of reasonable defaults for the detected platform and
compiler.
<tr>
<td> OpmDistClean
<td>
Add a target (`make distclean`) to the build system which can remove the
build files themselves from the build directory tree.
<tr>
<td> OpmDoc
<td>
Add target for building documentation, primarily Doxygen class reference
from the code.
<tr>
<td> OpmFiles
<td>
Load list of files from `CMakeLists_files.txt` and put into the applicable
variables.
<tr>
<td> OpmGrid
<td>
Adds the grid type selection code to config.h which is needed by dune-grid
if you want to set up a default grid. This is currently not needed by any
OPM project, and is provided only for porting client projects which previously
used this functionality from the autotools version.
<tr>
<td> OpmInit
<td>
Read the version information and project name from `dune.module`.
<tr>
<td> OpmInstall
<td>
Setup installation of the main library, public headers and debug symbols.
<tr>
<td> OpmKnown
<td>
Marks as "used" all configuration variables which is used only by some of
the OPM projects, so they don't generate warnings in the rest of them.
<tr>
<td> OpmLibMain
<td>
Driver module for the build process. First reads the list of prerequisites
and options, then set up the compiles and installations.
<tr>
<td> OpmProject
<td>
Set up pkg-config and CMake information files (see [Generated Files]
(#generated-files)) for this project, based on configuration.
<tr>
<td> OpmSatellites
<td>
Build test programs and examples for a library that is bundled in the project.
</table>
### Wrapper Modules
These modules wrap the CMake `find_library` function and adds the information
retrieved from the imported prerequisite to module-specific variables, so that
these can be added to the build in batch afterwards.
<table><thead><tr><th>File (.cmake)<th>Description<tbody>
<tr>
<td> OpmFind
<td>
Wrapper around `find_package`. Searches in various locations relative to this
project as well as in the system directories for a CMake module which can
locate the package. If it is found, adds the project variables (see
[Variables Reference](#variables-reference)) for this project into this one,
for instance include and library directories are added to the compile and link
command-line for this project.
<tr>
<td> OpmPackage
<td>
Typical way of finding an OPM package; searches for the header and library,
and tries to compile a test program. This is the general implementation of
a CMake find module, and is used to locate those of the prerequisites that
fits the pattern.
</table>
### Configuration Modules
These are modules for altering the compiler and/or linker option in some way,
or get information from the system. They are not tied to the OPM projects.
<table><thead><tr><th>File (.cmake)<th>Description<tbody>
<tr>
<td> UseCompVer
<td>
Get the version of GCC that is used to compile the project. This is used in
other modules to enable features that are known to exist/work only in certain
versions of GCC.
<tr>
<td> UseDebugSymbols
<td>
Set up the compile to generate debug symbols for the code. This is done also
if a release build was requested, to be able to do post-mortem debugging of
production code. (The debug symbols does not inhibit optimization).
<tr>
<td> UseDuneVer
<td>
Retrieve the version of DUNE which is available.
<tr>
<td> UseDynamicBoost
<td>
Determine if Boost is linked statically or dynamically (shared). This is
necessary to know for the unit tests.
<tr>
<td> UseFastBuilds
<td>
Enable certain techniques which is known to speed up the build itself.
<tr>
<td> UseFortranWrappers
<td>
Provide a macro for declaration of external symbols which is located in
Fortran libraries. It is not necessary to have a Fortran compiler present
to use this macro.
<tr>
<td> UseMultiArch
<td>
Check if the system uses the multi-arch scheme for organizing libraries
(currently derivatives of Debian do this).
<tr>
<td> UseOnlyNeeded
<td>
Only link to libraries which is actually used by the project. Some
platforms provide "under-linked" libraries (they need other libraries
but doesn't state so explicitly, but rather imply that the executable
must link to these itself), and this is also handled.
<tr>
<td> UseOpenMP
<td>
Add OpenMP features to the build. Since OpenMP is activated by pragmas
in the code, compiler options instead of libraries are needed.
<tr>
<td> UseOptimization
<td>
Compile with more extensive optimization that what is the default in
CMake.
<tr>
<td> UsePrecompHeaders
<td>
Set up precompiled headers if the project has a `opm/xxx/opm-xxx-pch.hpp`
header. Due to problems across various compilers, this is currently an
opt-in feature.
<tr>
<td> UseSystemInfo
<td>
Retrieve information about the system the build is performed on. This is
printed in the configuration log and can be helpful to troubleshoot
problems from error reports.
<tr>
<td> UseVCSInfo
<td>
Retrieve information about which Git revision is compiled. This is useful
to figure out which version an error report refers to.
<tr>
<td> UseVersion
<td>
Add version information for this project into the library binary, making
it available for query at runtime.
<tr>
<td> UseWarnings
<td>
Enable a more extensive set of warnings to be reported by the compiler
than what is the default in CMake.
</table>
## Variables Reference
The build system will setup variables with names of the pattern `xxx_YYY`
where xxx is the project name (here including the suite; e.g. "opm-core")
and yyy is the suffix in the list below. The project name is used verbatim,
i.e. there is no translation of dashes and case ("opm-core" and not "OPM_CORE").
<table><thead><tr><th>Suffix<th>Description<tbody>
<tr>
<td> _DEFINITIONS
<td>
Macro defines (of the type `-DFOO`) that needs to be added to the compile
of translation units contained in this library. This also includes defines
that must be present to headers which is included by this library.
<tr>
<td> _CONFIG_VARS
<td>
Defines which should be present in `config.h` of the project which
includes this library (client code). Only the names of the variables
are listed here; the actual values must be found by the configuration
script of the client.
<tr>
<td> _CONFIG_IMPL_VARS
<td>
Defines which should be present in `config.h` but is only used by
the internal code of the project itself. Use this list to get
defines without imposing a requirement on client code to also probe
for values.
<tr>
<td> _INCLUDE_DIR
<td>
Directory where the public headers of this project are stored.
<tr>
<td> _INCLUDE_DIRS
<td>
List of include directories that must be on the compiler search
path to compile code which uses this project. In addition to the
headers of this project itself, it also includes the transitive
closure of paths for all prerequisites as well.
<tr>
<td> _LABEL
<td>
Currently for OPM projects, this follows a pattern of `YYYY.MM`
where YYYY is the year of the release and MM is the month. This
gives information to humans about how up to date this instance
of the library is (but doesn't provide a way to check for
compatibility, which is why the VERSION alternatives exist).
<tr>
<td> _LIBRARY
<td>
Name and path of the binary to link with.
<tr>
<td> _LIBRARIES
<td>
Full list of the library of both this project, and all its
prerequisites, that need to be included in the link. I.e. the
client code should only include the transitive list from its
immediate prerequisites and not know about the full dependency
graph.
<tr>
<td> _LIBRARY_DIRS
<td>
Directories that should be added to the linker search path when
including this library.
<tr>
<td> _LINKER_FLAGS
<td>
Flags that must be added to the link when including this library.
<tr>
<td> _SOURCES
<td>
List of source files contained in this project. This enables libraries
to be distributed in source form (e.g. CJSON and TinyXML) and linked
directly into the project.
<tr>
<td> _TARGET
<td>
Name of the library which is generated by this project. CMake and
autotools do not like library names which contains dashes, so they
are stripped out. By using a macro for this we are guaranteed uniform
translation.
<tr>
<td> _VERSION
<td>
Textual concatenation of all components of the version number (see below)
with a dot inbetween. This form of version number can be compared using
CMake VERSION_{LESS|EQUAL|GREATER} operators.
<tr>
<td> _VERSION_MAJOR
<td>
Major version of the library. If the major versions doesn't match, then
compatibility with existing code cannot be reckoned.
<tr>
<td> _VERSION_MINOR
<td>
Minor version of the library. Libraries with newer minor version can
have more features, but should be able to run old code.
<tr>
<td> _VERSION_REVISION
<td>
Micro version of the library. This number is generally incremented
whenever bugfixes or performance improvements are made.
</table>