Proper dependencies for Doxygen build rules
authorTeemu Murtola <teemu.murtola@gmail.com>
Sun, 14 Sep 2014 04:34:46 +0000 (07:34 +0300)
committerGerrit Code Review <gerrit@gerrit.gromacs.org>
Fri, 19 Sep 2014 15:23:11 +0000 (17:23 +0200)
Now Doxygen build rules only get triggered if a relevant source file has
been changed.  This reduces the need for the -fast targets, and makes it
easier to consume these targets, e.g., in Jenkins without triggering
multiple builds of the XML documentation.

Add CMake helper functions to make using custom commands easier.  These
could be used elsewhere in the build system as well to isolate the
complexity into these functions, but that will be done in separate
changes.

Change-Id: I3411853da1948cd85e80df12b0c51df7d748f8d7

.gitattributes
cmake/gmxCustomCommandUtilities.cmake [new file with mode: 0644]
docs/.gitattributes [new file with mode: 0644]
docs/doxygen/CMakeLists.txt
src/external/.gitattributes

index 584ce56a882ff097b3fd28ea8bdfa7a82fe5e24b..bb30b7748ddf678cfe9713e85498b8f6ed12e598 100644 (file)
@@ -1,8 +1,8 @@
 # Generic rules
-*.c     filter=uncrustify
-*.cpp   filter=uncrustify
+*.c     filter=uncrustify gmx-doxygen
+*.cpp   filter=uncrustify gmx-doxygen
 *.cu    filter=uncrustify
-*.h     filter=uncrustify
+*.h     filter=uncrustify gmx-doxygen
 *.cuh   filter=uncrustify
 CMakeLists.txt  filter=copyright
 *.cmake         filter=copyright
@@ -23,7 +23,8 @@ cmake/FindBLAS.cmake                    !filter
 cmake/FindLAPACK.cmake                  !filter
 cmake/ThreadMPI.cmake                   !filter
 cmake/Platform/BluegeneQ*.cmake         !filter
