1 # Distributed under the OSI-approved BSD 3-Clause License. See accompanying
2 # file Copyright.txt or https://cmake.org/licensing for details.
4 if(NOT CMake_SOURCE_DIR)
5 set(CMakeHelp_STANDALONE 1)
6 cmake_minimum_required(VERSION 3.13...3.23 FATAL_ERROR)
7 get_filename_component(tmp "${CMAKE_CURRENT_SOURCE_DIR}" PATH)
8 get_filename_component(CMake_SOURCE_DIR "${tmp}" PATH)
9 include(${CMake_SOURCE_DIR}/Modules/CTestUseLaunchers.cmake)
10 include(${CMake_SOURCE_DIR}/Source/CMakeVersion.cmake)
11 include(${CMake_SOURCE_DIR}/Source/CMakeInstallDestinations.cmake)
12 configure_file(${CMAKE_CURRENT_SOURCE_DIR}/CTestCustom.cmake.in ${CMAKE_CURRENT_BINARY_DIR}/CTestCustom.cmake @ONLY)
14 unset(CMAKE_DATA_DIR CACHE)
15 macro(CMake_OPTIONAL_COMPONENT)
19 project(CMakeHelp NONE)
21 option(SPHINX_INFO "Build Info manual with Sphinx" OFF)
22 option(SPHINX_MAN "Build man pages with Sphinx" OFF)
23 option(SPHINX_HTML "Build html help with Sphinx" OFF)
24 option(SPHINX_SINGLEHTML "Build html single page help with Sphinx" OFF)
25 option(SPHINX_QTHELP "Build Qt help with Sphinx" OFF)
26 option(SPHINX_LATEXPDF "Build PDF help with Sphinx using LaTeX" OFF)
27 option(SPHINX_TEXT "Build text help with Sphinx (not installed)" OFF)
28 find_program(SPHINX_EXECUTABLE
30 DOC "Sphinx Documentation Builder (sphinx-doc.org)"
32 set(SPHINX_FLAGS "" CACHE STRING "Flags to pass to sphinx-build")
33 separate_arguments(sphinx_flags UNIX_COMMAND "${SPHINX_FLAGS}")
35 mark_as_advanced(SPHINX_TEXT)
36 mark_as_advanced(SPHINX_FLAGS)
38 if(NOT SPHINX_INFO AND NOT SPHINX_MAN AND NOT SPHINX_HTML AND NOT SPHINX_SINGLEHTML AND NOT SPHINX_QTHELP AND NOT SPHINX_TEXT AND NOT SPHINX_LATEXPDF)
40 elseif(NOT SPHINX_EXECUTABLE)
41 message(FATAL_ERROR "SPHINX_EXECUTABLE (sphinx-build) is not found!")
44 set(copyright_line_regex "^Copyright (2000-20[0-9][0-9] Kitware.*)")
45 file(STRINGS "${CMake_SOURCE_DIR}/Copyright.txt" copyright_line
46 LIMIT_COUNT 1 REGEX "${copyright_line_regex}")
47 if(copyright_line MATCHES "${copyright_line_regex}")
48 set(conf_copyright "${CMAKE_MATCH_1}")
50 set(conf_copyright "Kitware, Inc.")
53 if(CMake_SPHINX_CMAKE_ORG)
54 set(conf_baseurl "https://cmake.org/cmake/help/latest")
59 set(conf_docs "${CMake_SOURCE_DIR}/Help")
60 set(conf_path "${CMAKE_CURRENT_SOURCE_DIR}")
61 set(conf_version "${CMake_VERSION_MAJOR}.${CMake_VERSION_MINOR}.${CMake_VERSION_PATCH}")
62 set(conf_release "${CMake_VERSION}")
63 configure_file(conf.py.in conf.py @ONLY)
67 list(APPEND doc_formats html)
69 # we provide the path to the produced html output in the console
70 # for tools that support URI protocol schemes
71 set(html_post_commands
72 COMMAND ${CMAKE_COMMAND} -E echo "sphinx-build html: HTML documentation generated in file://${CMAKE_CURRENT_BINARY_DIR}/html/index.html"
77 list(APPEND doc_formats man)
80 list(APPEND doc_formats singlehtml)
83 list(APPEND doc_formats text)
86 find_program(MAKEINFO_EXECUTABLE
90 if (NOT MAKEINFO_EXECUTABLE)
91 message(FATAL_ERROR "MAKEINFO_EXECUTABLE (makeinfo) not found!")
93 list(APPEND doc_formats texinfo)
95 # Sphinx texinfo builder supports .info, .txt, .html and .pdf output.
96 # SPHINX_INFO controls the .info output.
97 set(texinfo_post_commands
98 COMMAND ${MAKEINFO_EXECUTABLE} --no-split -o
99 ${CMAKE_CURRENT_BINARY_DIR}/texinfo/cmake.info
100 ${CMAKE_CURRENT_BINARY_DIR}/texinfo/cmake.texi
104 find_package(Python REQUIRED)
106 find_program(QHELPGENERATOR_EXECUTABLE
107 NAMES qhelpgenerator-qt5 qhelpgenerator
108 DOC "qhelpgenerator tool"
110 if(NOT QHELPGENERATOR_EXECUTABLE)
111 message(FATAL_ERROR "QHELPGENERATOR_EXECUTABLE (qhelpgenerator) not found!")
113 list(APPEND doc_formats qthelp)
115 set(qthelp_post_commands
116 # Workaround for assistant prior to
117 # https://codereview.qt-project.org/#change,82250 in Qt 4.
118 COMMAND ${CMAKE_COMMAND} "-DCSS_DIR=${CMAKE_CURRENT_BINARY_DIR}/qthelp/_static"
119 -P "${CMAKE_CURRENT_SOURCE_DIR}/apply_qthelp_css_workaround.cmake"
120 # Workaround sphinx configurability:
121 # https://github.com/sphinx-doc/sphinx/issues/1448
122 COMMAND ${CMAKE_COMMAND} "-DQTHELP_DIR=${CMAKE_CURRENT_BINARY_DIR}/qthelp/"
123 -P "${CMAKE_CURRENT_SOURCE_DIR}/fixup_qthelp_names.cmake"
125 # Create proper identifiers. Workaround for
126 # https://github.com/sphinx-doc/sphinx/issues/1491
127 COMMAND "${Python_EXECUTABLE}"
128 "${CMAKE_CURRENT_SOURCE_DIR}/create_identifiers.py"
129 "${CMAKE_CURRENT_BINARY_DIR}/qthelp/"
131 COMMAND ${QHELPGENERATOR_EXECUTABLE}
132 ${CMAKE_CURRENT_BINARY_DIR}/qthelp/CMake.qhcp
136 list(APPEND doc_formats latexpdf)
139 set(doc_html_opts "")
140 if(CMake_SPHINX_CMAKE_ORG)
141 list(APPEND doc_html_opts
147 if(CMake_SPHINX_CMAKE_ORG_OUTDATED)
148 list(APPEND doc_html_opts -A outdated=1)
151 list(APPEND html_pre_commands
152 COMMAND ${CMAKE_COMMAND} -Dversion=${CMake_VERSION} -P ${CMAKE_CURRENT_SOURCE_DIR}/tutorial_archive.cmake
155 list(APPEND qthelp_post_commands
156 COMMAND ${CMAKE_COMMAND} -E copy
157 "${CMAKE_CURRENT_BINARY_DIR}/qthelp/CMake.qch"
158 "${CMAKE_CURRENT_BINARY_DIR}/html/CMake.qch"
162 set(doc_format_outputs "")
163 set(doc_format_last "")
164 foreach(format IN LISTS doc_formats)
165 set(doc_format_output "doc_format_${format}")
166 set(doc_format_log "build-${format}.log")
167 if(CMake_SPHINX_CMAKE_ORG)
168 set(doctrees "doctrees/${format}")
170 set(doctrees "doctrees")
172 if(format STREQUAL "latexpdf")
173 # This format does not use builder (-b) but make_mode (-M) which expects
174 # arguments in peculiar order
176 OUTPUT ${doc_format_output}
177 ${${format}_pre_commands}
178 COMMAND ${SPHINX_EXECUTABLE}
180 ${CMake_SOURCE_DIR}/Help
181 ${CMAKE_CURRENT_BINARY_DIR}/${format}
182 -c ${CMAKE_CURRENT_BINARY_DIR}
183 -d ${CMAKE_CURRENT_BINARY_DIR}/${doctrees}
185 ${doc_${format}_opts}
186 > ${doc_format_log} # log stdout, pass stderr
187 ${${format}_post_commands}
188 DEPENDS ${doc_format_last}
189 COMMENT "sphinx-build ${format}: see Utilities/Sphinx/${doc_format_log}"
193 # other formats use standard builder (-b) mode
195 OUTPUT ${doc_format_output}
196 ${${format}_pre_commands}
197 COMMAND ${SPHINX_EXECUTABLE}
198 -c ${CMAKE_CURRENT_BINARY_DIR}
199 -d ${CMAKE_CURRENT_BINARY_DIR}/${doctrees}
202 ${doc_${format}_opts}
203 ${CMake_SOURCE_DIR}/Help
204 ${CMAKE_CURRENT_BINARY_DIR}/${format}
205 > ${doc_format_log} # log stdout, pass stderr
206 ${${format}_post_commands}
207 DEPENDS ${doc_format_last}
208 COMMENT "sphinx-build ${format}: see Utilities/Sphinx/${doc_format_log}"
212 set_property(SOURCE ${doc_format_output} PROPERTY SYMBOLIC 1)
213 list(APPEND doc_format_outputs ${doc_format_output})
214 if(NOT CMake_SPHINX_CMAKE_ORG)
215 set(doc_format_last ${doc_format_output})
219 add_custom_target(documentation ALL DEPENDS ${doc_format_outputs})
221 if(CMake_SPHINX_DEPEND_ON_EXECUTABLES)
222 foreach(t IN ITEMS cmake ccmake cmake-gui cpack ctest)
224 # Build documentation after main executables.
225 add_dependencies(documentation ${t})
230 if(CMake_SPHINX_CMAKE_ORG)
235 CMake_OPTIONAL_COMPONENT(sphinx-info)
236 install(FILES ${CMAKE_CURRENT_BINARY_DIR}/texinfo/cmake.info
237 DESTINATION ${CMAKE_INFO_DIR}
243 file(GLOB man_rst RELATIVE ${CMake_SOURCE_DIR}/Help/manual
244 ${CMake_SOURCE_DIR}/Help/manual/*.[1-9].rst)
245 foreach(m IN LISTS man_rst)
246 if("x${m}" MATCHES "^x(.+)\\.([1-9])\\.rst$")
247 set(name "${CMAKE_MATCH_1}")
248 set(sec "${CMAKE_MATCH_2}")
250 if(NOT CMakeHelp_STANDALONE)
251 if(name STREQUAL "ccmake" AND NOT BUILD_CursesDialog)
253 elseif(name STREQUAL "cmake-gui" AND NOT BUILD_QtDialog)
258 CMake_OPTIONAL_COMPONENT(sphinx-man)
259 install(FILES ${CMAKE_CURRENT_BINARY_DIR}/man/${name}.${sec}
260 DESTINATION ${CMAKE_MAN_DIR}/man${sec}
269 CMake_OPTIONAL_COMPONENT(sphinx-html)
270 install(DIRECTORY ${CMAKE_CURRENT_BINARY_DIR}/html
271 DESTINATION ${CMAKE_DOC_DIR}
273 PATTERN .buildinfo EXCLUDE
277 if(SPHINX_SINGLEHTML)
278 CMake_OPTIONAL_COMPONENT(sphinx-singlehtml)
279 install(DIRECTORY ${CMAKE_CURRENT_BINARY_DIR}/singlehtml
280 DESTINATION ${CMAKE_DOC_DIR}
282 PATTERN .buildinfo EXCLUDE
287 CMake_OPTIONAL_COMPONENT(sphinx-qthelp)
288 install(FILES ${CMAKE_CURRENT_BINARY_DIR}/qthelp/CMake.qch
289 DESTINATION ${CMAKE_DOC_DIR} ${COMPONENT}
294 CMake_OPTIONAL_COMPONENT(sphinx-latexpdf)
295 install(FILES ${CMAKE_CURRENT_BINARY_DIR}/latexpdf/latex/CMake.pdf
296 DESTINATION ${CMAKE_DOC_DIR} ${COMPONENT}