From b103ff0aa77a7082872b2873a97c7d085c62f5f5 Mon Sep 17 00:00:00 2001 From: maier Date: Thu, 7 Mar 2013 10:40:35 +0000 Subject: [PATCH] CMake documentation overhaul, part 1 git-svn-id: https://svn.dealii.org/branches/branch_cmake@28780 0785d39b-7218-0410-832d-ea1e28bc413d --- deal.II/doc/development/cmake-internals.html | 288 ++++++++++++++++ deal.II/doc/development/cmake.html | 338 ++++--------------- deal.II/doc/development/toc.html | 9 +- 3 files changed, 353 insertions(+), 282 deletions(-) create mode 100644 deal.II/doc/development/cmake-internals.html diff --git a/deal.II/doc/development/cmake-internals.html b/deal.II/doc/development/cmake-internals.html new file mode 100644 index 0000000000..48681a9a5e --- /dev/null +++ b/deal.II/doc/development/cmake-internals.html @@ -0,0 +1,288 @@ + + + + The deal.II Readme + + + + + + + + + + + +

Details on the deal.II CMake build system

+ +

+ This page provides details about deal.II CMake build system. +

+ +

+ + + + +
Table of contents
+ +
+

+ + +

Developing the deal.II CMake system

+ +

+ To keep things clean, only the following variables should be + appended in the platform checks and feature configuration (beside + setting a lot of DEAL_II_* definitions...): +

+

+ + + +

Writing platform checks

+ +

+ Platform checks reside under cmake/checks. We currently have +

+
+	cmake/check/check_for_compiler_bugs.cmake
+	cmake/check/check_for_compiler_features.cmake
+	cmake/check/check_for_cxx_features.cmake
+      
+

+

+ Some Notes: +

+

+ +

+ General notes: +

+

+ + + +

Writing feature tests

+ +

+ TODO: This section is a bit outdated, update it! +

+

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

+

+ + +

Advanced setup