-cmake/*.c                               !filter
+cmake/*.c                               -filter -gmx-doxygen
+cmake/*.cpp                             -filter -gmx-doxygen
 cmake/*.c.cmakein                       !filter
 docs/doxygen/Doxyfile-*.cmakein         !filter
 docs/doxygen/*.cpp                      !filter
@@ -32,15 +33,16 @@ docs/doxygen/examples/*.c               filter=uncrustify_only
 docs/manual/UseLATEX.cmake              !filter
 scripts/GMXRC.*                         !filter
 scripts/make_gromos_rtp.py              !filter
-src/contrib/*                           !filter
+src/contrib/*                           -filter -gmx-doxygen
+src/external/*                          -filter -gmx-doxygen
 src/gromacs/gmxlib/nonbonded/preprocessor/gmxpreprocess.py !filter
 src/gromacs/linearalgebra/gmx_blas/*    !filter
 src/gromacs/linearalgebra/gmx_lapack/*  !filter
-src/gromacs/selection/parser.cpp        !filter
-src/gromacs/selection/parser.h          !filter
-src/gromacs/selection/scanner.cpp       !filter
-src/gromacs/selection/scanner_flex.h    !filter
-nb_kernel_Elec*                         filter=copyright
+src/gromacs/selection/parser.cpp        -filter -gmx-doxygen
+src/gromacs/selection/parser.h          -filter -gmx-doxygen
+src/gromacs/selection/scanner.cpp       -filter -gmx-doxygen
+src/gromacs/selection/scanner_flex.h    -filter
+nb_kernel_Elec*                         filter=copyright -gmx-doxygen
 nb_kernel*pre                           filter=copyright
 *.eps                                   binary
 *.jpg                                   binary
diff --git a/cmake/gmxCustomCommandUtilities.cmake b/cmake/gmxCustomCommandUtilities.cmake
new file mode 100644 (file)
index 0000000..902fa23
--- /dev/null
@@ -0,0 +1,263 @@
+#
+# This file is part of the GROMACS molecular simulation package.
+#
+# Copyright (c) 2014, by the GROMACS development team, led by
+# Mark Abraham, David van der Spoel, Berk Hess, and Erik Lindahl,
+# and including many others, as listed in the AUTHORS file in the
+# top-level source directory and at http://www.gromacs.org.
+#
+# GROMACS is free software; you can redistribute it and/or
+# modify it under the terms of the GNU Lesser General Public License
+# as published by the Free Software Foundation; either version 2.1
+# of the License, or (at your option) any later version.
+#
+# GROMACS is distributed in the hope that it will be useful,
+# but WITHOUT ANY WARRANTY; without even the implied warranty of
+# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
+# Lesser General Public License for more details.
+#
+# You should have received a copy of the GNU Lesser General Public
+# License along with GROMACS; if not, see
+# http://www.gnu.org/licenses, or write to the Free Software Foundation,
+# Inc., 51 Franklin Street, Fifth Floor, Boston, MA  02110-1301  USA.
+#
+# If you want to redistribute modifications to GROMACS, please
+# consider that scientific software is very special. Version
+# control is crucial - bugs must be traceable. We will be happy to
+# consider code for inclusion in the official distribution, but
+# derived work must not be called official GROMACS. Details are found
+# in the README & COPYING files - if they are missing, get the
+# official version at http://www.gromacs.org.
+#
+# To help us fund GROMACS development, we humbly ask that you cite
+# the research papers on the package. Check out http://www.gromacs.org.
+
+# Helper functions for creating custom commands
+#
+# CMake semantics of add_custom_command() and add_custom_target() are not
+# always very convenient or intuitive for creating commands that do not always
+# run.  This file provides a gmx_add_custom_output_target() to simplify the
+# task.  The function also provides some convenience features to remove code
+# duplication in some parts of the GROMACS build system.
+#
+# Additionally, gmx_get_stamp_filename() and gmx_get_files_with_gitattribute()
+# are provided independently to help in creating custom commands.
+
+# Helper function to create a stamp file name for a target.
+#
+# Usage:
+#   gmx_get_stamp_filename(<variable> <targetname>)
+#
+#   <variable>   - name of variable to receive the stamp name
+#   <targetname> - name of target for which to generate the stamp name
+#
+# This is used internally by gmx_add_custom_target(... OUTPUT STAMP ...), but
+# can also be called directly to create uniform stamp file names throughout the
+# build system.
+# <targetname> can be any string that is a part of a valid file name; it does
+# not need to name an existing or to-be-created target.
+function (gmx_get_stamp_filename variable targetname)
+    set(_filename "${targetname}")
+    if (NOT "${targetname}" MATCHES "stamp$")
+        set(_filename "${targetname}-timestamp")
+    endif()
+    set(${variable} "${CMAKE_CURRENT_BINARY_DIR}/${_filename}.txt"
+        PARENT_SCOPE)
+endfunction()
+
+# More flexible alternative to add_custom_command() and add_custom_target()
+# for dependent custom commands.  It adds a few convenience features:
+#   - Support for custom commands that always run (like add_custom_target()),
+#     but still have the ability to act as dependencies of other custom
+#     commands (such that the dependent commands run only if the output
+#     has been updated) also for Ninja.
+#   - Adds file-level dependencies between custom targets added with this
+#     command such that if there is a target-level dependency, it also implies
+#     that the custom command should always be run if the output file of the
+#     dependency has been updated.
+#   - Support for creating custom targets that produce stamp files whenever
+#     they run successfully, so that other targets can depend on those stamp
+#     files.
+#
+# Usage:
+#   gmx_add_custom_output_target(<target> [RUN_ALWAYS] [ADD_FAST_TARGET]
+#                                OUTPUT <STAMP | <output> >
+#                                [COMMAND <command1> [<args1...>]]
+#                                [COMMAND <command2> [<args2...>]]
+#                                [WORKING_DIRECTORY <dir>]
+#                                [DEPENDS <deps...>]
+#                                [DEPENDS_FILE_LIST <list>]
+#                                [COMMENT <comment>])
+#
+#   <target>
+#     - Name of the custom target to create.
+#   RUN_ALWAYS
+#     - Create the command such that it always runs.
+#       This takes care of differences between the Ninja generator and others,
+#       which require different rules to make this happen such that
+#       dependencies on the output of the target work correctly, also in the
+#       case the command does not always update the timestamp of the output.
+#       The dependencies listed with DEPENDS are ignored in this case.
+#   ADD_FAST_TARGET
+#     - In addition to creating <target>, create a secondary target
+#       <target>-fast that always runs the same commands, but does not have
+#       any dependencies.  Desired dependencies can be added separately using
+#       add_dependencies().  This supports cases where some of the dependencies
+#       are time-consuming to build, and it is possible to build the target
+#       even without up-to-date dependencies for testing only that part of the
+#       build.
+#   OUTPUT
+#     - Sets the name of the output file from this custom target.
+#       Can be set to STAMP, in which case a stamp file name is automatically
+#       generated and commands to touch that stamp whenever the target is made
+#       are added.
+#   COMMAND
+#     - Passed to add_custom_command()/add_custom_target().
+#       If OUTPUT STAMP is used, then a command to touch the stamp is
+#       automatically added.  In this case, it is allowed to not specify any
+#       commands explicitly.
+#   WORKING_DIRECTORY
+#     - Passed to add_custom_command()/add_custom_target()
+#   COMMENT
+#     - Passed to add_custom_command()/add_custom_target()
+#   DEPENDS
+#     - Dependencies passed to add_custom_command().  Any targets in this list
+#       that have been created with gmx_add_custom_output_target() are
+#       automatically expanded such that the custom command always runs if the
+#       output of the dependent target changes.  It is not necessary to list
+#       those output files here explicitly.
+#   DEPENDS_FILE_LIST
+#     - Names of variables from which dependencies are added verbatim.
+#       The target expansion described above is not performed for these
+#       dependencies, and the value passed to the function is the name of a
+#       list variable, not the list itself.  This provides much better
+#       performance if the dependency list is a long list of source files.
+#
+# This function does not need a VERBATIM argument; that is always used when
+# creating the underlying custom commands/targets.
+function (gmx_add_custom_output_target targetname)
+    # Parse the arguments
+    # CMakeParseArguments is not suitable, since it does not support the use of
+    # multiple COMMAND parameters that add_custom_target/command() supports.
+    set(_option "")
+    set(_command_args "")
+    set(_deps "")
+    set(_output "")
+    set(_stamp OFF)
+    set(_always OFF)
+    set(_add_fast OFF)
+    foreach (_arg ${ARGN})
+        if ("x${_arg}" STREQUAL "xRUN_ALWAYS")
+            set(_always ON)
+        elseif ("x${_arg}" STREQUAL "xADD_FAST_TARGET")
+            set(_add_fast ON)
+        elseif ("x${_arg}" MATCHES "^x(OUTPUT|DEPENDS|DEPENDS_FILE_LIST)$")
+            set(_option ${_arg})
+        elseif ("x${_arg}" MATCHES "^x(COMMAND|COMMENT|WORKING_DIRECTORY)$")
+            set(_option "PASS")
+            list(APPEND _command_args "${_arg}")
+        elseif ("${_option}" STREQUAL "DEPENDS")
+            list(APPEND _deps "${_arg}")
+            # If the dependency is a target created with this command, also add
+            # the output file as a dependency.
+            if (TARGET "${_arg}")
+                get_property(_target_output
+                    TARGET "${_arg}" PROPERTY GMX_CUSTOM_TARGET_OUTPUT_FILE)
+                if (_target_output)
+                    list(APPEND _deps ${_target_output})
+                endif()
+            endif()
+        elseif ("${_option}" STREQUAL "PASS")
+            list(APPEND _command_args "${_arg}")
+        elseif ("${_option}" STREQUAL "DEPENDS_FILE_LIST")
+            list(APPEND _deps ${${_arg}})
+        elseif ("${_option}" STREQUAL "OUTPUT")
+            if (_output)
+                message(FATAL_ERROR "Multiple OUTPUTs not supported")
+            endif()
+            if ("${_arg}" STREQUAL "STAMP")
+                gmx_get_stamp_filename(_output ${targetname})
+                set(_stamp ON)
+            else()
+                set(_output ${_arg})
+            endif()
+        else()
+            message(FATAL_ERROR "Unknown option ${_arg}")
+        endif()
+    endforeach()
+    # Add automatically a command to update the stamp if requested
+    if (_stamp)
+        list(APPEND _command_args COMMAND ${CMAKE_COMMAND} -E touch ${_output})
+    endif()
+    # Create the actual command as requested.
+    if (NOT _always)
+        # If the command does not need to run always, the standard CMake
+        # mechanism is sufficient.
+        add_custom_command(OUTPUT ${_output}
+            ${_command_args} DEPENDS ${_deps} VERBATIM)
+        add_custom_target(${targetname} DEPENDS ${_output})
+    elseif (CMAKE_GENERATOR STREQUAL "Ninja")
+        # Ninja requires all generated files mentioned in dependencies of custom
+        # commands to be actually mentioned in the build system, and luckily
+        # add_custom_command() makes that possible.
+        # But it seems impossible to create a robust custom command that would be
+        # always run, so other generators that do not have this constraint simply
+        # use an add_custom_target().
+        #
+        # The second, phony file is never created, so the rule is always
+        # triggered again.  TODO: Figure out why this works, even though ninja
+        # very eagerly complains about missing files.
+        # This unfortunately does not work with the make generator, as
+        # the non-existent second file causes some part of the generated system
+        # erase the first file at the beginning of every build, causing a full
+        # rebuild of the dependencies.
+        add_custom_command(OUTPUT ${_output} ${targetname}-phony
+            ${_command_args} VERBATIM)
+        # The generated Ninja build system would probably work fine even
+        # without this target, but CMake requires all custom commands to belong
+        # to a target in the same CMakeLists.txt to generate anything for them.
+        add_custom_target(${targetname} DEPENDS ${_output})
+    else()
+        # For other generators, a target-level dependency on the custom target
+        # ensures that the output is created before the dependent targets'
+        # dependencies are even evaluated.
+        add_custom_target(${targetname} ${_command_args} VERBATIM)
+    endif()
+    # Store the output file name in a custom property to be used in dependency
+    # resolution later.
+    if (NOT IS_ABSOLUTE ${_output})
+        set(_output ${CMAKE_CURRENT_BINARY_DIR}/${_output})
+    endif()
+    set_property(TARGET ${targetname}
+        PROPERTY GMX_CUSTOM_TARGET_OUTPUT_FILE ${_output})
+    # Create the fast target if requested.
+    if (_add_fast)
+        add_custom_target(${targetname}-fast ${_command_args} VERBATIM)
+    endif()
+endfunction()
+
+# Gets list of files in the source tree with the given git attribute set
+#
+# Usage:
+#   gmx_get_files_with_gitattribute(<variable> <attribute>)
+#
+#   <variable>  - name of variable to receive the file list
+#   <attribute> - name of git attribute to use
+#
+# This is useful to generate a list of dependencies for custom commands when
+# there is a long list of files that cannot be easily just globbed.
+# Using git attributes allows keeping complicated logic out of the build
+# system, as expressing such logic in a CMake script that would be reasonably
+# fast to evaluate for a long file list is convenient or easy.
+function (gmx_get_files_with_gitattribute variable attribute)
+    execute_process(
+        COMMAND ${GIT_EXECUTABLE} ls-files
+        COMMAND ${GIT_EXECUTABLE} check-attr ${attribute} --stdin
+        WORKING_DIRECTORY ${PROJECT_SOURCE_DIR}
+        OUTPUT_VARIABLE _files)
+    string(REGEX MATCHALL "[^\n]*: ${attribute}: set\n"
+           _files_with_attr "${_files}")
+    string(REGEX REPLACE "([^;]*): ${attribute}: set\n" "${PROJECT_SOURCE_DIR}/\\1"
+           _files "${_files_with_attr}")
+    set(${variable} ${_files} PARENT_SCOPE)
+endfunction()
diff --git a/docs/.gitattributes b/docs/.gitattributes
new file mode 100644 (file)
index 0000000..a996511
--- /dev/null
@@ -0,0 +1,2 @@
+doxygen/DoxygenLayout.xml gmx-doxygen
+doxygen/**/*.md           gmx-doxygen
index 9d439695b3a0c685214d8a92a15cb4004545296d..3dc0946222ed8a46e39999f1b214e7d1145d18a5 100644 (file)
@@ -32,6 +32,7 @@
 # To help us fund GROMACS development, we humbly ask that you cite
 # the research papers on the package. Check out http://www.gromacs.org.
 
