Commit 611eb26b authored by Nikita Sirgienko's avatar Nikita Sirgienko Committed by Craig Scott

FindDoxygen: add USE_STAMP_FILE option

The new option enables the behavior of only building if sources change.
parent 3ec986ce
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.
......@@ -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()
......
......@@ -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>
......
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)
/**
* \file
* \brief One C++ file w/ sample Doxygen comment just to produce any docs...
*/
/**
* \file
* \brief One C++ file w/ sample Doxygen comment just to produce any docs...
*/
Markdown is supported
0%
or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment