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