+include(gmxCustomCommandUtilities)
 include(gmxOptionUtilities)
 
 find_package(Doxygen QUIET)
@@ -63,31 +64,32 @@ endif()
 
 # Create a stamp file whenever cmake is run, as the list of installed files may
 # have changed.
-set(CONFIGURE_STAMP_FILE ${CMAKE_CURRENT_BINARY_DIR}/cmake-stamp.txt)
-file(WRITE ${CONFIGURE_STAMP_FILE} "Stamp for configuration")
+gmx_get_stamp_filename(configure_stamp_file cmake-configure)
+file(WRITE ${configure_stamp_file} "Timestamp for configuration")
 # Note that if you relocate this file, you also need to change gmxtree.py.
 set(INSTALLED_HEADERS_FILE ${CMAKE_CURRENT_BINARY_DIR}/installed-headers.txt)
-add_custom_command(OUTPUT ${INSTALLED_HEADERS_FILE}
+gmx_add_custom_output_target(find-installed-headers
+    OUTPUT ${INSTALLED_HEADERS_FILE}
     COMMAND ${CMAKE_COMMAND}
         -D SRCDIR=${CMAKE_SOURCE_DIR}
         -D BUILDDIR=${CMAKE_BINARY_DIR}
         -D OUTFILE=${INSTALLED_HEADERS_FILE}
         -P ${CMAKE_CURRENT_SOURCE_DIR}/getInstalledHeaders.cmake
-    DEPENDS ${CONFIGURE_STAMP_FILE}
-    COMMENT "Generating installed headers list" VERBATIM)
-add_custom_target(find-installed-headers DEPENDS ${INSTALLED_HEADERS_FILE})
+    DEPENDS ${configure_stamp_file}
+    COMMENT "Generating installed headers list")
 
 ########################################################################
 # Doxygen configuration
