From: Matthias Maier Date: Mon, 26 Aug 2013 05:20:51 +0000 (+0000) Subject: Documentation: Rewrite the documentation aboutdocumentation about sample CMakeLists... X-Git-Tag: v8.1.0~957 X-Git-Url: https://gitweb.dealii.org/cgi-bin/gitweb.cgi?a=commitdiff_plain;h=b0f2402486ef129fb0a9be0aff78c86c6f1509ac;p=dealii.git Documentation: Rewrite the documentation aboutdocumentation about sample CMakeLists.txts git-svn-id: https://svn.dealii.org/trunk@30492 0785d39b-7218-0410-832d-ea1e28bc413d --- diff --git a/deal.II/doc/development/CMakeLists.txt.sample b/deal.II/doc/development/CMakeLists.txt.sample deleted file mode 100644 index 549cf0d0bb..0000000000 --- a/deal.II/doc/development/CMakeLists.txt.sample +++ /dev/null @@ -1,61 +0,0 @@ -## ## -# A simple CMakeLists.txt file for use with 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 - ${TARGET}.cc - # You can specify additional files here! - ) - -# -# (Optional) -# 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 - ) - -# -# (Optional) -# 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} - ) - -# -# It is good practice to specify a version requirement: -# -CMAKE_MINIMUM_REQUIRED(VERSION 2.8.8) - -# -# Find and import the deal.II project configuration: -# -FIND_PACKAGE(deal.II 8.0 REQUIRED - HINTS - ${DEAL_II_DIRS} ../ ../../ $ENV{DEAL_II_DIR} - # - # If the deal.II library cannot be found (because it is not installed at a - # default location or your project resides at an uncommon place), you - # can specify additional hints for search paths here, e.g. - # "$ENV{HOME}/workspace/deal.II" - # - ) - -# -# And let deal.II do the rest: -# -DEAL_II_INITIALIZE_CACHED_VARIABLES() -PROJECT(${TARGET}) -DEAL_II_INVOKE_AUTOPILOT() diff --git a/deal.II/doc/development/CMakeLists.txt.sample1 b/deal.II/doc/development/CMakeLists.txt.sample1 new file mode 100644 index 0000000000..fda35efbf6 --- /dev/null +++ b/deal.II/doc/development/CMakeLists.txt.sample1 @@ -0,0 +1,20 @@ +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 new file mode 100644 index 0000000000..2003f225e9 --- /dev/null +++ b/deal.II/doc/development/CMakeLists.txt.sample2 @@ -0,0 +1,33 @@ +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! + ) + +# 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.txt.sample3 b/deal.II/doc/development/CMakeLists.txt.sample3 new file mode 100644 index 0000000000..7d484c182f --- /dev/null +++ b/deal.II/doc/development/CMakeLists.txt.sample3 @@ -0,0 +1,15 @@ +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(step-1 CXX) + +ADD_EXECUTABLE(step-1 step-1.cc) +DEAL_II_SETUP_TARGET(step-1) + +ADD_CUSTOM_TARGET(run COMMAND step-1 + COMMENT "Run with ${CMAKE_BUILD_TYPE} configuration" + ) diff --git a/deal.II/doc/development/cmakelists.html b/deal.II/doc/development/cmakelists.html index 96f699ef46..14f86756c6 100644 --- a/deal.II/doc/development/cmakelists.html +++ b/deal.II/doc/development/cmakelists.html @@ -21,17 +21,13 @@ Table of contents @@ -40,10 +36,6 @@

- - -

Example CMakeLists.txt files

-

cmake is the configuration and build tool we use in deal.II. Its advantage is not only that it makes @@ -59,81 +51,45 @@ 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 + potential use in your projects. (A detailed description of the deal.II project configuration is given in the - deal.II CMake ReadMe. + deal.II CMake ReadMe.)

- -

Simple CMakeLists.txt

+ +

Autopilot style CMakeLists.txt

