docs/doxygen/CMakeLists.txt

   1 #
   2 # This file is part of the GROMACS molecular simulation package.
   3 #
   4 # Copyright (c) 2012,2013,2014, 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 find_package(PythonInterp)
  60 set(USE_PYTHON_SCRIPTS OFF)
  61 if (PYTHONINTERP_FOUND AND NOT PYTHON_VERSION_STRING VERSION_LESS "2.6")
  62     set(USE_PYTHON_SCRIPTS ON)
  63 endif()
  64
  65 # Create a stamp file whenever cmake is run, as the list of installed files may
  66 # have changed.
  67 gmx_get_stamp_filename(configure_stamp_file cmake-configure)
  68 file(WRITE ${configure_stamp_file} "Timestamp for configuration")
  69 # Note that if you relocate this file, you also need to change gmxtree.py.
  70 set(INSTALLED_HEADERS_FILE ${CMAKE_CURRENT_BINARY_DIR}/installed-headers.txt)
  71 gmx_add_custom_output_target(find-installed-headers
  72     OUTPUT ${INSTALLED_HEADERS_FILE}
  73     COMMAND ${CMAKE_COMMAND}
  74         -D SRCDIR=${CMAKE_SOURCE_DIR}
  75         -D BUILDDIR=${CMAKE_BINARY_DIR}
  76         -D OUTFILE=${INSTALLED_HEADERS_FILE}
  77         -P ${CMAKE_CURRENT_SOURCE_DIR}/getInstalledHeaders.cmake
  78     DEPENDS ${configure_stamp_file}
  79     COMMENT "Generating installed headers list")
  80
  81 ########################################################################
  82 # Doxygen configuration
  83 #
  84 if (DOXYGEN_FOUND)
  85     # Generate Doxygen input configuration files
  86     file(GLOB NB_KERNEL_DIRS
  87          ${CMAKE_SOURCE_DIR}/src/gromacs/gmxlib/nonbonded/nb_kernel_*/)
  88     list(REMOVE_ITEM NB_KERNEL_DIRS
  89          ${CMAKE_SOURCE_DIR}/src/gromacs/gmxlib/nonbonded/nb_kernel_c)
  90     foreach (dir ${NB_KERNEL_DIRS})
  91         SET(NB_KERNEL_DIRS_TO_IGNORE_IN_DOXYGEN
  92             "${NB_KERNEL_DIRS_TO_IGNORE_IN_DOXYGEN} \\\n                         ${dir}")
  93     endforeach()
  94     set(DEPGRAPH_DIR ${CMAKE_CURRENT_BINARY_DIR}/depgraphs)
  95     set(DOXYGEN_SECTIONS "")
  96     set(DOXYGEN_EXTRA_SETTINGS "")
  97     if (GMX_COMPACT_DOXYGEN)
  98         set(DOXYGEN_EXTRA_SETTINGS "@INCLUDE   = ${CMAKE_CURRENT_SOURCE_DIR}/Doxyfile-compact")
  99     endif()
 100     configure_file(Doxyfile-common.cmakein Doxyfile-common)
 101     configure_file(Doxyfile-full.cmakein Doxyfile-full)
 102     configure_file(Doxyfile-lib.cmakein Doxyfile-lib)
 103     configure_file(Doxyfile-user.cmakein Doxyfile-user)
 104     configure_file(Doxyfile-xml.cmakein Doxyfile-xml)
 105
 106     configure_file(RunDoxygen.cmake.cmakein RunDoxygen.cmake @ONLY)
 107     gmx_configure_version_file(Doxyfile-version.cmakein Doxyfile-version
 108                                TARGET doxygen-version)
 109
 110     # Add a stamp that gets updated whenever a source file that contributes to
 111     # Doxygen is updated.  All Doxygen targets can then depend on this stamp,
 112     # instead of each specifying this massive set of dependencies.
 113     # TODO: The set of files that affects Doxygen is not exactly the same as
 114     # that which affects the dependency graphs, and neither is captured
 115     # perfectly with this set, but this can be improved if it becomes a real
 116     # issue (the differences are mainly in the generated group kernel files,
 117     # but there are some minor other differences as well).
 118     if (SOURCE_IS_GIT_REPOSITORY AND GIT_FOUND)
 119         gmx_get_files_with_gitattribute(doxygen_sources gmx-doxygen)
 120         # Add also common configuration files that influence the generation.
 121         set(doxygen_deps
 122             ${CMAKE_CURRENT_BINARY_DIR}/Doxyfile-common
 123             ${CMAKE_CURRENT_BINARY_DIR}/RunDoxygen.cmake)
 124         if (GMX_COMPACT_DOXYGEN)
 125             list(APPEND doxygen_deps ${CMAKE_CURRENT_BINARY_DIR}/Doxyfile-compact)
 126         endif()
 127         gmx_add_custom_output_target(doxygen-source-timestamp
 128             OUTPUT STAMP
 129             DEPENDS_FILE_LIST doxygen_sources
 130             DEPENDS ${doxygen_deps}
 131             COMMENT "Updating Doxygen source timestamp")
 132     else()
 133         # If there is no git, we just update the stamp every time, and the
 134         # builds are triggered every time.  This should be rare enough, but
 135         # this case still needs to be supported for the Jenkins job that builds
 136         # the documentation for a release from the release tarball.
 137         gmx_add_custom_output_target(doxygen-source-timestamp
 138             RUN_ALWAYS OUTPUT STAMP
 139             COMMENT "Updating Doxygen source timestamp")
 140     endif()
 141
 142     # Helper function to create a Doxygen build target
 143     function (add_doxygen_target TARGET TYPE COMMENT)
 144         set(_deps doxygen-source-timestamp doxygen-version
 145             ${CMAKE_CURRENT_BINARY_DIR}/Doxyfile-${TYPE})
 146         set(_fast_arg "")
 147         if ("${ARGN}" STREQUAL "DEPGRAPHS")
 148             set(_fast_arg "ADD_FAST_TARGET")
 149             if (TARGET dep-graphs-dot)
 150                 list(APPEND _deps dep-graphs-dot)
 151             endif()
 152         endif()
 153         gmx_add_custom_output_target(${TARGET} OUTPUT STAMP ${_fast_arg}
 154             # Ensure the directory exists to avoid spurious warnings
 155             COMMAND ${CMAKE_COMMAND} -E make_directory ${DEPGRAPH_DIR}
 156             COMMAND ${CMAKE_COMMAND} -DDOCTYPE=${TYPE} -P RunDoxygen.cmake
 157             DEPENDS ${_deps}
 158             WORKING_DIRECTORY ${CMAKE_CURRENT_BINARY_DIR}
 159             COMMENT "${COMMENT}")
 160         if (_fast_arg)
 161             add_dependencies(${TARGET}-fast doxygen-version)
 162         endif()
 163     endfunction()
 164
 165     # The XML target is necessary for the dependency graphs
 166     add_doxygen_target(doc-xml xml "Extracting Doxygen documentation to XML")
 167
 168     # Add targets for generating the dependency graphs; they are necessary for
 169     # the full and lib variants of the documentation.
 170     if (USE_PYTHON_SCRIPTS)
 171         # Add target that generates .dot files for the dependency graphs.
 172         # The output also depends on the Doxygen source files, but the
 173         # dependency on doc-xml takes care of that transitively.
 174         gmx_add_custom_output_target(dep-graphs-dot ADD_FAST_TARGET
 175             OUTPUT STAMP
 176             COMMAND ${PYTHON_EXECUTABLE}
 177                 ${CMAKE_CURRENT_SOURCE_DIR}/graphbuilder.py
 178                 -S ${CMAKE_SOURCE_DIR} -B ${CMAKE_BINARY_DIR}
 179                 --ignore-cycles ${CMAKE_CURRENT_SOURCE_DIR}/cycle-suppressions.txt
 180                 -o ${DEPGRAPH_DIR}
 181             DEPENDS doc-xml find-installed-headers
 182                 ${CMAKE_CURRENT_SOURCE_DIR}/doxygenxml.py
 183                 ${CMAKE_CURRENT_SOURCE_DIR}/gmxtree.py
 184                 ${CMAKE_CURRENT_SOURCE_DIR}/graphbuilder.py
 185                 ${CMAKE_CURRENT_SOURCE_DIR}/cycle-suppressions.txt
 186             COMMENT "Generating include dependency graphs for dot")
 187         add_dependencies(dep-graphs-dot-fast find-installed-headers)
 188
 189         # Add separate targets for converting the .dot files to .png.
 190         # These are not needed by the Doxygen targets, but are useful for
 191         # investigating just the graphs.
 192         set(dep_graphs_command_dot
 193             ${CMAKE_COMMAND} -DGRAPHDIR=${DEPGRAPH_DIR}
 194             -DDOT_EXECUTABLE=${DOXYGEN_DOT_EXECUTABLE}
 195             -P ${CMAKE_CURRENT_SOURCE_DIR}/generateGraphs.cmake)
 196         add_custom_target(dep-graphs      COMMAND ${dep_graphs_command_dot}
 197             COMMENT "Generating PNG include dependency graphs" VERBATIM)
 198         add_custom_target(dep-graphs-fast COMMAND ${dep_graphs_command_dot}
 199             COMMENT "Generating PNG include dependency graphs" VERBATIM)
 200         add_dependencies(dep-graphs      dep-graphs-dot)
 201         add_dependencies(dep-graphs-fast dep-graphs-dot-fast)
 202     endif()
 203
 204     # Create the actual targets to build the documentation.
 205     add_doxygen_target(doc-full full "Generating full documentation with Doxygen" DEPGRAPHS)
 206     add_doxygen_target(doc-lib  lib  "Generating library documentation with Doxygen" DEPGRAPHS)
 207     add_doxygen_target(doc-user user "Generating public API documentation with Doxygen")
 208     # Convenience targets to build all the documentation flavors.
 209     add_custom_target(doc-all)
 210     add_custom_target(doc-all-fast)
 211     add_dependencies(doc-all      doc-full doc-lib doc-user)
 212     add_dependencies(doc-all-fast doc-full-fast doc-lib-fast doc-user)
 213
 214     # Finally, create the doc-check target.
 215     if (USE_PYTHON_SCRIPTS)
 216         # TODO: Consider whether this is the best name and location for this
 217         # code, since not all of it is Doxygen-specific (but nearly all of it
 218         # relies on the Doxygen XML documentation).
 219         set(doc_check_command
 220             ${PYTHON_EXECUTABLE} ${CMAKE_CURRENT_SOURCE_DIR}/doxygen-check.py
 221             -S ${CMAKE_SOURCE_DIR} -B ${CMAKE_BINARY_DIR}
 222             -l ${CMAKE_CURRENT_BINARY_DIR}/doxygen-check.log
 223             --exitcode
 224             --ignore ${CMAKE_CURRENT_SOURCE_DIR}/suppressions.txt
 225             --ignore-cycles ${CMAKE_CURRENT_SOURCE_DIR}/cycle-suppressions.txt)
 226         add_custom_target(doc-check      COMMAND ${doc_check_command}
 227             COMMENT "Checking Doxygen documentation" VERBATIM)
 228         add_custom_target(doc-check-fast COMMAND ${doc_check_command}
 229             COMMENT "Checking Doxygen documentation" VERBATIM)
 230         add_dependencies(doc-check      doc-xml find-installed-headers)
 231         add_dependencies(doc-check-fast find-installed-headers)
 232     endif()
 233 endif()