-########################################################################
+#
 if (DOXYGEN_FOUND)
+    # Generate Doxygen input configuration files
     file(GLOB NB_KERNEL_DIRS
          ${CMAKE_SOURCE_DIR}/src/gromacs/gmxlib/nonbonded/nb_kernel_*/)
     list(REMOVE_ITEM NB_KERNEL_DIRS
          ${CMAKE_SOURCE_DIR}/src/gromacs/gmxlib/nonbonded/nb_kernel_c)
-    foreach (NB_KERNEL_DIR ${NB_KERNEL_DIRS})
+    foreach (dir ${NB_KERNEL_DIRS})
         SET(NB_KERNEL_DIRS_TO_IGNORE_IN_DOXYGEN
-            "${NB_KERNEL_DIRS_TO_IGNORE_IN_DOXYGEN} \\\n                         ${NB_KERNEL_DIR}")
+            "${NB_KERNEL_DIRS_TO_IGNORE_IN_DOXYGEN} \\\n                         ${dir}")
     endforeach()
     set(DEPGRAPH_DIR ${CMAKE_CURRENT_BINARY_DIR}/depgraphs)
     set(DOXYGEN_SECTIONS "")
@@ -105,30 +107,111 @@ if (DOXYGEN_FOUND)
     gmx_configure_version_file(Doxyfile-version.cmakein Doxyfile-version
                                TARGET doxygen-version)
 
