From: bangerth
+ The deal.II README file gives an overview over the basics
+ of configuring and building the deal.II
+ library. This page provides more details about configuring
+ with
+ When configuring deal.II by
+ running
+ Normally, one will then simply build the library in this
+ directory by calling
+ That said, it is occasionally helpful to run Details on the deal.II configuration and build system
-
-
-
- ==================================================
-
- The cmake build system for the deal.II project
-
- ==================================================
-
- Author: Matthias Maier cmake
and building with it.
+ Operating the configuration system
+
+ cmake
, the cmake
program
+ creates a cache in the current (build) directory that contains
+ the values of all variables that had previously been passed as
+ command line arguments, been found through running tests, or had
+ otherwise been set.
+ make
and install it. If the
+ library changes, one would just call make
again and
+ it would only re-compile those files that are depend on those
+ sources that have changed. In other words, one will rarely have
+ to deal with the cached variables at all.
+ cmake
+ again, either because one would like to change the configuration
+ parameters or because some configuration file (e.g., one of
+ the CMakeLists.txt
files) have changed. (In fact,
+ if the latter happens to be the case, then just
+ calling make
calls back and runs cmake
+ again automatically.) Either way, if that happens,
+ then cmake
will only run whatever tests are really
+ necessary; values for variables that are already in the cache
+ are not re-evaluated. This means that calling cmake
+ a second time without any arguments at all in a situation like
+ this
+
+
+ mkdir build
+ cd build
+ cmake -DCMAKE_INSTALL_PREFIX=/path/install/dir ../deal.II
+ cmake ../deal.II
+
+ has absolutely no effect: In particular, the second time around
+ it uses the CMAKE_INSTALL_PREFIX
value previously
+ passed, along with all other arguments one may have had on the
+ first invokation. This is different from the way
+ the autoconf/configure
mechanism worked.
+
+ This cache has an important reason: one can modify all sorts of + configuration parameters and thereby interact with the + configuration system is rather powerful (and, possibly, + destructive) ways. For example, the following commands +
+ + mkdir build + cd build + cmake ../deal.II + ccmake ++ First configure a bare-bone setup and then call + the
ccmake
program -- an interactive editor for the
+ cached variables. Similarly,
+ + + mkdir build + cd build + cmake ../deal.II + cmake -D<OPTION>=<VALUE> [...] ../deal.II ++ sets a variable the second time around without destroying all + the configuration that has happened the first time around. Likewise, +
+ + mkdir build + cd build + cmake ../deal.II + cmake -DDEAL_II_WITH_METIS=OFF ../ ++ switches off support for the METIS library that may have been + automatically detected the first time around but that we really + didn't want to link with. + + + +
+ Just like with simple make
, cmake
+ allows to build only selected targets. The difference is that
+ it's not quite so easy any more what the names of these targets
+ are. The most common scenario is that you only want to build
+ debug or optimized libraries. This can be achieved using the
+ following commands in the build directory:
+
+ + make deal_II.g # only debug library + make deal_II # only release (optimized) library + make all # both ++ + +
+ For a complete list of possible targets that allow even + finer-grained control, do +
+ + make help ++ + +
+ It is frequently useful to be able to see what a particular + command does. In that case, use the following: +
+ + make deal_II.g VERBOSE=ON ++ This will show, for every command executed, the exact command + line with which it was invoked, including compiler arguments, + etc. Every command
cmake
executes starts at the
+ build directory (rather than being executed by some recursively
+ invoked makefile) so that the command line can be copied and
+ executed from within the build directory.
+
+
+
+ + The various configuration options of the deal.II library are organized in + three categories: feature, component and build/install configuration. +
+ + +
+ deal.II provides (optional) interfaces to quite a number of external
+ libraries. All of these are represented by cmake
+ variables that are set to ON
if an external package
+ is found and recognized and to OFF
otherwise. By
+ explicitly setting it to off either on the command line or
+ using ccmake
, you can prevent deal.II from using
+ this external package, even if it is found.
+
+ Specifically, the following variables exist (the list may grow + over time, but names are standardized): +
DEAL_II_WITH_ARPACK - Build deal.II with support for ARPACK - DEAL_II_WITH_BLAS - Build deal.II with support for BLAS - DEAL_II_WITH_BOOST - Build deal.II with support for boost. Always activated - DEAL_II_WITH_FUNCTIONPARSER - Build deal.II with support for functionparser - 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_MUMPS - Build deal.II with support for Mumps - DEAL_II_WITH_MPI - Build deal.II with support for mpi - DEAL_II_WITH_NETCDF - Build deal.II with support for netcdf - DEAL_II_WITH_P4EST - Build deal.II with support for p4est - DEAL_II_WITH_PETSC - Build deal.II with support for PETSc - DEAL_II_WITH_SLEPC - Build deal.II with support for SLEPc - DEAL_II_WITH_THREADS - Build deal.II with support for tbb. This will enable thread support in deal.II - DEAL_II_WITH_TRILINOS - Build deal.II with support for trilinos - DEAL_II_WITH_UMFPACK - Build deal.II with support for UMFPACK - DEAL_II_WITH_ZLIB - Build deal.II with support for zlib - - An enabled feature will usually add one ore more dependencies to external - or 'bundled' (i.e. bundled with deal.II and residing under ./bundled/) - libraries. - - - There are some options to determine the behaviour of the dependency - resolution: - - The option DEAL_II_ALLOW_BUNDLED - - - If set to ON external libraries still have precedence. But if there is - no external library the bundled library will be used. - - - If set to OFF bundled 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_BUNDLED_<library> forces - the use of the bundled library. - - The option DEAL_II_FORCE_BUNDLED_(BOOST|FUNCTIONPARSER|THREADS|UMFPACK) - forces the use of the bundled library regardless whether - DEAL_II_ALLOW_BUNDLED is set to OFF or an external library is found. - - REMARKS: - - - To ensure that no bundled library is used at all DEAL_II_ALLOW_BUNDLED, - as well as every DEAL_II_FORCE_BUNDLED_<library> have to be set to OFF. - - - DEAL_II_FORCE_BUNDLED_<library>=ON will _not_ automatically enable the - corresponding DEAL_II_WITH_<feature> toggle. This has to be set - separately. - - - Auto configuration: - - As long as DEAL_II_WITH_<FEATURE> is not set to ON or OFF in the cache it - will be automatically configured. If a toggle DEAL_II_WITH_<FEATURE> is - defined it won't be altered. - This means that the very first configuration run will set all (at that - moment) available features to ON and the rest to OFF. In all subsequent - configuration steps DEAL_II_WITH_<FEATURE> have to be changed by hand.) - - This behaviour can be controlled via the variables: - - - DISABLE_AUTODETECTION=ON: This will disable any autoconfiguration by - setting undefined DEAL_II_WITH_<FEATURE> toggles to OFF: - - - FORCE_AUTODETECTION=ON: This will force the reconfiguration of every - feature by undefining DEAL_II_WITH_<FEATURE> prior to configuration, - effectively overwriting _any_ supplied or cached value. - - - External library locations - ========================== - - External libraries will be searched depending on hints in the following - order: - - 1.) Paths specified via CMAKE_PREFIX_PATH take precedence, e.g. with - - $ cmake -DCMAKE_PREFIX_PATH=~/workspace/local ../deal.II - - libraries from ~/workspace/local will be preferred for dependency - resolution. - - 2.) Hints given by <library>_DIR via command line or environment for - _some_ libraries: - - $ cmake -DP4EST_DIR=~/workspace/p4est-install/ ../deal.II - or - $ export P4EST_DIR=~/workspace/p4est-install/ - $ cmake ../deal.II - where -D<library>_DIR takes precedence over environment. - - Currently, the following variables will be considered: - - METIS_DIR, - MUMPS_DIR (and SCALAPACK_DIR, BLACS_DIR), - P4EST_DIR (and SC_DIR), - PETSC_DIR and PETSC_ARCH (forming ${PETSC_DIR}/${PETSC_ARCH}), - TRILINOS_DIR, - UMFPACK_DIR (and AMD_DIR, SUITESPARSECONFIG_DIR) - - 3.) The system default locations for libraries and includes. - - - Alternatively, cached variables set by the Find<Module> mechanism may be - set, hinted or overwritten directly! - - These variables are usually called <library>_INCLUDE_DIR(|S) and - <library>_(LIBRARY|LIBRARIES) (highly dependend of the actual library...). - - You can get a list via - - $ ccmake ../deal.II (or $ make edit_cache) - - and entering advanced configuration mode by pressing [t]. - Variables that could not be determined are suffixed with -NOTFOUND and - may be set by hand. - - - Component selection - =================== - - The following options control which components of deal.II will be - configured, build and installed: - - DEAL_II_COMPONENT_CONTRIB - Enable configuration and installation of the programs under contrib - This adds a COMPONENT "contrib" 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_DOCUMENTATION: - Enable configuration, build and installation of the documentation. - This adds a COMPONENT "documentation" 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. - - - Build configuration - =================== - - CMAKE_BUILD_TYPE: We support the "Debug", "Release" and "DebugRelease" - build targets. Default is the "DebugRelease" target. - - - Debug will compile a debug library libdeal_II.g.so with a lot of debug - code paths and assertions enabled, as well as a suitable set of debug - compiler flags. - - - Release will build an optimized libdeal_II.so. - - - DebugRelease will build both 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. - - - Option 2: Overwrite the default configuration by setting the following - cached variables: - - CMAKE_CXX_FLAGS - used during all builds - DEAL_II_CXX_FLAGS_DEBUG - additional flags for the debug library - DEAL_II_CXX_FLAGS_RELEASE - additional flags for the release library - - 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: - - $ cmake -DCMAKE_CXX_FLAGS="-Wno-sign-compare" <...> - - - The build can be further controlled by the following variables: - - - BUILD_SHARED_LIBS: If set, deal.II will be linked as a shared library - - - CMAKE_INSTALL_RPATH_USE_LINK_PATH: If set, the deal.II library will be - installed with rpaths set for all libraries outside of the system - search paths - - - 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 - - - The individual target directories can be overwritten by - DEAL_II_CMAKE_MACROS_RELDIR - DEAL_II_DOCUMENTATION_RELDIR - DEAL_II_EXAMPLES_RELDIR - DEAL_II_EXECUTABLE_RELDIR - DEAL_II_INCLUDE_RELDIR - DEAL_II_LIBRARY_RELDIR - DEAL_II_PROJECT_CONFIG_RELDIR - - - - -======================================== -How to use deal.II in your cmake project -======================================== - - - Finding the deal.II library - =========================== - - If DEAL_II_COMPONENT_PROJECT_CONFIG was set, finding the deal.II library - should be no more than - - FIND_PACKAGE(deal.II CONFIG REQUIRED) - - in your CMakeLists.txt file. - - You may have to hint for the location of the deal.IIConfig.cmake file. - Either by directly specifying deal.II_DIR to point to the path were the - deal.IIConfig.cmake files are located: - - $ cmake -Ddeal.II_DIR=/path/to/the/config/file <...> - - Or by specifying a search path via CMAKE_PREFIX_PATH, e.g. - - $ cmake -DCMAKE_PREFIX_PATH=~/workspace/local - - In this case deal.IIConfig.cmake will be searched in - ~/workspace/local/ - ~/workspace/local/lib/cmake/deal.II/ - - - deal.IIConfig.cmake - =================== - - Importing the deal.IIConfig.cmake file via FIND_PACKAGE will set a bunch - of variables and macros; all of the form DEAL_II_*. There is the usual - duplet: - - DEAL_II_INCLUDE_DIRS - DEAL_II_LIBRARIES ++ They all have standard meaning with the exception of + two:
DEAL_II_WITH_BOOST
is always ON
+ since the question is not whether or not to use BOOST but only
+ whether to use a copy of BOOST found on the system or to fall
+ back to the one found in the bundled/
directory of
+ deal.II. Secondly, DEAL_II_WITH_THREADS
decides
+ whether to use threads and if set to on also decides whether we
+ interface to the Threading Building Blocks (TBB) library which
+ we need in that case.
+
+
+
+ If enabled, each of the features above will usually add one ore
+ more dependencies to external or 'bundled' (i.e. bundled with
+ deal.II and residing under bundled/
) libraries.
+
+ There are some options to determine the behavior of the dependency
+ resolution. Specifically, the
+ option DEAL_II_ALLOW_BUNDLED
determines the
+ following question:
+
+ Thus, to ensure that no bundled library is used at all DEAL_II_ALLOW_BUNDLED, + as well as every DEAL_II_FORCE_BUNDLED_<library> have to be set to OFF. + Conversely, DEAL_II_FORCE_BUNDLED_<library>=ON will not automatically enable the + corresponding DEAL_II_WITH_<feature> toggle. This has to be set + separately. +
+ + ++ As long as DEAL_II_WITH_<FEATURE> is not set explicitly to ON or OFF in the cache it + will be automatically configured. If a toggle DEAL_II_WITH_<FEATURE> is + defined it won't be altered. + This means that the very first configuration run will set all + available features to ON and the rest to OFF. In all subsequent + configuration steps DEAL_II_WITH_<FEATURE> have to be + changed by hand, see the first section above. +
+ ++ This behavior can be controlled via several variables: +
+ External libraries will be searched depending on hints in the following + order: + +
+ Paths specified via CMAKE_PREFIX_PATH take precedence, e.g. with +
+ + cmake -DCMAKE_PREFIX_PATH=~/workspace/local ../deal.II ++ libraries from ~/workspace/local will be preferred for dependency + resolution. + + +
+ Hints given by <library>_DIR via command line or environment for + some libraries: +
+ + cmake -DP4EST_DIR=~/workspace/p4est-install/ ../deal.II ++ or +
+ + export P4EST_DIR=~/workspace/p4est-install/ + cmake ../deal.II ++ where -D<library>_DIR takes precedence over environment. + + +
+ Currently, the following variables will be considered: +
+ + METIS_DIR, + MUMPS_DIR (and SCALAPACK_DIR, BLACS_DIR), + P4EST_DIR (and SC_DIR), + PETSC_DIR and PETSC_ARCH (forming ${PETSC_DIR}/${PETSC_ARCH}), + TRILINOS_DIR, + UMFPACK_DIR (and AMD_DIR, SUITESPARSECONFIG_DIR) ++ + +
+ The system default locations for libraries and includes. +
++ Alternatively, cached variables set by the Find<Module> mechanism may be + set, hinted or overwritten directly. + These variables are usually called <library>_INCLUDE_DIR(|S) and + <library>_(LIBRARY|LIBRARIES) (highly dependend of the actual library). + You can get a list via +
+ + ccmake ../deal.II (or $ make edit_cache) ++ and entering advanced configuration mode by pressing [t]. + Variables that could not be determined are suffixed with -NOTFOUND and + may be set by hand. + + + +
+ The following options control which components of deal.II will be + configured, built and installed: + +
+ 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: + +
+ + CMAKE_CXX_FLAGS - used during all builds + DEAL_II_CXX_FLAGS_DEBUG - additional flags for the debug library + DEAL_II_CXX_FLAGS_RELEASE - additional flags for the release library ++ + The content of the cached variables will be preserved and added + to the end of the default compiler flags, hence providing the possibility + for overwriting a flag. E.g.: -Wsign-compare, set by the build system, + can be overwritten by specifying: +
+ + cmake -DCMAKE_CXX_FLAGS="-Wno-sign-compare" <...> ++
+ The build can be further controlled by the following variables: +
+ 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: +
+ + ${CMAKE_INSTALL_PREFIX}/ + common + common/scripts + doc + examples + include + lib ++ +
+ + ${CMAKE_INSTALL_PREFIX}/ + include + lib${LIB_SUFFIX} + /share/doc/deal.II/examples + /share/doc/deal.II/html ++
+ The individual target directories can be overwritten by setting the + following variables: +
+ + DEAL_II_CMAKE_MACROS_RELDIR + DEAL_II_DOCUMENTATION_RELDIR + DEAL_II_EXAMPLES_RELDIR + DEAL_II_EXECUTABLE_RELDIR + DEAL_II_INCLUDE_RELDIR + DEAL_II_LIBRARY_RELDIR + DEAL_II_PROJECT_CONFIG_RELDIR ++ + + +
+ Using deal.II in your own project is particularly simple if your
+ project also uses cmake
. The following subsections
+ describe this process.
+
+ If DEAL_II_COMPONENT_PROJECT_CONFIG was set, finding the deal.II library + should be no more than +
+ + FIND_PACKAGE(deal.II CONFIG REQUIRED) ++ in your CMakeLists.txt file. + You may have to hint for the location of the deal.IIConfig.cmake file. + Either by directly specifying deal.II_DIR to point to the path were the + deal.IIConfig.cmake files are located: +
+ + cmake -Ddeal.II_DIR=/path/to/the/config/file <...> ++ or by specifying a search path via CMAKE_PREFIX_PATH, e.g. +
+ + $ cmake -DCMAKE_PREFIX_PATH=~/workspace/local ++ In this case deal.IIConfig.cmake will be searched for in +
+ + ~/workspace/local/ + ~/workspace/local/lib/cmake/deal.II/ ++ + + +
+ Importing the deal.IIConfig.cmake file via FIND_PACKAGE will set a bunch + of variables and macros; all of the form DEAL_II_*. There is the usual + duplet: +
+ + DEAL_II_INCLUDE_DIRS + DEAL_II_LIBRARIES +(with "debug" and "optimized" keywords. For compatibility there is also DEAL_II_LIBRARIES_DEBUG and DEAL_II_LIBRARIES_RELEASE only specifying the respective set of libraries.) - - Interesting additional variables might be: - - DEAL_II_USER_DEFINITIONS - DEAL_II_USER_DEFINITIONS_DEBUG - DEAL_II_USER_DEFINITIONS_RELEASE - DEAL_II_LINKER_FLAGS - DEAL_II_LINKER_FLAGS_DEBUG - DEAL_II_LINKER_FLAGS_RELEASE - DEAL_II_CXX_FLAGS - DEAL_II_CXX_FLAGS_RELEASE - DEAL_II_CXX_FLAGS_DEBUG - - DEAL_II_TARGET_CONFIG - DEAL_II_TARGET_DEBUG - DEAL_II_TARGET_RELEASE - - - - - Setting up necessary configuration variables - ============================================ - - Usually for actually using deal.II the following configuration steps are - necessary. This can be either done by hand (a), or set up via macros (b). - - - a) Configuration by hand: - - - Set up all include directories for headers: - - INCLUDE_DIRECTORIES( - # The deal.II include directories: - ${DEAL_II_INCLUDE_DIRS} - # External include directories necessary for user programs: - ${DEAL_II_EXTERNAL_INCLUDE_DIRS} - ) - - - deal.II usually ships with an optimized Release and a Debug version - of the library. So it is a good idea to set up CMAKE_BUILD_TYPE - accordingly: - - SET(CMAKE_BUILD_TYPE "Debug" CACHE - "Choose the type of build, options are: Debug, Release" - ) - - A cached variable ensures that we can later switch the build type - by editing the cache: - - $ ccmake <...> or $ make edit_cache - - - Often, it is a good idea to use the same compiler and linker - flags as the deal.II library. - - SET(CMAKE_CXX_FLAGS ${DEAL_II_CXX_FLAGS}) - SET(CMAKE_CXX_FLAGS_RELEASE ${DEAL_II_CXX_FLAGS_RELEASE}) - SET(CMAKE_CXX_FLAGS_DEBUG ${DEAL_II_CXX_FLAGS_DEBUG}) - - (Optionally you can set them up with 'CACHE "..."' to be able - to edit them via ccmake or make edit_cache) - - - _After_ this, specify your project name: - - PROJECT(myProject) - - This ensures that the compiler detection and platform setup that - is issued by calling PROJECT(...) will run after we have set up - our cached variables. This way it is our choice of variables that - will be set and not the one determined in PROJECT(...)will be set - and not the one determined in PROJECT(...) - - - After defining your targets, e.g. - - ADD_EXECUTABLE(step-1 step-1.cc) - - you have to specify to link against deal.II and all external - libraries: - - TARGET_LINK_LIBRARIES(step-1 - ${DEAL_II_LIBRARIES} - ) - - - As well as using some preprocessor definitions: - - SET_TARGET_PROPERTIES(step-1 PROPERTIES - COMPILE_DEFINITIONS - "${DEAL_II_USER_DEFINITIONS}" - COMPILE_DEFINITIONS_DEBUG - "${DEAL_II_USER_DEFINITIONS_DEBUG}" - COMPILE_DEFINITIONS_RELEASE - "${DEAL_II_USER_DEFINITIONS_RELEASE}" - ) - - - Optionally, you can set the link flags to the one used by the - deal.II library: - - SET_TARGET_PROPERTIES(step-1 PROPERTIES - LINK_FLAGS - "${DEAL_II_LINKER_FLAGS}" - LINK_FLAGS_DEBUG - "${DEAL_II_LINKER_FLAGS_DEBUG}" - LINK_FLAGS_RELEASE - "${DEAL_II_LINKER_FLAGS_RELEASE}" - ) - - And this it is. - - - b) Configuration with the help of two convencience macros: - - All the steps explained in (a) can be automatically set with the help - of two convenience macros. This boils down to the following example - code: - - FIND_PACKAGE(deal.II CONFIG REQUIRED) - - DEAL_II_INITIALIZE_CACHED_VARIABLES() - - PROJECT(step-1) - - ADD_EXECUTABLE(step-1 step-1.cc) - DEAL_II_SETUP_TARGET(step-1) - - - c) It is also possible to include deal.II as external target directly - into a cmake project: - - INCLUDE(${DEAL_II_TARGET_CONFIG}) - - After that there is a target ${DEAL_II_TARGET_DEBUG} and - ${DEAL_II_TARGET_RELEASE} available. - - - -=========== -DEVELOPMENT -=========== - - - Fat note regarding platform checks and feature configuration - ============================================================ - - - ============ - - FAT NOTE - - ============ - - - To keep things clean, only the following variables should appended in the - platform checks and feature configuration (beside setting a lot of - DEAL_II_* definitions...): - - All with the following (internal) logic: - - name without _DEBUG or _RELEASE: Used for all targets - - <...>_DEBUG: _additionally_ used for debug targets - - <...>_RELEASE: _additionally_ used for release targets - - - For internal use: - - CMAKE_SHARED_LINKER_FLAGS - DEAL_II_SHARED_LINKER_FLAGS_DEBUG - DEAL_II_SHARED_LINKER_FLAGS_RELEASE - - for setting necessary linker flags for the deal.II library. - - CMAKE_CXX_FLAGS (and CMAKE_C_FLAGS) - DEAL_II_CXX_FLAGS_DEBUG (and DEAL_II_C_FLAGS_DEBUG) - DEAL_II_CXX_FLAGS_RELEASE (and DEAL_II_C_FLAGS_RELEASE) - - 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. - - DEAL_II_DEFINITIONS - DEAL_II_DEFINITIONS_DEBUG - DEAL_II_DEFINITIONS_RELEASE - - For setting necessary preprocessor definitions ("-D<...>") for - the compilation of the deal.II library - - - For internal and external use: - - DEAL_II_EXTERNAL_LIBRARIES - DEAL_II_EXTERNAL_LIBRARIES_DEBUG - DEAL_II_EXTERNAL_LIBRARIES_RELEASE - - Used to keep track of external libraries, the deal.II library - and user programs have to be linked against. - - - For external use: - - DEAL_II_USER_DEFINITIONS - DEAL_II_USER_DEFINITIONS_DEBUG - DEAL_II_USER_DEFINITIONS_RELEASE - - Used to keep track of external preprocessor definitions, - necessary for the compilation of user programs. - - - DEAL_II_USER_INCLUDE_DIRS - + Interesting additional variables might be: +
+ + DEAL_II_USER_DEFINITIONS + DEAL_II_USER_DEFINITIONS_DEBUG + DEAL_II_USER_DEFINITIONS_RELEASE + DEAL_II_LINKER_FLAGS + DEAL_II_LINKER_FLAGS_DEBUG + DEAL_II_LINKER_FLAGS_RELEASE + DEAL_II_CXX_FLAGS + DEAL_II_CXX_FLAGS_RELEASE + DEAL_II_CXX_FLAGS_DEBUG + + DEAL_II_TARGET_CONFIG + DEAL_II_TARGET_DEBUG + DEAL_II_TARGET_RELEASE ++ + + + +
+ Usually for actually using deal.II the following configuration steps are + necessary. This can be either done by hand (a), or set up via macros (b). +
+ + INCLUDE_DIRECTORIES( + # The deal.II include directories: + ${DEAL_II_INCLUDE_DIRS} + # External include directories necessary for user programs: + ${DEAL_II_EXTERNAL_INCLUDE_DIRS} + ) ++ +
+ + SET(CMAKE_BUILD_TYPE "Debug" CACHE + "Choose the type of build, options are: Debug, Release" + ) ++ + A cached variable ensures that we can later switch the build type + by editing the cache: +
+ + ccmake <...> or $ make edit_cache ++ +
+ + SET(CMAKE_CXX_FLAGS ${DEAL_II_CXX_FLAGS}) + SET(CMAKE_CXX_FLAGS_RELEASE ${DEAL_II_CXX_FLAGS_RELEASE}) + SET(CMAKE_CXX_FLAGS_DEBUG ${DEAL_II_CXX_FLAGS_DEBUG}) ++ (Optionally you can set them up with 'CACHE "..."' to be able + to edit them via ccmake or make edit_cache.) + +
+ + PROJECT(myProject) ++ This ensures that the compiler detection and platform setup that + is issued by calling PROJECT(...) will run after we have set up + our cached variables. This way it is our choice of variables that + will be set and not the one determined in PROJECT(...)will be set + and not the one determined in PROJECT(...) + +
+ + ADD_EXECUTABLE(step-1 step-1.cc) ++ you have to specify to link against deal.II and all external + libraries: +
+ + TARGET_LINK_LIBRARIES(step-1 + ${DEAL_II_LIBRARIES} + ) ++ +
+ SET_TARGET_PROPERTIES(step-1 PROPERTIES + COMPILE_DEFINITIONS + "${DEAL_II_USER_DEFINITIONS}" + COMPILE_DEFINITIONS_DEBUG + "${DEAL_II_USER_DEFINITIONS_DEBUG}" + COMPILE_DEFINITIONS_RELEASE + "${DEAL_II_USER_DEFINITIONS_RELEASE}" + ) + ++ +
+ + SET_TARGET_PROPERTIES(step-1 PROPERTIES + LINK_FLAGS + "${DEAL_II_LINKER_FLAGS}" + LINK_FLAGS_DEBUG + "${DEAL_II_LINKER_FLAGS_DEBUG}" + LINK_FLAGS_RELEASE + "${DEAL_II_LINKER_FLAGS_RELEASE}" + ) ++ And this it is. + +
+ + FIND_PACKAGE(deal.II CONFIG REQUIRED) + + DEAL_II_INITIALIZE_CACHED_VARIABLES() + + PROJECT(step-1) + + ADD_EXECUTABLE(step-1 step-1.cc) + DEAL_II_SETUP_TARGET(step-1) ++ + +
+ + INCLUDE(${DEAL_II_TARGET_CONFIG}) ++ After that there is a target ${DEAL_II_TARGET_DEBUG} and + ${DEAL_II_TARGET_RELEASE} available. +
+ To keep things clean, only the following variables should appended in the + platform checks and feature configuration (beside setting a lot of + DEAL_II_* definitions...): +
+ Platform checks reside under cmake/check. + We currently have +
+ + cmake/check/check_for_compiler_bugs.cmake + cmake/check/check_for_compiler_bugs_*.cmake + cmake/check/check_for_compiler_features.cmake + cmake/check/check_for_cxx_features.cmake ++ Useful commands are: +
+ + CHECK_CXX_SOURCE_COMPILES(source variable) + Checks whether it is possible to compile _and_ link the code snipet + <source>. If succesful, variable is set to 1. + + CHECK_CXX_SOURCE_RUNS(source variable) + variable is set to 1 if <source> coulde be succesfully compiled and + linked and the resulting program ran and exited wihtout error. + + CHECK_CXX_COMPILER_BUG(source variable) + Inverts the logic of CHECK_CXX_SOURCE_COMPILES(), i.e. variable is + set to 1 if it was not possible to compile and link <source>. + + CHECK_INCLUDE_FILE_CXX(header variable) + Check whether it is possible to compile and link a dummy program + including <header>. + + CHECK_FUNCTION_EXISTS(function variable) + Check for the existence of a function prototype with name + <function>. (Don't forget to specify the link libraries, see + below.) + + CHECK_CXX_COMPILER_FLAG(flag variable) + Sets the variable to 1 if the compiler understands the flag. ++ +
+ + PUSH_TEST_FLAG("-Werror") + CHECK_CXX_SOURCE_COMPILES(...) + POP_TEST_FLAG() ++ +
+ + SET(CMAKE_REQUIRED_LIBRARIES <a list of libraries> + CHECK_CXX_SOURCE_COMPILES(...) + SET(CMAKE_REQUIRED_LIBRARIES) ++
+ General notes: +
+ For a feature <feature> the following the following toggles, variables and + macros should be defined + (Note: <FEATURE> means all caps, <feature> means all lowercase): +
+ + FEATURE_<FEATURE>_DEPENDS (variable, optional) + a variable which contains an optional list of other features + this feature depends on (and which have to be enbled for this feature + to work.) The features must be given with the full option toggle: + DEAL_II_WITH_[...] + + FEATURE_<FEATURE>_FIND_EXTERNAL(var) (macro, mandatory) + which should set var to TRUE if all dependencies for the feature are + fulfilled. In this case all necessary variables for + FEATURE_<FEATURE>_CONFIGURE_EXTERNAL must be set. Otherwise + var should remain unset. + This macro must not give an error (SEND_ERROR or FATAL_ERROR). + + FEATURE_<FEATURE>_CONFIGURE_EXTERNAL(var) (macro, mandatory) + which should setup all necessary configuration for the feature with + external dependencies. var set to TRUE indicates success, + otherwise this script should issue a FATAL_ERROR. + + FEATURE_<FEATURE>_CONFIGURE_BUNDLED(var) (macro, optional) + which should setup all necessary configuration for the feature with + bundled source dependencies. var set to TRUE indicates success. + + FEATURE_<FEATURE>_CUSTOM_ERROR_MESSAGE() (variable, optional) + which should either be set to TRUE if FEATURE_<FEATURE>_ERROR_MESSAGE + is set up, or be undefined. + + FEATURE_<FEATURE>_ERROR_MESSAGE() (macro, optional) + which should print a meaningful error message (with FATAL_ERROR) for + the case that no external library was found (and bundled is not + allowed to be used.) If not defined, a suitable default error message + will be printed. ++ +
+ + DEAL_II_FORCE_BUNDLED_<FEATURE> (bool, optional) + If <feature> can be set up by bundled libraries, this + configuration option must be present to force the use of the bundled + dependencies + + FEATURE_<FEATURE>_HAVE_BUNDLED (variable, optional) + which should either be set to TRUE if all necessary libraries of the + features comes bundled with deal.II and hence can be supported + without external dependencies, or unset. ++ +