FindDoxygen: add USE_STAMP_FILE option

The new option enables the behavior of only building if sources change.

6 files changed, 102 insertions, 17 deletions

diff --git a/Help/release/dev/doxygen-add-docs-USE_STAMP_FILE.rst b/Help/release/dev/doxygen-add-docs-USE_STAMP_FILE.rst
new file mode 100644
index 0000000000..700ee6c29e
--- /dev/null
+++ b/Help/release/dev/doxygen-add-docs-USE_STAMP_FILE.rst
@@ -0,0 +1,7 @@
+doxygen-add-docs-USE_STAMP_FILE
+-------------------------------
+
+* The :command:`doxygen_add_docs` command from the :module:`FindDoxygen`
+  module gained a new ``USE_STAMP_FILE`` option.  When this option present,
+  the custom target created by the command will only re-run Doxygen if any
+  of the source files have changed since the last successful run.
diff --git a/Modules/FindDoxygen.cmake b/Modules/FindDoxygen.cmake
index ebd0b24abe..faa03f9185 100644
--- a/Modules/FindDoxygen.cmake
+++ b/Modules/FindDoxygen.cmake
@@ -70,6 +70,7 @@ Functions
     doxygen_add_docs(targetName
         [filesOrDirs...]
         [ALL]
+        [USE_STAMP_FILE]
         [WORKING_DIRECTORY dir]
         [COMMENT comment])
 
@@ -92,7 +93,19 @@ Functions
   the :command:`add_custom_target` command used to create the custom target
   internally.
 
-  If ALL is set, the target will be added to the default build target.
+  If ``ALL`` is set, the target will be added to the default build target.
+
+  If ``USE_STAMP_FILE`` is set, the custom command defined by this function will
+  create a stamp file with the name ``<targetName>.stamp`` in the current
+  binary directory whenever doxygen is re-run.  With this option present, all
+  items in ``<filesOrDirs>`` must be files (i.e. no directories, symlinks or
+  wildcards) and each of the files must exist at the time
+  ``doxygen_add_docs()`` is called.  An error will be raised if any of the
+  items listed is missing or is not a file when ``USE_STAMP_FILE`` is given.
+  A dependency will be created on each of the files so that doxygen will only
+  be re-run if one of the files is updated.  Without the ``USE_STAMP_FILE``
+  option, doxygen will always be re-run if the ``<targetName>`` target is built
+  regardless of whether anything listed in ``<filesOrDirs>`` has changed.
 
   The contents of the generated ``Doxyfile`` can be customized by setting CMake
   variables before calling ``doxygen_add_docs()``. Any variable with a name of
@@ -801,7 +814,7 @@ function(doxygen_list_to_quoted_strings LIST_VARIABLE)
 endfunction()
 
 function(doxygen_add_docs targetName)
