From 111e370b5a3a02339ce7110fc7daa723de2e5466 Mon Sep 17 00:00:00 2001 From: Guido Kanschat Date: Wed, 28 Aug 2013 04:43:09 +0000 Subject: [PATCH] improve html git-svn-id: https://svn.dealii.org/trunk@30513 0785d39b-7218-0410-832d-ea1e28bc413d --- deal.II/doc/development/cmake-internals.html | 523 +++++++++--------- deal.II/doc/development/cmake.html | 86 ++- deal.II/doc/development/cmakelists.html | 329 ++++++----- .../development/writing-documentation.html | 4 +- deal.II/doc/documentation.html | 408 +++++++------- deal.II/doc/readme.html | 61 +- 6 files changed, 720 insertions(+), 691 deletions(-) diff --git a/deal.II/doc/development/cmake-internals.html b/deal.II/doc/development/cmake-internals.html index 903af06bfa..fbfdbab628 100644 --- a/deal.II/doc/development/cmake-internals.html +++ b/deal.II/doc/development/cmake-internals.html @@ -11,157 +11,155 @@ - - - -

Build system internals

- -

- This page provides details about the CMake build system. Files - processed by the top level CMakeLists.txt script are - listed in the TOC in chronological order. -

- -

- - - - -
Table of contents
-
-
Coding convention -
-
Configuration: -
-
./CMakeLists.txt and - ./cmake/setup_*.cmake -
./cmake/checks/check_*.cmake -
./cmake/modules/Find*.cmake -
./cmake/configure/configure_*.cmake -
Global variables controlling the build process -
-
Target definition and installation -
-
./include/deal.II/base/config.h.in -
./source/CMakeLists.txt -
./cmake/config/CMakeLists.txt -
-
-

Table of contents
- - Coding convention - - Configuration: - - `./CMakeLists.txt` and - `./cmake/setup_.cmake` - `./cmake/checks/check_.cmake` - `./cmake/modules/Find.cmake` - `./cmake/configure/configure_.cmake` - Global variables controlling the build process - - Target definition and installation - - `./include/deal.II/base/config.h.in` - `./source/CMakeLists.txt` - `./cmake/config/CMakeLists.txt` - -

- - -

Coding convention

- Coding conventions are always a matter of choice. Nevertheless, the - following rules should be considered: -

- Statements and keywords are written in all caps. -
- Indenting is done by two spaces; the usual indenting rules apply. -
- The ELSE(), ENDIF(), - ENDFOREACH(), etc. statements shall not repeat the - corresponding condition in IF(), - FOREACH(), etc. -
- To emphasize a comment it may be enclosed by a leading and - trailing empty comment line. -

- An example: -

-
-    FOREACH(_build ${DEAL_II_BUILD_TYPES})
-      #
-      # Set an appropriate keyword depending on target and build type:
-      #
-      IF(NOT "${CMAKE_BUILD_TYPE}" STREQUAL "DebugRelease")
-        SET(_keyword "general")
-      ELSE()
-        IF(_build MATCHES DEBUG)
-          SET(_keyword "debug")
-        ELSE()
-          SET(_keyword "optimized")
-        ENDIF()
-      ENDIF()
-    ENDFOREACH()
-

- Line break is at 78 characters and should be obeyed whenever - reasonable. -
- Long statements should be broken into several lines at reasonable - places. Additional lines for a statement are indented by 2 - spaces. -
- Multiline statements must end with the closing bracket at a - single line: -

-
-    LIST(APPEND CONFIG_LIBRARIES
-      ${_keyword}
-      ${CONFIG_LIBRARIES_${_build}}
-      )
-
-    SET_TARGET_PROPERTIES(${DEAL_II_BASE_NAME}${DEAL_II_${build}_SUFFIX}
-      PROPERTIES
-      VERSION ${VERSION}
-      SOVERSION ${VERSION}
-      LINK_FLAGS "${DEAL_II_LINKER_FLAGS_${build}}"
-      COMPILE_DEFINITIONS "${DEAL_II_DEFINITIONS};${DEAL_II_DEFINITIONS_${build}}"
-      COMPILE_FLAGS "${DEAL_II_CXX_FLAGS_${build}}"
-      )
-

- CMake operates almost always with variables in global state. To guard - against accidental overwrite of variables the following naming - conventions must be followed at all times: -

- Global (configuration) variables are written in all caps. When - introducing a new one, ensure that the name isn't already used - somewhere else. Unrelated global variables must never be - overwritten. -
- Global variables can be prefixed by DEAL_II_. - (Global variables defined by CMake are usually prefixed by - CMAKE_.) -
- Local variables should always be named in all lowercase with a - leading "_". Local variables cannot be assumed to remain valid. - The may get overwritten at any time. -

- - - -

`./CMakeLists.txt` and `./cmake/setup_*.cmake`

- -

- The very first configuration steps after some initial setup in - ./CMakeLists.txt takes place in some - ./cmake/setup_*.cmake files: -

