]> https://gitweb.dealii.org/ - dealii-svn.git/commitdiff
Finalize the documentation
authormaier <maier@0785d39b-7218-0410-832d-ea1e28bc413d>
Sun, 11 Nov 2012 13:58:24 +0000 (13:58 +0000)
committermaier <maier@0785d39b-7218-0410-832d-ea1e28bc413d>
Sun, 11 Nov 2012 13:58:24 +0000 (13:58 +0000)
git-svn-id: https://svn.dealii.org/branches/branch_cmake@27502 0785d39b-7218-0410-832d-ea1e28bc413d

deal.II/CMakeLists.txt
deal.II/TODO.CMAKE
deal.II/cmake/config/Make.global_options.in
deal.II/doc/development/CMakeLists.txt.example [new file with mode: 0644]
deal.II/doc/development/cmake.html
deal.II/doc/development/cmakelists.html [new file with mode: 0644]
deal.II/doc/development/svn.html
deal.II/doc/development/toc.html
deal.II/doc/readme.html

index 19087316baf76e84657285533b2ea1ac81eae479..272ed6682f0f96796d4e6b66d786627efdfe5c2f 100644 (file)
@@ -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.            #
 #                                                                         #
 ##                                                                       ##
 
index 0000750470ddc022a6cf647bd3bd54f45cde8583..dd2cfa6abdd3dbf71380b2e5e21b31dae13e4d2f 100644 (file)
@@ -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
index cd03ed040bf9bf2e5c0068925a038cc7b2bc23e2..7f34e20468d950b45305486a098180f0e5f59ac5 100644 (file)
@@ -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 (file)
index 0000000..0aa72d7
--- /dev/null
@@ -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()
+
index d4bb49b7cf56838bf93323f757549eedd3a7fa16..ff5c7d85c76de34633c261f61429c276c70bcd3b 100644 (file)
@@ -5,7 +5,7 @@
     <title>The deal.II Readme</title>
     <link href="../screen.css" rel="StyleSheet">
     <meta name="author" content="the deal.II authors <authors @ dealii.org>">
-    <meta name="copyright" content="Copyright (C) 1999, 2000, 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010, 2011, 2012 by the deal.II authors">
+    <meta name="copyright" content="Copyright (C) 2012 by the deal.II authors">
     <meta name="date" content="$Date$">
     <meta name="svn_id" content="$Id$">
     <meta name="keywords" content="deal.II">