+    # Add a stamp that gets updated whenever a source file that contributes to
+    # Doxygen is updated.  All Doxygen targets can then depend on this stamp,
+    # instead of each specifying this massive set of dependencies.
+    # TODO: The set of files that affects Doxygen is not exactly the same as
+    # that which affects the dependency graphs, and neither is captured
+    # perfectly with this set, but this can be improved if it becomes a real
+    # issue (the differences are mainly in the generated group kernel files,
+    # but there are some minor other differences as well).
+    if (SOURCE_IS_GIT_REPOSITORY AND GIT_FOUND)
+        gmx_get_files_with_gitattribute(doxygen_sources gmx-doxygen)
+        # Add also common configuration files that influence the generation.
+        set(doxygen_deps
+            ${CMAKE_CURRENT_BINARY_DIR}/Doxyfile-common
+            ${CMAKE_CURRENT_BINARY_DIR}/RunDoxygen.cmake)
+        if (GMX_COMPACT_DOXYGEN)
+            list(APPEND doxygen_deps ${CMAKE_CURRENT_BINARY_DIR}/Doxyfile-compact)
+        endif()
+        gmx_add_custom_output_target(doxygen-source-timestamp
+            OUTPUT STAMP
+            DEPENDS_FILE_LIST doxygen_sources
+            DEPENDS ${doxygen_deps}
+            COMMENT "Updating Doxygen source timestamp")
+    else()
+        # If there is no git, we just update the stamp every time, and the
+        # builds are triggered every time.  This should be rare enough, but
+        # this case still needs to be supported for the Jenkins job that builds
+        # the documentation for a release from the release tarball.
+        gmx_add_custom_output_target(doxygen-source-timestamp
+            RUN_ALWAYS OUTPUT STAMP
+            COMMENT "Updating Doxygen source timestamp")
+    endif()
+
+    # Helper function to create a Doxygen build target
     function (add_doxygen_target TARGET TYPE COMMENT)