setup_cached_variables.cmake: - This sets up all cached variables prior to the call to - PROJECT(deal.II). For details see the comment at the - top. Furthermore, some bookkeeping for compiler and linker flags - takes place, see the section - about compile flags. -
setup_deal_ii.cmake: - This file is included immediately after the call to - PROJECT(deal.II) and will set up all magic - numbers such as names, definitions, relative and absolute - paths used in the build system. Most of the definitions are - guarded with the help of the SET_IF_EMPTY macro so - that it is possible to override the values from the command line. -

setup_compiler_flags.cmake - sets up a suitable set of default compile flag for a known - compiler by including the appropriate - setup_compiler_flags_*.cmake file. When adding new - flags or compiler support, please respect the following note -

+
+Build system internals
+
+
+  This page provides details about the CMake build system. Files
+  processed by the top level CMakeLists.txt script are
+  listed in the TOC in chronological order.
+
+
+
+  
+    Coding convention
+    Configuration
+      
+	./CMakeLists.txt and
+	    ./cmake/setup_*.cmake
+	./cmake/checks/check_*.cmake
+        ./cmake/modules/Find*.cmake
+	./cmake/configure/configure_*.cmake
+	Global variables controlling the build process
+      
+    
+    Target definition and installation
+      
+	./include/deal.II/base/config.h.in
+        ./source/CMakeLists.txt
+        ./cmake/config/CMakeLists.txt
+      
+    
+
+
+
+ Coding convention 
+
+  Coding conventions are always a matter of choice. Nevertheless, the
+  following rules should be considered:
+  

+    
+      Statements and keywords are written in all caps.
+    

+      Indenting is done by two spaces; the usual indenting rules apply.
+    

+      The ELSE(), ENDIF(),
+      ENDFOREACH(), etc. statements shall not repeat the
+      corresponding condition in IF(),
+      FOREACH(), etc.
+    

+      To emphasize a comment it may be enclosed by a leading and
+      trailing empty comment line.
+  
+  An example:
++FOREACH(_build ${DEAL_II_BUILD_TYPES})
+#
+# Set an appropriate keyword depending on target and build type:
+#
+  IF(NOT "${CMAKE_BUILD_TYPE}" STREQUAL "DebugRelease")
+    SET(_keyword "general")
+  ELSE()
+    IF(_build MATCHES DEBUG)
+      SET(_keyword "debug")
+    ELSE()
+      SET(_keyword "optimized")
+    ENDIF()
+  ENDIF()
+ENDFOREACH()
+
+
+
+  
+    Line break is at 78 characters and should be obeyed whenever
+    reasonable.
+  

+    Long statements should be broken into several lines at reasonable
+    places. Additional lines for a statement are indented by 2
+    spaces.
+  

+    Multiline statements must end with the closing bracket at a
+    single line:
+
++LIST(APPEND CONFIG_LIBRARIES
+  ${_keyword}
+  ${CONFIG_LIBRARIES_${_build}}
+)
+
+SET_TARGET_PROPERTIES(${DEAL_II_BASE_NAME}${DEAL_II_${build}_SUFFIX}
+  PROPERTIES
+  VERSION ${VERSION}
+  SOVERSION ${VERSION}
+  LINK_FLAGS "${DEAL_II_LINKER_FLAGS_${build}}"
+  COMPILE_DEFINITIONS "${DEAL_II_DEFINITIONS};${DEAL_II_DEFINITIONS_${build}}"
+  COMPILE_FLAGS "${DEAL_II_CXX_FLAGS_${build}}"
+)
+
+
+
+  CMake operates almost always with variables in global state. To
+  guard against accidental overwrite of variables the following naming
+  conventions must be followed at all times:
+
+
+
+  
+    Global (configuration) variables are written in all caps. When
+    introducing a new one, ensure that the name isn't already used
+    somewhere else. Unrelated global variables must never be
+    overwritten.
+  

+    Global variables can be prefixed by DEAL_II_.
+    (Global variables defined by CMake are usually prefixed by
+    CMAKE_.)
+  

+    Local variables should always be named in all lowercase with a
+    leading "_". Local variables cannot be assumed to remain valid.
+    The may get overwritten at any time.
+
+
+
+Configuration
+
+
+ ./CMakeLists.txt and ./cmake/setup_*.cmake 
+
+
+  The very first configuration steps after some initial setup in
+  ./CMakeLists.txt takes place in some
+  ./cmake/setup_*.cmake files:
+  

+     setup_cached_variables.cmake:
+      This sets up all cached variables prior to the call to
+      PROJECT(deal.II). For details see the comment at the
+      top. Furthermore, some bookkeeping for compiler and linker flags
+      takes place, see the section
+        about compile flags.
+    
 setup_deal_ii.cmake:
+      This file is included immediately after the call to
+      PROJECT(deal.II) and will set up all magic
+        numbers such as names, definitions, relative and absolute
+      paths used in the build system. Most of the definitions are
+      guarded with the help of the SET_IF_EMPTY macro so
+      that it is possible to override the values from the command line.
+    
 setup_compiler_flags.cmake
+      sets up a suitable set of default compile flag for a known
+      compiler by including the appropriate
+      setup_compiler_flags_*.cmake file. When adding new
+      flags or compiler support, please respect the following note
+
+ 
     #
     # (./cmake/setup_compiler_flags.cmake)
