]> https://gitweb.dealii.org/ - dealii-svn.git/commitdiff
Doc: Update CMake documentation. Add a section about configuration and
authormaier <maier@0785d39b-7218-0410-832d-ea1e28bc413d>
Sat, 5 Oct 2013 15:03:16 +0000 (15:03 +0000)
committermaier <maier@0785d39b-7218-0410-832d-ea1e28bc413d>
Sat, 5 Oct 2013 15:03:16 +0000 (15:03 +0000)
building, reflect recent changes

git-svn-id: https://svn.dealii.org/branches/branch_port_the_testsuite@31148 0785d39b-7218-0410-832d-ea1e28bc413d

deal.II/cmake/setup_finalize.cmake
deal.II/doc/users/cmake.html

index 8e7fda24ce6a0e4037163f71595159c18f6679b7..ed18ccc6b683ea110833d0720aef98e9745684f1 100644 (file)
@@ -263,7 +263,7 @@ ENDFOREACH()
 
 _summary(
 "#\n#  Detailed information (compiler flags, feature configuration) can be found in detailed.log
-#\n#  Run  $ make info  to print a help messa, or  $ make help  for a list of top level targets\n"
+#\n#  Run  $ make info  to print a help message with a list of top level targets\n"
   )
 
 _both("#\n###")
index 5524e0eda842817c4f559c5489289c73eab202f5..37fce5e748accec64aef5679ea4133fb6e6358e1 100644 (file)
             <li><a href="#operatingshortcuts">Shortcuts</a></li>
          </ol>
        </li>
+       <li><a href="#build">Configuring and Building deal.II</a>
+          <ol>
+            <li><a href="#buildtargets">Primary build targets</a></li>
+            <li><a href="#buildinformation">Information about current configuration</a></li>
+            <li><a href="#buildinsource">Out-of-source versus in-source builds</a></li>
+            <li><a href="#buildgenerator">CMake Generators</a></li>
+            <li><a href="#buildinstall">Installation</a></li>
+         </ol>
+        </li>
        <li><a href="#configure">Configuration options</a>
          <ol>
            <li><a href="#configurefeature">Feature configuration</a></li>
@@ -49,7 +58,7 @@
        <li><a href="#compiling">Compiling only certain parts</a></li>
       </ol>
     </div>
-    
+
     <a name="operating"></a>
     <h2>Operating cmake</h2>
 
       will be expanded to the full <code>DEAL_II_COMPONENT_*</code> variable name).
     </p>
 
