X-Git-Url: http://biod.pnpi.spb.ru/gitweb/?a=blobdiff_plain;f=docs%2Fdoxygen%2FCMakeLists.txt;h=3dc0946222ed8a46e39999f1b214e7d1145d18a5;hb=d390204c99b638867390820d03961fd4a4d78656;hp=9d439695b3a0c685214d8a92a15cb4004545296d;hpb=4c23d613a90b6aab7d2abf73e11a4a0c43d35c7c;p=alexxy%2Fgromacs.git diff --git a/docs/doxygen/CMakeLists.txt b/docs/doxygen/CMakeLists.txt index 9d439695b3..3dc0946222 100644 --- a/docs/doxygen/CMakeLists.txt +++ b/docs/doxygen/CMakeLists.txt @@ -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()