-Table of contents
+=================
+TABLE OF CONTENTS
=================
-The philosophy
+ Introduction
-Quick start
+ The philosophy
-Useful bits
+ Quick start
-Feature configuration
+ Useful bits
-Build configuration
+ Configuration
-Installation
+ Feature configuration
-Component selection
+ Component selection
-Fat note regarding platform checks and feature configuration
+ Build configuration
-Writing platform checks
+ Installation
-Writing features
+ Development
+ Fat note regarding platform checks and feature configuration
+ Writing platform checks
+ Writing features
-The philosophy
-==============
- »I need a new keyboard, my CAPS-KEY is stuck because of writing all
- this cmake script...«
-TODO
+============
+INTRODUCTION
+============
+ TODO
-Quick start
-===========
+ The philosophy
+ ==============
-* Make a build directory, configure, compile and install:
+ »I need a new keyboard, my CAPS-KEY is stuck because of writing all
+ this cmake script...«
- $ mkdir build
- $ cd build
- $ cmake -DCMAKE_INSTALL_PREFIX=/path/install/dir ../
- $ make install
+ TODO
+ Quick start
+ ===========
-Useful bits
-===========
+ * Make a build directory, configure, compile and install:
+ $ mkdir build
+ $ cd build
+ $ cmake -DCMAKE_INSTALL_PREFIX=/path/install/dir ../
+ $ make install
-* All cached variables can be either set via
- ( $ cd build )
- $ ccmake
+ Useful bits
+ ===========
- or at the prompt via:
- ( $ cd build )
- $ cmake -D<OPTION>=<VALUE> [...] path/to/source/tree
+ * All cached variables can be either set via
-* Configure with autodetection, afterwards disable a feature:
+ ( $ cd build )
+ $ ccmake
- ( $ cd build )
- $ cmake -DDEAL_II_FEATURE_AUTODETECTION=ON ../
- $ cmake -DDEAL_II_FEATURE_AUTODETECTION=OFF -DDEAL_II_WITH_METIS=OFF ../
- $ make install
+ or at the prompt via:
-* Build and install only a specific component:
+ ( $ cd build )
+ $ cmake -D<OPTION>=<VALUE> [...] path/to/source/tree
- ( $ cd build )
- $ make <component>
- $ cmake -DCOMPONENT=<component> -P build/cmake_install.cmake
+ * Configure with autodetection, afterwards disable a feature:
+ ( $ cd build )
+ $ cmake -DDEAL_II_FEATURE_AUTODETECTION=ON ../
+ $ cmake -DDEAL_II_FEATURE_AUTODETECTION=OFF -DDEAL_II_WITH_METIS=OFF ../
+ $ make install
+ * Build and install only a specific component:
+ ( $ cd build )
+ $ make <component>
+ $ cmake -DCOMPONENT=<component> -P build/cmake_install.cmake
-Feature configuration
-=====================
-TODO: Reformulate
-The first bunch of options of type DEAL_II_WITH_<feature> are for
-configuration of the various features of the deal.II library.
-An enabled feature will usually add one ore more dependencies to external
-or 'contrib' (i.e. bundled with deal.II and residing under ./contrib/)
-libraries.
+=============
+CONFIGURATION
+=============
-The option DEAL_II_ALLOW_CONTRIB determines the behaviour of the
-dependency resolution:
-- If set to ON external libraries still have precedence. But if there is
- no external library the bundled contrib library will be used.
+ The various configuration options of the deal.II library are organized in
+ three categories: Feature, Component and build/install configuration.
-- If set to OFF the contrib libraries will not be used and the dependency
- resolution will fail if there is no external library. EXCEPT (there is
- always an exception, isn't it?) DEAL_II_FORCE_CONTRIB_<library> forces
- the use of the bundled contrib library.
+ Feature configuration
+ =====================
-Autoconfiguration: If the option DEAL_II_FEATURE_AUTODETECTION is enabled
-the DEAL_II_WITH_<feature> toggles will be automatically set (overwriting
-any previous configuration) depending on whether they can be supported or
-not.
-(Note: DEAL_II_FEATURE_AUTODETECTION will respect DEAL_II_ALLOW_CONTRIB
-and DEAL_II_FORCE_CONTRIB_<feature>)
+ deal.II provides (optional) interfaces to quite a number of external
+ libraries:
+ DEAL_II_WITH_ARPACK
+ Build deal.II with support for ARPACK
-The option DEAL_II_FORCE_CONTRIB_<library> forces the use of the bundled
-contrib library regardless whether DEAL_II_ALLOW_CONTRIB is set to OFF or
-an external library is found.
+ DEAL_II_WITH_BLAS
+ Build deal.II with support for BLAS
-REMARKS:
+ DEAL_II_WITH_BOOST
+ Build deal.II with support for boost. Always activated
-- To ensure that no bundled library is used at all DEAL_II_ALLOW_CONTRIB,
- as well as every DEAL_II_FORCE_CONTRIB_<library> have to be set to OFF.
+ DEAL_II_WITH_DOXYGEN
+ Build deal.II with support for doxygen and dot
-- DEAL_II_FORCE_CONTRIB_<library>=ON will _not_ automatically enable the
- corresponding DEAL_II_WITH_<feature> toggle. This has to be set
- separately.
+ DEAL_II_WITH_FUNCTIONPARSER
+ Build deal.II with support for functionparser
-TODO: A list of all DEAL_II_WITH_* options
+ DEAL_II_WITH_LAPACK
+ Build deal.II with support for LAPACK
+ DEAL_II_WITH_METIS
+ Build deal.II with support for Metis
+ DEAL_II_WITH_MPI
+ Build deal.II with support for mpi
+ DEAL_II_WITH_NETCDF
+ Build deal.II with support for netcdf
-Build configuration
-===================
+ DEAL_II_WITH_P4EST
+ Build deal.II with support for P4EST
+ DEAL_II_WITH_TBB
+ Build deal.II with support for tbb. This will enable thread support in deal.II
-CMAKE_BUILD_TYPES: We support the "Debug" and "Release" build targets.
-Default is the "Release" target.
+ DEAL_II_WITH_TRILINOS
+ Build deal.II with support for trilinos
-- Debug will enable a lot of debug code paths and Assertions, as well as
- compiling the library with a suitable set of debug compiler flags.
+ DEAL_II_WITH_UMFPACK
+ Build deal.II with support for UMFPACK
-- Release will chose a suitable set of optimizing flags.
+ DEAL_II_WITH_ZLIB
+ Build deal.II with support for zlib
+ An enabled feature will usually add one ore more dependencies to external
+ or 'contrib' (i.e. bundled with deal.II and residing under ./contrib/)
+ libraries.
-deal.II will configure sensible default CFLAGS and CXXFLAGS depending on
-platform, compiler and build target. There are two options, if this is
-not desired:
-- Option 1: Disable the configuration completely by setting
- DEAL_II_SETUP_DEFAULT_COMPILER_FLAGS to OFF.
- Beware of the fact that certain features may still pull in necessary
- compiler flags.
+ There are some options to determine the behaviour of the dependency
+ resolution:
-- Option 2: Overwrite the default configuration by setting the following
- cached variables:
+ The option DEAL_II_ALLOW_CONTRIB determines the behaviour of the
+ dependency resolution:
- CMAKE_CXX_FLAGS - used during all builds
- CMAKE_CXX_FLAGS_DEBUG - additional flags used during debug builds
- CMAKE_CXX_FLAGS_RELEASE - additional flags used during release builds
- (same for CMAKE_C_...)
+ - If set to ON external libraries still have precedence. But if there is
+ no external library the bundled contrib library will be used.
-The content of the cached variables will be preserved and added
-*_TO THE END_* of the default compiler flags, hence giving a possibility
-for overwriting a flag. E.g.: -Wsign-compare, set by the build system,
-can be overwritten by specifying:
+ - If set to OFF the contrib libraries will not be used and the dependency
+ resolution will fail if there is no external library. EXCEPT (there is
+ always an exception, isn't it?) DEAL_II_FORCE_CONTRIB_<library> forces
+ the use of the bundled contrib library.
- $ cmake -DCMAKE_CXX_FLAGS="-Wno-sign-compare" <...>
+ The option DEAL_II_FORCE_CONTRIB_(BOOST|FUNCTIONPARSER|TBB|UMFPACK)
+ forces the use of the bundled contrib library regardless whether
+ DEAL_II_ALLOW_CONTRIB is set to OFF or an external library is found.
+ Autoconfiguration:
+ If the option DEAL_II_FEATURE_AUTODETECTION is enabled the
+ DEAL_II_WITH_<feature> toggles will be automatically set (overwriting any
+ previous configuration) depending on whether they can be supported or
+ not.
+ (Note: DEAL_II_FEATURE_AUTODETECTION will respect DEAL_II_ALLOW_CONTRIB
+ and DEAL_II_FORCE_CONTRIB_<feature>)
-The build can be further controlled by the following variables:
+ REMARKS:
-- BUILD_SHARED_LIBS: If set, deal.II will be linked as a shared library
+ - To ensure that no bundled library is used at all DEAL_II_ALLOW_CONTRIB,
+ as well as every DEAL_II_FORCE_CONTRIB_<library> have to be set to OFF.
-- CMAKE_INSTALL_RPATH_USE_LINK_PATH: If set, the deal.II library will be
- installed with its rpath value set to point to all libraries outside of
- the system search pathes.
+ - DEAL_II_FORCE_CONTRIB_<library>=ON will _not_ automatically enable the
+ corresponding DEAL_II_WITH_<feature> toggle. This has to be set
+ separately.
-Component selection
-===================
+ Component selection
+ ===================
-The following options control which components of the deal.II shall be
-configured, build and installed:
+ The following options control which components of the deal.II will be
+ configured, build and installed:
-- DEAL_II_COMPONENT_EXAMPLES:
- Enable configuration and installation of the example steps.
- This adds a COMPONENT "examples" to the build system.
+ - DEAL_II_COMPONENT_EXAMPLES:
+ Enable configuration and installation of the example steps.
+ This adds a COMPONENT "examples" to the build system.
-- DEAL_II_COMPONENT_DOCUMENTATION:
- Enable configuration, build and installation of the documentation.
- This adds a COMPONENT "documentation" to the build system.
+ - DEAL_II_COMPONENT_DOCUMENTATION:
+ Enable configuration, build and installation of the documentation.
+ This adds a COMPONENT "documentation" to the build system.
-- DEAL_II_COMPONENT_COMPAT_FILES:
- Enable installation of legacy files and tools for compatibility with
- the old build system
- This adds a COMPONENT "compat_files" to the build system.
+ - DEAL_II_COMPONENT_COMPAT_FILES:
+ Enable installation of legacy files and tools for compatibility with
+ the old build system
+ This adds a COMPONENT "compat_files" to the build system.
-- DEAL_II_COMPONENT_PROJECT_CONFIG:
- Enable configuration and installation of a cmake project config. Useful
- for finding ( FIND_PACKAGE(DEAL_II) ) the deal.II library out of cmake
- build systems. This adds a COMPONENT "project_config" to the build
- system.
+ - DEAL_II_COMPONENT_PROJECT_CONFIG:
+ Enable configuration and installation of a cmake project config. Useful
+ for finding ( FIND_PACKAGE(DEAL_II) ) the deal.II library out of cmake
+ build systems. This adds a COMPONENT "project_config" to the build
+ system.
-Installation
-============
+ Build configuration
+ ===================
+
+
+ CMAKE_BUILD_TYPES: We support the "Debug" and "Release" build targets.
+ Default is the "Release" target.
+
+ - Debug will enable a lot of debug code paths and Assertions, as well as
+ compiling the library with a suitable set of debug compiler flags.
+
+ - Release will chose a suitable set of optimizing flags.
+
+
+ deal.II will configure sensible default CFLAGS and CXXFLAGS depending on
+ platform, compiler and build target. There are two options, if this is
+ not desired:
+
+ - Option 1: Disable the configuration completely by setting
+ DEAL_II_SETUP_DEFAULT_COMPILER_FLAGS to OFF.
+ Beware of the fact that certain features may still pull in necessary
+ compiler flags.
+
+ - Option 2: Overwrite the default configuration by setting the following
+ cached variables:
-CMAKE_INSTALL_PREFIX determines the location, where the deal.II library
-will be installed.
+ CMAKE_CXX_FLAGS - used during all builds
+ CMAKE_CXX_FLAGS_DEBUG - additional flags used during debug builds
+ CMAKE_CXX_FLAGS_RELEASE - additional flags used during release builds
+ (same for CMAKE_C_...)
-Please note that depending on whether DEAL_II_COMPONENT_COMPAT_FILES is
-set, there will be different folder structures:
+ The content of the cached variables will be preserved and added
+ *_TO THE END_* of the default compiler flags, hence giving a possibility
+ for overwriting a flag. E.g.: -Wsign-compare, set by the build system,
+ can be overwritten by specifying:
-With DEAL_II_COMPONENT_COMPAT_FILES=ON:
+ $ cmake -DCMAKE_CXX_FLAGS="-Wno-sign-compare" <...>
-${CMAKE_INSTALL_PREFIX}/
- common
- common/scripts
- doc
- examples
- include
- lib
-With DEAL_II_COMPONENT_COMPAT_FILES=OFF:
+ The build can be further controlled by the following variables:
-${CMAKE_INSTALL_PREFIX}/
- include
- lib${LIB_SUFFIX}
- /share/doc/deal.II/examples
- /share/doc/deal.II/html
+ - BUILD_SHARED_LIBS: If set, deal.II will be linked as a shared library
-If DEAL_II_COMPONENT_COMPAT_FILES is set to OFF, the individual target
-directories can be overwritten by
- DEAL_II_DOCUMENTATION_RELDIR
- DEAL_II_EXAMPLES_RELDIR
- DEAL_II_INCLUDE_RELDIR
- DEAL_II_LIBRARY_RELDIR
- DEAL_II_PROJECT_CONFIG_RELDIR
+ - CMAKE_INSTALL_RPATH_USE_LINK_PATH: If set, the deal.II library will be
+ installed with its rpath value set to point to all libraries outside of
+ the system search pathes.
-Fat note regarding platform checks and feature configuration
-============================================================
+ Installation
+ ============
+
+ CMAKE_INSTALL_PREFIX determines the location, where the deal.II library
+ will be installed.
+
+ Please note that depending on whether DEAL_II_COMPONENT_COMPAT_FILES is
+ set, there will be different folder structures:
+
+ With DEAL_II_COMPONENT_COMPAT_FILES=ON:
+
+ ${CMAKE_INSTALL_PREFIX}/
+ common
+ common/scripts
+ doc
+ examples
+ include
+ lib
+
+ With DEAL_II_COMPONENT_COMPAT_FILES=OFF:
+
+ ${CMAKE_INSTALL_PREFIX}/
+ include
+ lib${LIB_SUFFIX}
+ /share/doc/deal.II/examples
+ /share/doc/deal.II/html
+
+ If DEAL_II_COMPONENT_COMPAT_FILES is set to OFF, the individual target
+ directories can be overwritten by
+ DEAL_II_DOCUMENTATION_RELDIR
+ DEAL_II_EXAMPLES_RELDIR
+ DEAL_II_INCLUDE_RELDIR
+ DEAL_II_LIBRARY_RELDIR
+ DEAL_II_PROJECT_CONFIG_RELDIR
+
+
+
+
+==========
+DEVELOPMENT
+===========
+
+
+ Fat note regarding platform checks and feature configuration
+ ============================================================
- ============
+ ============
- FAT NOTE
+ FAT NOTE
- ============
+ ============
-To keep things clean, only the following cmake variables should be
-altered in the platform checks and feature configuration
-(beside setting a lot of DEAL_II_* definitions...):
+ To keep things clean, only the following cmake variables should be
+ altered in the platform checks and feature configuration
+ (beside setting a lot of DEAL_II_* definitions...):
-For internal use:
+ For internal use:
- CMAKE_SHARED_LINKER_FLAGS
- for setting necessary linker flags for the deal.II library.
+ CMAKE_SHARED_LINKER_FLAGS
+ for setting necessary linker flags for the deal.II library.
- CMAKE_CXX_FLAGS (and CMAKE_C_FLAGS)
- for setting necessary compiler flags, e.g. -std=c++11 (if
- available).
+ CMAKE_CXX_FLAGS (and CMAKE_C_FLAGS)
+ for setting necessary compiler flags, e.g. -std=c++11 (if
+ available).
- INCLUDE_DIRECTORIES(...)
- For setting necessary include dirs for the compilation of the
- deal.II library.
+ INCLUDE_DIRECTORIES(...)
+ For setting necessary include dirs for the compilation of the
+ deal.II library.
- ADD_DEFINITIONS(...)
- For setting necessary preprocessor definitions ("-D<...>") for
- the compilation of the deal.II library
+ ADD_DEFINITIONS(...)
+ For setting necessary preprocessor definitions ("-D<...>") for
+ the compilation of the deal.II library
- ADD_DEPENDENCIES(deal_ii_target_dependencies ...)
- Used as a dummy target for all the stuff that has to be done
- before the library can be compiled.
+ ADD_DEPENDENCIES(deal_ii_target_dependencies ...)
+ Used as a dummy target for all the stuff that has to be done
+ before the library can be compiled.
-For internal and external use:
+ For internal and external use:
- DEAL_II_EXTERNAL_LIBRARIES
- Used to keep track of external libraries, the deal.II library
- and user programs have to be linked against.
+ DEAL_II_EXTERNAL_LIBRARIES
+ Used to keep track of external libraries, the deal.II library
+ and user programs have to be linked against.
-For external use:
+ For external use:
- DEAL_II_EXTERNAL_DEFINITIONS
- Used to keep track of external preprocessor definitions,
- necessary for the compilation of user programs.
+ DEAL_II_EXTERNAL_DEFINITIONS
+ Used to keep track of external preprocessor definitions,
+ necessary for the compilation of user programs.
- DEAL_II_EXTERNAL_INCLUDE_DIRS
- Used to keep track of external include dirs, necessary for the
- compilation of user programs.
+ DEAL_II_EXTERNAL_INCLUDE_DIRS
+ Used to keep track of external include dirs, necessary for the
+ compilation of user programs.
-Writing platform checks
-=======================
+ Writing platform checks
+ =======================
-TODO
+ TODO
-Writing features
-================
+ Writing features
+ ================
-TODO
+ TODO