-        add_custom_target(${TARGET}
+        set(_deps doxygen-source-timestamp doxygen-version
+            ${CMAKE_CURRENT_BINARY_DIR}/Doxyfile-${TYPE})
+        set(_fast_arg "")
+        if ("${ARGN}" STREQUAL "DEPGRAPHS")
+            set(_fast_arg "ADD_FAST_TARGET")
+            if (TARGET dep-graphs-dot)
+                list(APPEND _deps dep-graphs-dot)
+            endif()
+        endif()
+        gmx_add_custom_output_target(${TARGET} OUTPUT STAMP ${_fast_arg}
             # Ensure the directory exists to avoid spurious warnings
-            ${CMAKE_COMMAND} -E make_directory ${DEPGRAPH_DIR}
+            COMMAND ${CMAKE_COMMAND} -E make_directory ${DEPGRAPH_DIR}
             COMMAND ${CMAKE_COMMAND} -DDOCTYPE=${TYPE} -P RunDoxygen.cmake
+            DEPENDS ${_deps}
             WORKING_DIRECTORY ${CMAKE_CURRENT_BINARY_DIR}
-            COMMENT "${COMMENT}" VERBATIM)
-        add_dependencies(${TARGET} doxygen-version)
+            COMMENT "${COMMENT}")
+        if (_fast_arg)
+            add_dependencies(${TARGET}-fast doxygen-version)
+        endif()
     endfunction()