The easiest way to write a CMakeLists.txt file is to use - an "autopilot" style macro. Here is an example for the step-1 - tutorial program (plain text version) that can be used for simple + 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
+      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
-      ${TARGET}.cc
+      step-1.cc
       # You can specify additional files here!
       )
 
-    #
-    # (Optional)
-    # 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
-      )
-
-    #
-    # (Optional)
-    # 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}
-      )
-
-    #
-    # It is good practice to specify a version requirement:
-    #
     CMAKE_MINIMUM_REQUIRED(VERSION 2.8.8)
-
-    #
-    # Find and import the deal.II project configuration:
-    #
-    FIND_PACKAGE(deal.II 8.0 REQUIRED
-      HINTS
-        ${DEAL_II_DIR} ../ ../../ $ENV{DEAL_II_DIR}
-      #
-      # If the deal.II library cannot be found (because it is not installed at a
-      # default location or your project resides at an uncommon place), you
-      # can specify additional hints for search paths here, e.g.
-      # "$ENV{HOME}/workspace/deal.II"
-      #
-      )
-
-    #
-    # And let deal.II do the rest:
-    #
     DEAL_II_INITIALIZE_CACHED_VARIABLES()
-    PROJECT(${TARGET})
+    PROJECT(${TARGET} CXX)
     DEAL_II_INVOKE_AUTOPILOT()
+ This CMakeLists.txt is intended for use with a small project and in-source build (i.e., one does not create a separate build directory as we recommend for the deal.II build @@ -149,106 +105,123 @@ ### # - # Successfully set up project step-1 with deal.II-8.0.pre found at - # /usr/local + # Successfully set up project step-1 with deal.II-99.99.svn30300 found at + # /usr # - # CMAKE_BUILD_TYPE: Debug - # TARGET_SRC: step-1.cc + # CMAKE_BUILD_TYPE: Debug # # You can now run - # $ make - to compile and link the program - # $ make run - to (compile, link and) run the program + # $ make - to compile and link the program + # $ make run - to (compile, link and) run the program # - # $ make debug - to switch the build type to "Debug" - # $ make release - to switch the build type to "Release" - # $ make edit_cache - to change (cached) configuration variables - # and rerun the configure and generate phases of CMake + # $ make debug - to switch the build type to Debug + # $ make release - to switch the build type to Release # - # $ make clean - to remove the generated executable as well as - # all intermediate compilation files - # $ make runclean - to remove all output generated by the program - # $ make distclean - to clean the directory from _all_ generated - # files (includes clean, runclean and the removal - # of the generated build system) + # $ make edit_cache - to change (cached) configuration variables + # and rerun the configure and generate phases of CMake + # + # $ make strip_comments - strip the source files in this + # directory off the documentation comments + # $ make clean - to remove the generated executable as well as + # all intermediate compilation files + # $ make runclean - to remove all output generated by the program + # $ make distclean - to clean the directory from _all_ generated + # files (includes clean, runclean and the removal + # of the generated build system) + # + # $ make help - to view this message again # # Have a nice day! # ### + 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): + 
+
+    # (Optional)
+    # 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
+      )
+
+    # (Optional)
+    # 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}
+      )
+
+ +

- -

Advanced CMakeLists.txt

+ +

Simple CMakeLists.txt

- For large projects the simple CMakeLists.txt presented - above tends to be too inflexible. - So, if you wish to have more control about targets the - DEAL_II_SETUP_TARGET macro might be of interest for you. - Here is a full example, again using the step-1 tutorial program as a - template: + For larger projects the simple CMakeLists.txt presented + above tends to be too inflexible. So, if you wish to have more + control about targets the DEAL_II_SETUP_TARGET macro + might be of interest for you. Here is a full example, again using the + step-1 tutorial program as a template (plain text version): 

 
-    #
-    # It is good practise to specify a version requirement:
-    #
     CMAKE_MINIMUM_REQUIRED(VERSION 2.8.8)
 