+
+
+    <a name="build"></a>
+    <h2>Configuring and Building deal.II</h2>
+
+    <p>
+      This section provides some further details and advanced topics with
+      respect to configuration and building that is not covered in the <a
+      href="../readme.html" target="body">README</a>.
+    </p>
+
+    <a name="buildtargets"></a>
+    <h3>Primary build targets</h3>
+
+    <p> The current list of primary build targets can be queried via
+    <code>make info</code>:
+      <pre>
+
+    ###
+    #
+    #  The following targets are available (invoke via $ make &lt;target&gt;):
+    #
+    #    all            - compiles the library and all enabled components
+    #    clean          - removes all generated files
+    #    install        - installs into CMAKE_INSTALL_PREFIX
+    #    help           - prints a list of valid top level targets
+    #    info           - prints this help message
+    #
+    #    edit_cache     - runs ccmake for changing (cached) configuration variables
+    #                     and reruns the configure and generate phases of CMake
+    #    rebuild_cache  - reruns the configure and generate phases of CMake
+    #
+    #    compat_files   - builds and installs the 'compat_files' component
+    #    documentation  - builds and installs the 'documentation' component
+    #    examples       - builds and installs the 'examples' component
+    #    library        - builds and installs the 'library' component
+    #    mesh_converter - builds and installs the 'mesh_converter' component
+    #    parameter_gui  - builds and installs the 'parameter_gui' component
+    #
+    #    test           - runs a minimal set of tests
+    #
+    #    setup_test     - sets up the testsuite subprojects
+    #    clean_test     - runs the 'clean' target in every testsuite subproject
+    #    prune_test     - removes all testsuite subprojects
+    #
+    ###
+      </pre>
+
+
+    <a name="buildinformation"></a>
+    <h3>Information about current configuration</h3>
+
+    <p>
+      A configuration run of <code>cmake</code> (or <code>ccmake</code>)
+      writes a short summary of the current configuration into
+      <code>CMAKE_BUILD_DIR/summary.log</code>:
+      <pre>
+
+    ###
+    #
+    #  deal.II configuration:
+    #        CMAKE_BUILD_TYPE:       DebugRelease
+    #        BUILD_SHARED_LIBS:      ON
+    #        CMAKE_INSTALL_PREFIX:   /tmp/deal.II/install
+    #        CMAKE_SOURCE_DIR:       /tmp/deal.II/deal.II (Version 8.1.pre)
+    #        CMAKE_BINARY_DIR:       /tmp/deal.II/build
+    #        CMAKE_CXX_COMPILER:     GNU 4.7.3 on platform Linux x86_64
+    #                                /usr/bin/c++
+    #
+    #  Configured Features (DEAL_II_ALLOW_BUNDLED = ON, DEAL_II_ALLOW_AUTODETECTION = ON):
+    #      ( DEAL_II_WITH_64BIT_INDICES = OFF )
+    #        DEAL_II_WITH_ARPACK set up with external dependencies
+    #        DEAL_II_WITH_BOOST set up with external dependencies
+    #        [...]
+    #
+    #  Component configuration:
+    #        DEAL_II_COMPONENT_COMPAT_FILES
+    #      ( DEAL_II_COMPONENT_DOCUMENTATION = OFF )
+    #        DEAL_II_COMPONENT_EXAMPLES
+    #        DEAL_II_COMPONENT_MESH_CONVERTER
+    #      ( DEAL_II_COMPONENT_PARAMETER_GUI = OFF )
+    #
+    #  Detailed information (compiler flags, feature configuration) can be found in detailed.log
+    #
+    #  Run  $ make info  to print a help message with a list of top level targets
+    #
+    ###
+      </pre>
+      This summary is also printed at the end of the configuration phase.
+      It tells you about build and install directory locations, feature
+      configuration (whether a feature is enabled with external/internal
+      dependencies, disabled or forced) and component configuration.
+      A more detailed version can be found in
+      <code>CMAKE_BUILD_DIR/detailed.log</code> that also includes detailed
+      information about feature configuration, e.g.
+      <pre>
+
+    #        DEAL_II_WITH_BOOST set up with external dependencies
+    #            BOOST_VERSION = 1.52.0
+    #            BOOST_DIR = 
+    #            Boost_INCLUDE_DIRS = /usr/include
+    #            Boost_LIBRARIES = /usr/lib64/libboost_serialization-mt.so;/usr/lib64/libboost_system-mt.so;
+    # [...]
+      </pre>
+      If this information is not sufficient, you might want to have a look
+      at the following files in <code>CMAKE_BUILD_DIR</code>
+      <ul>
+        <li><code>CMakeCache.txt</code>: The file CMake stores its cached
+        variables in. Do not change directly.
+        <li><code>include/deal.II/base/config.h</code>: The generated
+        config.h file
+        <li><code>lib/cmake/deal.II/deal.IIConfig.cmake</code>: The project
+        configuration file for external projects.
+      </ul>
+    </p>
+
+
+
+    <a name="buildinsource"></a>
+    <h3>Out-of-source versus in-source builds</h3>
+
+    <p>
+      A so called out-of-source build is a setup where the build directory
+      (the directory containing intermediate and generated files) is
+      different from the source directory (the directory containing the
+      source code). With CMake an out-of-source build is set up by invoking
+      <code>cmake</code> (or <code>ccmake</code>) from the designated build
+      directory, so for example (a build directory under the source
+      directory):
+      <pre>
+
+      $ mkdir build
+      $ cd build
+      $ cmake ..
+      </pre>
+      The big advantage is that source files and intermediate files are
+      strictly separated (highly desired for version control) and that you
+      can have multiple build directories (with different configuration) at
+      the same time.
+    </p>
+
+    <p>
+      <b>Note:</b> However, under rare occasions an in-source build might be
+      useful or needed , so it is supported
+      <pre>
+
+      $ cmake .
+      </pre>
+      But we highly discourage it!
+    </p>
+
+    <a name="buildgenerator"></a>
+    <h3>CMake Generators</h3>
+
+    <p>
+      Cmake is a <i>Makefile Generator</i>. This allows to switch the
+      generator that is used to something different. If you for example want
+      to automatically generate an Eclipse project of deal.II, you can run
+      <pre>
+
+      $ cmake -G"Eclipse CDT4 - Unix Makefiles" [...]
+      </pre>
+      and load up the build directory as a project directly into Eclipse.
+      Have a look at the <a href="https://code.google.com/p/dealii/w/list"
+      target="_top">Wiki</a> for more information.
+    </p>
+
+    <p>
+      An interesting alternative to (GNU) Make might also be <a
+      href="http://martine.github.io/ninja/">Ninja</a>. Configure via
+      <pre>
+
+      $ cmake -GNinja [...]
+      </pre>
+      and run <code>ninja</code> instead of <code>make</code>.
+    </p>
+
+
+    <a name="buildinstall"></a>
+    <h3>Installation</h3>
+
+    <p>
+      It is not necessary to install the library in order to use deal.II.
+      Invoking the <code>all</code> or <code>library</code> target will
+      compile the library and set up all necessary configuration in the
+      build directory so that external projects can directly use it.
+      However, we strongly recommend to proceed in the way explained in the
+      <a href="../readme.html" target="body">README</a> and install the
+      library to a designated install directory (different from source and
+      build directory).
+    </p>
+
+    <p>
+      For installing the library it is necessary to set the CMake variable
+      <code>CMAKE_INSTALL_PREFIX</code> to the designated install
+      directory. You can do this by invoking <code>cmake</code> together
+      with <code>-DCMAKE_INSTALL_PREFIX=&lt;...&gt;</code> or by invoking
+      <code>ccmake</code>.
+    </p>
+
+    <p>
+      <b>Note:</b> When you don't install deal.II to an install directory
+      and use it directly from a build directory,
+      both, the build <i>and</i> source directories have to be kept.
+    </p>
+
+    <p>
+      <b>Note:</b> It is not necessary for the source, build and or install
+      directory to be different. All combinations are supported.
+    </p>
+
+
+    <h4>Install a single component</h4>
+
+    <p>
+      If you want to only generate, compile and install a specific
+      component (most notably the documentation) you can use one of the
+      following top level targets:
+      <pre>
+
+    compat_files   - builds and installs the 'compat_files' component
+    documentation  - builds and installs the 'documentation' component
+    examples       - builds and installs the 'examples' component
+    library        - builds and installs the 'library' component
+    mesh_converter - builds and installs the 'mesh_converter' component
+    parameter_gui  - builds and installs the 'parameter_gui' component
+      </pre>
+
+
     <a name="configure"></a>
     <h2>Configuration options</h2>
 
     </p>
 
 
+
     <a name="configurefeature"></a>
     <h3>Feature configuration</h3>
 
     <h3> Installation </h3>
 
     <p>
-      the location,
-      where the <acronym>deal.II</acronym> library will be
-      installed to is set with the help of
+      the location, where the <acronym>deal.II</acronym> library will be
+      installed when invoking <code>make install</code> to is set with the
+      help of
       <pre>
 
     CMAKE_INSTALL_PREFIX
 
       Please note that depending on whether
       <code>DEAL_II_COMPONENT_COMPAT_FILES</code> is set, there will be
-      different directory structures:
+      a different default directory structure:
       <ul>
        <li>
           With <code>DEAL_II_COMPONENT_COMPAT_FILES=ON</code>:
     </p>
 
     <p>
-      The individual target directories can be overwritten by setting the
+      The default directory structure can be changed by by setting the
       following variables:
       <pre>
 
       library. Rather, <code>make install</code> will still want to have both
       libraries up to date and will therefore invoke <code>make all</code>
       automatically. To restrict builds in such a way that only one library
-      will be installed, see <a href="#configurebuild">this section</a>.
+      will be installed, see <a href="#configurebuild">configuration</a>
+      and <a href="#buildinstall">installation</a> sections.
     </p>
 
     <hr />

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.