# 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)
# 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 "")
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
--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()