-    #
-    # Find and import the deal.II project configuration:
-    #
     FIND_PACKAGE(deal.II 8.0 REQUIRED
-      HINTS
-        ${DEAL_II_DIR} ../ ../../ $ENV{DEAL_II_DIR}
-      #
-      # If the deal.II library cannot be found (because it is not installed at a
-      # default location or your project resides at an uncommon place), you
-      # can specify additional hints for search paths here, e.g.
-      # "$ENV{HOME}/workspace/deal.II"
-      #
+      HINTS ${DEAL_II_DIR} ../ ../../ $ENV{DEAL_II_DIR}
       )
 
-    #
-    # Initialize cached variables: This will set the compiler and
-    # compiler flags to the values deal.II was configured with, as well as,
-    # CMAKE_BUILD_TYPE to "Debug".
-    # These values can be altered by editing the cache via
-    #   $ make edit_cache
-    #
     DEAL_II_INITIALIZE_CACHED_VARIABLES()
+    PROJECT(step-1 CXX)
 
-    #
-    # PROJECT has to be called after DEAL_II_INITIALIZE_CACHED_VARIABLES
-    # otherwise CMake will have already set the compiler and compiler
-    # flags.
-    #
-    PROJECT(step-1)
-
-    #
-    # Specify a target:
-    #
     ADD_EXECUTABLE(step-1 step-1.cc)
-
-    #
-    # DEAL_II_SETUP_TARGET will set up all necessary include paths,
-    # preprocessor definitions and the link interface:
-    #
     DEAL_II_SETUP_TARGET(step-1)
+
+ TODO: Explain the two macros! + + TODO: Optionally, specify a run target: + 
 
-    #
     # (Optional)
     # If you wish to have a "run" target for make, specify one:
-    #
-    ADD_CUSTOM_TARGET(run
-      COMMAND step-1
-      COMMENT "Run ${TARGET} with ${CMAKE_BUILD_TYPE} configuration"
+    ADD_CUSTOM_TARGET(run COMMAND step-1
+      COMMENT "Run with ${CMAKE_BUILD_TYPE} configuration"
       )
+ TODO: More in the next section

- -

Advanced setup for deal.II in a CMake project

+ + +

Advanced CMakeLists.txt

+ + 
+
+    TODO: 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

@@ -283,190 +256,19 @@

- -

deal.IIConfig.cmake

+ +

deal.IIConfig.cmake

Importing the deal.IIConfig.cmake file via FIND_PACKAGE - will set a bunch of variables and macros; all of the form - DEAL_II_*. There is the usual duplet: + will set the following variables and macros; all of the form + DEAL_II_*: 

 
-    DEAL_II_INCLUDE_DIRS
-    DEAL_II_LIBRARIES
-
- (with debug and optimized keywords. For - compatibility there is also DEAL_II_LIBRARIES_DEBUG - and DEAL_II_LIBRARIES_RELEASE only specifying the - respective set of libraries.) -

- -

- Interesting additional variables might be: - 

+      TODO: A long list with detailed explanation...
 
-    DEAL_II_USER_DEFINITIONS
-    DEAL_II_USER_DEFINITIONS_DEBUG
-    DEAL_II_USER_DEFINITIONS_RELEASE
-    DEAL_II_LINKER_FLAGS
-    DEAL_II_LINKER_FLAGS_DEBUG
-    DEAL_II_LINKER_FLAGS_RELEASE
-    DEAL_II_CXX_FLAGS
-    DEAL_II_CXX_FLAGS_DEBUG
-    DEAL_II_CXX_FLAGS_RELEASE
-
-    DEAL_II_TARGET_CONFIG
-    DEAL_II_TARGET
-    DEAL_II_TARGET_DEBUG
-    DEAL_II_TARGET_RELEASE
-

- - - - -

Setting up necessary configuration variables

- -

- For actually using deal.II in your CMake - project some configuration steps are necessary. These can be - either set via macros or by hand: -

    -
  1. Configuration with the help of - two convencience macros: -

    - deal.IIConfig.cmake includes some convenience macros - to automatically setup all necessary configuration. A fully - functional, minimal example for the step-1 tutorial program is: - 

    -
-    FIND_PACKAGE(deal.II REQUIRED)
-
-    DEAL_II_INITIALIZE_CACHED_VARIABLES()
-
-    PROJECT(step-1)
-
-    ADD_EXECUTABLE(step-1 step-1.cc)
-    DEAL_II_SETUP_TARGET(step-1)
-
    -

    - - -
  2. Configuration by hand: -
      -
    • Set up all include directories for header files: - 
      -
-    INCLUDE_DIRECTORIES(${DEAL_II_INCLUDE_DIRS})
-
      - -
    • - deal.II usually ships with an optimized Release and a Debug version - of the library. So it is a good idea to set up - CMAKE_BUILD_TYPE accordingly: - 
      -
-    SET(CMAKE_BUILD_TYPE "Debug" CACHE
-      "Choose the type of build, options are: Debug, Release"
-      )
-
      - - A cached variable ensures that we can later switch the build type - by editing the cache: - 
      -
-    make edit_cache
-
      - -
    • Often, it is a good idea to use the same compiler and linker - flags as the deal.II library. - 
      -
-    SET(CMAKE_CXX_FLAGS ${DEAL_II_CXX_FLAGS})
-    SET(CMAKE_CXX_FLAGS_RELEASE ${DEAL_II_CXX_FLAGS_RELEASE})
-    SET(CMAKE_CXX_FLAGS_DEBUG ${DEAL_II_CXX_FLAGS_DEBUG})
-
      - (Optionally you can set up the variables with the - CACHE to be able to edit them via ccmake or - make edit_cache.) - -
    • - After this, specify your project name: - 
      -
-    PROJECT(myProject)
-
      - This ensures that the compiler detection and platform setup - that is issued by calling PROJECT(...) will run - after we have set up our cached variables. This way it is - our choice of variables that will be set and not the default - values determined by the PROJECT(...) call. - -
    • - After defining your targets, e.g. - 
      -
-    ADD_EXECUTABLE(step-1 step-1.cc)
-
      - you have to specify to link against deal.II and all external - libraries: - 
      -
-    TARGET_LINK_LIBRARIES(step-1 ${DEAL_II_LIBRARIES})
-
      - -
    • as well as using some preprocessor definitions: - 
      -
-    SET_TARGET_PROPERTIES(step-1 PROPERTIES
-      COMPILE_DEFINITIONS
-      "${DEAL_II_USER_DEFINITIONS}"
-      COMPILE_DEFINITIONS_DEBUG
-      "${DEAL_II_USER_DEFINITIONS_DEBUG}"
-      COMPILE_DEFINITIONS_RELEASE
-      "${DEAL_II_USER_DEFINITIONS_RELEASE}"
-      )
-
      - -
    • Optionally, you can set the link flags to the one used by the - deal.II library: - 
      -
-    SET_TARGET_PROPERTIES(step-1 PROPERTIES
-      LINK_FLAGS
-      "${DEAL_II_LINKER_FLAGS}"
-      LINK_FLAGS_DEBUG
-      "${DEAL_II_LINKER_FLAGS_DEBUG}"
-      LINK_FLAGS_RELEASE
-      "${DEAL_II_LINKER_FLAGS_RELEASE}"
-      )
-
      - And this it is. - -
    - -
  3. - Exported targets: -

    - For an advanced setup in a big CMake project - deal.IIConfig.cmake - provides information about the deal.II - installation with traditional variables, see - here, as well as external CMake - targets with link interface for direct inclusion: - 

    -
-    INCLUDE(${DEAL_II_TARGET_CONFIG})
-
-    ADD_EXECUTABLE(step-1
-      step-1.cc
-      ${DEAL_II_TARGET}
-      )
-
    -

    -