-    # The targets ending with -fast do the same thing as the target without the
-    # suffix, but assume that time-consuming dependencies have already been
-    # built, making it faster and more convenient to test a single part of the
-    # system.
-    add_doxygen_target(doc-full      full "Generating full documentation with Doxygen")
-    add_doxygen_target(doc-full-fast full "Generating full documentation with Doxygen")
-    add_doxygen_target(doc-lib       lib  "Generating library documentation with Doxygen")
-    add_doxygen_target(doc-lib-fast  lib  "Generating library documentation with Doxygen")
-    add_doxygen_target(doc-user      user "Generating public API documentation with Doxygen")
-    add_doxygen_target(doc-xml       xml  "Extracting Doxygen documentation to XML")
+
+    # The XML target is necessary for the dependency graphs
+    add_doxygen_target(doc-xml xml "Extracting Doxygen documentation to XML")
+
+    # Add targets for generating the dependency graphs; they are necessary for
+    # the full and lib variants of the documentation.
+    if (USE_PYTHON_SCRIPTS)
+        # Add target that generates .dot files for the dependency graphs.
+        # The output also depends on the Doxygen source files, but the
+        # dependency on doc-xml takes care of that transitively.
+        gmx_add_custom_output_target(dep-graphs-dot ADD_FAST_TARGET
+            OUTPUT STAMP
+            COMMAND ${PYTHON_EXECUTABLE}
+                ${CMAKE_CURRENT_SOURCE_DIR}/graphbuilder.py
+                -S ${CMAKE_SOURCE_DIR} -B ${CMAKE_BINARY_DIR}
+                --ignore-cycles ${CMAKE_CURRENT_SOURCE_DIR}/cycle-suppressions.txt
+                -o ${DEPGRAPH_DIR}
+            DEPENDS doc-xml find-installed-headers
+                ${CMAKE_CURRENT_SOURCE_DIR}/doxygenxml.py
+                ${CMAKE_CURRENT_SOURCE_DIR}/gmxtree.py
+                ${CMAKE_CURRENT_SOURCE_DIR}/graphbuilder.py
+                ${CMAKE_CURRENT_SOURCE_DIR}/cycle-suppressions.txt
+            COMMENT "Generating include dependency graphs for dot")
+        add_dependencies(dep-graphs-dot-fast find-installed-headers)
+
+        # Add separate targets for converting the .dot files to .png.
+        # These are not needed by the Doxygen targets, but are useful for
+        # investigating just the graphs.
+        set(dep_graphs_command_dot
+            ${CMAKE_COMMAND} -DGRAPHDIR=${DEPGRAPH_DIR}
+            -DDOT_EXECUTABLE=${DOXYGEN_DOT_EXECUTABLE}
+            -P ${CMAKE_CURRENT_SOURCE_DIR}/generateGraphs.cmake)
+        add_custom_target(dep-graphs      COMMAND ${dep_graphs_command_dot}
+            COMMENT "Generating PNG include dependency graphs" VERBATIM)
+        add_custom_target(dep-graphs-fast COMMAND ${dep_graphs_command_dot}
+            COMMENT "Generating PNG include dependency graphs" VERBATIM)
+        add_dependencies(dep-graphs      dep-graphs-dot)
+        add_dependencies(dep-graphs-fast dep-graphs-dot-fast)
+    endif()
+
+    # Create the actual targets to build the documentation.
+    add_doxygen_target(doc-full full "Generating full documentation with Doxygen" DEPGRAPHS)
+    add_doxygen_target(doc-lib  lib  "Generating library documentation with Doxygen" DEPGRAPHS)
+    add_doxygen_target(doc-user user "Generating public API documentation with Doxygen")
+    # Convenience targets to build all the documentation flavors.
     add_custom_target(doc-all)
     add_custom_target(doc-all-fast)
