From 384a1a928163df5a79728fedd2d026deb08fb531 Mon Sep 17 00:00:00 2001 From: Matthias Maier Date: Sat, 5 Oct 2013 15:03:16 +0000 Subject: [PATCH] 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 --- deal.II/cmake/setup_finalize.cmake | 2 +- deal.II/doc/users/cmake.html | 254 ++++++++++++++++++++++++++++- 2 files changed, 248 insertions(+), 8 deletions(-) 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. +
    3. Information about current configuration
    4. +
    5. Out-of-source versus in-source builds
    6. +
    7. CMake Generators
    8. +
    9. Installation
    10. +
    +
  • Configuration options
    1. Feature configuration
    2. @@ -49,7 +58,7 @@
    3. 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.
           


      -- 2.39.5