From: Matthias Maier Date: Sat, 5 Oct 2013 15:03:16 +0000 (+0000) Subject: Doc: Update CMake documentation. Add a section about configuration and X-Git-Tag: v8.1.0~570^2~101 X-Git-Url: https://gitweb.dealii.org/cgi-bin/gitweb.cgi?a=commitdiff_plain;h=384a1a928163df5a79728fedd2d026deb08fb531;p=dealii.git Doc: Update CMake documentation. Add a section about configuration and building, reflect recent changes git-svn-id: https://svn.dealii.org/branches/branch_port_the_testsuite@31148 0785d39b-7218-0410-832d-ea1e28bc413d --- diff --git a/deal.II/cmake/setup_finalize.cmake b/deal.II/cmake/setup_finalize.cmake index 8e7fda24ce..ed18ccc6b6 100644 --- a/deal.II/cmake/setup_finalize.cmake +++ b/deal.II/cmake/setup_finalize.cmake @@ -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###") diff --git a/deal.II/doc/users/cmake.html b/deal.II/doc/users/cmake.html index 5524e0eda8..37fce5e748 100644 --- a/deal.II/doc/users/cmake.html +++ b/deal.II/doc/users/cmake.html @@ -33,6 +33,15 @@
  • Shortcuts
    • +
  • Configuring and Building deal.II +
      +
    1. Primary build targets
      2. +
    2. Information about current configuration
      3. +
    3. Out-of-source versus in-source builds
      4. +
    4. CMake Generators
      5. +
    5. Installation
      6. +
    +
  • Configuration options
    1. Feature configuration
      2. @@ -49,7 +58,7 @@
    2. Compiling only certain parts
    - +

    Operating cmake

    @@ -194,6 +203,235 @@ will be expanded to the full DEAL_II_COMPONENT_* variable name).

    + + + +

    Configuring and Building deal.II

    + +

    + This section provides some further details and advanced topics with + respect to configuration and building that is not covered in the README. +

    + + +

    Primary build targets

    + +

    The current list of primary build targets can be queried via + make info: + 

    +
+    ###
+    #
+    #  The following targets are available (invoke via $ make <target>):
+    #
+    #    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
+    #
+    ###
+
    + + + +

    Information about current configuration

    + +

    + A configuration run of cmake (or ccmake) + writes a short summary of the current configuration into + CMAKE_BUILD_DIR/summary.log: + 

    +
+    ###
+    #
+    #  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
+    #
+    ###
+
    + 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 + CMAKE_BUILD_DIR/detailed.log that also includes detailed + information about feature configuration, e.g. + 
    +
+    #        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;
+    # [...]
+
    + If this information is not sufficient, you might want to have a look + at the following files in CMAKE_BUILD_DIR + +

    + + + + +

    Out-of-source versus in-source builds

    + +

    + 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 + cmake (or ccmake) from the designated build + directory, so for example (a build directory under the source + directory): + 

    +
+      $ mkdir build
+      $ cd build
+      $ cmake ..
+
    + 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. +

    + +

    + Note: However, under rare occasions an in-source build might be + useful or needed , so it is supported + 

    +
+      $ cmake .
+
    + But we highly discourage it! +

    + + +

    CMake Generators

    + +

    + Cmake is a Makefile Generator. 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 + 

    +
+      $ cmake -G"Eclipse CDT4 - Unix Makefiles" [...]
+
    + and load up the build directory as a project directly into Eclipse. + Have a look at the Wiki for more information. +

    + +

    + An interesting alternative to (GNU) Make might also be Ninja. Configure via + 

    +
+      $ cmake -GNinja [...]
+
    + and run ninja instead of make. +

    + + + +

    Installation

    + +

    + It is not necessary to install the library in order to use deal.II. + Invoking the all or library 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 + README and install the + library to a designated install directory (different from source and + build directory). +

    + +

    + For installing the library it is necessary to set the CMake variable + CMAKE_INSTALL_PREFIX to the designated install + directory. You can do this by invoking cmake together + with -DCMAKE_INSTALL_PREFIX=<...> or by invoking + ccmake. +

    + +

    + Note: When you don't install deal.II to an install directory + and use it directly from a build directory, + both, the build and source directories have to be kept. +

    + +

    + Note: It is not necessary for the source, build and or install + directory to be different. All combinations are supported. +

    + + +

    Install a single component

    + +

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

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

    Configuration options

    @@ -207,6 +445,7 @@

    +

    Feature configuration

    @@ -687,9 +926,9 @@

    Installation

    - the location, - where the deal.II library will be - installed to is set with the help of + the location, where the deal.II library will be + installed when invoking make install to is set with the + help of 

     
     CMAKE_INSTALL_PREFIX
@@ -697,7 +936,7 @@
 
       Please note that depending on whether
       DEAL_II_COMPONENT_COMPAT_FILES is set, there will be
-      different directory structures:
+      a different default directory structure:
       
      
 	
    • 
           With DEAL_II_COMPONENT_COMPAT_FILES=ON:
@@ -733,7 +972,7 @@
     
      
 
     
      
-      The individual target directories can be overwritten by setting the
+      The default directory structure can be changed by by setting the
       following variables:
       
       
@@ -816,7 +1055,8 @@
       library. Rather, make install will still want to have both
       libraries up to date and will therefore invoke make all
       automatically. To restrict builds in such a way that only one library
-      will be installed, see this section.
+      will be installed, see configuration
+      and installation sections.