-    add_dependencies(doc-all doc-full doc-lib doc-user)
+    add_dependencies(doc-all      doc-full doc-lib doc-user)
     add_dependencies(doc-all-fast doc-full-fast doc-lib-fast doc-user)
 
+    # Finally, create the doc-check target.
     if (USE_PYTHON_SCRIPTS)
         # TODO: Consider whether this is the best name and location for this
         # code, since not all of it is Doxygen-specific (but nearly all of it
@@ -140,42 +223,11 @@ if (DOXYGEN_FOUND)
             --exitcode
             --ignore ${CMAKE_CURRENT_SOURCE_DIR}/suppressions.txt
             --ignore-cycles ${CMAKE_CURRENT_SOURCE_DIR}/cycle-suppressions.txt)
-        add_custom_target(doc-check COMMAND ${doc_check_command}
+        add_custom_target(doc-check      COMMAND ${doc_check_command}
             COMMENT "Checking Doxygen documentation" VERBATIM)
-        add_dependencies(doc-check doc-xml find-installed-headers)
         add_custom_target(doc-check-fast COMMAND ${doc_check_command}
             COMMENT "Checking Doxygen documentation" VERBATIM)
+        add_dependencies(doc-check      doc-xml find-installed-headers)
         add_dependencies(doc-check-fast find-installed-headers)
-
-        set(dep_graphs_command_python
-            ${PYTHON_EXECUTABLE} ${CMAKE_CURRENT_SOURCE_DIR}/graphbuilder.py
-            -S ${CMAKE_SOURCE_DIR} -B ${CMAKE_BINARY_DIR}
-            --ignore-cycles ${CMAKE_CURRENT_SOURCE_DIR}/cycle-suppressions.txt
-            -o ${DEPGRAPH_DIR})
-        set(dep_graphs_command_dot
-            ${CMAKE_COMMAND} -DGRAPHDIR=${DEPGRAPH_DIR}
-            -DDOT_EXECUTABLE=${DOXYGEN_DOT_EXECUTABLE}
-            -P ${CMAKE_CURRENT_SOURCE_DIR}/generateGraphs.cmake)
-        add_custom_target(dep-graphs-dot
-            COMMAND ${dep_graphs_command_python}
-            COMMENT "Generating include dependency graphs for dot" VERBATIM)
-        add_custom_target(dep-graphs
-            COMMAND ${dep_graphs_command_dot}
-            COMMENT "Generating PNG include dependency graphs" VERBATIM)
-        add_dependencies(dep-graphs-dot doc-xml find-installed-headers)
-        add_dependencies(dep-graphs dep-graphs-dot)
-        add_dependencies(doc-full dep-graphs-dot)
-        add_dependencies(doc-lib dep-graphs-dot)
-
-        add_custom_target(dep-graphs-dot-fast
-            COMMAND ${dep_graphs_command_python}
-            COMMENT "Generating include dependency graphs for dot" VERBATIM)
-        add_custom_target(dep-graphs-fast
-            COMMAND ${dep_graphs_command_dot}
-            COMMENT "Generating PNG include dependency graphs" VERBATIM)
-        # Finding the installed headers doesn't actually run again if nothing
-        # has changed, so that can be safely added as a dependency.
-        add_dependencies(dep-graphs-dot-fast find-installed-headers)
-        add_dependencies(dep-graphs-fast dep-graphs-dot-fast)
     endif()
 endif()
index ad2a03b0bb1af9e57639ecb9c0edc2409d4e995c..5c61d8f626f5b8a1b49910d783e756a7e2d573e6 100644 (file)
@@ -1,2 +1 @@
-* !filter
 gmock-1.7.0/CMakeLists.txt      filter=copyright