@@ -208,20 +206,21 @@
     #   ./cmake/checks/check_01_system_features.cmake
     #   ./cmake/checks/check_02_compiler_bugs.cmake
     #
-          
-      
-    
+

- -

`./cmake/checks/check_*.cmake`

+ +

`./cmake/checks/check_*.cmake`

- The next step in the configuration process is to include all - checks residing under ./cmake/checks. Currently - there are: -

+
+  The next step in the configuration process is to include all
+  checks residing under ./cmake/checks. Currently
+  there are:
 
+
+    
     ./cmake/checks/check_01_compiler_features.cmake
       - Search for support for compiler dependent features such as stack
         trace support, demangler support, etc.
@@ -240,24 +239,27 @@
 
     ./cmake/checks/check_02_compiler_bugs.cmake
       - Check for compiler bugs
-      
-      
-        
-          A check usually consists of a call to one of the macros below
-          that will set up a global variable. Please stick to the naming
-          convention HAVE_<..>, resp.
-          DEAL_II_(HAVE|USE)_<..>. It is forbidden to
-          use a variable name starting with
-          DEAL_II_WITH_<..> because this prefix is
-          exclusively reserved for the feature mechanism described
-          below. For some tests it might be necessary to manipulate global variables.
-        

-          A platform check should have a prominent comment explaining what
-	  it does and why it is there, and should state author and year.
-        

-          There are a number of readily available platform check macros:
-	 +
+
+
+
+  
+    A check usually consists of a call to one of the macros below
+    that will set up a global variable. Please stick to the naming
+    convention HAVE_<..>, resp.
+    DEAL_II_(HAVE|USE)_<..>. It is forbidden to
+      use a variable name starting with
+      DEAL_II_WITH_<..> because this prefix is
+      exclusively reserved for the feature mechanism described
+      below. For some tests it might be necessary to manipulate
+    global variables.
+  

+    A platform check should have a prominent comment explaining what
+    it does and why it is there, and should state author and year.
+  

+    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 snippet
@@ -291,65 +293,67 @@
 
     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:
-	  +
+
+  
 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()
-	  
+

Necessary include directories and libraries necessary for - linkage can be set in the list variables - CMAKE_REQUIRED_INCLUDES and - CMAKE_REQUIRED_LIBRARIES. It is best to append these - lists and later on reset CMAKE_REQUIRED_* (including - CMAKE_REQUIRED_FLAGS) to their default values: -

+   Necessary include directories and libraries necessary for
+    linkage can be set in the list variables
+    CMAKE_REQUIRED_INCLUDES and
+    CMAKE_REQUIRED_LIBRARIES. It is best to append these
+    lists and later on reset CMAKE_REQUIRED_* (including
+    CMAKE_REQUIRED_FLAGS) to their default values:
+    
+ 
     LIST(APPEND CMAKE_REQUIRED_INCLUDES <a list of includes>)
     LIST(APPEND CMAKE_REQUIRED_LIBRARIES <a list of libraries>)
     CHECK_CXX_SOURCE_COMPILES(...)
     RESET_CMAKE_REQUIRED()
-	  
-      
-    
-
-
-
-    
-     ./cmake/modules/Find*.cmake 
-
-    
-      These are find modules for the configure_*.cmake files
-      and the CONFIGURE_FEATURE macro as will explained later.
-      It is crucial that a find module behaves correctly. Therefore, the
-      following rules are mandatory:
-      

-        
-          The sole purpose of a find module is to find an external
-          library (no deal.II specific dependency checking, no
-          compatibility checking).
-        

-          It should do so by appropriate FIND_LIBRARY and
-          FIND_PATH calls. The results of this calls should be the
-          only cached variables.
-        

-          FIND_PACKAGE_HANDLE_STANDARD_ARGS should be used for
-          setting FEATURE_FOUND as this already respects the
-          QUIET and REQUIRED keywords.
-        

-          A WARNING, SEND_ERROR or
-          FATAL_ERROR must be avoided (the only exception is
-          the REQUIRED keyword).
-        

-          If successful, the following uncached variables might be set:
-          -
+
+
+
+
+
+ ./cmake/modules/Find*.cmake 
+
+
+  These are find modules for the configure_*.cmake files
+  and the CONFIGURE_FEATURE macro as will explained later.
+  It is crucial that a find module behaves correctly. Therefore, the
+  following rules are mandatory:
+  

+    
+      The sole purpose of a find module is to find an external
+      library (no deal.II specific dependency checking, no
+      compatibility checking).
+    

+      It should do so by appropriate FIND_LIBRARY and
+      FIND_PATH calls. The results of this calls should be the
+      only cached variables.
+    

+      FIND_PACKAGE_HANDLE_STANDARD_ARGS should be used for
+      setting FEATURE_FOUND as this already respects the
+      QUIET and REQUIRED keywords.
+    

+      A WARNING, SEND_ERROR or
+      FATAL_ERROR must be avoided (the only exception is
+      the REQUIRED keyword).
+    

+      If successful, the following uncached variables might be set:
+
++	
     FEATURE_FOUND
     FEATURE_LIBRARIES
     FEATURE_INCLUDE_DIRS
