From: maier Date: Thu, 7 Mar 2013 10:40:35 +0000 (+0000) Subject: CMake documentation overhaul, part 1 X-Git-Url: https://gitweb.dealii.org/cgi-bin/gitweb.cgi?a=commitdiff_plain;h=b103ff0aa77a7082872b2873a97c7d085c62f5f5;p=dealii-svn.git CMake documentation overhaul, part 1 git-svn-id: https://svn.dealii.org/branches/branch_cmake@28780 0785d39b-7218-0410-832d-ea1e28bc413d --- 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