-    set(_options ALL)
+    set(_options ALL USE_STAMP_FILE)
     set(_one_value_args WORKING_DIRECTORY COMMENT)
     set(_multi_value_args)
     cmake_parse_arguments(_args
@@ -978,9 +991,10 @@ doxygen_add_docs() for target ${targetName}")
     endif()
 
     # Build up a list of files we can identify from the inputs so we can list
-    # them as SOURCES in the custom target (makes them display in IDEs). We
-    # must do this before we transform the various DOXYGEN_... variables below
-    # because we need to process DOXYGEN_INPUT as a list first.
+    # them as DEPENDS and SOURCES in the custom command/target (the latter
+    # makes them display in IDEs). This must be done before we transform the
+    # various DOXYGEN_... variables below because we need to process
+    # DOXYGEN_INPUT as a list first.
     unset(_sources)
     foreach(_item IN LISTS DOXYGEN_INPUT)
         get_filename_component(_abs_item "${_item}" ABSOLUTE
@@ -989,11 +1003,13 @@ doxygen_add_docs() for target ${targetName}")
            NOT IS_DIRECTORY "${_abs_item}" AND
            NOT IS_SYMLINK "${_abs_item}")
             list(APPEND _sources "${_abs_item}")
+        elseif(_args_USE_STAMP_FILE)
+            message(FATAL_ERROR "Source does not exist or is not a file:\n"
+                "    ${_abs_item}\n"
+                "Only existing files may be specified when the "
+                "USE_STAMP_FILE option is given.")
         endif()
     endforeach()
-    if(_sources)
-        list(INSERT _sources 0 SOURCES)
-    endif()
 
     # Transform known list type options into space separated strings.
     set(_doxygen_list_options
@@ -1107,15 +1123,35 @@ doxygen_add_docs() for target ${targetName}")
         set(_all ALL)
     endif()
 
-    # Add the target
-    add_custom_target( ${targetName} ${_all} VERBATIM
-        COMMAND ${CMAKE_COMMAND} -E make_directory ${_original_doxygen_output_dir}
-        COMMAND "${DOXYGEN_EXECUTABLE}" "${_target_doxyfile}"
-        WORKING_DIRECTORY "${_args_WORKING_DIRECTORY}"
-        DEPENDS "${_target_doxyfile}"
-        COMMENT "${_args_COMMENT}"
-        ${_sources}
-    )
+    # Only create the stamp file if asked to. If we don't create it,
+    # the target will always be considered out-of-date.
+    if(_args_USE_STAMP_FILE)
+        set(__stamp_file "${CMAKE_CURRENT_BINARY_DIR}/${targetName}.stamp")
+        add_custom_command(
+            VERBATIM
+            OUTPUT ${__stamp_file}
+            COMMAND ${CMAKE_COMMAND} -E make_directory ${_original_doxygen_output_dir}
+            COMMAND "${DOXYGEN_EXECUTABLE}" "${_target_doxyfile}"
+            COMMAND ${CMAKE_COMMAND} -E touch ${__stamp_file}
+            WORKING_DIRECTORY "${_args_WORKING_DIRECTORY}"
+            DEPENDS "${_target_doxyfile}" ${_sources}
+            COMMENT "${_args_COMMENT}"
+        )
+        add_custom_target(${targetName} ${_all}
+            DEPENDS ${__stamp_file}
+            SOURCES ${_sources}
+        )
+        unset(__stamp_file)
+    else()
+        add_custom_target( ${targetName} ${_all} VERBATIM
+            COMMAND ${CMAKE_COMMAND} -E make_directory ${_original_doxygen_output_dir}
+            COMMAND "${DOXYGEN_EXECUTABLE}" "${_target_doxyfile}"
+            WORKING_DIRECTORY "${_args_WORKING_DIRECTORY}"
+            DEPENDS "${_target_doxyfile}" ${_sources}
+            COMMENT "${_args_COMMENT}"
+            SOURCES ${_sources}
+        )
+    endif()
 
 endfunction()
 
diff --git a/Tests/FindDoxygen/CMakeLists.txt b/Tests/FindDoxygen/CMakeLists.txt
index 7ce98d59b9..41e6255eb7 100644
--- a/Tests/FindDoxygen/CMakeLists.txt
+++ b/Tests/FindDoxygen/CMakeLists.txt
@@ -28,6 +28,16 @@ add_test(NAME FindDoxygen.AllTarget COMMAND
   --test-command ${CMAKE_CTEST_COMMAND} -C $<CONFIGURATION>
 )
 
+add_test(NAME FindDoxygen.StampFile COMMAND
+  ${CMAKE_CTEST_COMMAND} -C $<CONFIGURATION>
+  --build-and-test
+  "${CMake_SOURCE_DIR}/Tests/FindDoxygen/StampFile"
+  "${CMake_BINARY_DIR}/Tests/FindDoxygen/StampFile"
+  --build-target allDocTargets
+  ${build_generator_args}
+  --build-options ${build_options}
+)
+
 if(CMake_TEST_FindDoxygen_Dot)
   add_test(NAME FindDoxygen.DotComponentTest COMMAND
     ${CMAKE_CTEST_COMMAND} -C $<CONFIGURATION>
diff --git a/Tests/FindDoxygen/StampFile/CMakeLists.txt b/Tests/FindDoxygen/StampFile/CMakeLists.txt
new file mode 100644
index 0000000000..2d06540587
--- /dev/null
+++ b/Tests/FindDoxygen/StampFile/CMakeLists.txt
@@ -0,0 +1,24 @@
+cmake_minimum_required(VERSION 3.8)
+project(TestFindDoxygen VERSION 1.0 LANGUAGES NONE)
+
+find_package(Doxygen REQUIRED)
+
+doxygen_add_docs(docsWithoutFilesWithStamp USE_STAMP_FILE)
+if(NOT EXISTS "${PROJECT_BINARY_DIR}/Doxyfile.docsWithoutFilesWithStamp")
+    message(FATAL_ERROR "Missing generated file: Doxyfile.docsWithoutFilesWithStamp")
+endif()
+if(NOT TARGET docsWithoutFilesWithStamp)
+    message(FATAL_ERROR "Target docsWithoutFilesWithStamp not created")
+endif()
+
+doxygen_add_docs(docsWithFilesWithStamp main.cpp main2.cpp USE_STAMP_FILE)
+if(NOT EXISTS "${PROJECT_BINARY_DIR}/Doxyfile.docsWithFilesWithStamp")
+    message(FATAL_ERROR "Missing generated file: Doxyfile.docsWithFilesWithStamp")
+endif()
+if(NOT TARGET docsWithFilesWithStamp)
+    message(FATAL_ERROR "Target docsWithFilesWithStamp not created")
+endif()
+
+
+add_custom_target(allDocTargets)
+add_dependencies(allDocTargets docsWithoutFilesWithStamp docsWithFilesWithStamp)
diff --git a/Tests/FindDoxygen/StampFile/main.cpp b/Tests/FindDoxygen/StampFile/main.cpp
new file mode 100644
index 0000000000..925f0afe09
--- /dev/null
+++ b/Tests/FindDoxygen/StampFile/main.cpp
@@ -0,0 +1,4 @@
+/**
+ * \file
+ * \brief One C++ file w/ sample Doxygen comment just to produce any docs...
+ */
diff --git a/Tests/FindDoxygen/StampFile/main2.cpp b/Tests/FindDoxygen/StampFile/main2.cpp
new file mode 100644
index 0000000000..925f0afe09
--- /dev/null
+++ b/Tests/FindDoxygen/StampFile/main2.cpp
@@ -0,0 +1,4 @@
+/**
+ * \file
+ * \brief One C++ file w/ sample Doxygen comment just to produce any docs...
+ */