docs/doxygen/CMakeLists.txt

   1 #
   2 # This file is part of the GROMACS molecular simulation package.
   3 #
   4 # Copyright (c) 2012,2013,2014,2015,2016 by the GROMACS development team.
   5 # Copyright (c) 2017,2018,2019,2020,2021, by the GROMACS development team, led by
   6 # Mark Abraham, David van der Spoel, Berk Hess, and Erik Lindahl,
   7 # and including many others, as listed in the AUTHORS file in the
   8 # top-level source directory and at http://www.gromacs.org.
   9 #
  10 # GROMACS is free software; you can redistribute it and/or
  11 # modify it under the terms of the GNU Lesser General Public License
  12 # as published by the Free Software Foundation; either version 2.1
  13 # of the License, or (at your option) any later version.
  14 #
  15 # GROMACS is distributed in the hope that it will be useful,
  16 # but WITHOUT ANY WARRANTY; without even the implied warranty of
  17 # MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
  18 # Lesser General Public License for more details.
  19 #
  20 # You should have received a copy of the GNU Lesser General Public
  21 # License along with GROMACS; if not, see
  22 # http://www.gnu.org/licenses, or write to the Free Software Foundation,
  23 # Inc., 51 Franklin Street, Fifth Floor, Boston, MA  02110-1301  USA.
  24 #
  25 # If you want to redistribute modifications to GROMACS, please
  26 # consider that scientific software is very special. Version
  27 # control is crucial - bugs must be traceable. We will be happy to
  28 # consider code for inclusion in the official distribution, but
  29 # derived work must not be called official GROMACS. Details are found
  30 # in the README & COPYING files - if they are missing, get the
  31 # official version at http://www.gromacs.org.
  32 #
  33 # To help us fund GROMACS development, we humbly ask that you cite
  34 # the research papers on the package. Check out http://www.gromacs.org.
  35
  36 include(gmxCustomCommandUtilities)
  37 include(gmxOptionUtilities)
  38
  39 find_package(Doxygen QUIET)
  40 if (DOXYGEN_FOUND)
  41     # This logic closely follows that found in FindDoxygen.cmake for dot,
  42     # except that the PATH variable is not cached.
  43     find_program(DOXYGEN_MSCGEN_EXECUTABLE
  44         NAMES mscgen
  45         DOC "Message sequence chart renderer tool (http://www.mcternan.me.uk/mscgen/)")
  46     if (DOXYGEN_MSCGEN_EXECUTABLE)
  47         set(DOXYGEN_MSCGEN_FOUND TRUE)
  48         get_filename_component(DOXYGEN_MSCGEN_PATH "${DOXYGEN_MSCGEN_EXECUTABLE}" PATH)
  49     endif()
  50     mark_as_advanced(DOXYGEN_MSCGEN_EXECUTABLE)
  51 endif()
  52
  53 gmx_dependent_option(
  54     GMX_COMPACT_DOXYGEN
  55     "Skip parts of Doxygen documentation (in particular, many graphs) to save disk space and time"
  56     OFF
  57     DOXYGEN_FOUND)
  58 mark_as_advanced(GMX_COMPACT_DOXYGEN)
  59
  60 set(USE_PYTHON_SCRIPTS OFF)
  61 if (Python3_Interpreter_FOUND)
  62     set(USE_PYTHON_SCRIPTS ON)
  63 endif()
  64
  65 # Note that if you relocate this file, you also need to change gmxtree.py.
  66 # TODO: Try to find a solution where this would be hard-coded here, completely
  67 # separate from the logic that generates it.
  68 set(INSTALLED_HEADERS_FILE ${PROJECT_BINARY_DIR}/src/gromacs/installed-headers.txt)
  69
  70 ########################################################################
  71 # Doxygen configuration
  72 #
  73 if (DOXYGEN_FOUND)
  74     # Generate Doxygen input configuration files
  75     set(DEPGRAPH_DIR ${CMAKE_CURRENT_BINARY_DIR}/depgraphs)
  76     set(DOXYGEN_SECTIONS "")
  77     set(DOXYGEN_EXTRA_SETTINGS "")
  78     if (GMX_COMPACT_DOXYGEN)
  79         set(DOXYGEN_EXTRA_SETTINGS "@INCLUDE   = ${CMAKE_CURRENT_SOURCE_DIR}/Doxyfile-compact")
  80     endif()
  81     set(DOXYGENLIST "html-full;html-lib;html-user;xml")
  82     foreach(_target ${DOXYGENLIST})
  83         set(_targetdir ${HTML_OUTPUT_DIR}/doxygen/${_target})
  84         if (NOT EXISTS ${_targetdir})
  85             file(MAKE_DIRECTORY ${_targetdir})
  86         endif()
  87     endforeach()
  88     set(DOXYGENLIST "common;dev;full;lib;user;xml")
  89     foreach(_target ${DOXYGENLIST})
  90         configure_file(Doxyfile-${_target}.cmakein Doxyfile-${_target})
  91     endforeach()
  92
  93     configure_file(RunDoxygen.cmake.cmakein RunDoxygen.cmake @ONLY)
  94     gmx_configure_version_file(Doxyfile-version.cmakein Doxyfile-version
  95                                TARGET doxygen-version)
  96
  97     # Add a stamp that gets updated whenever a source file that contributes to
  98     # Doxygen is updated.  All Doxygen targets can then depend on this stamp,
  99     # instead of each specifying this massive set of dependencies.
 100     # TODO: The set of files that affects Doxygen is not exactly the same as
 101     # that which affects the dependency graphs, and neither is captured
 102     # perfectly with this set, but this can be improved if it becomes a real
 103     # issue (the differences are mainly in the generated group kernel files,
 104     # but there are some minor other differences as well).
 105     if (SOURCE_IS_GIT_REPOSITORY AND GIT_FOUND)
 106         gmx_get_files_with_gitattribute(doxygen_sources gmx-doxygen)
 107         # Add also common configuration files that influence the generation.
 108         set(doxygen_deps
 109             ${CMAKE_CURRENT_BINARY_DIR}/Doxyfile-common
 110             ${CMAKE_CURRENT_BINARY_DIR}/RunDoxygen.cmake)
 111         if (GMX_COMPACT_DOXYGEN)
 112             list(APPEND doxygen_deps ${CMAKE_CURRENT_SOURCE_DIR}/Doxyfile-compact)
 113         endif()
 114         gmx_add_custom_output_target(doxygen-source-timestamp
 115             OUTPUT STAMP
 116             DEPENDS_FILE_LIST doxygen_sources
 117             DEPENDS ${doxygen_deps}
 118             COMMENT "Updating Doxygen source timestamp")
 119     else()
 120         # If there is no git, we just update the stamp every time, and the
 121         # builds are triggered every time.  This should be rare enough, but
 122         # this case still needs to be supported for the Jenkins job that builds
 123         # the documentation for a release from the release tarball.
 124         gmx_add_custom_output_target(doxygen-source-timestamp
 125             RUN_ALWAYS OUTPUT STAMP
 126             COMMENT "Updating Doxygen source timestamp")
 127     endif()
 128
 129     # Helper function to create a Doxygen build target
 130     function (add_doxygen_target TARGET TYPE COMMENT)
 131         set(_deps doxygen-source-timestamp doxygen-version
 132             ${CMAKE_CURRENT_BINARY_DIR}/Doxyfile-${TYPE})
 133         set(_fast_arg "")
 134         list (FIND ARGN "DEPGRAPHS" _index)
 135         if (${_index} GREATER -1)
 136             set(_fast_arg "ADD_FAST_TARGET")
 137             if (TARGET dep-graphs-dot)
 138                 list(APPEND _deps dep-graphs-dot)
 139             endif()
 140         endif()
 141         list (FIND ARGN "DEPXML" _index)
 142         if (${_index} GREATER -1)
 143             list(APPEND _deps doxygen-xml)
 144         endif()
 145         gmx_add_custom_output_target(${TARGET} OUTPUT STAMP ${_fast_arg}
 146             # Ensure the directory exists to avoid spurious warnings
 147             COMMAND ${CMAKE_COMMAND} -E make_directory ${DEPGRAPH_DIR}
 148             COMMAND ${CMAKE_COMMAND} -DDOCTYPE=${TYPE} -P RunDoxygen.cmake
 149             DEPENDS ${_deps}
 150             WORKING_DIRECTORY ${CMAKE_CURRENT_BINARY_DIR}
 151             COMMENT "${COMMENT}" USES_TERMINAL)
 152         if (_fast_arg)
 153             add_dependencies(${TARGET}-fast doxygen-version)
 154         endif()
 155     endfunction()
 156
 157     # The XML target is necessary for the dependency graphs
 158     add_doxygen_target(doxygen-xml xml "Extracting Doxygen documentation to XML")
 159
 160     # Add targets for generating the dependency graphs; they are necessary for
 161     # the full and lib variants of the documentation.
 162     if (USE_PYTHON_SCRIPTS)
 163         # Add target that generates .dot files for the dependency graphs.
 164         # The output also depends on the Doxygen source files, but the
 165         # dependency on doxygen-xml takes care of that transitively.
 166         gmx_add_custom_output_target(dep-graphs-dot ADD_FAST_TARGET
 167             OUTPUT STAMP
 168             COMMAND ${Python3_EXECUTABLE}
 169                 ${CMAKE_CURRENT_SOURCE_DIR}/graphbuilder.py
 170                 -S ${CMAKE_SOURCE_DIR} -B ${CMAKE_BINARY_DIR}
 171                 -o ${DEPGRAPH_DIR}
 172             DEPENDS doxygen-xml ${INSTALLED_HEADER_FILE}
 173                 ${CMAKE_CURRENT_SOURCE_DIR}/doxygenxml.py
 174                 ${CMAKE_CURRENT_SOURCE_DIR}/gmxtree.py
 175                 ${CMAKE_CURRENT_SOURCE_DIR}/graphbuilder.py
 176             COMMENT "Generating include dependency graphs for dot"
 177             USES_TERMINAL)
 178
 179         # Add separate targets for converting the .dot files to .png.
 180         # These are not needed by the Doxygen targets, but are useful for
 181         # investigating just the graphs.
 182         set(dep_graphs_command_dot
 183             ${CMAKE_COMMAND} -DGRAPHDIR=${DEPGRAPH_DIR}
 184             -DDOT_EXECUTABLE=${DOXYGEN_DOT_EXECUTABLE}
 185             -P ${CMAKE_CURRENT_SOURCE_DIR}/generateGraphs.cmake)
 186         add_custom_target(dep-graphs      COMMAND ${dep_graphs_command_dot}
 187             COMMENT "Generating PNG include dependency graphs" VERBATIM)
 188         add_custom_target(dep-graphs-fast COMMAND ${dep_graphs_command_dot}
 189             COMMENT "Generating PNG include dependency graphs" VERBATIM)
 190         add_dependencies(dep-graphs      dep-graphs-dot)
 191         add_dependencies(dep-graphs-fast dep-graphs-dot-fast)
 192     endif()
 193
 194     # Create the actual targets to build the documentation.
 195     add_doxygen_target(doxygen-full full "Generating full documentation with Doxygen" DEPGRAPHS DEPXML)
 196     add_doxygen_target(doxygen-lib  lib  "Generating library documentation with Doxygen" DEPGRAPHS DEPXML)
 197     add_doxygen_target(doxygen-user user "Generating public API documentation with Doxygen" DEPXML)
 198     add_doxygen_target(doxygen-dev dev "Generating verbose developer docs with Doxygen" DEPGRAPHS DEPXML)
 199     # Convenience targets to build all the documentation flavors.
 200     add_custom_target(doxygen-all)
 201     add_custom_target(doxygen-all-fast)
 202     add_dependencies(doxygen-all      doxygen-full doxygen-lib doxygen-user)
 203     add_dependencies(doxygen-all-fast doxygen-full-fast doxygen-lib-fast doxygen-user)
 204
 205     # Finally, create the check-source target.
 206     if (USE_PYTHON_SCRIPTS)
 207         # TODO: Consider whether this is the best location for this code,
 208         # since not all of it is Doxygen-specific (but nearly all of it
 209         # relies on the Doxygen XML documentation).
 210         # The output .log file currently needs to be here, since Jenkins
 211         # expects that.
 212         set(check_source_command
 213             ${Python3_EXECUTABLE} ${CMAKE_CURRENT_SOURCE_DIR}/check-source.py
 214             -S ${CMAKE_SOURCE_DIR} -B ${CMAKE_BINARY_DIR}
 215             -l ${CMAKE_CURRENT_BINARY_DIR}/check-source.log
 216             --ignore ${CMAKE_CURRENT_SOURCE_DIR}/suppressions.txt)
 217         add_custom_target(check-source      COMMAND ${check_source_command}
 218             COMMENT "Checking source code for various issues" VERBATIM USES_TERMINAL)
 219         add_custom_target(check-source-fast COMMAND ${check_source_command}
 220             COMMENT "Checking source code for various issues" VERBATIM USES_TERMINAL)
 221         add_dependencies(check-source       doxygen-xml)
 222     endif()
 223 else()
 224     function (add_disabled_doxygen_target TARGET)
 225         add_custom_target(${TARGET}
 226             COMMAND ${CMAKE_COMMAND} -E echo
 227                 "Cannot build/run target ${TARGET} because Doxygen is not available"
 228             COMMENT "Doxygen not available" VERBATIM)
 229     endfunction()
 230     add_disabled_doxygen_target(doxygen-all)
 231     add_disabled_doxygen_target(doxygen-all-fast)
 232     add_disabled_doxygen_target(doxygen-xml)
 233     add_disabled_doxygen_target(doxygen-user)
 234     add_disabled_doxygen_target(doxygen-lib)
 235     add_disabled_doxygen_target(doxygen-lib-fast)
 236     add_disabled_doxygen_target(doxygen-full)
 237     add_disabled_doxygen_target(doxygen-full-fast)
 238     add_disabled_doxygen_target(check-source)
 239     add_disabled_doxygen_target(check-source-fast)
 240     add_disabled_doxygen_target(dep-graphs)
 241     add_disabled_doxygen_target(dep-graphs-fast)
 242 endif()