2 # This file is part of the GROMACS molecular simulation package.
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.
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.
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.
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.
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.
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.
36 include(gmxCustomCommandUtilities)
37 include(gmxOptionUtilities)
39 find_package(Doxygen QUIET)
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
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)
50 mark_as_advanced(DOXYGEN_MSCGEN_EXECUTABLE)
55 "Skip parts of Doxygen documentation (in particular, many graphs) to save disk space and time"
58 mark_as_advanced(GMX_COMPACT_DOXYGEN)
60 set(USE_PYTHON_SCRIPTS OFF)
61 if (Python3_Interpreter_FOUND)
62 set(USE_PYTHON_SCRIPTS ON)
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)
70 ########################################################################
71 # Doxygen configuration
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")
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})
88 set(DOXYGENLIST "common;dev;full;lib;user;xml")
89 foreach(_target ${DOXYGENLIST})
90 configure_file(Doxyfile-${_target}.cmakein Doxyfile-${_target})
93 configure_file(RunDoxygen.cmake.cmakein RunDoxygen.cmake @ONLY)
94 gmx_configure_version_file(Doxyfile-version.cmakein Doxyfile-version
95 TARGET doxygen-version)
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.
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)
114 gmx_add_custom_output_target(doxygen-source-timestamp
116 DEPENDS_FILE_LIST doxygen_sources
117 DEPENDS ${doxygen_deps}
118 COMMENT "Updating Doxygen source timestamp")
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 CI 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")
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})
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)
141 list (FIND ARGN "DEPXML" _index)
142 if (${_index} GREATER -1)
143 list(APPEND _deps doxygen-xml)
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
150 WORKING_DIRECTORY ${CMAKE_CURRENT_BINARY_DIR}
151 COMMENT "${COMMENT}" USES_TERMINAL)
153 add_dependencies(${TARGET}-fast doxygen-version)
157 # The XML target is necessary for the dependency graphs
158 add_doxygen_target(doxygen-xml xml "Extracting Doxygen documentation to XML")
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
168 COMMAND ${Python3_EXECUTABLE}
169 ${CMAKE_CURRENT_SOURCE_DIR}/graphbuilder.py
170 -S ${CMAKE_SOURCE_DIR} -B ${CMAKE_BINARY_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"
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)
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)
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 CI
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)
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)
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)