From: maier Date: Sun, 11 Nov 2012 13:58:24 +0000 (+0000) Subject: Finalize the documentation X-Git-Url: https://gitweb.dealii.org/cgi-bin/gitweb.cgi?a=commitdiff_plain;h=e9f3c6bd53e2174c805fe250d248f3c8f72cf2d4;p=dealii-svn.git Finalize the documentation git-svn-id: https://svn.dealii.org/branches/branch_cmake@27502 0785d39b-7218-0410-832d-ea1e28bc413d --- diff --git a/deal.II/CMakeLists.txt b/deal.II/CMakeLists.txt index 19087316ba..272ed6682f 100644 --- a/deal.II/CMakeLists.txt +++ b/deal.II/CMakeLists.txt @@ -16,8 +16,8 @@ # # # The cmake build system for the deal.II project # # # -# See README.cmake for further details on how to use the cmake build # -# system of deal.II. # +# See doc/readme.html and doc/development/cmake.html for further # +# details on how to use the cmake build system of deal.II. # # # ## ## diff --git a/deal.II/TODO.CMAKE b/deal.II/TODO.CMAKE index 0000750470..dd2cfa6abd 100644 --- a/deal.II/TODO.CMAKE +++ b/deal.II/TODO.CMAKE @@ -1,4 +1,4 @@ -Major: +Minor: * The documentation @@ -6,12 +6,6 @@ Major: (WB: actually, no -- this is a change that should happen on mainline once we have migrated the whole wiki) - - Write a page on how to use deal.II in external CMake projects. - (doc/development/toc.html already links to it) - (A more detailed copy of what is already standing in cmake.html) - -Minor: - * The following feature has to be written: TECPLOT * Fixup the TODOs in diff --git a/deal.II/cmake/config/Make.global_options.in b/deal.II/cmake/config/Make.global_options.in index cd03ed040b..7f34e20468 100644 --- a/deal.II/cmake/config/Make.global_options.in +++ b/deal.II/cmake/config/Make.global_options.in @@ -7,12 +7,8 @@ ############################################################################### ## Please note: ## -## This is a compatibility Make.global_options file generated by cmake -## from the ./config/Make.global_options.in file. -## -## TODO: -## This file exports several variables. They are documented in -## the file doc/development/makefiles.html. +## This is a compatibility Make.global_options file generated by CMake +## from the ./cmake/config/Make.global_options.in file. ## ############################################################################### diff --git a/deal.II/doc/development/CMakeLists.txt.example b/deal.II/doc/development/CMakeLists.txt.example new file mode 100644 index 0000000000..0aa72d7f36 --- /dev/null +++ b/deal.II/doc/development/CMakeLists.txt.example @@ -0,0 +1,62 @@ +## ## +# 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 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_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/cmake.html b/deal.II/doc/development/cmake.html index d4bb49b7cf..ff5c7d85c7 100644 --- a/deal.II/doc/development/cmake.html +++ b/deal.II/doc/development/cmake.html @@ -5,7 +5,7 @@ The deal.II Readme - + diff --git a/deal.II/doc/development/cmakelists.html b/deal.II/doc/development/cmakelists.html new file mode 100644 index 0000000000..dedd267598 --- /dev/null +++ b/deal.II/doc/development/cmakelists.html @@ -0,0 +1,263 @@ + + + + The deal.II Readme + + + + + + + + + + +

How to interface with deal.II in your own + project

+ +

+ + + + +
Table of contents
+ +
+

+ + + +

Using deal.II in a CMake project

+ +

+ This section 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

+ +

+ The easiest way to write a CMakeLists.txt file is to use + an "autopilot" style macro which mimics the old user + Makefile behaviour. Here is an example for the step-1 + tutorial program: (raw version.) +

+
+    #
+    # 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 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_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()
+      
+ + This CMakeLists.txt is intended for use with a small + project and in-source build: +
+
+    $ cd step-1
+    $ cmake .
+
+    [...]
+
+    ###
+    #
+    #  Successfully set up project  step-1  with  deal.II-8.0.pre  found at
+    #      /usr/local
+    #
+    #  CMAKE_BUILD_TYPE:   Debug
+    #  TARGET_SRC:         step-1.cc
+    #
+    #  You can now run
+    #      $ 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 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)
+    #
+    #  Have a nice day!
+    #
+    ###
+      
+

+ + +

Advanced 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 for the step-1 tutorial program: +

+
+    #
+    # 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_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"
+      #
+      )
+
+    #
+    # 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 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)
+
+    #
+    # (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"
+      )
+      
+ + Further details can be found in the deal.II CMake ReadME. +

+ + +

Legacy Make.global_options

+ +

+ The CMake build system sets up the following compatibility files (if + DEAL_II_COMPONENT_COMPAT_FILES is set, which is default): +

+
+    ${CMAKE_INSTALL_PREFIX}
+        ./common/Make.global_options
+        ./common/scripts/expand_instantiations
+        ./common/scripts/make_dependencies
+        ./common/scripts/report_features
+      
+ + Therefore, it should be sufficient to set D in the old + user Makefiles to: +
+
+    D=/path/install/dir
+      
+ where /path/install/dir is the directory set up via + CMAKE_INSTALL_PREFIX (the path + deal.II was installed to). +

+ + + +
+ +
+ The deal.II Group + $Date$ +
+ + diff --git a/deal.II/doc/development/svn.html b/deal.II/doc/development/svn.html index 6df44fcfe9..712ac50631 100644 --- a/deal.II/doc/development/svn.html +++ b/deal.II/doc/development/svn.html @@ -61,11 +61,13 @@
  1. Create the branch using
    +
     	svn copy http://www.dealii.org/svn/dealii/trunk/ http://www.dealii.org/svn/dealii/branches/new-branch-name
           
  2. Either check out the new branch or switch your working copy by
    +
     	svn switch http://www.dealii.org/svn/dealii/branches/new-branch-name
           
    This command assumes you are in the top level directory, the one @@ -74,6 +76,7 @@
  3. After some development of the branch, if you want to merge changes that have been made on mainline in the meantime, you can use this command:
    +
     	svn merge ^/trunk
           
    This command will only run if you have no local changes in your working diff --git a/deal.II/doc/development/toc.html b/deal.II/doc/development/toc.html index eef63e99a1..5bcdf928c2 100644 --- a/deal.II/doc/development/toc.html +++ b/deal.II/doc/development/toc.html @@ -41,7 +41,7 @@ This page provides extensive information about usage and development of the deal.II CMake build system. -
  4. Example CMakefiles: +

  5. Example CMakeLists.txt: TODO

    diff --git a/deal.II/doc/readme.html b/deal.II/doc/readme.html index 3fec4fda7e..e381fb88be 100644 --- a/deal.II/doc/readme.html +++ b/deal.II/doc/readme.html @@ -79,7 +79,7 @@ target="_top">deal.II Wiki! Most other combinations of POSIX-style operating systems and C++ - standards compliant compilers should also work. If they don't, please + Standard compliant compilers should also work. If they don't, please report it as a bug.