<li><a href="#tuningbuild">Build configuration</a>
<li><a href="#tuninginstall">Installation</a>
</ul>
- <li><a href="#ext">How to use deal.II in your cmake project</a>
+ <li><a href="#ext">How to use deal.II in your CMake project</a>
<ul>
<li><a href="#extfinding">Finding the deal.II library</a>
<li><a href="#extcmake">deal.IIConfig.cmake</a>
<li><a href="#extsetup">Setting up necessary configuration variables</a>
</ul>
- <li><a href="#dev">Developing the <acronym>deal.II</acronym> <code>cmake</code> system</a>
+ <li><a href="#dev">Developing the <acronym>deal.II</acronym> CMake system</a>
<ul>
<li><a href="#devplatform">Writing platform checks</a>
<li><a href="#devfeature">Writing feature tests</a>
<h3>Fine tuning the configuration system</h3>
<p>
- The various configuration options of the deal.II library are
- organized in three categories: <a href="#tuningfeature">feature</a>,
- <a href="#tuningcomp">component</a>, and
- <a href="#tuningbuild">build</a>/<a href="#tuninginstall">install</a>
+ The various configuration options of the
+ <acronym>deal.II</acronym> library are organized in three
+ categories: <a href="#tuningfeature">feature</a>,
+ <a href="#tuningcomp">component</a>, and <a
+ href="#tuningbuild">build</a>/<a href="#tuninginstall">install</a>
configuration.
</p>
<h4>Feature configuration</h4>
<p>
- deal.II provides (optional) interfaces to quite a number of external
- libraries. All of these are represented by <code>cmake</code>
- variables that are set to <code>ON</code> if an external package
- is found and recognized and to <code>OFF</code> otherwise. By
- explicitly setting it to off either on the command line or
- using <code>ccmake</code>, you can prevent deal.II from using
- this external package, even if it is found.
+ <acronym>deal.II</acronym> provides (optional) interfaces to quite
+ a number of external libraries. All of these are represented by
+ <code>cmake</code> variables that are set to <code>ON</code> if
+ an external package is found or to <code>OFF</code> otherwise. By
+ explicitly setting it to off either on the command line or using
+ <code>ccmake</code>, you can prevent <acronym>deal.II</acronym>
+ from using this external package, even if it is found.
</p>
<p>
DEAL_II_WITH_ZLIB
</pre>
They all have standard meaning with the exception of
- two: <code>DEAL_II_WITH_BOOST</code> is always <code>ON</code>
- 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 <code>bundled/</code> directory of
- deal.II. Secondly, <code>DEAL_II_WITH_THREADS</code> 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.
+ two:
+ <ul>
+ <li> <code>DEAL_II_WITH_BOOST</code> is always <code>ON</code>
+ since BOOST is a mandatory build time dependency.
+
+ <li> <code>DEAL_II_WITH_THREADS</code> decides whether to use
+ threads and if set to <code>ON</code> also decides whether
+ we interface to the Threading Building Blocks (TBB) library
+ which we need in that case.
+ </ul>
</p>
<p>
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 <code>bundled/</code>) libraries.
+ <acronym>deal.II</acronym> and residing under <code>bundled/</code>)
+ libraries.
</p>
<p>
There are some options to determine the behavior of the dependency
resolution. Specifically, the
option <code>DEAL_II_ALLOW_BUNDLED</code> determines the
- following question:
+ following:
<ul>
- <li> If set to ON external libraries still have precedence. But if there is
- no external library the bundled library will be used.
-
- <li> If set to OFF bundled libraries will not be used and the dependency
- resolution will fail if there is no external library
-
- <li>DEAL_II_FORCE_BUNDLED_<library> forces the use of
- the bundled library regardless whether DEAL_II_ALLOW_BUNDLED
- is set to OFF or an external library is found. This applies
- to the options
- DEAL_II_FORCE_BUNDLED_(BOOST|FUNCTIONPARSER|THREADS|UMFPACK).
+ <li> If set to <code>ON</code> external libraries still have
+ precedence. But if there is no external library the bundled
+ library will be used.
+
+ <li> If set to <code>OFF</code> bundled libraries will not be
+ used and the dependency resolution will fail if there is no
+ external library
+
+ <li><code>DEAL_II_FORCE_BUNDLED_<library></code> forces
+ the use of the bundled library regardless whether
+ <code>DEAL_II_ALLOW_BUNDLED</code> is set to <code>OFF</code>
+ or an external library is found. This applies to the options
+ <code>DEAL_II_FORCE_BUNDLED_(BOOST|FUNCTIONPARSER|THREADS|UMFPACK)</code>.
</ul>
</p>
<p>
- 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.
+ Thus, to ensure that no bundled library is used at all
+ <code>DEAL_II_ALLOW_BUNDLED</code>, as well as every
+ <code>DEAL_II_FORCE_BUNDLED_<library></code>
+ have to be set to <code>OFF</code>. Conversely,
+ </code>DEAL_II_FORCE_BUNDLED_<library>=ON</code>
+ will not automatically enable the corresponding
+ <code>DEAL_II_WITH_<feature></code> toggle. This has to be
+ set separately.
</p>
<h4> Autoconfiguration </h4>
<p>
- As long as DEAL_II_WITH_<FEATURE> is not explicitly 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
- 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.
+ As long as <code>DEAL_II_WITH_<FEATURE></code> is
+ not explicitly set to <code>ON</code> or <code>OFF</code>
+ in the cache it will be automatically configured. If a toggle
+ <code>DEAL_II_WITH_<FEATURE></code> is defined it won't
+ be altered.
+ This means that the very first configuration run will set
+ all available features to <code>ON</code> and the rest
+ to <code>OFF</code>. In all subsequent configuration steps
+ <code>DEAL_II_WITH_<FEATURE></code> has to be changed by hand,
+ see the previous section.
</p>
<p>
This behavior can be controlled via several variables:
<ul>
<li>
- DISABLE_AUTODETECTION=ON: This will disable any autoconfiguration by
- setting undefined DEAL_II_WITH_<FEATURE> toggles to
- OFF.
+ <code>DEAL_II_ALLOW_AUTODETECTION=OFF</code>: This will
+ disable any autoconfiguration by setting undefined
+ <code>DEAL_II_WITH_<FEATURE></code> toggles to
+ <code>OFF</code>.
<li>
- FORCE_AUTODETECTION=ON: This will force the reconfiguration of every
- feature by undefining DEAL_II_WITH_<FEATURE> prior to configuration,
- effectively overwriting <b>any</b> supplied or cached value.
+ <code>DEAL_II_FORCE_AUTODETECTION=ON</code>: This will
+ force the reconfiguration of every feature by undefining
+ <code>DEAL_II_WITH_<FEATURE></code> prior to
+ configuration, effectively overwriting <i>any</i> supplied or
+ cached value.
</ul>
</p>
<p>
External libraries will be searched depending on hints in the following
order:
-
<ol>
<li>
<p>
- Paths specified via CMAKE_PREFIX_PATH take precedence, e.g. with
+ Paths specified via <code>CMAKE_PREFIX_PATH</code> take
+ precedence, e.g. with
<pre>
- cmake -DCMAKE_PREFIX_PATH=~/workspace/local ../deal.II
+ cmake -DCMAKE_PREFIX_PATH=~/workspace/local ../deal.II
</pre>
- libraries from ~/workspace/local will be preferred for dependency
- resolution.
+ libraries from <code>~/workspace/local</code> will be
+ preferred for dependency resolution.
</p>
<li>
<p>
- Hints given by <library>_DIR via command line or environment for
- <i>some</i> libraries:
- <pre>
+ Hints given by <code><library>_DIR</code> via command
+ line or environment for <i>some</i> libraries:
+ <pre>
- cmake -DP4EST_DIR=~/workspace/p4est-install/ ../deal.II
+ cmake -DP4EST_DIR=~/workspace/p4est-install/ ../deal.II
</pre>
or
<pre>
- export P4EST_DIR=~/workspace/p4est-install/
- cmake ../deal.II
+ export P4EST_DIR=~/workspace/p4est-install/
+ cmake ../deal.II
</pre>
- where -D<library>_DIR takes precedence over environment.
+ where <code>-D<library>_DIR</code> takes precedence
+ over environment.
</p>
<p>
Currently, the following variables will be considered:
<pre>
- HDF5_DIR
- METIS_DIR,
- MUMPS_DIR (and SCALAPACK_DIR, BLACS_DIR),
- P4EST_DIR (and SC_DIR),
- PETSC_DIR and PETSC_ARCH (forming ${PETSC_DIR}/${PETSC_ARCH}),
- SLEPC_DIR and SLEPC_ARCH (forming ${SLEPC_DIR}/${SLEPC_ARCH}),
- TRILINOS_DIR,
- UMFPACK_DIR (and AMD_DIR, SUITESPARSECONFIG_DIR)
+ ARPACK_DIR,
+ HDF5_DIR,
+ METIS_DIR,
+ MUMPS_DIR (and SCALAPACK_DIR, BLACS_DIR),
+ P4EST_DIR (and SC_DIR),
+ PETSC_DIR and PETSC_ARCH (forming ${PETSC_DIR}/${PETSC_ARCH}),
+ SLEPC_DIR and SLEPC_ARCH (forming ${SLEPC_DIR}/${SLEPC_ARCH}),
+ TRILINOS_DIR,
+ UMFPACK_DIR (and AMD_DIR, SUITESPARSECONFIG_DIR)
</pre>
</p>
</p>
<p>
- 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
+ Alternatively, cached variables set by the
+ <code>Find<Module></code> mechanism may be set,
+ hinted or overwritten directly. These variables are usually
+ called <code><library>_INCLUDE_DIR(|S)</code> and
+ <code><library>_(LIBRARY|LIBRARIES)</code> (highly dependend
+ of the actual library). You can get a list via
<pre>
- make edit_cache
+ make edit_cache
</pre>
and entering advanced configuration mode by pressing [t].
- Variables that could not be determined are suffixed with -NOTFOUND and
- may be set by hand.
+ Variables that could not be determined are suffixed with
+ <code>-NOTFOUND</code> and may be set by hand.
</p>
<h4> Component selection </h4>
<p>
- The following options control which components of deal.II will be
- configured, built and installed:
+ The following options control which components of
+ <acronym>deal.II</acronym> will be configured, built and installed:
<ul>
<li>
- DEAL_II_COMPONENT_CONTRIB:
- Enable configuration and installation of the programs under contrib
- This adds a COMPONENT "contrib" to the build system.
+ <code>DEAL_II_COMPONENT_CONTRIB</code>:
+ Enable configuration and installation of programs
+ in <code>contrib/</code>. This adds a component
+ <code>contrib</code> to the build system.
<li>
- 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.
+ <code>DEAL_II_COMPONENT_COMPAT_FILES</code>:
+ Enable installation of legacy files and tools for
+ compatibility with the old build system This adds a component
+ <code>compat_files</code> to the build system.
<li>
- DEAL_II_COMPONENT_DOCUMENTATION:
- Enable configuration, build and installation of the documentation.
- This adds a COMPONENT "documentation" to the build system.
+ <code>DEAL_II_COMPONENT_DOCUMENTATION</code>:
+ Enable configuration, build and installation of the
+ documentation. This adds a component <code>documentation</code>
+ to the build system.
<li>
- DEAL_II_COMPONENT_EXAMPLES:
+ <code>DEAL_II_COMPONENT_EXAMPLES</code>:
Enable configuration and installation of the example steps.
- This adds a COMPONENT "examples" to the build system.
+ This adds a component <code>examples</code> to the build system.
</ul>
</p>
<h4> Build configuration </h4>
<p>
- 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:
+ deal.II will configure sensible default <code>CFLAGS</code> and
+ <code>CXXFLAGS</code> depending on platform, compiler and build
+ target. There are two options to override this behaviour:
<ol>
<li>
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.
+ <code>DEAL_II_SETUP_DEFAULT_COMPILER_FLAGS</code> to
+ <code>OFF</code>. Beware of the fact that certain features
+ may still pull in necessary compiler flags.
<li>
Overwrite the default configuration by setting the following
cached variables:
<pre>
- 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
+ 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
</pre>
- The content of the cached variables will be preserved and added
- <i>to the end</i> 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:
+ The content of the cached variables will be preserved
+ and added <i>to the end</i> of the default compiler flags,
+ hence providing the possibility for overwriting a flag. E.g.:
+ <code>-Wsign-compare</code>, set by the build system, can be
+ overwritten by specifying:
<pre>
- cmake -DCMAKE_CXX_FLAGS="-Wno-sign-compare" <...>
+ cmake -DCMAKE_CXX_FLAGS="-Wno-sign-compare" <...>
</pre>
</ol>
</p>
The build can be further controlled by the following variables:
<ul>
<li>
- BUILD_SHARED_LIBS: If set, deal.II will be linked as a shared library
+ <code>BUILD_SHARED_LIBS</code>: If set (default),
+ <acronym>deal.II</acronym> will be linked as a shared library
<li>
- 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
+ <code>CMAKE_INSTALL_RPATH_USE_LINK_PATH</code>: If set
+ (default), the <acronym>deal.II</acronym> library will be
+ installed with rpaths set for all libraries outside of the
+ system search paths
</ul>
</p>
<h4> Installation </h4>
<p>
- 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:
+ <code>CMAKE_INSTALL_PREFIX</code> determines the location,
+ where the <acronym>deal.II</acronym> library will be
+ installed to. Please note that depending on whether
+ <code>DEAL_II_COMPONENT_COMPAT_FILES</code> is set, there will be
+ different directory structures:
<ul>
<li>
- With DEAL_II_COMPONENT_COMPAT_FILES=ON:
+ With <code>DEAL_II_COMPONENT_COMPAT_FILES=ON</code>:
<pre>
- ${CMAKE_INSTALL_PREFIX}/
- common
- common/scripts
- doc
- examples
- include
- lib
+ ${CMAKE_INSTALL_PREFIX}/
+ bin
+ cmake/macros
+ common
+ common/scripts
+ doc
+ examples
+ include
+ lib
+ lib/cmake/deal.II
</pre>
<li>
- With DEAL_II_COMPONENT_COMPAT_FILES=OFF:
+ With <code>DEAL_II_COMPONENT_COMPAT_FILES=OFF</code>:
<pre>
- ${CMAKE_INSTALL_PREFIX}/
- include
- lib${LIB_SUFFIX}
- share/doc/deal.II/examples
- share/doc/deal.II/html
+ ${CMAKE_INSTALL_PREFIX}/
+ bin
+ include
+ lib${LIB_SUFFIX}
+ lib${LIB_SUFFIX}/cmake/deal.II
+ share/deal.II/
+ share/deal.II/cmake/macros
+ share/doc/deal.II/examples
+ share/doc/deal.II/html
</pre>
</ul>
</p>
following variables:
<pre>
- 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
+ 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
</pre>
</p>
<a name="ext"></a>
- <h3> How to use deal.II in your cmake project </h3>
+ <h3> How to use deal.II in your CMake project </h3>
<p>
- Using deal.II in your own project is particularly simple if your
- project also uses <code>cmake</code>. The following subsections
- describe this process.
+ Using <acronym>deal.II</acronym> in your own project is particularly
+ simple if your project also uses <code>cmake</code>. The following
+ subsections describe this process.
</p>
<h4> Finding the deal.II library </h4>
<p>
- Finding the deal.II library should be no more than
+ Finding the <acronym>deal.II</acronym> library should be no more than
<pre>
- FIND_PACKAGE(deal.II CONFIG REQUIRED)
+ FIND_PACKAGE(deal.II REQUIRED)
</pre>
- 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:
+ in your CMakeLists.txt file. You may have to hint for the location
+ of the <code>deal.IIConfig.cmake</code> file. Either by directly
+ specifying <code>deal.II_DIR</code> to point to the path were the
+ <code>deal.IIConfig.cmake</code> file is located:
<pre>
- cmake -Ddeal.II_DIR=/path/to/the/config/file <...>
+ cmake -Ddeal.II_DIR=/path/to/the/config/file <...>
</pre>
- or by specifying a search path via CMAKE_PREFIX_PATH, e.g.
+ or by specifying a search path via <code>CMAKE_PREFIX_PATH</code>,
+ e.g.
<pre>
- $ cmake -DCMAKE_PREFIX_PATH=~/workspace/local
+ cmake -DCMAKE_PREFIX_PATH=~/workspace/local
</pre>
- In this case deal.IIConfig.cmake will be searched for in
+ In this case <code>deal.IIConfig.cmake</code> will be searched
+ for in
<pre>
- ~/workspace/local/
- ~/workspace/local/lib/cmake/deal.II/
+ ~/workspace/local/
+ ~/workspace/local/lib/cmake/deal.II/
</pre>
</p>
<h4> deal.IIConfig.cmake </h4>
<p>
- 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:
+ Importing the deal.IIConfig.cmake file via <code>FIND_PACKAGE</code>
+ will set a bunch of variables and macros; all of the form
+ <code>DEAL_II_*</code>. There is the usual duplet:
<pre>
- DEAL_II_INCLUDE_DIRS
- DEAL_II_LIBRARIES
+ DEAL_II_INCLUDE_DIRS
+ DEAL_II_LIBRARIES
</pre>
- (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.)
+ (with <code>debug</code> and <code>optimized</code> keywords. For
+ compatibility there is also <code>DEAL_II_LIBRARIES_DEBUG</code>
+ and <code>DEAL_II_LIBRARIES_RELEASE</code> only specifying the
+ respective set of libraries.)
+ </p>
+
+ <p>
Interesting additional variables might be:
<pre>
- 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
+ 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
</pre>
</p>
<h4> Setting up necessary configuration variables </h4>
<p>
- Usually for actually using deal.II the following configuration steps are
- necessary. This can be either done by hand (1.), or set up via macros
- (2.).
+ For actually using <acronym>deal.II</acronym> in your CMake
+ project some configuration steps are necessary. These can be
+ either set via <a href="#extsetupmacro">macros</a> or by <a
+ href="#extsetuphand">hand</a>:
<ol>
- <li> Configuration by hand:
+ <a name="extsetupmacro"></a><li> <b>Configuration with the help of
+ two convencience macros:</b>
+ <p>
+ <code>deal.IIConfig.cmake</code> includes some convenience macros
+ to automatically setup all necessary configuration. A fully
+ functional, minimal example for the step-1 tutorial program is:
+ <pre>
+
+ FIND_PACKAGE(deal.II REQUIRED)
+
+ DEAL_II_INITIALIZE_CACHED_VARIABLES()
+
+ PROJECT(step-1)
+
+ ADD_EXECUTABLE(step-1 step-1.cc)
+ DEAL_II_SETUP_TARGET(step-1)
+ </pre>
+ </p>
+
+
+ <a name="extsetuphand"></a><li> <b>Configuration by hand:</b>
<ul>
- <li> Set up all include directories for headers:
+ <li> Set up all include directories for header files:
<pre>
- INCLUDE_DIRECTORIES(
- # The deal.II include directories:
- ${DEAL_II_INCLUDE_DIRS}
- # External include directories necessary for user programs:
- ${DEAL_II_EXTERNAL_INCLUDE_DIRS}
- )
+ INCLUDE_DIRECTORIES(${DEAL_II_INCLUDE_DIRS})
</pre>
<li>
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:
+ of the library. So it is a good idea to set up
+ <code>CMAKE_BUILD_TYPE</code> accordingly:
<pre>
- SET(CMAKE_BUILD_TYPE "Debug" CACHE
- "Choose the type of build, options are: Debug, Release"
- )
+ SET(CMAKE_BUILD_TYPE "Debug" CACHE
+ "Choose the type of build, options are: Debug, Release"
+ )
</pre>
A cached variable ensures that we can later switch the build type
by editing the cache:
<pre>
- ccmake <...> or $ make edit_cache
+ make edit_cache
</pre>
<li> Often, it is a good idea to use the same compiler and linker
flags as the deal.II library.
<pre>
- 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})
+ 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})
</pre>
- (Optionally you can set them up with 'CACHE "..."' to be able
- to edit them via ccmake or make edit_cache.)
+ (Optionally you can set up the variables with the
+ <code>CACHE</code> to be able to edit them via ccmake or
+ make edit_cache.)
<li>
<i>After</i> this, specify your project name:
<pre>
- PROJECT(myProject)
+ PROJECT(myProject)
</pre>
- 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(...)
+ This ensures that the compiler detection and platform setup
+ that is issued by calling <code>PROJECT(...)</code> 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 default
+ values determined by the <code>PROJECT(...)</code> call.
<li>
After defining your targets, e.g.
<pre>
- ADD_EXECUTABLE(step-1 step-1.cc)
+ ADD_EXECUTABLE(step-1 step-1.cc)
</pre>
you have to specify to link against deal.II and all external
libraries:
<pre>
- TARGET_LINK_LIBRARIES(step-1
- ${DEAL_II_LIBRARIES}
- )
+ TARGET_LINK_LIBRARIES(step-1 ${DEAL_II_LIBRARIES})
</pre>
- <li> As well as using some preprocessor definitions:
+ <li> as well as using some preprocessor definitions:
<pre>
- 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
+ COMPILE_DEFINITIONS
+ "${DEAL_II_USER_DEFINITIONS}"
+ COMPILE_DEFINITIONS_DEBUG
+ "${DEAL_II_USER_DEFINITIONS_DEBUG}"
+ COMPILE_DEFINITIONS_RELEASE
+ "${DEAL_II_USER_DEFINITIONS_RELEASE}"
+ )
</pre>
<li> Optionally, you can set the link flags to the one used by the
deal.II library:
<pre>
- 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}"
- )
+ 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}"
+ )
</pre>
And this it is.
</ul>
- <li> Configuration with the help of two convencience macros:
- All the steps explained in the first option above can be automatically done with the help
- of two convenience macros. This boils down to the following example
- code:
- <pre>
-
- 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)
- </pre>
-
-
- <li> It is also possible to include deal.II as an external target directly
- into a cmake project:
- <pre>
-
- INCLUDE(${DEAL_II_TARGET_CONFIG})
- </pre>
- After that there is a target ${DEAL_II_TARGET_DEBUG} and
- ${DEAL_II_TARGET_RELEASE} available.
+ <li>
+ <b>Advanced setup:</b>
+
+ <p>
+ For an advanced setup in a big CMake project
+ <code><a href="#extcmake">deal.IIConfig.cmake</a></code>
+ provides information about the <acronym>deal.II</acronym>
+ installation with traditional variables, see
+ <a href="#extcmake">here</a>, as well as <i>external CMake
+ targets</i> with link interface for direct inclusion:
+ <pre>
+
+ INCLUDE(${DEAL_II_TARGET_CONFIG})
+ </pre>
+ After that there is a target
+ <code>${DEAL_II_TARGET_DEBUG}</code> and
+ <code>${DEAL_II_TARGET_RELEASE}</code> available:
+ <pre>
+
+ ADD_EXECUTABLE(step-1
+ step-1.cc
+ ${DEAL_II_TARGET_DEBUG}
+ )
+ </pre>
+ <b>TODO: Check and simplify</b>
+ </p>
</ol>
</p>
<a name="dev"></a>
- <h3> Developing the <acronym>deal.II</acronym> <code>cmake</code>system </h3>
+ <h3> Developing the <acronym>deal.II</acronym> CMake system </h3>
<p>
- 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...):
+ To keep things clean, only the following variables should be
+ appended in the platform checks and feature configuration (beside
+ setting a lot of <code>DEAL_II_*</code> definitions...):
<ul>
<li>
- All with the following (internal) logic:
+ The general (internal) logic for variables applies:
<ul>
- <li>name without _DEBUG or _RELEASE: Used for all targets
- <li> <...>_DEBUG: _additionally_ used for debug targets
- <li> <...>_RELEASE: _additionally_ used for release targets
+ <li>A variable name without <code>_DEBUG</code> or
+ <code>_RELEASE</code>: Used for all targets
+ <li> <code><...>_DEBUG</code>: <i>additionally</i> used for debug targets
+ <li> <code><...>_RELEASE</code>: <i>additionally</i> used for release targets
</ul>
<li>
For internal use, for setting necessary linker flags for the deal.II library:
<ul>
- <li> CMAKE_SHARED_LINKER_FLAGS
- <li> DEAL_II_SHARED_LINKER_FLAGS_DEBUG
- <li> DEAL_II_SHARED_LINKER_FLAGS_RELEASE
+ <li> <code>CMAKE_SHARED_LINKER_FLAGS</code>
+ <li> <code>DEAL_II_SHARED_LINKER_FLAGS_DEBUG</code>
+ <li> <code>DEAL_II_SHARED_LINKER_FLAGS_RELEASE</code>
</ul>
<li>
- For internal use, for setting necessary compiler flags, e.g. -std=c++11 (if
- available)"
+ For internal use, for setting necessary compiler flags, e.g.
+ <code>-std=c++11</code> (if available):
<ul>
- <li> CMAKE_CXX_FLAGS (and CMAKE_C_FLAGS)
- <li> DEAL_II_CXX_FLAGS_DEBUG (and DEAL_II_C_FLAGS_DEBUG)
- <li> DEAL_II_CXX_FLAGS_RELEASE (and DEAL_II_C_FLAGS_RELEASE)
+ <li> <code>CMAKE_CXX_FLAGS</code> (and <code>CMAKE_C_FLAGS</code>)
+ <li> <code>DEAL_II_CXX_FLAGS_DEBUG</code> (and
+ <code>DEAL_II_C_FLAGS_DEBUG</code>)
+ <li> <code>DEAL_II_CXX_FLAGS_RELEASE</code> (and
+ <code>DEAL_II_C_FLAGS_RELEASE</code>)
</ul>
<li>
For internal use, for setting necessary include dirs for the compilation of the
- deal.II library:
+ <acronym>deal.II</acronym> library:
<ul>
- <li>
- INCLUDE_DIRECTORIES(...)
+ <li> <code>INCLUDE_DIRECTORIES(...)</code>
</ul>
<li>
- For internal use, for setting necessary preprocessor definitions ("-D<...>") for
- the compilation of the deal.II library:
+ For internal use, for setting necessary preprocessor definitions
+ (<code>-D<...></code>) for the compilation of the
+ deal.II library:
<ul>
- <li> DEAL_II_DEFINITIONS
- <li> DEAL_II_DEFINITIONS_DEBUG
- <li> DEAL_II_DEFINITIONS_RELEASE
+ <li> <code>DEAL_II_DEFINITIONS</code>
+ <li> <code>DEAL_II_DEFINITIONS_DEBUG</code>
+ <li> <code>DEAL_II_DEFINITIONS_RELEASE</code>
</ul>
<li>
- For internal and external use (used to keep track of external libraries, the deal.II library
- and user programs have to be linked against):
+ For internal and external use, used to keep track of external
+ libraries, the <acronym>deal.II</acronym> library and user
+ programs have to be linked against:
<ul>
- <li> DEAL_II_EXTERNAL_LIBRARIES
- <li> DEAL_II_EXTERNAL_LIBRARIES_DEBUG
- <li> DEAL_II_EXTERNAL_LIBRARIES_RELEASE
+ <li> <code>DEAL_II_EXTERNAL_LIBRARIES</code>
+ <li> <code>DEAL_II_EXTERNAL_LIBRARIES_DEBUG</code>
+ <li> <code>DEAL_II_EXTERNAL_LIBRARIES_RELEASE</code>
</ul>
<li>
- For external use (used to keep track of external preprocessor definitions,
- necessary for the compilation of user programs):
+ For external use, used to keep track of external preprocessor
+ definitions, necessary for the compilation of user programs:
<ul>
- <li> DEAL_II_USER_DEFINITIONS
- <li> DEAL_II_USER_DEFINITIONS_DEBUG
- <li> DEAL_II_USER_DEFINITIONS_RELEASE
+ <li> <code>DEAL_II_USER_DEFINITIONS</code>
+ <li> <code>DEAL_II_USER_DEFINITIONS_DEBUG</code>
+ <li> <code>DEAL_II_USER_DEFINITIONS_RELEASE</code>
</ul>
<li>
Used to keep track of external include dirs, necessary for the
compilation of user programs:
<ul>
- <li>
- DEAL_II_USER_INCLUDE_DIRS
+ <li> <code>DEAL_II_USER_INCLUDE_DIRS</code>
</ul>
</ul>
</p>
<h4> Writing platform checks </h4>
<p>
- Platform checks reside under cmake/check.
- We currently have
+ Platform checks reside under <code>cmake/checks</code>. We currently have
<pre>
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
</pre>
- Useful commands are:
+ </p>
+ <p>
+ <b>Some Notes:</b>
<ul>
<li> There are a number of readily available platform check macros:
<pre>
- 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_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_SOURCE_RUNS(source variable)
+ - variable is set to 1 if <source> coulde be succesfully compiled and
+ linked and the resulting program ran and exited without 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_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_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_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.
+ CHECK_CXX_COMPILER_FLAG(flag variable)
+ - Sets the variable to 1 if the compiler understands the flag.
</pre>
<li> Necessary compiler flags can easily set in the string variable
- CMAKE_REQUIRED_FLAGS. There are two small macros that do this job
- nicely:
+ <code>CMAKE_REQUIRED_FLAGS</code>. There are two small macros
+ that do this job nicely:
<pre>
- PUSH_TEST_FLAG("-Werror")
- CHECK_CXX_SOURCE_COMPILES(...)
- POP_TEST_FLAG()
+ PUSH_TEST_FLAG("-Werror")
+ CHECK_CXX_SOURCE_COMPILES(...)
+ POP_TEST_FLAG()
</pre>
<li> Libraries necessary for linkage can be set in the list variable
- CMAKE_REQUIRED_LIBRARIES. It is best two hard set this variable to a
- specific value and later on cleaning it, instead of appending/removing:
+ <code>CMAKE_REQUIRED_LIBRARIES</code>. It is best two hard set
+ this variable to a specific value and later on cleaning it,
+ instead of appending/removing:
<pre>
- SET(CMAKE_REQUIRED_LIBRARIES <a list of libraries>
- CHECK_CXX_SOURCE_COMPILES(...)
- SET(CMAKE_REQUIRED_LIBRARIES)
+ SET(CMAKE_REQUIRED_LIBRARIES <a list of libraries>
+ CHECK_CXX_SOURCE_COMPILES(...)
+ SET(CMAKE_REQUIRED_LIBRARIES)
</pre>
</ul>
</p>
<p>
- General notes:
+ <b>General notes:</b>
<ul>
<li> A platform check should have a prominent comment explaining what
it does and why it is there, as well as a stating the author and the
year.
- <li> Definition toggles in include/deal.II/base/config.h.in should have
- a prominent comment explaining it and should be grouped by file
- exporting the definition
+ <li> Definition toggles in
+ <code>include/deal.II/base/config.h.in</code> should have a
+ prominent comment explaining it and should be grouped by file
+ exporting the definition
</ul>
</p>
<h4> Writing feature tests </h4>
<p>
- For a feature <feature> the following the following toggles, variables and
- macros should be defined
- (Note: <FEATURE> means all caps, <feature> means all lowercase):
+ For a feature <code><feature></code> the following
+ the following toggles, variables and macros should be
+ defined (Note: <code><FEATURE></code> means all caps,
+ <code><feature></code> means all lowercase):
<ul>
<li>
- A file cmake/configure/configure_<feature>.cmake defining how to
- configure <feature>:
+ A file
+ <code>cmake/configure/configure_<feature>.cmake</code>
+ defining how to configure <code><feature></code>:
<pre>
- 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.
+ 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.
</pre>
<li>
- In bundled/CMakeLists.txt:
+ In <code>bundled/CMakeLists.txt</code>:
<pre>
- 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
+ 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.
+ 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.
</pre>
- <li> Setup of compilation and installation if
- FEATURE_<FEATURE>_BUNDLED_CONFIGURED is set.
+ Setup of compilation and installation if
+ <code>FEATURE_<FEATURE>_BUNDLED_CONFIGURED</code> is set.
</ul>
-
</p>
<hr>