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(gmxOptionUtilities)
  36
  37 find_package(Doxygen QUIET)
  38 if (DOXYGEN_FOUND)
  39     # This logic closely follows that found in FindDoxygen.cmake for dot,
  40     # except that the PATH variable is not cached.
  41     find_program(DOXYGEN_MSCGEN_EXECUTABLE
  42         NAMES mscgen
  43         DOC "Message sequence chart renderer tool (http://www.mcternan.me.uk/mscgen/)")
  44     if (DOXYGEN_MSCGEN_EXECUTABLE)
  45         set(DOXYGEN_MSCGEN_FOUND TRUE)
  46         get_filename_component(DOXYGEN_MSCGEN_PATH "${DOXYGEN_MSCGEN_EXECUTABLE}" PATH)
  47     endif()
  48     mark_as_advanced(DOXYGEN_MSCGEN_EXECUTABLE)
  49 endif()
  50
  51 gmx_dependent_option(
  52     GMX_COMPACT_DOXYGEN
  53     "Skip parts of Doxygen documentation (in particular, many graphs) to save disk space and time"
  54     OFF
  55     DOXYGEN_FOUND)
  56 mark_as_advanced(GMX_COMPACT_DOXYGEN)
  57
  58 find_package(PythonInterp)
  59 set(USE_PYTHON_SCRIPTS OFF)
  60 if (PYTHONINTERP_FOUND AND NOT PYTHON_VERSION_STRING VERSION_LESS "2.6")
  61     set(USE_PYTHON_SCRIPTS ON)
  62 endif()
  63
  64 # Create a stamp file whenever cmake is run, as the list of installed files may
  65 # have changed.
  66 set(CONFIGURE_STAMP_FILE ${CMAKE_CURRENT_BINARY_DIR}/cmake-stamp.txt)
  67 file(WRITE ${CONFIGURE_STAMP_FILE} "Stamp for configuration")
  68 # Note that if you relocate this file, you also need to change gmxtree.py.
  69 set(INSTALLED_HEADERS_FILE ${CMAKE_CURRENT_BINARY_DIR}/installed-headers.txt)
  70 add_custom_command(OUTPUT ${INSTALLED_HEADERS_FILE}
  71     COMMAND ${CMAKE_COMMAND}
  72         -D SRCDIR=${CMAKE_SOURCE_DIR}
  73         -D BUILDDIR=${CMAKE_BINARY_DIR}
  74         -D OUTFILE=${INSTALLED_HEADERS_FILE}
  75         -P ${CMAKE_CURRENT_SOURCE_DIR}/getInstalledHeaders.cmake
  76     DEPENDS ${CONFIGURE_STAMP_FILE}
  77     COMMENT "Generating installed headers list" VERBATIM)
  78 add_custom_target(find-installed-headers DEPENDS ${INSTALLED_HEADERS_FILE})
  79
  80 ########################################################################
  81 # Doxygen configuration
  82 ########################################################################
  83 if (DOXYGEN_FOUND)
  84     file(GLOB NB_KERNEL_DIRS
  85          ${CMAKE_SOURCE_DIR}/src/gromacs/gmxlib/nonbonded/nb_kernel_*/)
  86     list(REMOVE_ITEM NB_KERNEL_DIRS
  87          ${CMAKE_SOURCE_DIR}/src/gromacs/gmxlib/nonbonded/nb_kernel_c)
  88     foreach (NB_KERNEL_DIR ${NB_KERNEL_DIRS})
  89         SET(NB_KERNEL_DIRS_TO_IGNORE_IN_DOXYGEN
  90             "${NB_KERNEL_DIRS_TO_IGNORE_IN_DOXYGEN} \\\n                         ${NB_KERNEL_DIR}")
  91     endforeach()
  92     set(DEPGRAPH_DIR ${CMAKE_CURRENT_BINARY_DIR}/depgraphs)
  93     set(DOXYGEN_SECTIONS "")
  94     set(DOXYGEN_EXTRA_SETTINGS "")
  95     if (GMX_COMPACT_DOXYGEN)
  96         set(DOXYGEN_EXTRA_SETTINGS "@INCLUDE   = ${CMAKE_CURRENT_SOURCE_DIR}/Doxyfile-compact")
  97     endif()
  98     configure_file(Doxyfile-common.cmakein Doxyfile-common)
  99     configure_file(Doxyfile-full.cmakein Doxyfile-full)
 100     configure_file(Doxyfile-lib.cmakein Doxyfile-lib)
 101     configure_file(Doxyfile-user.cmakein Doxyfile-user)
 102     configure_file(Doxyfile-xml.cmakein Doxyfile-xml)
 103
 104     configure_file(RunDoxygen.cmake.cmakein RunDoxygen.cmake @ONLY)
 105     gmx_configure_version_file(Doxyfile-version.cmakein Doxyfile-version
 106                                TARGET doxygen-version)
 107
 108     function (add_doxygen_target TARGET TYPE COMMENT)
 109         add_custom_target(${TARGET}
 110             # Ensure the directory exists to avoid spurious warnings
 111             ${CMAKE_COMMAND} -E make_directory ${DEPGRAPH_DIR}
 112             COMMAND ${CMAKE_COMMAND} -DDOCTYPE=${TYPE} -P RunDoxygen.cmake
 113             WORKING_DIRECTORY ${CMAKE_CURRENT_BINARY_DIR}
 114             COMMENT "${COMMENT}" VERBATIM)
 115         add_dependencies(${TARGET} doxygen-version)
 116     endfunction()
 117     # The targets ending with -fast do the same thing as the target without the
 118     # suffix, but assume that time-consuming dependencies have already been
 119     # built, making it faster and more convenient to test a single part of the
 120     # system.
 121     add_doxygen_target(doc-full      full "Generating full documentation with Doxygen")
 122     add_doxygen_target(doc-full-fast full "Generating full documentation with Doxygen")
 123     add_doxygen_target(doc-lib       lib  "Generating library documentation with Doxygen")
 124     add_doxygen_target(doc-lib-fast  lib  "Generating library documentation with Doxygen")
 125     add_doxygen_target(doc-user      user "Generating public API documentation with Doxygen")
 126     add_doxygen_target(doc-xml       xml  "Extracting Doxygen documentation to XML")
 127     add_custom_target(doc-all)
 128     add_custom_target(doc-all-fast)
 129     add_dependencies(doc-all doc-full doc-lib doc-user)
 130     add_dependencies(doc-all-fast doc-full-fast doc-lib-fast doc-user)
 131
 132     if (USE_PYTHON_SCRIPTS)
 133         # TODO: Consider whether this is the best name and location for this
 134         # code, since not all of it is Doxygen-specific (but nearly all of it
 135         # relies on the Doxygen XML documentation).
 136         set(doc_check_command
 137             ${PYTHON_EXECUTABLE} ${CMAKE_CURRENT_SOURCE_DIR}/doxygen-check.py
 138             -S ${CMAKE_SOURCE_DIR} -B ${CMAKE_BINARY_DIR}
 139             -l ${CMAKE_CURRENT_BINARY_DIR}/doxygen-check.log
 140             --exitcode
 141             --ignore ${CMAKE_CURRENT_SOURCE_DIR}/suppressions.txt
 142             --ignore-cycles ${CMAKE_CURRENT_SOURCE_DIR}/cycle-suppressions.txt)
 143         add_custom_target(doc-check COMMAND ${doc_check_command}
 144             COMMENT "Checking Doxygen documentation" VERBATIM)
 145         add_dependencies(doc-check doc-xml find-installed-headers)
 146         add_custom_target(doc-check-fast COMMAND ${doc_check_command}
 147             COMMENT "Checking Doxygen documentation" VERBATIM)
 148         add_dependencies(doc-check-fast find-installed-headers)
 149
 150         set(dep_graphs_command_python
 151             ${PYTHON_EXECUTABLE} ${CMAKE_CURRENT_SOURCE_DIR}/graphbuilder.py
 152             -S ${CMAKE_SOURCE_DIR} -B ${CMAKE_BINARY_DIR}
 153             --ignore-cycles ${CMAKE_CURRENT_SOURCE_DIR}/cycle-suppressions.txt
 154             -o ${DEPGRAPH_DIR})
 155         set(dep_graphs_command_dot
 156             ${CMAKE_COMMAND} -DGRAPHDIR=${DEPGRAPH_DIR}
 157             -DDOT_EXECUTABLE=${DOXYGEN_DOT_EXECUTABLE}
 158             -P ${CMAKE_CURRENT_SOURCE_DIR}/generateGraphs.cmake)
 159         add_custom_target(dep-graphs-dot
 160             COMMAND ${dep_graphs_command_python}
 161             COMMENT "Generating include dependency graphs for dot" VERBATIM)
 162         add_custom_target(dep-graphs
 163             COMMAND ${dep_graphs_command_dot}
 164             COMMENT "Generating PNG include dependency graphs" VERBATIM)
 165         add_dependencies(dep-graphs-dot doc-xml find-installed-headers)
 166         add_dependencies(dep-graphs dep-graphs-dot)
 167         add_dependencies(doc-full dep-graphs-dot)
 168         add_dependencies(doc-lib dep-graphs-dot)
 169
 170         add_custom_target(dep-graphs-dot-fast
 171             COMMAND ${dep_graphs_command_python}
 172             COMMENT "Generating include dependency graphs for dot" VERBATIM)
 173         add_custom_target(dep-graphs-fast
 174             COMMAND ${dep_graphs_command_dot}
 175             COMMENT "Generating PNG include dependency graphs" VERBATIM)
 176         # Finding the installed headers doesn't actually run again if nothing
 177         # has changed, so that can be safely added as a dependency.
 178         add_dependencies(dep-graphs-dot-fast find-installed-headers)
 179         add_dependencies(dep-graphs-fast dep-graphs-dot-fast)
 180     endif()
 181 endif()