]> https://gitweb.dealii.org/ - dealii-svn.git/commitdiff
Update on the documentation
authormaier <maier@0785d39b-7218-0410-832d-ea1e28bc413d>
Sat, 22 Sep 2012 17:33:24 +0000 (17:33 +0000)
committermaier <maier@0785d39b-7218-0410-832d-ea1e28bc413d>
Sat, 22 Sep 2012 17:33:24 +0000 (17:33 +0000)
git-svn-id: https://svn.dealii.org/branches/branch_cmake@26634 0785d39b-7218-0410-832d-ea1e28bc413d

deal.II/CMakeLists.txt
deal.II/README_CMAKE

index 69bd2a1864fe0595d29b457caff4cdb04f19d457..f74daa9effdb48428e4ce3ccb2f22a5a977aeaa5 100644 (file)
@@ -68,8 +68,7 @@ OPTION(DEAL_II_FORCE_CONTRIB_BOOST
   OFF)
 
 OPTION(DEAL_II_WITH_DOXYGEN
-  "Enable the generation and installation of the documentation via doxygen.
-  This feature adds a COMPONENT \"documentation\" to the build system."
+  "Build deal.II with support for doxygen and dot."
   OFF)
 
 OPTION(DEAL_II_WITH_FUNCTIONPARSER
index e1360604188cabbf35f8338e4d51d9207fe7fec1..e23297dc2a5c0eba5376c26614ebf72334dc647a 100644 (file)
 
 
 
-Table of contents
+=================
+TABLE OF CONTENTS
 =================
 
-The philosophy
+  Introduction
 
-Quick start
+      The philosophy
 
-Useful bits
+      Quick start
 
-Feature configuration
+      Useful bits
 
-Build configuration
+  Configuration
 
-Installation
+      Feature configuration
 
-Component selection
+      Component selection
 
-Fat note regarding platform checks and feature configuration
+      Build configuration
 
-Writing platform checks
+      Installation
 
-Writing features
+  Development
 
+      Fat note regarding platform checks and feature configuration
 
+      Writing platform checks
 
+      Writing features
 
-The philosophy
-==============
 
-        »I need a new keyboard, my CAPS-KEY is stuck because of writing all
-         this cmake script...«
 
-TODO
 
+============
+INTRODUCTION
+============
 
 
+  TODO
 
-Quick start
-===========
 
+  The philosophy
+  ==============
 
-* Make a build directory, configure, compile and install:
+          »I need a new keyboard, my CAPS-KEY is stuck because of writing all
+           this cmake script...«
 
-      $ mkdir build
-      $ cd build
-      $ cmake -DCMAKE_INSTALL_PREFIX=/path/install/dir ../
-      $ make install
+  TODO
 
 
+  Quick start
+  ===========
 
 
-Useful bits
-===========
+  * Make a build directory, configure, compile and install:
 
+        $ mkdir build
+        $ cd build
+        $ cmake -DCMAKE_INSTALL_PREFIX=/path/install/dir ../
+        $ make install
 
-* All cached variables can be either set via
 
-    ( $ cd build )
-      $ ccmake
+  Useful bits
+  ===========
 
-  or at the prompt via:
 
-    ( $ cd build )
-      $ cmake -D<OPTION>=<VALUE> [...] path/to/source/tree
+  * All cached variables can be either set via
 
-* Configure with autodetection, afterwards disable a feature:
+      ( $ cd build )
+        $ ccmake
 
-    ( $ cd build )
-      $ cmake -DDEAL_II_FEATURE_AUTODETECTION=ON ../
-      $ cmake -DDEAL_II_FEATURE_AUTODETECTION=OFF -DDEAL_II_WITH_METIS=OFF ../
-      $ make install
+    or at the prompt via:
 
-* Build and install only a specific component:
+      ( $ cd build )
+        $ cmake -D<OPTION>=<VALUE> [...] path/to/source/tree
 
-    ( $ cd build )
-      $ make <component>
-      $ cmake -DCOMPONENT=<component> -P build/cmake_install.cmake
+  * Configure with autodetection, afterwards disable a feature:
 
+      ( $ cd build )
+        $ cmake -DDEAL_II_FEATURE_AUTODETECTION=ON ../
+        $ cmake -DDEAL_II_FEATURE_AUTODETECTION=OFF -DDEAL_II_WITH_METIS=OFF ../
+        $ make install
 
+  * Build and install only a specific component:
 
+      ( $ cd build )
+        $ make <component>
+        $ cmake -DCOMPONENT=<component> -P build/cmake_install.cmake
 
-Feature configuration
-=====================
 
-TODO: Reformulate
 
-The first bunch of options of type DEAL_II_WITH_<feature> are for
-configuration of the various features of the deal.II library.
-An enabled feature will usually add one ore more dependencies to external
-or 'contrib' (i.e. bundled with deal.II and residing under ./contrib/)
-libraries.
 
+=============
+CONFIGURATION
+=============
 
-The option DEAL_II_ALLOW_CONTRIB determines the behaviour of the
-dependency resolution:
 
-- If set to ON external libraries still have precedence. But if there is
-  no external library the bundled contrib library will be used.
+  The various configuration options of the deal.II library are organized in
+  three categories: Feature, Component and build/install configuration.
 
-- If set to OFF the contrib libraries will not be used and the dependency
-  resolution will fail if there is no external library. EXCEPT (there is
-  always an exception, isn't it?) DEAL_II_FORCE_CONTRIB_<library> forces
-  the use of the bundled contrib library.
 
+  Feature configuration
+  =====================
 
-Autoconfiguration: If the option DEAL_II_FEATURE_AUTODETECTION is enabled
-the DEAL_II_WITH_<feature> toggles will be automatically set (overwriting
-any previous configuration) depending on whether they can be supported or
-not.
-(Note: DEAL_II_FEATURE_AUTODETECTION will respect DEAL_II_ALLOW_CONTRIB
-and DEAL_II_FORCE_CONTRIB_<feature>)
+  deal.II provides (optional) interfaces to quite a number of external
+  libraries:
 
+    DEAL_II_WITH_ARPACK
+        Build deal.II with support for ARPACK
 
-The option DEAL_II_FORCE_CONTRIB_<library> forces the use of the bundled
-contrib library regardless whether DEAL_II_ALLOW_CONTRIB is set to OFF or
-an external library is found.
+    DEAL_II_WITH_BLAS
+        Build deal.II with support for BLAS
 
-REMARKS:
+    DEAL_II_WITH_BOOST
+        Build deal.II with support for boost. Always activated
 
-- To ensure that no bundled library is used at all DEAL_II_ALLOW_CONTRIB,
-  as well as every DEAL_II_FORCE_CONTRIB_<library> have to be set to OFF.
+    DEAL_II_WITH_DOXYGEN
+        Build deal.II with support for doxygen and dot
 
-- DEAL_II_FORCE_CONTRIB_<library>=ON will _not_ automatically enable the
-  corresponding DEAL_II_WITH_<feature> toggle. This has to be set
-  separately.
+    DEAL_II_WITH_FUNCTIONPARSER
+        Build deal.II with support for functionparser
 
-TODO: A list of all DEAL_II_WITH_* options
+    DEAL_II_WITH_LAPACK
+        Build deal.II with support for LAPACK
 
+    DEAL_II_WITH_METIS
+        Build deal.II with support for Metis
 
+    DEAL_II_WITH_MPI
+        Build deal.II with support for mpi
 
+    DEAL_II_WITH_NETCDF
+        Build deal.II with support for netcdf
 
-Build configuration
-===================
+    DEAL_II_WITH_P4EST
+        Build deal.II with support for P4EST
 
+    DEAL_II_WITH_TBB
+        Build deal.II with support for tbb. This will enable thread support in deal.II
 
-CMAKE_BUILD_TYPES: We support the "Debug" and "Release" build targets.
-Default is the "Release" target.
+    DEAL_II_WITH_TRILINOS
+        Build deal.II with support for trilinos
 
-- Debug will enable a lot of debug code paths and Assertions, as well as
-  compiling the library with a suitable set of debug compiler flags.
+    DEAL_II_WITH_UMFPACK
+        Build deal.II with support for UMFPACK
 
-- Release will chose a suitable set of optimizing flags.
+    DEAL_II_WITH_ZLIB
+        Build deal.II with support for zlib
 
+  An enabled feature will usually add one ore more dependencies to external
+  or 'contrib' (i.e. bundled with deal.II and residing under ./contrib/)
+  libraries.
 
-deal.II will configure sensible default CFLAGS and CXXFLAGS depending on
-platform, compiler and build target. There are two options, if this is
-not desired:
 
-- Option 1: Disable the configuration completely by setting
-  DEAL_II_SETUP_DEFAULT_COMPILER_FLAGS to OFF.
-  Beware of the fact that certain features may still pull in necessary
-  compiler flags.
+  There are some options to determine the behaviour of the dependency
+  resolution:
 
-- Option 2: Overwrite the default configuration by setting the following
-  cached variables:
+  The option DEAL_II_ALLOW_CONTRIB determines the behaviour of the
+  dependency resolution:
 
-    CMAKE_CXX_FLAGS         -  used during all builds
-    CMAKE_CXX_FLAGS_DEBUG   -  additional flags used during debug builds
-    CMAKE_CXX_FLAGS_RELEASE -  additional flags used during release builds
-    (same for CMAKE_C_...)
+    - If set to ON external libraries still have precedence. But if there is
+      no external library the bundled contrib library will be used.
 
-The content of the cached variables will be preserved and added
-*_TO THE END_* of the default compiler flags, hence giving a possibility
-for overwriting a flag. E.g.: -Wsign-compare, set by the build system,
-can be overwritten by specifying:
+    - If set to OFF the contrib libraries will not be used and the dependency
+      resolution will fail if there is no external library. EXCEPT (there is
+      always an exception, isn't it?) DEAL_II_FORCE_CONTRIB_<library> forces
+      the use of the bundled contrib library.
 
-  $ cmake -DCMAKE_CXX_FLAGS="-Wno-sign-compare" <...>
+  The option DEAL_II_FORCE_CONTRIB_(BOOST|FUNCTIONPARSER|TBB|UMFPACK)
+  forces the use of the bundled  contrib library regardless whether
+  DEAL_II_ALLOW_CONTRIB is set to OFF or an external library is found.
 
+  Autoconfiguration:
+  If the option DEAL_II_FEATURE_AUTODETECTION is enabled the
+  DEAL_II_WITH_<feature> toggles will be automatically set (overwriting any
+  previous configuration) depending on whether they can be supported or
+  not.
+  (Note: DEAL_II_FEATURE_AUTODETECTION will respect DEAL_II_ALLOW_CONTRIB
+  and DEAL_II_FORCE_CONTRIB_<feature>)
 
-The build can be further controlled by the following variables:
+  REMARKS:
 
-- BUILD_SHARED_LIBS: If set, deal.II will be linked as a shared library
+  - To ensure that no bundled library is used at all DEAL_II_ALLOW_CONTRIB,
+    as well as every DEAL_II_FORCE_CONTRIB_<library> have to be set to OFF.
 
-- CMAKE_INSTALL_RPATH_USE_LINK_PATH: If set, the deal.II library will be
-  installed with its rpath value set to point to all libraries outside of
-  the system search pathes.
+  - DEAL_II_FORCE_CONTRIB_<library>=ON will _not_ automatically enable the
+    corresponding DEAL_II_WITH_<feature> toggle. This has to be set
+    separately.
 
 
 
 
-Component selection
-===================
+  Component selection
+  ===================
 
 
-The following options control which components of the deal.II shall be
-configured, build and installed:
+  The following options control which components of the deal.II will be
+  configured, build and installed:
 
-- DEAL_II_COMPONENT_EXAMPLES:
-  Enable configuration and installation of the example steps.
-  This adds a COMPONENT "examples" to the build system.
+  - DEAL_II_COMPONENT_EXAMPLES:
+    Enable configuration and installation of the example steps.
+    This adds a COMPONENT "examples" to the build system.
 
-- DEAL_II_COMPONENT_DOCUMENTATION:
-  Enable configuration, build and installation of the documentation.
-  This adds a COMPONENT "documentation" to the build system.
+  - DEAL_II_COMPONENT_DOCUMENTATION:
+    Enable configuration, build and installation of the documentation.
+    This adds a COMPONENT "documentation" to the build system.
 
-- DEAL_II_COMPONENT_COMPAT_FILES:
-  Enable installation of legacy files and tools for compatibility with
-  the old build system
-  This adds a COMPONENT "compat_files" to the build system.
+  - DEAL_II_COMPONENT_COMPAT_FILES:
+    Enable installation of legacy files and tools for compatibility with
+    the old build system
+    This adds a COMPONENT "compat_files" to the build system.
 
-- DEAL_II_COMPONENT_PROJECT_CONFIG:
-  Enable configuration and installation of a cmake project config. Useful
-  for finding ( FIND_PACKAGE(DEAL_II) ) the deal.II library out of cmake
-  build systems. This adds a COMPONENT "project_config" to the build
-  system.
+  - DEAL_II_COMPONENT_PROJECT_CONFIG:
+    Enable configuration and installation of a cmake project config. Useful
+    for finding ( FIND_PACKAGE(DEAL_II) ) the deal.II library out of cmake
+    build systems. This adds a COMPONENT "project_config" to the build
+    system.
 
 
 
 
-Installation
-============
+  Build configuration
+  ===================
+
+
+  CMAKE_BUILD_TYPES: We support the "Debug" and "Release" build targets.
+  Default is the "Release" target.
+
+  - Debug will enable a lot of debug code paths and Assertions, as well as
+    compiling the library with a suitable set of debug compiler flags.
+
+  - Release will chose a suitable set of optimizing flags.
+
+
+  deal.II will configure sensible default CFLAGS and CXXFLAGS depending on
+  platform, compiler and build target. There are two options, if this is
+  not desired:
+
+  - Option 1: Disable the configuration completely by setting
+    DEAL_II_SETUP_DEFAULT_COMPILER_FLAGS to OFF.
+    Beware of the fact that certain features may still pull in necessary
+    compiler flags.
+
+  - Option 2: Overwrite the default configuration by setting the following
+    cached variables:
 
-CMAKE_INSTALL_PREFIX determines the location, where the deal.II library
-will be installed.
+      CMAKE_CXX_FLAGS         -  used during all builds
+      CMAKE_CXX_FLAGS_DEBUG   -  additional flags used during debug builds
+      CMAKE_CXX_FLAGS_RELEASE -  additional flags used during release builds
+      (same for CMAKE_C_...)
 
-Please note that depending on whether DEAL_II_COMPONENT_COMPAT_FILES is
-set, there will be different folder structures:
+  The content of the cached variables will be preserved and added
+  *_TO THE END_* of the default compiler flags, hence giving a possibility
+  for overwriting a flag. E.g.: -Wsign-compare, set by the build system,
+  can be overwritten by specifying:
 
-With DEAL_II_COMPONENT_COMPAT_FILES=ON:
+    $ cmake -DCMAKE_CXX_FLAGS="-Wno-sign-compare" <...>
 
-${CMAKE_INSTALL_PREFIX}/
-    common
-    common/scripts
-    doc
-    examples
-    include
-    lib
 
-With DEAL_II_COMPONENT_COMPAT_FILES=OFF:
+  The build can be further controlled by the following variables:
 
-${CMAKE_INSTALL_PREFIX}/
-    include
-    lib${LIB_SUFFIX}
-    /share/doc/deal.II/examples
-    /share/doc/deal.II/html
+  - BUILD_SHARED_LIBS: If set, deal.II will be linked as a shared library
 
-If DEAL_II_COMPONENT_COMPAT_FILES is set to OFF, the individual target
-directories can be overwritten by
-    DEAL_II_DOCUMENTATION_RELDIR
-    DEAL_II_EXAMPLES_RELDIR
-    DEAL_II_INCLUDE_RELDIR
-    DEAL_II_LIBRARY_RELDIR
-    DEAL_II_PROJECT_CONFIG_RELDIR
+  - CMAKE_INSTALL_RPATH_USE_LINK_PATH: If set, the deal.II library will be
+    installed with its rpath value set to point to all libraries outside of
+    the system search pathes.
 
 
 
 
-Fat note regarding platform checks and feature configuration
-============================================================
+  Installation
+  ============
+
+  CMAKE_INSTALL_PREFIX determines the location, where the deal.II library
+  will be installed.
+
+  Please note that depending on whether DEAL_II_COMPONENT_COMPAT_FILES is
+  set, there will be different folder structures:
+
+  With DEAL_II_COMPONENT_COMPAT_FILES=ON:
+
+  ${CMAKE_INSTALL_PREFIX}/
+      common
+      common/scripts
+      doc
+      examples
+      include
+      lib
+
+  With DEAL_II_COMPONENT_COMPAT_FILES=OFF:
+
+  ${CMAKE_INSTALL_PREFIX}/
+      include
+      lib${LIB_SUFFIX}
+      /share/doc/deal.II/examples
+      /share/doc/deal.II/html
+
+  If DEAL_II_COMPONENT_COMPAT_FILES is set to OFF, the individual target
+  directories can be overwritten by
+      DEAL_II_DOCUMENTATION_RELDIR
+      DEAL_II_EXAMPLES_RELDIR
+      DEAL_II_INCLUDE_RELDIR
+      DEAL_II_LIBRARY_RELDIR
+      DEAL_II_PROJECT_CONFIG_RELDIR
+
+
+
+
+==========
+DEVELOPMENT
+===========
+
+
+  Fat note regarding platform checks and feature configuration
+  ============================================================
 
 
-                          ============
+                            ============
 
-                            FAT NOTE
+                              FAT NOTE
 
-                          ============
+                            ============
 
 
-To keep things clean, only the following cmake variables should be
-altered in the platform checks and feature configuration
-(beside setting a lot of DEAL_II_* definitions...):
+  To keep things clean, only the following cmake variables should be
+  altered in the platform checks and feature configuration
+  (beside setting a lot of DEAL_II_* definitions...):
 
 
-For internal use:
+  For internal use:
 
-    CMAKE_SHARED_LINKER_FLAGS
-        for setting necessary linker flags for the deal.II library.
+      CMAKE_SHARED_LINKER_FLAGS
+          for setting necessary linker flags for the deal.II library.
 
-    CMAKE_CXX_FLAGS (and CMAKE_C_FLAGS)
-        for setting necessary compiler flags, e.g. -std=c++11 (if
-        available).
+      CMAKE_CXX_FLAGS (and CMAKE_C_FLAGS)
+          for setting necessary compiler flags, e.g. -std=c++11 (if
+          available).
 
-    INCLUDE_DIRECTORIES(...)
-        For setting necessary include dirs for the compilation of the
-        deal.II library.
+      INCLUDE_DIRECTORIES(...)
+          For setting necessary include dirs for the compilation of the
+          deal.II library.
 
-    ADD_DEFINITIONS(...)
-        For setting necessary preprocessor definitions ("-D<...>") for
-        the compilation of the deal.II library
+      ADD_DEFINITIONS(...)
+          For setting necessary preprocessor definitions ("-D<...>") for
+          the compilation of the deal.II library
 
-    ADD_DEPENDENCIES(deal_ii_target_dependencies ...)
-        Used as a dummy target for all the stuff that has to be done
-        before the library can be compiled.
+      ADD_DEPENDENCIES(deal_ii_target_dependencies ...)
+          Used as a dummy target for all the stuff that has to be done
+          before the library can be compiled.
 
 
-For internal and external use:
+  For internal and external use:
 
-    DEAL_II_EXTERNAL_LIBRARIES
-        Used to keep track of external libraries, the deal.II library
-        and user programs have to be linked against.
+      DEAL_II_EXTERNAL_LIBRARIES
+          Used to keep track of external libraries, the deal.II library
+          and user programs have to be linked against.
 
 
-For external use:
+  For external use:
 
-    DEAL_II_EXTERNAL_DEFINITIONS
-        Used to keep track of external preprocessor definitions,
-        necessary for the compilation of user programs.
+      DEAL_II_EXTERNAL_DEFINITIONS
+          Used to keep track of external preprocessor definitions,
+          necessary for the compilation of user programs.
 
 
-    DEAL_II_EXTERNAL_INCLUDE_DIRS
-        Used to keep track of external include dirs, necessary for the
-        compilation of user programs.
+      DEAL_II_EXTERNAL_INCLUDE_DIRS
+          Used to keep track of external include dirs, necessary for the
+          compilation of user programs.
 
 
 
 
-Writing platform checks
-=======================
+  Writing platform checks
+  =======================
 
 
-TODO
+  TODO
 
 
 
 
-Writing features
-================
+  Writing features
+  ================
 
-TODO
+  TODO
 

In the beginning the Universe was created. This has made a lot of people very angry and has been widely regarded as a bad move.

Douglas Adams


Typeset in Trocchi and Trocchi Bold Sans Serif.