From 59ac8a3ac0113d981d52a9a45e81a9d1faa27a9d Mon Sep 17 00:00:00 2001 From: maier Date: Wed, 25 Sep 2013 20:30:34 +0000 Subject: [PATCH] Finish documentation git-svn-id: https://svn.dealii.org/trunk@30925 0785d39b-7218-0410-832d-ea1e28bc413d --- deal.II/doc/development/CMakeLists.txt.sample | 11 + .../doc/development/CMakeLists.txt.sample1 | 20 - .../doc/development/CMakeLists.txt.sample2 | 13 - .../doc/development/CMakeLists.txt.sample3 | 36 +- deal.II/doc/development/cmakelists.html | 359 ++++++++++++++++-- 5 files changed, 368 insertions(+), 71 deletions(-) create mode 100644 deal.II/doc/development/CMakeLists.txt.sample delete mode 100644 deal.II/doc/development/CMakeLists.txt.sample1 diff --git a/deal.II/doc/development/CMakeLists.txt.sample b/deal.II/doc/development/CMakeLists.txt.sample new file mode 100644 index 0000000000..58dde0ac2c --- /dev/null +++ b/deal.II/doc/development/CMakeLists.txt.sample @@ -0,0 +1,11 @@ +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) + +ADD_EXECUTABLE(mycode mycode.cc) +DEAL_II_SETUP_TARGET(mycode) diff --git a/deal.II/doc/development/CMakeLists.txt.sample1 b/deal.II/doc/development/CMakeLists.txt.sample1 deleted file mode 100644 index fda35efbf6..0000000000 --- a/deal.II/doc/development/CMakeLists.txt.sample1 +++ /dev/null @@ -1,20 +0,0 @@ -FIND_PACKAGE(deal.II 8.0 REQUIRED - HINTS - ${DEAL_II_DIR} ../ ../../ $ENV{DEAL_II_DIR} - # You can specify additional hints for search paths here, e.g. - # $ENV{HOME}/workspace/deal.II - ) - -# Set the name of the project and target: -SET(TARGET "step-1") - -# Declare all source files the target consists of: -SET(TARGET_SRC - step-1.cc - # You can specify additional files here! - ) - -CMAKE_MINIMUM_REQUIRED(VERSION 2.8.8) -DEAL_II_INITIALIZE_CACHED_VARIABLES() -PROJECT(${TARGET} CXX) -DEAL_II_INVOKE_AUTOPILOT() diff --git a/deal.II/doc/development/CMakeLists.txt.sample2 b/deal.II/doc/development/CMakeLists.txt.sample2 index 2003f225e9..fda35efbf6 100644 --- a/deal.II/doc/development/CMakeLists.txt.sample2 +++ b/deal.II/doc/development/CMakeLists.txt.sample2 @@ -14,19 +14,6 @@ SET(TARGET_SRC # You can specify additional files here! ) -# Specify a list of files (file globs) that will be removed -# with the "make runclean" and "make distclean" targets. -# (If empty, sensible default values will be used.) -SET(CLEAN_UP_FILES - # a custom list of globs, e.g. *.log *.vtk - ) - -# A custom command line that should be invoked by "make run". -# (If empty, ./${TARGET} will be invoked.) -SET(TARGET_RUN - # a custom command line, e.g. mpirun -np 2 ${TARGET} - ) - CMAKE_MINIMUM_REQUIRED(VERSION 2.8.8) DEAL_II_INITIALIZE_CACHED_VARIABLES() PROJECT(${TARGET} CXX) diff --git a/deal.II/doc/development/CMakeLists.txt.sample3 b/deal.II/doc/development/CMakeLists.txt.sample3 index 7d484c182f..2003f225e9 100644 --- a/deal.II/doc/development/CMakeLists.txt.sample3 +++ b/deal.II/doc/development/CMakeLists.txt.sample3 @@ -1,15 +1,33 @@ -CMAKE_MINIMUM_REQUIRED(VERSION 2.8.8) - FIND_PACKAGE(deal.II 8.0 REQUIRED - HINTS ${DEAL_II_DIR} ../ ../../ $ENV{DEAL_II_DIR} + HINTS + ${DEAL_II_DIR} ../ ../../ $ENV{DEAL_II_DIR} + # You can specify additional hints for search paths here, e.g. + # $ENV{HOME}/workspace/deal.II ) -DEAL_II_INITIALIZE_CACHED_VARIABLES() -PROJECT(step-1 CXX) +# Set the name of the project and target: +SET(TARGET "step-1") -ADD_EXECUTABLE(step-1 step-1.cc) -DEAL_II_SETUP_TARGET(step-1) +# Declare all source files the target consists of: +SET(TARGET_SRC + step-1.cc + # You can specify additional files here! + ) -ADD_CUSTOM_TARGET(run COMMAND step-1 - COMMENT "Run with ${CMAKE_BUILD_TYPE} configuration" +# Specify a list of files (file globs) that will be removed +# with the "make runclean" and "make distclean" targets. +# (If empty, sensible default values will be used.) +SET(CLEAN_UP_FILES + # a custom list of globs, e.g. *.log *.vtk ) + +# A custom command line that should be invoked by "make run". +# (If empty, ./${TARGET} will be invoked.) +SET(TARGET_RUN + # a custom command line, e.g. mpirun -np 2 ${TARGET} + ) + +CMAKE_MINIMUM_REQUIRED(VERSION 2.8.8) +DEAL_II_INITIALIZE_CACHED_VARIABLES() +PROJECT(${TARGET} CXX) +DEAL_II_INVOKE_AUTOPILOT() diff --git a/deal.II/doc/development/cmakelists.html b/deal.II/doc/development/cmakelists.html index fe34b34891..815852c8dd 100644 --- a/deal.II/doc/development/cmakelists.html +++ b/deal.II/doc/development/cmakelists.html @@ -26,7 +26,15 @@
  • Advanced CMakeLists.txt
      -
    1. TODO, see list
    2. +
    3. Source directory layout
    4. +
    5. Control statements
    6. +
    7. File globs
    8. +
    9. DEAL_II_SETUP_TARGET revisited
    10. +
    11. DEAL_II_INITIALIZE_CACHED_VARIABLES revisited
    12. +
    13. Customizing include directories and compile definitions
    14. +
    15. External libraries
    16. +
    17. The "run" target revisited
    18. +
    19. Install a project
  • Autopilot style CMakeLists.txt
  • @@ -64,11 +72,9 @@ full control of what's happening and is easily extensible to more complex projects, as exemplified in the subsections here and later in the section on advanced topics. Here is a full example - (plain text + (plain text version): -

    Fix plain text after finalizing!

    -
     CMAKE_MINIMUM_REQUIRED(VERSION 2.8.8)
     
    @@ -107,27 +113,23 @@ DEAL_II_SETUP_TARGET(mycode)
     
     

    After finding the deal.II project, we fetch a set of cached variables - with the DEAL_II_INITIALIZE_CACHED_VARIABLES() macro. You + with the + DEAL_II_INITIALIZE_CACHED_VARIABLES macro. You can inspect these for instance with ccmake.

    -

    link to detailed explanation of the macro below

    -

    Every CMakeLists.txt must contain a project definition, which we do next.

    - Finally, the last two lines define the executable that is to be - produced and its source code. The DEAL_II_SETUP_TARGET macro - will set up necessary incllude directories, compile defintions and the - link interface. + Finally, the last two lines define the executable that is to be produced + and its source code. The + DEAL_II_SETUP_TARGET macro will set up necessary + incllude directories, compile defintions and the link interface.

    - -

    link to detailed explanation of the macro below

    -

    Adding multiple executable targets

    @@ -261,8 +263,102 @@ ADD_CUSTOM_TARGET(run COMMAND mycode

    Advanced CMakeLists.txt

    -

    This section covers some advanced topics for a user -CMakeLIists.txt file.

    +

    This section covers some advanced topics for a user +CMakeLists.txt file.

    + + +

    Source directory layout

    + +

    For complex projects it is desirable to organize source code and header +files in subdirectories. Assume the following project structure with a +library "mylib" and an executable "mycode": + +

    +mylib/source/*.cc
    +mylib/include/*.h
    +
    +mycode/source/*.cc
    +mycode/include/*.h
    +
    + +In this case the top level CMakeLists.txt file may be: +
    +# top level CMakeLists.txt
    +CMAKE_MINIMUM_REQUIRED(VERSION 2.8.8)
    +FIND_PACKAGE(deal.II 8.0 REQUIRED)
    +
    +DEAL_II_INITIALIZE_CACHED_VARIABLES()
    +PROJECT(myproject)
    +
    +ADD_SUBDIRECTORY(mylib)
    +ADD_SUBDIRECTORY(mycode)
    +
    +The ADD_SUBDIRECTORY statement will include the CMakeLists.txt +file in the specified subdirectory. In our case: + +
    +# mylib/CMakeLists.txt
    +
    +INCLUDE_DIRECTORIES(include)
    +
    +ADD_LIBRARY(mylib
    +  source/mylib1.cc
    +  source/mylib2.cc
    +  )
    +
    +DEAL_II_SETUP_TARGET(mylib)
    +
    + +We have to add the directory include for the header files to +the current include directories with the INCLUDE_DIRECTORIES +statement (see this section for +details). The corresponding configuration file for the executable looks +like: + +
    +# mycode/CMakeLists.txt
    +
    +INCLUDE_DIRECTORIES(
    +  include
    +  ${CMAKE_SOURCE_DIR}/mylib/include
    +  )
    +
    +ADD_EXECUTABLE(mycode source/mycode.cc)
    +DEAL_II_SETUP_TARGET(mycode)
    +
    +TARGET_LINK_LIBRARIES(mycode mylib)
    +
    + +

    +Please note that CMakeLists.txt files have directory scope. +Any manipulation of properties and variables have only effect in the +current directory (and subdirectories, included with +ADD_SUBDIRECTORY. The level above will not be affected. +Therefore, we have to specify the include directories for "mylib" again in +the subdirectory mycode - this time with full path +${CMAKE_SOURCE_DIR}/mylib/include. +

    + +

    +CMake defines the following variables for access to important directories: + +

    +CMAKE_SOURCE_DIR
    +  - the source directory (i.e. the directory of the top level
    +    CMakeLists.txt file)
    +
    +CMAKE_BINARY_DIR
    +  - the (top level) build directory
    +
    +CMAKE_CURRENT_SOURCE_DIR
    +  - the current source directory, i.e. location of the currently processed
    +    CMakeLists.txt file (top level or included via ADD_SUBDIRECTORY)
    +
    +CMAKE_CURRENT_BINARY_DIR
    +  - the build (sub)directory corresponding to CMAKE_CURRENT_SOURCE_DIR
    +
    + +

    Control statements

    @@ -289,7 +385,6 @@ behind ELSE() and ENDIF(). have a look at the CMake documentation for a complete list. Important examples are: -

    Link!

     IF(${variable})
       - the body will be evaluated if the variable "variable" is defined and
    @@ -360,37 +455,148 @@ source file you have to touch a CMakeLists.txt file or to run
     
     
     

    DEAL_II_SETUP_TARGET revisited

    - -

    Well, write this!

    +

    +The DEAL_II_SETUP_TARGET macro is responsible for setting up a +target to compile and link against deal.II. It will append the +INCLUDE_DIRECTORIES property with the location of the deal.II +include directories, and the compile definitions and linker flags property +COMPILE_DEFINITIONS and LINK_FLAGS by their +respective values (depending on build type and available debug and/or +optimized flavor of the library). +

    +

    +Except in the case of an object library, the specified target will be set +up to link against deal.II (and its transitive link interface) as well. +

    DEAL_II_INITIALIZE_CACHED_VARIABLES revisited

    -

    Well, write this!

    +

    +The DEAL_II_INITIALIZE_CACHED_VARIABLES macro is responsible +for setting up cached variables and has to invoked before the +PROJECT call: +

    +FIND_PACKAGE(deal.II 8.0 REQUIRED)
    +
    +DEAL_II_INITIALIZE_CACHED_VARIABLES()
     
    +PROJECT(myproject)
    +
    +The macro will set an uninitialized CMAKE_BUILD_TYPE variable +to Debug (or Release if the debug library is not +available). If CMAKE_BUILD_TYPE is specified it will +automatically be reset if the given value is unsupported by the deal.II +installation. +

    +

    +Furthermore, this macro sets the C++ compiler and the compile flags to +default values (the same values that were used to compile deal.II itself). +These are CMAKE_CXX_COMPILER and CMAKE_CXX_FLAGS, +as well as - depending on the configuration - +DEAL_II_FLAGS_DEBUG, or DEAL_II_FLAGS_RELEASE, or +both. +

    Customizing include directories and compile definitions

    -

    Well, write this!

    +

    +You can specify custom include directories and compile definitions prior to +a target definition on a per directory basis (have a look at the CMake +documentation for further details): + +

    +INCLUDE_DIRECTORIES(include1 include2)
    +
    +ADD_DEFINITIONS(-DFOO -DBAR="BAZ")
     
    +ADD_EXECUTABLE(...) # or ADD_LIBRARY(...)
    +
    +

    External libraries

    -

    Well, write this!

    +

    +For external libraries that provide a CMake project configuration or where +a CMake find module is available, including this external library in your +project is more or less straightforward. E.g. to require an external +project "foo" at least of version 8.0 write: +

    +FIND_PACKAGE(foo 8.0 REQUIRED)
    +
    +Alternatively, the version number and REQUIRED keyword can be +omitted. (Depending on the external library) the project configuration or +find macro will usually define variables like FOO_INCLUDE_DIRS +and FOO_LIBRARIES that can be directly used in your +CMakeLists.txt file: + +
    +INCLUDE_DIRECTORIES(${FOO_INCLUDE_DIRS})
     
    +ADD_EXECUTABLE(mycode mycode.cc)
    +DEAL_II_SETUP_TARGET(mycode)
    +
    +TARGET_LINK_LIBRARIES(mycode ${FOO_LIBRARIES})
    +
    +The first statement will set up the include directories for the following +targets as explained above. The last statement with +TARGET_LINK_LIBRARIES will add the libraries in the +FOO_LIBRARIES variable to the link interface of the target +mycode. +

    The "run" target revisited

    -

    Well, write this!

    +

    The simple run statement as explained above will run the generated executable in the +build directory. Sometimes it is more desirable to run the executable in a +dedicated run directory within in the build directory which is +a copy of a skeleton run folder from the source directory: + +

    +# Copy folder run from the source to the build directory:
    +FILE(COPY ${CMAKE_SOURCE_DIR}/run DESTINATION ${CMAKE_BINARY_DIR})
     
    +ADD_EXECUTABLE(mycode mycode.cc)
    +SET_PROPERTY(TARGET mycode
    +  PROPERTY RUNTIME_OUTPUT_DIRECTORY ${CMAKE_BINARY_DIR}/run
    +  )
    +ADD_CUSTOM_TARGET(run
    +  COMMAND mycode
    +  WORKING_DIRECTORY ${CMAKE_BINARY_DIR}/run
    +  )
    +
    +Here, we modify the RUNTIME_OUTPUT_DIRECTORY property of our +target so that the executable is linked inside our designated +run folder, so that it is conveniently available as an +executable inside the run folder. Furthermore, we specify a +WORKING_DIRECTORY for the run target, so that +make run invokes the executable inside the intendet run +directory. +

    Install a project

    +

    If you want the make install to install your project to +CMAKE_INSTALL_PREFIX (that may be set on command line or in +the cache during the configuration stage), add appropriate +INSTALL statements. To install e.g. a project consisting of a +library and an executable as well as a run folder: + +

    +# [...] all the target definitions
    +
    +INSTALL(TARGETS mylib DESTINATION lib)
    +INSTALL(TARGETS mycode DESTINATION bin)
    +
    +INSTALL(DIRECTORY run DESTINATION share/mycode/run)
    +

    Autopilot style CMakeLists.txt

    @@ -401,7 +607,7 @@ source file you have to touch a CMakeLists.txt file or to run 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:

    @@ -479,7 +685,7 @@ $ cmake . There are two additional configuration options (in addition to TARGET and TARGET_SRC) that can be set via variables before DEAL_II_INVOKE_AUTOPILOT() is called - (plain text version): + (plain text version):
     # (Optional)
    @@ -507,12 +713,107 @@ SET(TARGET_RUN
       will set the following variables and macros; all of the form
       DEAL_II_*:
     

    -
      
    -A long list with detailed explanation...  
    -
    - +
    +#
    +# General package information:
    +#
    +
    +DEAL_II_PACKAGE_NAME
    +DEAL_II_PACKAGE_VERSION     - the full package version string, e.g. "8.1.pre"
    +DEAL_II_PACKAGE_VENDOR
    +DEAL_II_PACKAGE_DESCRIPTION
    +
    +DEAL_II_VERSION             - version string without suffix, e.g. "8.1"
    +DEAL_II_VERSION_MAJOR       - the major number, e.g. "8"
    +DEAL_II_VERSION_MINOR       - the minor version number, e.g. "1"
    +
    +DEAL_II_BUILD_TYPE          - the configured build type, e.g. "DebugRelease"
    +DEAL_II_BUILD_TYPES         - an all caps list of available configurations,
    +                              e.g. "DEBUG;RELEASE"
    +
    +#
    +# Information about component locations:
    +#
    +
    +DEAL_II_PATH
    +DEAL_II_CMAKE_MACROS_RELDIR
    +DEAL_II_COMMON_RELDIR
    +DEAL_II_DOCREADME_RELDIR
    +DEAL_II_DOCHTML_RELDIR
    +DEAL_II_EXAMPLES_RELDIR
    +DEAL_II_EXECUTABLE_RELDIR
    +DEAL_II_INCLUDE_RELDIR
    +DEAL_II_LIBRARY_RELDIR
    +DEAL_II_PROJECT_CONFIG_RELDIR
    +
    +DEAL_II_BUILD_DIR             - true if deal.II was picked up from a build
    +                                dir, false if the configuration is from an installation
    +
    +#
    +# Compiler and linker configuration
    +#
    +
    +DEAL_II_CXX_COMPILER             - the compiler used to compile deal.II
    +
    +DEAL_II_CXX_FLAGS                - compile flags for all configurations
    +DEAL_II_CXX_FLAGS_DEBUG          - _additional_ compile flags for the debug configuration
    +DEAL_II_CXX_FLAGS_RELEASE        - _additional_ compile flags for the release configuration
    +
    +DEAL_II_LINKER_FLAGS             - link flags for all configurations
    +DEAL_II_LINKER_FLAGS_DEBUG       - _additional_ link flags for debug configuration
    +DEAL_II_LINKER_FLAGS_RELEASE     - _additional_ link flags for release configuration
     
    +DEAL_II_USER_DEFINITIONS         - compile definitions for all configurations
    +DEAL_II_USER_DEFINITIONS_DEBUG   - _additional_ compile definitions for debug configuration
    +DEAL_II_USER_DEFINITIONS_RELEASE - _additional_ compile definitions for release configuration
     
    +DEAL_II_STATIC_EXECUTABLE        - true if the link interface is set up to
    +                                   compile resulting executables statically
    +
    +#
    +# Information about include directories and libraries
    +#
    +
    +DEAL_II_INCLUDE_DIRS
    +
    +DEAL_II_LIBRARIES_DEBUG   - a list of the full link interface for the debug configuration
    +DEAL_II_LIBRARIES_RELEASE - a list of the full link interface for the release configuration
    +DEAL_II_LIBRARIES         - full list of libraries with "debug" and "optimized" keywords
    +
    +#
    +# Information about library targets
    +#
    +
    +DEAL_II_TARGET_CONFIG  - the target config file
    +
    +DEAL_II_TARGET_DEBUG   - the name of the debug target that is available after inclusion
    +                         of the target config file
    +DEAL_II_TARGET_RELEASE - the name of the release target
    +DEAL_II_TARGET         - full list of targets with "debug" and "optimized" keywords
    +
    +#
    +# Feature configuration: The following booleans are set to "ON" or "OFF" depending
    +# on the current feature configuration:
    +#
    +
    +DEAL_II_WITH_64BIT_INDICES
    +DEAL_II_WITH_ARPACK
    +DEAL_II_WITH_BOOST
    +DEAL_II_WITH_FUNCTIONPARSER
    +DEAL_II_WITH_HDF5
    +DEAL_II_WITH_LAPACK
    +DEAL_II_WITH_METIS
    +DEAL_II_WITH_MPI
    +DEAL_II_WITH_MUMPS
    +DEAL_II_WITH_NETCDF
    +DEAL_II_WITH_P4EST
    +DEAL_II_WITH_PETSC
    +DEAL_II_WITH_SLEPC
    +DEAL_II_WITH_THREADS
    +DEAL_II_WITH_TRILINOS
    +DEAL_II_WITH_UMFPACK
    +DEAL_II_WITH_ZLIB
    +

    Legacy Make.global_options

    -- 2.39.5