diff --git a/deal.II/doc/development/cmakelists.html b/deal.II/doc/development/cmakelists.html
new file mode 100644 (file)
index 0000000..dedd267
--- /dev/null
@@ -0,0 +1,263 @@
+<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN"
+         "http://www.w3.org/TR/html4/loose.dtd">
+<html>
+  <head>
+    <title>The deal.II Readme</title>
+    <link href="../screen.css" rel="StyleSheet">
+    <meta name="author" content="the deal.II authors <authors @ dealii.org>">
+    <meta name="copyright" content="Copyright (C) 2012 by the deal.II authors">
+    <meta name="date" content="$Date$">
+    <meta name="svn_id" content="$Id$">
+    <meta name="keywords" content="deal.II">
+  </head>
+
+  <body>
+
+    <h1>How to interface with <acronym>deal.II</acronym> in your own
+      project</h1>
+
+    <p>
+    <table class="tutorial" width="50%">
+      <tr><th colspan="2"><b><small>Table of contents</small></b></th></tr>
+      <tr><td valign="top">
+         <ul>
+            <li><a href="#cmake">Using <acronym>deal.II</acronym> in a
+              CMake project</a>
+             <ul>
+                <li><a href="#cmakesimple">Simple CMakeLists.txt</a>
+                <li><a href="#cmakeadvanced">Advanced CMakeLists.txt</a>
+             </ul>
+            <li><a href="#legacy">Legacy
+              <code>Make.global_options</code></a>
+         </ul>
+       </td>
+      </tr>
+    </table>
+    </p>
+
+
+    <a name="cmake"></a>
+    <h3> Using <acronym>deal.II</acronym> in a CMake project </h3>
+
+    <p>
+      This section presents some <code>CMakeLists.txt</code> examples for
+      potential use in your projects. A detailed description of the
+      <acronym>deal.II</acronym> project configuration is given in the 
+      <a href="cmake.html#ext" target="body">deal.II CMake ReadME</a>.
+    </p>
+
+    <a name="cmakesimple"></a>
+    <h4>Simple CMakeLists.txt</h4>
+
+    <p>
+      The easiest way to write a <code>CMakeLists.txt</code> file is to use
+      an "autopilot" style macro which mimics the old user
+      <code>Makefile</code> behaviour. Here is an example for the step-1
+      tutorial program: (<a href="CMakeLists.txt.example" target="_top">raw</a> version.)
+      <pre>
+
+    #
+    # 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()
+      </pre>
+
+      This <code>CMakeLists.txt</code> is intended for use with a small
+      project and <i>in-source</i> build:
+      <pre>
+
+    $ 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!
+    #
+    ###
+      </pre>
+    </p>
+
+    <a name="cmakeadvanced"></a>
+    <h4>Advanced CMakeLists.txt</h4>
+
+    <p>
+      For large projects the simple <code>CMakeLists.txt</code> presented
+      above tends to be too inflexible.
+      So, if you wish to have more control about targets the
+      <code>DEAL_II_SETUP_TARGET</code> macro might be of interest for you.
+      Here is a full example for the step-1 tutorial program:
+      <pre>
+
+    #
+    # 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"
+      )
+      </pre>
+
+    Further details can be found in the <a href="cmake.html#ext"
+      target="body">deal.II CMake ReadME</a>.
+   </p>
+
+    <a name="legacy"></a>
+    <h3> Legacy Make.global_options </h3>
+
+    <p>
+      The CMake build system sets up the following compatibility files (if
+      <code>DEAL_II_COMPONENT_COMPAT_FILES</code> is set, which is default):
+      <pre>
+
+    ${CMAKE_INSTALL_PREFIX}
+        ./common/Make.global_options
+        ./common/scripts/expand_instantiations
+        ./common/scripts/make_dependencies
+        ./common/scripts/report_features
+      </pre>
+
+      Therefore, it should be sufficient to set <code>D</code> in the old
+      user Makefiles to:
+      <pre>
+
+    D=/path/install/dir
+      </pre>
+      where <code>/path/install/dir</code> is the directory set up via
+      <code>CMAKE_INSTALL_PREFIX</code> (the path
+      <acronym>deal.II</acronym> was installed to).
+    </p>
+
+
+
+    <hr>
+
+    <address>
+      <a href="mail.html" target="body">The deal.II Group</a>
+      $Date$
+    </address>
+  </body>
+</html>
index 6df44fcfe932fa8ca46e60dd00e804d435eaefae..712ac50631fd2b7d159bf15a9b1106c75890745f 100644 (file)
   <ol>
     <li> Create the branch using
       <pre>
+
        svn copy http://www.dealii.org/svn/dealii/trunk/ http://www.dealii.org/svn/dealii/branches/new-branch-name
       </pre>
 
     <li> Either check out the new branch or switch your working copy by
       <pre>
+
        svn switch http://www.dealii.org/svn/dealii/branches/new-branch-name
       </pre>
       This command assumes you are in the top level directory, the one
@@ -74,6 +76,7 @@
     <li> 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:
       <pre>
+
        svn merge ^/trunk
       </pre>
       This command will only run if you have no local changes in your working
index eef63e99a12e3909219af95d536f343b3e6bdc5b..5bcdf928c26cb2613609a18ab71f0b05d2586a7b 100644 (file)
@@ -41,7 +41,7 @@
          This page provides extensive information about usage and
          development of the <acronym>deal.II</acronym> CMake build system.
 
-    <li> <p><a href="cmakefiles.html" target="body">Example CMakefiles</a>:
+    <li> <p><a href="cmakelists.html" target="body">Example CMakeLists.txt</a>:
          TODO
          </p>
 
index 3fec4fda7e3fd60d3e10e85aa8c40916ba43d9ea..e381fb88bed86cef188704490a744ba066193cf3 100644 (file)
@@ -79,7 +79,7 @@
                 target="_top">deal.II Wiki</a>!
       </ul>
       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.
     </p>
 

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.