@@ -359,41 +363,43 @@
     FEATURE_VERSION_MAJOR
     FEATURE_VERSION_MINOR
     FEATURE_VERSION_SUBMINOR
-          
-          There are obviously valid exceptions from this rule, though.
-        

-          Only "local" variables "_<all lowercase>" or
-          "global" variables prefixed by FEATURE_ may be
-          altered. Do not set DEAL_II_* or CMAKE_*
-          variables directly!
-        

-          A hint with FEATURE_DIR can be set up for
-          convenience. It is best to start the Find module by
-          -
-    SET_IF_EMPTY(FEATURE_DIR "$ENV{FEATURE_DIR}")
-          
-          and use FEATURE_DIR as a hint. If the external
-          library could be found, hide it via
-          MARK_AS_ADVANCED, if the external library could not
-          be found, set a cache value:
-          -
-    SET(FEATURE_DIR "" CACHE PATH "An optional hint to a FEATURE directory")
-          
-      
+

+There are obviously valid exceptions from this rule, though. +

+ Only "local" variables "_<all lowercase>" or + "global" variables prefixed by FEATURE_ may be + altered. Do not set DEAL_II_* or CMAKE_* + variables directly! +

+ A hint with FEATURE_DIR can be set up for + convenience. It is best to start the Find module by +

 
-    
-     ./cmake/configure/configure_*.cmake 
+    SET_IF_EMPTY(FEATURE_DIR "$ENV{FEATURE_DIR}")
+

+ +and use FEATURE_DIR as a hint. If the external +library could be found, hide it via +MARK_AS_ADVANCED, if the external library could not +be found, set a cache value: +

+  
+    SET(FEATURE_DIR "" CACHE PATH "An optional hint to a FEATURE directory")
+

+ -

- The final step in the configuration phase is the setup of features - (which refer to external or bundled libraries - deal.II can optionally interface with.) -

+ +

`./cmake/configure/configure_*.cmake`

+ +

+ The final step in the configuration phase is the setup of features + (which refer to external or bundled libraries + deal.II can optionally interface with.) + +

At bare minimum configure_<feature>.cmake @@ -574,7 +580,8 @@

- + +

Target definition and installation

`./include/deal.II/base/config.h.in`

diff --git a/deal.II/doc/development/cmake.html b/deal.II/doc/development/cmake.html index 8139fdc110..2683cc1d7e 100644 --- a/deal.II/doc/development/cmake.html +++ b/deal.II/doc/development/cmake.html @@ -24,38 +24,34 @@ deal.II CMake build system.

- - - - -
Table of contents
-
-
Operating cmake -
-
Manipulating the cache -
ccmake and special build targets -
Shortcuts -
-
Configuration options -
-
Feature configuration -
Autoconfiguration -
External library locations -
Manual override -
Component selection -
Build configuration -
Selecting a compiler -
Installation -
-
Initial cache file and advanced options -
Compiling only certain parts -
-
-

Table of contents
- - Operating cmake - - Manipulating the cache - `ccmake` and special build targets - Shortcuts - - Configuration options - - Feature configuration - Autoconfiguration - External library locations - Manual override - Component selection - Build configuration - Selecting a compiler - Installation - - Initial cache file and advanced options - Compiling only certain parts - -

- +

Operating cmake +
+
Configuration options +
+
Initial cache file and advanced options
Compiling only certain parts

+ -

Operating cmake

When configuring deal.II by @@ -129,7 +125,7 @@

Manipulating the cache

A cached variable can be set on the command line via @@ -153,7 +149,7 @@

`ccmake` and special build targets

A very convenient way to alter the configuration is to use the graphical @@ -177,7 +173,7 @@

Shortcuts

All variables starting with WITH_ will be automatically @@ -199,7 +195,7 @@

Configuration options

The various configuration options of the @@ -212,7 +208,7 @@ -

Feature configuration

deal.II provides (optional) interfaces to quite @@ -304,7 +300,7 @@ -

Autoconfiguration

As long as DEAL_II_WITH_<FEATURE> is @@ -339,7 +335,7 @@ -

External library locations

External libraries will be searched depending on hints in the following @@ -416,7 +412,7 @@

Manual override

Warning: Do not do this unless absolutely necessary!

It is possible to override the CMake find mechanism for external @@ -462,7 +458,7 @@ -

Component selection

The following options control which components of @@ -532,7 +528,7 @@ -

Build configuration

The cmake variable CMAKE_BUILD_TYPE @@ -595,7 +591,7 @@ -

Selecting a compiler

Compilers can be switched either by command line or by setting @@ -659,7 +655,7 @@ -

Installation

the location, @@ -726,7 +722,7 @@ -

Initial cache file and advanced options

A sample configuration file for preloading the CMake cache with

@@ -740,7 +736,7 @@
 
 
     
-     Compiling only certain parts 
+     Compiling only certain parts 
     
 
     

diff --git a/deal.II/doc/development/cmakelists.html b/deal.II/doc/development/cmakelists.html
index d0a7a833f9..44fb38ae3f 100644
--- a/deal.II/doc/development/cmakelists.html
+++ b/deal.II/doc/development/cmakelists.html
@@ -11,63 +11,64 @@
     
   
   