+ + A sample configuration file for preloading the CMake cache with +
+
+    $ cmake -C Config.sample <...>
+    
+ can be found here. + This sample configuration covers all options mentioned in this + documentation as well as some advanced aspects in feature + configuration. + +
+ +
+ The deal.II Group + $Date$ +
+ + diff --git a/deal.II/doc/development/cmake.html b/deal.II/doc/development/cmake.html index 6f30a55946..3a74740548 100644 --- a/deal.II/doc/development/cmake.html +++ b/deal.II/doc/development/cmake.html @@ -33,14 +33,15 @@ system
  • Compiling only certain parts -
  • Fine tuning the configuration system +
  • Configuration options
  • How to use deal.II in your CMake project -
  • Developing the deal.II CMake system - -
  • Advanced setup +
  • Initial cache file and advanced options @@ -193,24 +189,24 @@ library. Rather, make install will still want to have both libraries up to date and will therefore invoke make all automatically. To restrict builds in such a way that only one library - will be installed, see this section. + will be installed, see this section.

    - -

    Fine tuning the configuration system

    + +

    Configuration options

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

    - +

    Feature configuration

    @@ -250,10 +246,8 @@

  • DEAL_II_WITH_BOOST is always ON since BOOST is a mandatory build time dependency. -
  • 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. +
  • DEAL_II_WITH_THREADS enables threading support + with the help of the Threading Building Blocks (TBB) library.

    @@ -303,7 +297,7 @@ - +

    Autoconfiguration

    @@ -338,7 +332,7 @@

    - +

    External library locations

    @@ -393,7 +387,7 @@

  • - The system default locations for libraries and includes. + The default system locations for libraries and includes.

    @@ -401,10 +395,8 @@

    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 + hinted or overwritten directly (variable names are highly + dependend on the actual library). You can get a list via

     
         make edit_cache
    @@ -414,8 +406,27 @@
           -NOTFOUND and may be set by hand.
         

    + +

    Manual override

    + It is possible to override the CMake find mechanism for external + libraries manually. This is e.g. useful if a non standard lapack/blas + installation should be used (and cannot be found by the + FindLapack.cmake module shipped with CMake) + In this case you can by hand +
     
    -    
    +    cmake -DLAPACK_FOUND=true \
    +          -DLAPACK_LIBRARIES="library;and;complete;link;interface" \
    +          -DLAPACK_LINKER_FLAGS="" <...>
    +      
    + You can set these values on the command line, with ccmake or by + providing an initial cache file, see + advanced setup section. + Possible manual overrides are explained in detail in the + in the Config.sample file. + + +

    Component selection

    @@ -474,36 +485,32 @@

    - +

    Build configuration

    - As explained in this section above, one can - limit make to building only a subset of the usual - libraries. However, this does not restrict the set of things that need - to be built so that make install can install them. Rather, - the cmake variable - CMAKE_BUILD_TYPE controls the type of build. - We support the Debug, Release - and DebugRelease build targets. Default is the - DebugRelease target. + The cmake variable CMAKE_BUILD_TYPE + controls the type of build. We support Debug, + Release and DebugRelease mode. Default + is DebugRelease.

    • Passing cmake the flag -DCMAKE_BUILD_TYPE=Debug will produce makefiles - that require only compiling and installing the debug library - libdeal_II.g.so + that compile and install only the debug library + libdeal_II.g.so.
    • Passing cmake the flag -DCMAKE_BUILD_TYPE=Release result in only - compiling and installing libdeal_II.so. + compiling and installing the optimized library libdeal_II.so.
    • Passing cmake the flag -DCMAKE_BUILD_TYPE=DebugRelease will build and install both libraries.
    - For more information on what these targets represent, see the general - discussion here. + + For more information, see the general discussion here.

    @@ -519,7 +526,7 @@ may still pull in necessary compiler flags.

  • - Overwrite the default configuration by setting the following + Override the default configuration by setting the following cached variables:
     
    @@ -530,7 +537,7 @@
     
     	  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.:
    +	  hence providing the possibility for overriding a flag. E.g.:
     	  -Wsign-compare, set by the build system, can be
     	  overwritten by specifying:
     	  
    @@ -561,7 +568,7 @@
         

    - +

    Installation

    @@ -850,237 +857,8 @@

    - -

    Developing the deal.II CMake system

    - -

    - To keep things clean, only the following variables should be - appended in the platform checks and feature configuration (beside - setting a lot of DEAL_II_* definitions...): -

      -
    • - The general (internal) logic for variables applies: -
        -
      • A variable name without _DEBUG or - _RELEASE: Used for all targets -
      • <...>_DEBUG: additionally used for debug targets -
      • <...>_RELEASE: additionally used for release targets -
      - -
    • - For internal use, for setting necessary linker flags for the deal.II library: -
        -
      • CMAKE_SHARED_LINKER_FLAGS -
      • DEAL_II_SHARED_LINKER_FLAGS_DEBUG -
      • DEAL_II_SHARED_LINKER_FLAGS_RELEASE -
      - -
    • - For internal use, for setting necessary compiler flags, e.g. - -std=c++11 (if available): -
        -
      • CMAKE_CXX_FLAGS -
      • DEAL_II_CXX_FLAGS_DEBUG -
      • DEAL_II_CXX_FLAGS_RELEASE -
      - -
    • - For internal use, for setting necessary include dirs for the compilation of the - deal.II library: -
        -
      • INCLUDE_DIRECTORIES(...) -
      - -
    • - For internal use, for setting necessary preprocessor definitions - (-D<...>) for the compilation of the - deal.II library: -
        -
      • DEAL_II_DEFINITIONS -
      • DEAL_II_DEFINITIONS_DEBUG -
      • DEAL_II_DEFINITIONS_RELEASE -
      - -
    • - For internal and external use, used to keep track of external - libraries, the deal.II library and user - programs have to be linked against: -
        -
      • DEAL_II_EXTERNAL_LIBRARIES -
      • DEAL_II_EXTERNAL_LIBRARIES_DEBUG -
      • DEAL_II_EXTERNAL_LIBRARIES_RELEASE -
      - -
    • - For external use, used to keep track of external preprocessor - definitions, necessary for the compilation of user programs: -
        -
      • DEAL_II_USER_DEFINITIONS -
      • DEAL_II_USER_DEFINITIONS_DEBUG -
      • DEAL_II_USER_DEFINITIONS_RELEASE -
      - -
    • - Used to keep track of external include dirs, necessary for the - compilation of user programs: -
        -
      • DEAL_II_USER_INCLUDE_DIRS -
      -
    -

    - - - -

    Writing platform checks

    - -

    - Platform checks reside under cmake/checks. We currently have -

    -
    -	cmake/check/check_for_compiler_bugs.cmake
    -	cmake/check/check_for_compiler_features.cmake
    -	cmake/check/check_for_cxx_features.cmake
    -      
    -

    -

    - Some Notes: -

      -
    • There are a number of readily available platform check macros: -
      -
      -    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 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_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.
      -	  
      - -
    • Necessary compiler flags can easily set in the string variable - CMAKE_REQUIRED_FLAGS. There are two small macros - that do this job nicely: -
      -
      -    PUSH_TEST_FLAG("-Werror")
      -    CHECK_CXX_SOURCE_COMPILES(...)
      -    POP_TEST_FLAG()
      -	  
      - -
    • 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: -
      -
      -    SET(CMAKE_REQUIRED_LIBRARIES <a list of libraries>
      -    CHECK_CXX_SOURCE_COMPILES(...)
      -    SET(CMAKE_REQUIRED_LIBRARIES)
      -	  
      -
    -

    - -

    - General notes: -

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

    - - - -

    Writing feature tests

    - -

    - TODO: This section is a bit outdated, update it! -

    -

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

      - -
    • - A file - cmake/configure/configure_<feature>.cmake - defining how to configure <feature>: -
      -    FEATURE_${feature}_DEPENDS    (a variable)
      -      - 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)  (a macro)
      -      - 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.
      -        If not defined, FIND_PACKAGE(${feature}) is called.
      -
      -    FEATURE_<FEATURE>_CONFIGURE_EXTERNAL()  (a macro)
      -      - which should setup all necessary configuration for the feature with
      -        external dependencies. If something goes wrong this macro must
      -        issue a FATAL_ERROR.
      -
      -    FEATURE_<FEATURE>_CONFIGURE_BUNDLED()  (a macro)
      -      - which should setup all necessary configuration for the feature with
      -        bundled source dependencies. If something goes wrong this macro must
      -        issue a FATAL_ERROR.
      -
      -    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.
      -	  
      - -
    • - In bundled/CMakeLists.txt: -
      -
      -    DEAL_II_FORCE_BUNDLED_<FEATURE> (a boolean)
      -      - If <feature> can be set up by bundled libraries, this
      -        configuration option must be present to force use of bundled
      -        dependencies
      -
      -    FEATURE_<FEATURE>_HAVE_BUNDLED  (a variable)
      -      - 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.
      -	  
      - - Setup of compilation and installation if - FEATURE_<FEATURE>_BUNDLED_CONFIGURED is set. -
    -

    - -

    Advanced setup

    +

    Initial cache file and advanced options

    A sample configuration file for preloading the CMake cache with
    diff --git a/deal.II/doc/development/toc.html b/deal.II/doc/development/toc.html
    index 99b2656d20..1e3de347b8 100644
    --- a/deal.II/doc/development/toc.html
    +++ b/deal.II/doc/development/toc.html
    @@ -38,8 +38,8 @@
     
         
  • deal.II CMake documentation: - This page provides extensive information about usage and - development of the deal.II CMake build system. + This page provides extensive information about usage + of the deal.II CMake build system.

  • Example CMakeLists.txt: An overview of how to write the CMakeLists.txt input @@ -48,6 +48,11 @@ the deal.II library.

    +
  • + deal.II CMake internals: + This page provides details about deal.II CMake + build system. +

  • Writing documentation: To document the library and our application programs, we use -- 2.39.5