From 081b017bdb1766ef7673bf811b0d28429b4d70a6 Mon Sep 17 00:00:00 2001 From: bangerth Date: Fri, 2 Nov 2012 21:15:52 +0000 Subject: [PATCH] html-ize. git-svn-id: https://svn.dealii.org/branches/branch_cmake@27321 0785d39b-7218-0410-832d-ea1e28bc413d --- deal.II/doc/cmake.html | 1645 +++++++++++++++++++++------------------- 1 file changed, 864 insertions(+), 781 deletions(-) diff --git a/deal.II/doc/cmake.html b/deal.II/doc/cmake.html index 8a64fcf241..51c9177007 100644 --- a/deal.II/doc/cmake.html +++ b/deal.II/doc/cmake.html @@ -16,808 +16,891 @@

Details on the deal.II configuration and build system

- - - - ================================================== - - The cmake build system for the deal.II project - - ================================================== - - Author: Matthias Maier , 2012 - - - - - WARNING: A BIT OUT OF DATE, ATM - - - - -================= -TABLE OF CONTENTS -================= - - Introduction - - The philosophy - - Quick start - - Useful bits - - Configuration - - Feature configuration - - External library locations - - Component selection - - Build configuration - - Installation - - How to use deal.II in your cmake project - - Finding the deal.II library - - Setting up necessary configuration variables - - Development - - Fat note regarding platform checks and feature configuration - - Writing platform checks - - Writing features - - - - -============ -INTRODUCTION -============ - - - The philosophy - ============== - - I need a new keyboard, my CAPS-KEY is stuck because of writing all - this cmake script... - - - Quick start - =========== - - * Make a build directory, configure, compile and install: - - $ mkdir build - $ cd build - $ cmake -DCMAKE_INSTALL_PREFIX=/path/install/dir ../ - $ make install - - * Check out the examples, shipped with deal.II: - - $ cd /path/to/install/dir/examples - - - Useful bits - =========== - - * All cached variables can be either set via - - ( $ cd build ) - $ ccmake - - or at the prompt via: - - ( $ cd build ) - $ cmake -D<OPTION>=<VALUE> [...] path/to/source/tree - - * Configure with autodetection, afterwards disable a feature: - - ( $ cd build ) - $ cmake ../ - $ cmake -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 - - * The build system cmake generates allows fine grained control. It is - e.g. possible to only compile a single file: - - $ cd source/dofs - $ make obj_dofs.inst - [ 0%] Building CXX object scripts/CMakeFiles/expand_instantiations.dir/expand_instantiations.cc.o - Linking CXX executable expand_instantiations - [ 0%] Built target expand_instantiations - [ 33%] Generating block_info.inst - [ 33%] Generating dof_accessor.inst - [ 33%] Generating dof_handler.inst - [ 66%] Generating dof_handler_policy.inst - [ 66%] Generating dof_objects.inst - [ 66%] Generating dof_renumbering.inst - [100%] Generating dof_tools.inst - [100%] Built target obj_dofs.inst - $ make dof_handler.o - Building CXX object source/dofs/CMakeFiles/obj_dofs.dir/dof_handler.cc.o - - For a list of valid targets of a given folder just type - - $ make help - - - - -============= -CONFIGURATION -============= - - - The various configuration options of the deal.II library are organized in - three categories: Feature, Component and build/install configuration. - - - Feature configuration - ===================== - - deal.II provides (optional) interfaces to quite a number of external - libraries: +

+ 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 cmake and building with it. +

+ + +

Operating the configuration system

+ +

+ When configuring deal.II by + running 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. +

+ +

+ Normally, one will then simply build the library in this + directory by calling 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. +

+ +

+ That said, it is occasionally helpful to run 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. +

+ + +

Compiling and building only certain parts

+ +

+ 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. +

+ + +

Fine tuning the configuration system

+ +

+ The various configuration options of the deal.II library are organized in + three categories: feature, component and build/install configuration. +

+ + +

Feature 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. +

+ + +

Autoconfiguration

+ +

+ 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 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, built and installed: + +

+

+ + +

Build configuration

+ +

+ 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: + +

    +
  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. + +
  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 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: +

+

+ + +

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: +

+

+ +

+ 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
+      
+

+ + +

How to use deal.II in your cmake project

+ +

+ Using deal.II in your own project is particularly simple if your + project also uses cmake. The following subsections + describe this process. +

+ + +

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 for 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
+      
(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
+      
+

+ + + +

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). +

    +
  1. 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. + +
    + +
  2. Configuration with the help of two convencience macros: + All the steps explained in the first option above can be automatically dpme 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)
    +	  
    + + +
  3. 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

+ +

+ 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...): +

+

+ + +

Writing platform checks

+ +

+ 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: + +

+ +

+ General notes: +

+

+ + +

Writing feature tests

+ +

+ For a feature <feature> the following the following toggles, variables and + macros should be defined + (Note: <FEATURE> means all caps, <feature> means all lowercase): +

+ +


-- 2.39.5