-  
-    
-    
How to use CMake to configure your projects with deal.II
-    
-    
+
+How to use CMake to configure your projects with deal.II
+
+
+  
+    Simple CMakeLists.txt
       
-        Simple CMakeLists.txt
-	  
-	    Adding multiple executable targets
-	    
Adding libraries and common source files
-	    
Adding a "run" target
-	  
-        
Autopilot style CMakeLists.txt            
Advanced CMakeLists.txt
-              
-		 TODO, see list
-              
-            
deal.IIConfig.cmake
-            
Legacy
-		Make.global_options
+	
Adding multiple executable targets
+	Adding libraries and common source files
+	Adding a "run" target
       
-    
-
-    
-      cmake is the configuration and build tool we use
-      in deal.II. Its advantage is not only that it makes
-      configuration of deal.II itself simpler across
-      platforms (compared to the older autoconf/make combination)
-      but also that it exports information about the deal.II
-      configuration that makes it particularly simple for projects
-      using deal.II to configure and link against it.
-    
-
-    
-      cmake is controlled by input files that by convention are
-      called CMakeLists.txt, listing both configuration commands
-      as well as dependencies between source files and targets.
-      This page presents some CMakeLists.txt examples for
-      potential use in your projects. (A detailed description of the
-      deal.II project configuration is given in the
-      deal.II CMake ReadMe.)
-    
-
-    
-    Simple CMakeLists.txt
-
-    
-      In this section, we start out with a
-      minimal CMakeLists.txt based on
-      the DEAL_II_SETUP_TARGET macro. This method gives
-      full control of what's happening and is easily extensible to
-      more complex projects, as exemplified in the subsections here an
-      later in the section on advanced
-      topics. Here is a full example
-      (plain text
-      version):
-      
-      
 Fix plain text after finalizing!
+

Advanced CMakeLists.txt +

TODO, see list

Autopilot style CMakeLists.txt

deal.IIConfig.cmake

Legacy Make.global_options

+ + + +

+ cmake is the configuration and build tool we use + in deal.II. Its advantage is not only that it makes + configuration of deal.II itself simpler across + platforms (compared to the older autoconf/make combination) + but also that it exports information about the deal.II + configuration that makes it particularly simple for projects + using deal.II to configure and link against it. +

+ +

+ cmake is controlled by input files that by convention are + called CMakeLists.txt, listing both configuration commands + as well as dependencies between source files and targets. + This page presents some CMakeLists.txt examples for + potential use in your projects. (A detailed description of the + deal.II project configuration is given in the + deal.II CMake ReadMe.) +

+ + +

Simple CMakeLists.txt

+ +

+ In this section, we start out with a + minimal CMakeLists.txt based on + the DEAL_II_SETUP_TARGET macro. This method gives + full control of what's happening and is easily extensible to + more complex projects, as exemplified in the subsections here an + later in the section on advanced + topics. Here is a full example + (plain text + version): + +

Fix plain text after finalizing!

 CMAKE_MINIMUM_REQUIRED(VERSION 2.8.8)
@@ -75,21 +76,58 @@ CMAKE_MINIMUM_REQUIRED(VERSION 2.8.8)
 FIND_PACKAGE(deal.II 8.0 REQUIRED
   HINTS ${DEAL_II_DIR} ../ ../../ $ENV{DEAL_II_DIR}
 )
-
 DEAL_II_INITIALIZE_CACHED_VARIABLES()
+
 PROJECT(myproject CXX)
 
 ADD_EXECUTABLE(mycode mycode.cc)
 DEAL_II_SETUP_TARGET(mycode)

Explain the code!

+ The first line of this code makes sure that a sufficiently high + version of CMake is installed. 2.8.8 is the minimal version required + to set up deal.II, therefore it is safe to use this + number here. +

+ +

+ Next, we find our deal.II installation, in this case requiring at + least version 8.0, which is the first version using + CMake. The HINTS are a list of directories where the + install directory of deal.II is likely to be found. Here, we check + whether we are in a subdirectory (first and second level) of the + deal.II installation and otherwise use the + variable DEAL_II_DIR. + Matthias, what is the difference between the first + and the last entry? This list can be changed according to your + preferences. After finding the deal.II project, we fetch its chached + variables. You can inspect these for instance + with ccmake. +

+ +

+ Every CMAkeLists.txt must contain a project definition, + which we do next. Matthias, I have been happy + without the CXX...? +

+ +

+ Finally, the last two lines define the executable that is to be + produced and its source code. +

+ + +

Explain the macros or link to explanation below

+ + +

Adding multiple executable targets

+ +

+ In order to specify multiple executable targets, simply repeat + the last two lines of the simple CMakeLists.txt: +

- -

Adding multiple executable targets

- -

In order to specify multiple executable targets, simply repeat - the last two lines of the simple CMakeLists.txt:

 ADD_EXECUTABLE(mycode2 mycode2.cc)
 DEAL_II_SETUP_TARGET(mycode2)
@@ -157,19 +195,78 @@ ADD_CUSTOM_TARGET(run COMMAND mycode

- -

Autopilot style CMakeLists.txt

+ +

Advanced `CMakeLists.txt`

- If you want a make interface similar to the deal.II library and - its tutorial, namely maker targets for debug and release - versions, running the code and cleaning, the easiest way to - write a CMakeLists.txt file may be to use - an "autopilot" style macro. Here is a minimalistic example for the - step-1 tutorial program (plain text version) that can be used for simple - projects: -

+  
+  A Subsection for each of the following:
+  
+  - control statements (if and foreach)
+  
+  - file glob to pick up sources
+  
+  - DEAL_II_SETUP_TARGET and DEAL_II_INITIALIZE_CACHED_VARIABLES
+  revisited
+  
+  - add include dirs and compile definitions to a directory or target
+  
+  - provide a ./run folder and target
+  
+  - custom targets to switch between release and debug
+  
+  - installation
+

+ + +

Finding the deal.II library

+ +

+ Finding the deal.II library should be no more than +

+    
+    FIND_PACKAGE(deal.II 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 file is located: + +

is deal.II_DIR still accurate? We use different +above. BTW, that is an UGLY variable name.

+ +

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

+ + +

Autopilot style CMakeLists.txt

+ +

+ If you want a make interface similar to the deal.II library and + its tutorial, namely maker targets for debug and release + versions, running the code and cleaning, the easiest way to + write a CMakeLists.txt file may be to use + an "autopilot" style macro. Here is a minimalistic example for the + step-1 tutorial program (plain text version) that can be used for simple + projects: +

 FIND_PACKAGE(deal.II 8.0 REQUIRED
@@ -263,81 +360,19 @@ SET(TARGET_RUN
 )

- -

Advanced `CMakeLists.txt`

+
+  deal.IIConfig.cmake 
 
-      A Subsection for each of the following:
-
-      - Common code for several targets. Library or adding to target definition
-
-      - control statements (if and foreach)
-
-      - file glob to pick up sources
-
-      - DEAL_II_SETUP_TARGET and DEAL_II_INITIALIZE_CACHED_VARIABLES
-        revisited
-
-      - add include dirs and compile definitions to a directory or target
-
-      - provide a ./run folder and target
-
-      - custom targets to switch between release and debug
-
-      - installation
-

- - -

Finding the deal.II library

- -

- Finding the deal.II library should be no more than -

-
-    FIND_PACKAGE(deal.II 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 file is located: - -

is deal.II_DIR still accurate? We use different above - -

-
-    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 the following variables and macros; all of the form - DEAL_II_*: -

- -

A long list with detailed explanation...

- -

+ Importing the deal.IIConfig.cmake file via FIND_PACKAGE + will set the following variables and macros; all of the form + DEAL_II_*: +

  
+A long list with detailed explanation...  
+

+ diff --git a/deal.II/doc/development/writing-documentation.html b/deal.II/doc/development/writing-documentation.html index 4ab4d3e318..e9b037dffd 100644 --- a/deal.II/doc/development/writing-documentation.html +++ b/deal.II/doc/development/writing-documentation.html @@ -179,9 +179,9 @@

Typewriter font:

In order to use typewriter font for instance for function - arguments or variables, use the <tt> HTML + arguments or variables, use the <code> HTML tag. For a single word, you can also use the form @p - one_word_without_spaces.

+ one_word_without_spaces. The <tt> is obsolete in HTML5

If you refer to member variables and member functions diff --git a/deal.II/doc/documentation.html b/deal.II/doc/documentation.html index 941beef63e..40baede90b 100644 --- a/deal.II/doc/documentation.html +++ b/deal.II/doc/documentation.html @@ -10,200 +10,194 @@ - - - - - -

Online documentation

- - - - - -

Table of contents
- - ReadMe - Tutorials - Programming interface - Development information - Reports - Publications - Copyright and licence - -

- - -

- deal.II comes with quite extensive online - documentation, which falls into several categories. They are - listed below. -

- - -

ReadMe

- -

- First, there is the README file of - the library. It gives information on system requirements, - installation, and copyright. -

- -

Tutorials

- -

- The tutorial is - for new users of the library. It explains the basic elements of - finite element programs based on the library, and provides small - example programs. You can also reach the tutorial link from the menu bar - at the left. -

- -

- Note that along with the rest of the documentation, the local HTML pages - of the tutorials need to be generated first. Please follow the - instructions in the - ReadMe file on how to do - this. -

- - -

Programming interface

- -

- The programming - interface/manual pages are what you will need most often as a - reference of all classes, functions and variables in the library. They - are extensively documented (presently more than 5000 pages if - printed), and generated by Doxygen. There is also a quick link to these pages from - the menu bar at the left. -

- -

- The documentation uses many of the features of Doxygen. In particular, - the link takes you straight to a page that lists modules, a way - to group classes with similar purposes. This may be what you are probably - interested in when you are not yet familiar with the library. If you - already know your way around and want to look up the signature of a - particular member function, for example, you may go to the class view or - choose any of the other ways in which Doxygen allows you to navigate - through the documentation. -

- -

- Just as for the tutorials, the API docs need to be generated first, - if you download deal.II. Please follow the - instructions in the - ReadMe file on how to do - this. -

- - -

Development information

- -

- If you plan to develop your own applications using - deal.II, it might be worth to take a look - at this - page. -

- - -

Reports

- -

- There are a number of papers that describe the overall design or - individual aspects of deal.II. Please refer to the - papers listed at the top of the publications page for full references. In addition, - there are the following reports: -

- A publication on the - basics of dimension independent - programming in deal.II (by Wolfgang - Bangerth). This explains some of the fundamentals of the - library's design, though rather briefly due to the page - limit imposed for the publication. -
- -
- This publication appeared in - the proceedings of the 16th IMACS World Congress, - Lausanne, Switzerland, 2000. See the - publications - page for the full reference as well as a way to obtain a - reprint of the original paper as a postscript or PDF file. -
- -
- A brief report about the classes involved in the - iterators and accessors - used to access cells in the triangulations and the data - thereon, such as their geometry, the number of the - degrees of freedom, data values, etc. You may want to - read this object or parts of it if you want to know what - information is available from iterators (by Wolfgang - Bangerth). -
- -
- A brief report on mapping functions of higher polynomial - degrees (by Ralf Hartmann). These allow the realisation - of higher order boundary approximations. This report - gives the theoretical background of the - MappingQ class. -
- -
- A report on - assembling matrices (by Wolfgang - Bangerth). This report looks in particular at how - matrices are assembled for vector-valued problems, and - how things change if vector-valued finite elements are - used for which the shape functions have more than one - non-zero vector component, such as Nedelec or - Raviart-Thomas elements. There are printable - versions of the report - in postscript and - PDF format. -
- -
- A very detailed report on - Nedelec elements (by Anna - Schneebeli, University of Basel, Switzerland). It - explains the construction and application of Nedelec - edge elements for H-curl spaces, as used, for example, - in the numerical solution of the Maxwell equations. It - also gives numerical results obtained with deal.II. - There is also a postscript version of the report. -
- -
- A report on the - codimension one capabilities - of the library (by Antonio DeSimone, Luca Heltai - and Cataldo Manigrasso, SISSA, Trieste, Italy). It - explains in detail how to use the - library for the solution of problems defined on codimension - one manifolds, such as, for example, Boundary Element Methods. -

- - -

Publications

+ + +

Online documentation

+ +

ReadMe
Tutorials
Programming interface
Development information
Reports
Publications
Copyright and licence

+ +

+ deal.II comes with quite extensive online + documentation, which falls into several categories. They are + listed below. +

+ +

ReadMe

+ +

+ First, there is the README file of + the library. It gives information on system requirements, + installation, and copyright. +

+ +

Tutorials

+ +

+ The tutorial is + for new users of the library. It explains the basic elements of + finite element programs based on the library, and provides small + example programs. You can also reach the tutorial link from the menu bar + at the left. +

+ +

+ Note that along with the rest of the documentation, the local HTML pages + of the tutorials need to be generated first. Please follow the + instructions in the + ReadMe file on how to do + this. +

+ + +

Programming interface

+ +

+ The programming + interface/manual pages are what you will need most often as a + reference of all classes, functions and variables in the library. They + are extensively documented (presently more than 5000 pages if + printed), and generated by Doxygen. There is also a quick link to these pages from + the menu bar at the left. +

+ +

+ The documentation uses many of the features of Doxygen. In particular, + the link takes you straight to a page that lists modules, a way + to group classes with similar purposes. This may be what you are probably + interested in when you are not yet familiar with the library. If you + already know your way around and want to look up the signature of a + particular member function, for example, you may go to the class view or + choose any of the other ways in which Doxygen allows you to navigate + through the documentation. +

+ +

+ Just as for the tutorials, the API docs need to be generated first, + if you download deal.II. Please follow the + instructions in the + ReadMe file on how to do + this. +

+ + +

Development information

+ +

+ If you plan to develop your own applications using + deal.II, it might be worth to take a look + at this + page. +

+ + +

Reports

+ +

+ There are a number of papers that describe the overall design or + individual aspects of deal.II. Please refer to the + papers listed at the top of the publications page for full references. In addition, + there are the following reports: +

+
+ A publication on the + basics of dimension independent + programming in deal.II (by Wolfgang + Bangerth). This explains some of the fundamentals of the + library's design, though rather briefly due to the page + limit imposed for the publication. +
+ +
+ This publication appeared in + the proceedings of the 16th IMACS World Congress, + Lausanne, Switzerland, 2000. See the + publications + page for the full reference as well as a way to obtain a + reprint of the original paper as a postscript or PDF file. +
+
+ A brief report about the classes involved in the + iterators and accessors + used to access cells in the triangulations and the data + thereon, such as their geometry, the number of the + degrees of freedom, data values, etc. You may want to + read this object or parts of it if you want to know what + information is available from iterators (by Wolfgang + Bangerth). +
+ A brief report on mapping functions of higher polynomial + degrees (by Ralf Hartmann). These allow the realisation + of higher order boundary approximations. This report + gives the theoretical background of the + MappingQ class. +
+ A report on + assembling matrices (by Wolfgang + Bangerth). This report looks in particular at how + matrices are assembled for vector-valued problems, and + how things change if vector-valued finite elements are + used for which the shape functions have more than one + non-zero vector component, such as Nedelec or + Raviart-Thomas elements. There are printable + versions of the report + in postscript and + PDF format. +
+ A very detailed report on + Nedelec elements (by Anna + Schneebeli, University of Basel, Switzerland). It + explains the construction and application of Nedelec + edge elements for H-curl spaces, as used, for example, + in the numerical solution of the Maxwell equations. It + also gives numerical results obtained with deal.II. + There is also a postscript version of the report. +
+ A report on the + codimension one capabilities of the library + (by Antonio DeSimone, Luca Heltai and Cataldo Manigrasso, + SISSA, Trieste, Italy). It explains in detail how to use the + library for the solution of problems defined on codimension + one manifolds, such as, for example, Boundary Element + Methods. +

+ + +

Publications

A list of @@ -211,26 +205,28 @@ deal.II can be found on this page.

- - -

Copyright and License

- -

deal.II is copyright of the - deal.II authors. - It is a joint effort of the current maintainers, Wolfgang - Bangerth, Timo Heister, Guido Kanschat, and quite a number of - contributors. deal.II is distributed under an + + +

Copyright and License

+ +

+ deal.II is copyright of the + deal.II authors. It is + a joint effort of the current maintainers, Wolfgang Bangerth, + Timo Heister, Guido Kanschat, and quite a number of + contributors. deal.II is distributed under + an OpenSource license. The full text of the license can be found in license.html.

Contact

We have a discussion group for discussion of issues of general interest to users and developers of deal.II.

- +

More specific questions may be sent to the authors immediately at the address firstName.lastname at dealii.org.

@@ -242,5 +238,5 @@ alt="Valid HTML 4.01!" height="31" width="88">

- + diff --git a/deal.II/doc/readme.html b/deal.II/doc/readme.html index b08a508c30..d9e5f3927f 100644 --- a/deal.II/doc/readme.html +++ b/deal.II/doc/readme.html @@ -26,39 +26,34 @@ -

Installation instructions and further information - on deal.II

- - - - - -

Table of contents
- - System requirements - - Supported platforms - Additional software requirements - - Installation - - Unpacking - Configuring and building the library - Configuring and building the documentation - Configuration options - - Selecting optional behavior - Optional interfaces to - other software packages - More information on configuring - and building the library - - - Problems, questions, mailing lists - License - -

Table of contents

System requirements -
- Supported platforms -
- Additional software requirements -
-
Installation -
-
Problems, questions, mailing lists -
License -

- +

Installation instructions and further information + on deal.II

+ +

System requirements +
1. Supported platforms +
2. Additional software requirements +
+
Installation +
+
Problems, questions, mailing lists +
License +

System requirements

-- 2.39.5

Build system internals

Coding convention

./CMakeLists.txt and ./cmake/setup_*.cmake

Build system internals

Coding convention

Configuration

./CMakeLists.txt and ./cmake/setup_*.cmake

./cmake/checks/check_*.cmake

./cmake/checks/check_*.cmake

./cmake/modules/Find*.cmake

./cmake/modules/Find*.cmake

./cmake/configure/configure_*.cmake

./cmake/configure/configure_*.cmake

Target definition and installation

./include/deal.II/base/config.h.in

Operating cmake

Operating cmake

Manipulating the cache

Manipulating the cache

ccmake and special build targets

ccmake and special build targets

Shortcuts

Shortcuts

Configuration options

Configuration options

Feature configuration

Feature configuration

Autoconfiguration

Autoconfiguration

External library locations

External library locations

Manual override

Manual override

Component selection

Component selection

Build configuration

Build configuration

Selecting a compiler

Selecting a compiler

Installation

Installation

Initial cache file and advanced options

Initial cache file and advanced options

Compiling only certain parts

Compiling only certain parts

How to use CMake to configure your projects with deal.II

How to use CMake to configure your projects with deal.II

Simple CMakeLists.txt

Simple CMakeLists.txt

Adding multiple executable targets

Adding multiple executable targets

Autopilot style CMakeLists.txt

Advanced CMakeLists.txt

Finding the deal.II library

Autopilot style CMakeLists.txt

Advanced CMakeLists.txt

deal.IIConfig.cmake

Finding the deal.II library

deal.IIConfig.cmake

Online documentation

Online documentation

Contact

Contact

Installation instructions and further information - on deal.II

Installation instructions and further information + on deal.II

System requirements

`./CMakeLists.txt` and `./cmake/setup_*.cmake`

`./CMakeLists.txt` and `./cmake/setup_*.cmake`

`./cmake/checks/check_*.cmake`

`./cmake/checks/check_*.cmake`

`./cmake/modules/Find*.cmake`

`./cmake/modules/Find*.cmake`

`./cmake/configure/configure_*.cmake`

`./cmake/configure/configure_*.cmake`

`./include/deal.II/base/config.h.in`

`ccmake` and special build targets

`ccmake` and special build targets

Advanced `CMakeLists.txt`

Advanced `CMakeLists.txt`

`deal.IIConfig.cmake`

`deal.IIConfig.cmake`