Changeset View
Changeset View
Standalone View
Standalone View
cmake/modules/KDbAddQCH.cmake
- This file was added.
| 1 | #.rst: | ||||
|---|---|---|---|---|---|
| 2 | # KDbAddQCH | ||||
| 3 | # ------------------ | ||||
| 4 | # | ||||
| 5 | # This module provides the ``kdb_add_qch`` function for generating API | ||||
| 6 | # documentation files in the QCH format, and the ``kdb_install_qch_export`` | ||||
| 7 | # function for generating and installing exported CMake targets for such | ||||
| 8 | # generated QCH files to enable builds of other software with generation of | ||||
| 9 | # QCH files to create links into the given QCH files. | ||||
| 10 | # | ||||
| 11 | # :: | ||||
| 12 | # | ||||
| 13 | # kdb_add_qch(<name> | ||||
| 14 | # OUTPUT_BASENAME <basename> | ||||
| 15 | # VERSION <version> | ||||
| 16 | # QCH_INSTALL_DESTINATION <qchfile_install_path> | ||||
| 17 | # TAGFILE_INSTALL_DESTINATION <tagsfile_install_path> | ||||
| 18 | # [SOURCE_DIRS <dir> [<dir2> [...]]] | ||||
| 19 | # [SOURCES <file> [<file2> [...]]] | ||||
| 20 | # |MD_MAINPAGE <md_file>] | ||||
| 21 | # [IMAGE_DIRS <idir> [<idir2> [...]]] | ||||
| 22 | # [EXAMPLE_DIRS <edir> [<edir2> [...]]] | ||||
| 23 | # [ORG_DOMAIN <domain>] | ||||
| 24 | # [NAMESPACE <namespace>] | ||||
| 25 | # [LINK_QCHS <qch> [<qch2> [...]]] | ||||
| 26 | # [LINK_QCHS_VERSIONED <qchv> [<qchv2> [...]]] | ||||
| 27 | # [BLANK_MACROS <macro> [<macro2> [...]]] | ||||
| 28 | # [CONFIG_TEMPLATE <configtemplate_file>] | ||||
| 29 | # [VERBOSE] | ||||
| 30 | # ) | ||||
| 31 | # | ||||
| 32 | # This macro adds a target called <name> for the creation of an API | ||||
| 33 | # documentation manual named ``<basename>.qch``in the QCH format from the | ||||
| 34 | # given sources. | ||||
| 35 | # It currently uses doxygen, future versions might optionally also allow other | ||||
| 36 | # tools. | ||||
| 37 | # Next to the QCH file the target will generate a corresponding doxygen tag | ||||
| 38 | # file name ``<basename>.tags``, which enables creating links from other | ||||
| 39 | # documentation into the generated QCH file. | ||||
| 40 | # | ||||
| 41 | # If the required tools are not found, the macro will skip creation of the | ||||
| 42 | # target and only emit a warning, so the use of the macro can be introduced | ||||
| 43 | # without requiring anyone to also have the needed tools present at that time. | ||||
| 44 | # This behaviour might change in future versions to result in a fail instead. | ||||
| 45 | # It is recommended to make the use of this macro optional, by depending | ||||
| 46 | # the call to ``kdb_add_qch()`` on a CMake option being set, with a name like | ||||
| 47 | # ``BUILD_QCH`` and being TRUE by default. This will allow the developers to | ||||
| 48 | # saves resources on normal source development build cycles by setting this | ||||
| 49 | # option to FALSE. | ||||
| 50 | # | ||||
| 51 | # The macro will set the target properties DOXYGEN_TAGFILE, QHP_NAMESPACE, | ||||
| 52 | # QHP_NAMESPACE_VERSIONED and QHP_VIRTUALFOLDER to the respective values, to | ||||
| 53 | # allow other code access to them, e.g. the macro kdb_install_qch_export(). | ||||
| 54 | # To enable the use of the target <name> as item for LINK_QCHS or | ||||
| 55 | # LINK_QCHS_VERSIONED in further ``kdb_add_qch()`` calls in the current build, | ||||
| 56 | # additionally a target property DOXYGEN_TAGFILE_BUILD is set, with the path | ||||
| 57 | # of the created doxygen tag file in the build dir. | ||||
| 58 | # If existing, ``kdb_add_qch()`` will use this property instead of | ||||
| 59 | # DOXYGEN_TAGFILE for access to the tags file. | ||||
| 60 | # | ||||
| 61 | # OUTPUT_BASENAME specifies the base name for the generated documentation and | ||||
| 62 | # the files. | ||||
| 63 | # | ||||
| 64 | # VERSION specifies the version of the library for which the documentation is | ||||
| 65 | # created. | ||||
| 66 | # | ||||
| 67 | # SOURCE_DIRS specifies the dirs (incl. subdirs) with the source files for | ||||
| 68 | # which the API documentation should be generated. Dirs can be relative to | ||||
| 69 | # the current source dir. Dependencies to the files in the dirs are not | ||||
| 70 | # tracked currently, other than with the SOURCES argument. So do not use for | ||||
| 71 | # sources generated during the build. | ||||
| 72 | # Needs to be used when SOURCES or CONFIG_TEMPLATE are not used. | ||||
| 73 | # | ||||
| 74 | # SOURCES specifies the source files for which the API documentation should be | ||||
| 75 | # generated. | ||||
| 76 | # Needs to be used when SOURCE_DIRS or CONFIG_TEMPLATE are not used. | ||||
| 77 | # | ||||
| 78 | # MD_MAINPAGE specifies a file in Markdown format that should be used as main | ||||
| 79 | # page. This page will overrule any ``\mainpage`` command in the included | ||||
| 80 | # sources. | ||||
| 81 | # | ||||
| 82 | # IMAGE_DIRS specifies the dirs which contain images that are included in the | ||||
| 83 | # documentation. Dirs can be relative to the current source dir. | ||||
| 84 | # | ||||
| 85 | # EXAMPLE_DIRS specifies the dirs which contain examples that are included in | ||||
| 86 | # the documentation. Dirs can be relative to the current source dir. | ||||
| 87 | # | ||||
| 88 | # QCH_INSTALL_DESTINATION specifies where the generated QCH file will be | ||||
| 89 | # installed. | ||||
| 90 | # | ||||
| 91 | # TAGFILE_INSTALL_DESTINATION specifies where the generated tag file will be | ||||
| 92 | # installed. | ||||
| 93 | # | ||||
| 94 | # NAMESPACE can be used to set a custom namespace <namespace> of the generated | ||||
| 95 | # QCH file. The namepspace is used as the unique id by QHelpEngine (cmp. | ||||
| 96 | # http://doc.qt.io/qt-5/qthelpproject.html#namespace). | ||||
| 97 | # The default namespace is ``<domain>.<basename>``. | ||||
| 98 | # Needs to be used when ORG_DOMAIN is not used. | ||||
| 99 | # | ||||
| 100 | # ORG_DOMAIN can be used to define the organization domain prefix for the | ||||
| 101 | # default namespace of the generated QCH file. | ||||
| 102 | # Needs to be used when NAMESPACE is not used. | ||||
| 103 | # | ||||
| 104 | # LINK_QCHS specifies a list of other QCH targets which should be used for | ||||
| 105 | # creating references to API documenation of code in external libraries. | ||||
| 106 | # For each target <qch> in the list these target properties are expected to be | ||||
| 107 | # defined: DOXYGEN_TAGFILE, QHP_NAMESPACE and QHP_VIRTUALFOLDER. | ||||
| 108 | # If any of these is not existing, <qch> will be ignored. | ||||
| 109 | # Use the macro kdb_install_qch_export for exporting a target with these | ||||
| 110 | # properties with the CMake config of a library. | ||||
| 111 | # Any target <qch> can also be one created before in the same buildsystem by | ||||
| 112 | # another call of ``kdb_add_qch()``. | ||||
| 113 | # | ||||
| 114 | # LINK_QCHS_VERSIONED does basically the same as LINK_QCHS, but binds the links | ||||
| 115 | # to a certain version. | ||||
| 116 | # For each <qchv> in the list these target properties are expected to be | ||||
| 117 | # defined: DOXYGEN_TAGFILE, QHP_NAMESPACE_VERSIONED and QHP_VIRTUALFOLDER. | ||||
| 118 | # If any of these is not existing, <qchv> will be ignored. | ||||
| 119 | # Use the macro kdb_install_qch_export for exporting a target with these | ||||
| 120 | # properties with the CMake config of a library. | ||||
| 121 | # Any <qchv> can also be one created before in the same buildsystem by another | ||||
| 122 | # call of ``kdb_add_qch()``. | ||||
| 123 | # | ||||
| 124 | # BLANK_MACROS specifies a list of C/C++ macro names which should be ignored by | ||||
| 125 | # the API dox generation tool and handled as if they resolve to empty strings. | ||||
| 126 | # Examples are export macros only defined in generated files, so whose | ||||
| 127 | # definition might be not available to the tool. | ||||
| 128 | # | ||||
| 129 | # CONFIG_TEMPLATE specifies a custom cmake template file for the config file | ||||
| 130 | # that is created to control the execution of the API dox generation tool. | ||||
| 131 | # The following CMake variables need to be used: | ||||
| 132 | # ECM_DOXYGENQCH_PERL_EXECUTABLE, ECM_DOXYGENQCH_QHELPGENERATOR_EXECUTABLE, | ||||
| 133 | # ECM_DOXYGENQCH_FILEPATH, ECM_DOXYGENQCH_TAGFILE. | ||||
| 134 | # The following CMake variables can be used: | ||||
| 135 | # ECM_DOXYGENQCH_PROJECTNAME, ECM_DOXYGENQCH_PROJECTVERSION, | ||||
| 136 | # ECM_DOXYGENQCH_VIRTUALFOLDER, ECM_DOXYGENQCH_FULLNAMESPACE, | ||||
| 137 | # ECM_DOXYGENQCH_TAGFILES, | ||||
| 138 | # ECM_DOXYGENQCH_WARN_LOGFILE, ECM_DOXYGENQCH_QUIET. | ||||
| 139 | # There is no guarantue that the other CMake variables currently used in the | ||||
| 140 | # default config file template will also be present with the same semantics | ||||
| 141 | # in future versions of this macro. | ||||
| 142 | # | ||||
| 143 | # VERBOSE tells the API dox generation tool to be more verbose about its | ||||
| 144 | # activity. | ||||
| 145 | # | ||||
| 146 | # Example usage: | ||||
| 147 | # | ||||
| 148 | # .. code-block:: cmake | ||||
| 149 | # | ||||
| 150 | # kdb_add_qch( | ||||
| 151 | # MyLib_QCH | ||||
| 152 | # OUTPUT_BASENAME MyLib | ||||
| 153 | # VERSION "0.42.0" | ||||
| 154 | # ORG_DOMAIN org.myorg | ||||
| 155 | # SOURCE_DIRS | ||||
| 156 | # src | ||||
| 157 | # LINK_QCHS | ||||
| 158 | # Qt5Core_QCH | ||||
| 159 | # Qt5Xml_QCH | ||||
| 160 | # Qt5Gui_QCH | ||||
| 161 | # Qt5Widgets_QCH | ||||
| 162 | # BLANK_MACROS | ||||
| 163 | # MyLib_EXPORT | ||||
| 164 | # MyLib_DEPRECATED | ||||
| 165 | # TAGFILE_INSTALL_DESTINATION ${CMAKE_INSTALL_PREFIX}/share/docs/tags | ||||
| 166 | # QCH_INSTALL_DESTINATION ${CMAKE_INSTALL_PREFIX}/share/docs/qch | ||||
| 167 | # ) | ||||
| 168 | # | ||||
| 169 | # Example usage (with two QCH files, second linking first): | ||||
| 170 | # | ||||
| 171 | # .. code-block:: cmake | ||||
| 172 | # | ||||
| 173 | # kdb_add_qch( | ||||
| 174 | # MyLib_QCH | ||||
| 175 | # OUTPUT_BASENAME MyLib | ||||
| 176 | # VERSION ${MyLib_VERSION} | ||||
| 177 | # ORG_DOMAIN org.myorg | ||||
| 178 | # SOURCES ${MyLib_PUBLIC_HEADERS} | ||||
| 179 | # MD_MAINPAGE src/mylib/README.md | ||||
| 180 | # LINK_QCHS Qt5Core_QCH | ||||
| 181 | # TAGFILE_INSTALL_DESTINATION ${CMAKE_INSTALL_PREFIX}/share/docs/tags | ||||
| 182 | # QCH_INSTALL_DESTINATION ${CMAKE_INSTALL_PREFIX}/share/docs/qch | ||||
| 183 | # ) | ||||
| 184 | # kdb_add_qch( | ||||
| 185 | # MyOtherLib_QCH | ||||
| 186 | # OUTPUT_BASENAME MyOtherLib | ||||
| 187 | # VERSION ${MyOtherLib_VERSION} | ||||
| 188 | # ORG_DOMAIN org.myorg | ||||
| 189 | # SOURCES ${MyOtherLib_PUBLIC_HEADERS} | ||||
| 190 | # MD_MAINPAGE src/myotherlib/README.md | ||||
| 191 | # LINK_QCHS Qt5Core_QCH MyLib_QCH | ||||
| 192 | # TAGFILE_INSTALL_DESTINATION ${CMAKE_INSTALL_PREFIX}/share/docs/tags | ||||
| 193 | # QCH_INSTALL_DESTINATION ${CMAKE_INSTALL_PREFIX}/share/docs/qch | ||||
| 194 | # ) | ||||
| 195 | # | ||||
| 196 | # :: | ||||
| 197 | # | ||||
| 198 | # kdb_install_qch_export( | ||||
| 199 | # TARGETS <name> [<name2> [...]]] | ||||
| 200 | # FILE <file> | ||||
| 201 | # DESTINATION <dest> | ||||
| 202 | # [COMPONENT <component>}] | ||||
| 203 | # ) | ||||
| 204 | # | ||||
| 205 | # This macro creates and installs a CMake file <file> which exports the given | ||||
| 206 | # QCH targets <name> etc., so they can be picked up by CMake-based builds of | ||||
| 207 | # other software that also generate QCH files (using ``kdb_add_qch()``) and | ||||
| 208 | # which should include links to the QCH files created by the given targets. | ||||
| 209 | # The installed CMake file <file> is expected to be included by the CMake | ||||
| 210 | # config file created for the software the related QCH files are documenting. | ||||
| 211 | # | ||||
| 212 | # TARGETS specifies the QCH targets which should be exported. If a target does | ||||
| 213 | # not exist or does not have all needed properties, a warning will be | ||||
| 214 | # generated and the target skipped. | ||||
| 215 | # This behaviour might change in future versions to result in a fail instead. | ||||
| 216 | # | ||||
| 217 | # FILE specifies the name of the created CMake file, typically with a .cmake | ||||
| 218 | # extension. | ||||
| 219 | # | ||||
| 220 | # DESTINATION specifies the directory on disk to which the file will be | ||||
| 221 | # installed. It usually is the same as the one where the CMake config files | ||||
| 222 | # for this software are installed. | ||||
| 223 | # | ||||
| 224 | # COMPONENT specifies the the installation component name with which the | ||||
| 225 | # install rule is associated. | ||||
| 226 | # | ||||
| 227 | # Example usage: | ||||
| 228 | # | ||||
| 229 | # .. code-block:: cmake | ||||
| 230 | # | ||||
| 231 | # kdb_install_qch_export( | ||||
| 232 | # TARGETS MyLib_QCH | ||||
| 233 | # FILE MyLibQCHTargets.cmake | ||||
| 234 | # DESTINATION "${CMAKE_INSTALL_PREFIX}/lib/cmake/MyLib" | ||||
| 235 | # COMPONENT Devel | ||||
| 236 | # ) | ||||
| 237 | # | ||||
| 238 | # Since 5.29.0. | ||||
| 239 | | ||||
| 240 | #============================================================================= | ||||
| 241 | # Copyright 2016 Friedrich W. H. Kossebau <kossebau@kde.org> | ||||
| 242 | # | ||||
| 243 | # Redistribution and use in source and binary forms, with or without | ||||
| 244 | # modification, are permitted provided that the following conditions | ||||
| 245 | # are met: | ||||
| 246 | # | ||||
| 247 | # 1. Redistributions of source code must retain the copyright | ||||
| 248 | # notice, this list of conditions and the following disclaimer. | ||||
| 249 | # 2. Redistributions in binary form must reproduce the copyright | ||||
| 250 | # notice, this list of conditions and the following disclaimer in the | ||||
| 251 | # documentation and/or other materials provided with the distribution. | ||||
| 252 | # 3. The name of the author may not be used to endorse or promote products | ||||
| 253 | # derived from this software without specific prior written permission. | ||||
| 254 | # | ||||
| 255 | # THIS SOFTWARE IS PROVIDED BY THE AUTHOR ``AS IS'' AND ANY EXPRESS OR | ||||
| 256 | # IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES | ||||
| 257 | # OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. | ||||
| 258 | # IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY DIRECT, INDIRECT, | ||||
| 259 | # INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT | ||||
| 260 | # NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, | ||||
| 261 | # DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY | ||||
| 262 | # THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT | ||||
| 263 | # (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF | ||||
| 264 | # THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. | ||||
| 265 | | ||||
| 266 | # needed to find helper files | ||||
| 267 | get_filename_component(_module_dir ${CMAKE_CURRENT_LIST_FILE} PATH) | ||||
| 268 | | ||||
| 269 | # Estimate KDB_QTQCH_FULL_INSTALL_DIR | ||||
| 270 | include(KDEInstallDirs) # for KDE_INSTALL_USE_QT_SYS_PATHS & KDE_INSTALL_FULL_DATAROOTDIR | ||||
| 271 | include("${_module_dir}/KDbQueryQmake.cmake") | ||||
| 272 | if(KDE_INSTALL_USE_QT_SYS_PATHS) | ||||
| 273 | query_qmake(qt_docs_dir QT_INSTALL_DOCS) | ||||
| 274 | set(KDB_QTQCH_FULL_INSTALL_DIR "${qt_docs_dir}") | ||||
| 275 | else() | ||||
| 276 | set(KDB_QTQCH_FULL_INSTALL_DIR "${KDE_INSTALL_FULL_DATAROOTDIR}/doc") | ||||
| 277 | endif() | ||||
staniek: QCH uppercase? What's this convention? | |||||
Is was following the uppercase HTML which KDEInstallDirs is using for the DOCBUNDLEDIR vars. But would agree that lowercase feels more natural on *nixoid systems, will change. kossebau: Is was following the uppercase HTML which KDEInstallDirs is using for the DOCBUNDLEDIR vars. | |||||
please tell me if the files are co-installable, i.e. paths use ${KDB_BASE_NAME} or so staniek: please tell me if the files are co-installable, i.e. paths use ${KDB_BASE_NAME} or so | |||||
Co-installability in the same directory completely depends on what is used with the OUTPUT_BASENAME argument in the kdb_add_qch(...) call. Currently it is just KDb, so will not work. Changing now to ${KDB_BASE_NAME} kossebau: Co-installability in the same directory completely depends on what is used with the… | |||||
| 278 | | ||||
| 279 | include(CMakeParseArguments) | ||||
| 280 | | ||||
| 281 | function(kdb_add_qch target_name) | ||||
| 282 | # Parse arguments | ||||
| 283 | set(options VERBOSE) | ||||
| 284 | set(oneValueArgs OUTPUT_BASENAME QCH_INSTALL_DESTINATION TAGFILE_INSTALL_DESTINATION VERSION NAMESPACE MD_MAINPAGE ORG_DOMAIN CONFIG_TEMPLATE) | ||||
| 285 | set(multiValueArgs SOURCE_DIRS SOURCES IMAGE_DIRS EXAMPLE_DIRS BLANK_MACROS LINK_QCHS LINK_QCHS_VERSIONED) | ||||
| 286 | cmake_parse_arguments(ARGS "${options}" "${oneValueArgs}" "${multiValueArgs}" ${ARGN}) | ||||
| 287 | | ||||
| 288 | # check required args | ||||
| 289 | foreach(_arg_name OUTPUT_BASENAME QCH_INSTALL_DESTINATION TAGFILE_INSTALL_DESTINATION VERSION) | ||||
| 290 | if(NOT DEFINED ARGS_${_arg_name}) | ||||
| 291 | message(FATAL_ERROR "${_arg_name} needs to be defined when calling kdb_add_qch") | ||||
| 292 | endif() | ||||
| 293 | endforeach() | ||||
| 294 | if(NOT DEFINED ARGS_SOURCE_DIRS AND NOT DEFINED ARGS_SOURCES AND NOT DEFINED ARGS_CONFIG_TEMPLATE) | ||||
| 295 | message(FATAL_ERROR "SOURCE_DIRS or SOURCES needs to be defined when calling kdb_add_qch") | ||||
| 296 | endif() | ||||
| 297 | if(DEFINED ARGS_SOURCE_DIRS AND DEFINED ARGS_SOURCES) | ||||
| 298 | message(FATAL_ERROR "Either SOURCE_DIRS or SOURCES, not both, needs to be defined when calling kdb_add_qch") | ||||
| 299 | endif() | ||||
| 300 | if(NOT DEFINED ARGS_ORG_DOMAIN AND NOT DEFINED ARGS_NAMESPACE) | ||||
| 301 | message(FATAL_ERROR "ORG_DOMAIN or NAMESPACE needs to be defined when calling kdb_add_qch") | ||||
| 302 | endif() | ||||
| 303 | | ||||
| 304 | # create QCH targets for Qt | ||||
| 305 | # Ideally one day Qt CMake Config files provide these | ||||
| 306 | if(NOT TARGET Qt5Core_QCH) | ||||
| 307 | # get Qt version, if any | ||||
| 308 | find_package(Qt5Core CONFIG QUIET) | ||||
| 309 | # lookup tag files | ||||
| 310 | query_qmake(qt_docs_dir QT_INSTALL_DOCS) | ||||
| 311 | find_path(_qtcoreTagsPath qtcore/qtcore.tags | ||||
| 312 | PATHS | ||||
| 313 | ${qt_docs_dir} | ||||
| 314 | ) | ||||
| 315 | | ||||
| 316 | if(Qt5Core_FOUND AND _qtcoreTagsPath) | ||||
| 317 | string(REPLACE "." "" _version ${Qt5Core_VERSION}) | ||||
| 318 | # TODO: properly find each tag file | ||||
| 319 | # TODO: complete list of Qt modules | ||||
| 320 | foreach(_module | ||||
| 321 | Bluetooth Concurrent Core DBus Gui Location Multimedia MultimediaWidgets | ||||
| 322 | Network Positioning PrintSupport Qml Quick Sensors SerialPort Sql Svg | ||||
| 323 | WebEngine WebView Widgets Xml XmlPatterns | ||||
| 324 | ) | ||||
| 325 | string(TOLOWER ${_module} _lowermodule) | ||||
| 326 | | ||||
| 327 | add_custom_target(Qt5${_module}_QCH) | ||||
| 328 | set_target_properties(Qt5${_module}_QCH PROPERTIES | ||||
| 329 | DOXYGEN_TAGFILE "${_qtcoreTagsPath}/qt${_lowermodule}/qt${_lowermodule}.tags" | ||||
| 330 | QHP_NAMESPACE "org.qt-project.qt${_lowermodule}" | ||||
| 331 | QHP_NAMESPACE_VERSIONED "org.qt-project.qt${_lowermodule}.${_version}" | ||||
| 332 | QHP_VIRTUALFOLDER "qt${_lowermodule}" | ||||
| 333 | IMPORTED TRUE | ||||
| 334 | ) | ||||
| 335 | endforeach() | ||||
| 336 | endif() | ||||
| 337 | endif() | ||||
| 338 | | ||||
| 339 | # find required tools | ||||
| 340 | find_package(Perl) | ||||
| 341 | set_package_properties(Perl PROPERTIES | ||||
| 342 | TYPE OPTIONAL | ||||
| 343 | ) | ||||
| 344 | find_package(Doxygen) | ||||
| 345 | set_package_properties(Doxygen PROPERTIES | ||||
| 346 | TYPE OPTIONAL | ||||
| 347 | DESCRIPTION "Tool for API Documentation generation" | ||||
| 348 | URL "http://www.doxygen.org/" | ||||
| 349 | ) | ||||
| 350 | if (DOXYGEN_FOUND AND DOXYGEN_VERSION VERSION_LESS 1.8.13 AND NOT DOXYGEN_PATCHED_JSFILESADDED) | ||||
| 351 | message(WARNING "Make sure Doxygen is patched with https://github.com/doxygen/doxygen/commit/bf9415698e53d79b, then pass -DDOXYGEN_PATCHED_JSFILESADDED=ON to cmake") | ||||
| 352 | set(DOXYGEN_FOUND FALSE) | ||||
| 353 | endif() | ||||
| 354 | # TODO: use Qt5::qhelpgenerator for Qt >= 5.7.1 | ||||
| 355 | find_program(ECM_DOXYGENQCH_QHELPGENERATOR_EXECUTABLE NAMES qhelpgenerator-qt5 qhelpgenerator) | ||||
| 356 | | ||||
| 357 | # prepare base dirs, working file names and other vars | ||||
| 358 | set(_qch_file_basename "${ARGS_OUTPUT_BASENAME}.qch") | ||||
| 359 | set(_tags_file_basename "${ARGS_OUTPUT_BASENAME}.tags") | ||||
| 360 | set(_qch_buildpath "${CMAKE_CURRENT_BINARY_DIR}/${_qch_file_basename}") | ||||
| 361 | set(_tags_buildpath "${CMAKE_CURRENT_BINARY_DIR}/${_tags_file_basename}") | ||||
| 362 | set(_apidox_builddir "${CMAKE_CURRENT_BINARY_DIR}/${ARGS_OUTPUT_BASENAME}_ECMDoxygenQCH") | ||||
| 363 | if (DEFINED ARGS_NAMESPACE) | ||||
| 364 | set(_namespace "${ARGS_NAMESPACE}") | ||||
| 365 | else() | ||||
| 366 | set(_namespace "${ARGS_ORG_DOMAIN}.${ARGS_OUTPUT_BASENAME}") | ||||
| 367 | endif() | ||||
| 368 | string(REPLACE "." "_" _dotLessVersion ${ARGS_VERSION}) | ||||
| 369 | set(_versioned_namespace "${_namespace}.${_dotLessVersion}") | ||||
| 370 | set(_sources) | ||||
| 371 | set(_dep_tagfiles) | ||||
| 372 | set(_dep_qch_targets) | ||||
| 373 | | ||||
| 374 | ### Create doxygen config file | ||||
| 375 | set(_doxygenconfig_file "${CMAKE_CURRENT_BINARY_DIR}/${ARGS_OUTPUT_BASENAME}_ECMDoxygenQCH.config") | ||||
| 376 | if (DEFINED ARGS_CONFIG_TEMPLATE) | ||||
| 377 | set(_doxygenconfig_template_file "${ARGS_CONFIG_TEMPLATE}") | ||||
| 378 | else() | ||||
| 379 | set(_doxygenconfig_template_file "${_module_dir}/KDbDoxygenQCH.config.in") | ||||
| 380 | endif() | ||||
| 381 | # Setup variables used in config file template, ECM_DOXYGENQCH_* | ||||
| 382 | set(ECM_DOXYGENQCH_OUTPUTDIR "\"${_apidox_builddir}\"") | ||||
| 383 | set(ECM_DOXYGENQCH_TAGFILE "\"${_tags_buildpath}\"") | ||||
| 384 | set(ECM_DOXYGENQCH_LAYOUTFILE "\"${_module_dir}/KDbDoxygenQCHLayout.xml\"") | ||||
| 385 | set(ECM_DOXYGENQCH_IMAGEDIRS) | ||||
| 386 | foreach(_image_DIR IN LISTS ARGS_IMAGE_DIRS) | ||||
| 387 | if (NOT IS_ABSOLUTE ${_image_DIR}) | ||||
| 388 | set(_image_DIR "${CMAKE_CURRENT_SOURCE_DIR}/${_image_DIR}") | ||||
| 389 | endif() | ||||
| 390 | # concat dirs separated by a break, it is no issue that first has also a leading break | ||||
| 391 | set(ECM_DOXYGENQCH_IMAGEDIRS "${ECM_DOXYGENQCH_IMAGEDIRS} \\\n\"${_image_DIR}\"") | ||||
| 392 | endforeach() | ||||
| 393 | set(ECM_DOXYGENQCH_EXAMPLEDIRS) | ||||
| 394 | foreach(_example_DIR IN LISTS ARGS_EXAMPLE_DIRS) | ||||
| 395 | if (NOT IS_ABSOLUTE ${_example_DIR}) | ||||
| 396 | set(_example_DIR "${CMAKE_CURRENT_SOURCE_DIR}/${_example_DIR}") | ||||
| 397 | endif() | ||||
| 398 | # concat dirs separated by a break, it is no issue that first has also a leading break | ||||
| 399 | set(ECM_DOXYGENQCH_EXAMPLEDIRS "${ECM_DOXYGENQCH_EXAMPLEDIRS} \\\n\"${_example_DIR}\"") | ||||
| 400 | endforeach() | ||||
| 401 | if (ARGS_MD_MAINPAGE) | ||||
| 402 | if (NOT IS_ABSOLUTE ${ARGS_MD_MAINPAGE}) | ||||
| 403 | set(ARGS_MD_MAINPAGE "${CMAKE_CURRENT_SOURCE_DIR}/${ARGS_MD_MAINPAGE}") | ||||
| 404 | endif() | ||||
| 405 | set(ECM_DOXYGENQCH_MAINPAGE_MDFILE "\"${ARGS_MD_MAINPAGE}\"") | ||||
| 406 | else() | ||||
| 407 | set(ECM_DOXYGENQCH_MAINPAGE_MDFILE) | ||||
| 408 | endif() | ||||
| 409 | set(ECM_DOXYGENQCH_INPUT) | ||||
| 410 | if (ARGS_SOURCE_DIRS) | ||||
| 411 | foreach(_source_DIR IN LISTS ARGS_SOURCE_DIRS) | ||||
| 412 | if (NOT IS_ABSOLUTE ${_source_DIR}) | ||||
| 413 | set(_source_DIR "${CMAKE_CURRENT_SOURCE_DIR}/${_source_DIR}") | ||||
| 414 | endif() | ||||
| 415 | # concat dirs separated by a break, it is no issue that first has also a leading break | ||||
| 416 | set(ECM_DOXYGENQCH_INPUT "${ECM_DOXYGENQCH_INPUT} \\\n\"${_source_DIR}\"") | ||||
| 417 | endforeach() | ||||
| 418 | if (ARGS_MD_MAINPAGE) | ||||
| 419 | set(ECM_DOXYGENQCH_INPUT "${ECM_DOXYGENQCH_INPUT} \\\n\"${ARGS_MD_MAINPAGE}\"") | ||||
| 420 | endif() | ||||
| 421 | set(ECM_DOXYGENQCH_FILE_PATTERNS "*.h *.cpp *.hpp *.hh *.cc *.h++ *.c++ *.hxx *.cxx *.dox *.md") | ||||
| 422 | else() | ||||
| 423 | foreach(_source IN LISTS ARGS_SOURCES) | ||||
| 424 | if (NOT IS_ABSOLUTE ${_source}) | ||||
| 425 | set(_source "${CMAKE_CURRENT_SOURCE_DIR}/${_source}") | ||||
| 426 | endif() | ||||
| 427 | list(APPEND _sources "${_source}") | ||||
| 428 | endforeach() | ||||
| 429 | if (ARGS_MD_MAINPAGE) | ||||
| 430 | list(FIND _sources ${ARGS_MD_MAINPAGE} _mainpage_index) | ||||
| 431 | if (_mainpage_index STREQUAL -1) | ||||
| 432 | list(APPEND _sources "${ARGS_MD_MAINPAGE}") | ||||
| 433 | endif() | ||||
| 434 | endif() | ||||
| 435 | foreach(_source IN LISTS _sources) | ||||
| 436 | # concat sources separated by a break, it is no issue that first has also a leading break | ||||
| 437 | set(ECM_DOXYGENQCH_INPUT "${ECM_DOXYGENQCH_INPUT} \\\n\"${_source}\"") | ||||
| 438 | endforeach() | ||||
| 439 | set(ECM_DOXYGENQCH_FILE_PATTERNS "") | ||||
| 440 | endif() | ||||
| 441 | | ||||
| 442 | set(ECM_DOXYGENQCH_PROJECTNAME ${ARGS_OUTPUT_BASENAME}) | ||||
| 443 | file(RELATIVE_PATH _builddirrelative_filepath "${_apidox_builddir}/html" ${_qch_buildpath}) | ||||
| 444 | set(ECM_DOXYGENQCH_FILEPATH "\"${_builddirrelative_filepath}\"") | ||||
| 445 | set(ECM_DOXYGENQCH_PROJECTVERSION ${ARGS_VERSION}) | ||||
| 446 | set(ECM_DOXYGENQCH_VIRTUALFOLDER "${ARGS_OUTPUT_BASENAME}") | ||||
| 447 | set(ECM_DOXYGENQCH_FULLNAMESPACE ${_versioned_namespace}) | ||||
| 448 | set(ECM_DOXYGENQCH_BLANK_MACROS) | ||||
| 449 | foreach(_macro IN LISTS ARGS_BLANK_MACROS) | ||||
| 450 | # concat dirs separated by a break, it is no issue that first has also a leading break | ||||
| 451 | set(ECM_DOXYGENQCH_BLANK_MACROS "${ECM_DOXYGENQCH_BLANK_MACROS} \\\n${_macro}=\"\"") | ||||
| 452 | endforeach() | ||||
| 453 | set(ECM_DOXYGENQCH_TAGFILES) | ||||
| 454 | foreach(_versioned_postfix "" "_VERSIONED") | ||||
| 455 | foreach(_link_qch IN LISTS ARGS_LINK_QCHS${_versioned_postfix}) | ||||
| 456 | set(_target_usable TRUE) | ||||
| 457 | if (NOT TARGET ${_link_qch}) | ||||
| 458 | message(STATUS "No such target ${_link_qch} defined when calling kdb_add_qch().") | ||||
| 459 | set(_target_usable FALSE) | ||||
| 460 | elseif() | ||||
| 461 | foreach(_propertyname | ||||
| 462 | DOXYGEN_TAGFILE | ||||
| 463 | QHP_NAMESPACE${_versioned_postfix} | ||||
| 464 | QHP_VIRTUALFOLDER | ||||
| 465 | ) | ||||
| 466 | if(NOT "${_property}") | ||||
| 467 | message(STATUS "No property ${_propertyname} set on ${_link_qch} when calling kdb_add_qch().") | ||||
| 468 | set(_target_usable FALSE) | ||||
| 469 | endif() | ||||
| 470 | endforeach() | ||||
| 471 | endif() | ||||
| 472 | if(_target_usable) | ||||
| 473 | list(APPEND _dep_qch_targets ${_link_qch}) | ||||
| 474 | get_target_property(_link_qch_tagfile ${_link_qch} DOXYGEN_TAGFILE) | ||||
| 475 | get_target_property(_link_qch_tagfile_build ${_link_qch} DOXYGEN_TAGFILE_BUILD) | ||||
| 476 | get_target_property(_link_qch_namespace ${_link_qch} QHP_NAMESPACE${_versioned_postfix}) | ||||
| 477 | get_target_property(_link_qch_virtualfolder ${_link_qch} QHP_VIRTUALFOLDER) | ||||
| 478 | # if same build, then prefer build version over any installed one | ||||
| 479 | if (${_link_qch_tagfile_build}) | ||||
| 480 | set(_link_qch_tagfile ${_link_qch_tagfile_build}) | ||||
| 481 | list(APPEND _dep_tagfiles "${_link_qch_tagfile}") | ||||
| 482 | endif() | ||||
| 483 | set(_tagfile_entry "\"${_link_qch_tagfile}=qthelp://${_link_qch_namespace}/${_link_qch_virtualfolder}/\"") | ||||
| 484 | # concat dirs separated by a break, it is no issue that first has also a leading break | ||||
| 485 | set(ECM_DOXYGENQCH_TAGFILES "${ECM_DOXYGENQCH_TAGFILES} \\\n${_tagfile_entry}") | ||||
| 486 | else() | ||||
| 487 | message(WARNING "No linking to API dox of ${_link_qch}.") | ||||
| 488 | endif() | ||||
| 489 | endforeach() | ||||
| 490 | endforeach() | ||||
| 491 | | ||||
| 492 | set(ECM_DOXYGENQCH_WARN_LOGFILE "\"${_doxygenconfig_file}.log\"") | ||||
| 493 | if(ARGS_VERBOSE) | ||||
| 494 | set(ECM_DOXYGENQCH_QUIET "NO") | ||||
| 495 | else() | ||||
| 496 | set(ECM_DOXYGENQCH_QUIET "YES") | ||||
| 497 | endif() | ||||
| 498 | set(ECM_DOXYGENQCH_PERL_EXECUTABLE "${PERL_EXECUTABLE}") | ||||
| 499 | | ||||
| 500 | if (NOT DOXYGEN_FOUND) | ||||
| 501 | message(WARNING "Unable to find the doxygen utility - API dox QCH file will not be generated!") | ||||
| 502 | elseif(NOT ECM_DOXYGENQCH_QHELPGENERATOR_EXECUTABLE) | ||||
Curent message may be not informative enough so I propose: Unable to find the doxygen utility -> Unable to find the doxygen utility version ${DOXYGEN_MIN_VERSION) (and for the other repos) I just realized I have Doxygen 1.8.12, which is the last released. What's special in 1.8.13? staniek: Curent message may be not informative enough so I propose:
Unable to find the doxygen utility… | |||||
Alternative proposal (as implemented in updated patch):
It will have (once released) the mentioned patch for doxygen which fixes the hardcoded JS files not being added to the QCH file. kossebau: Alternative proposal (as implemented in updated patch):
list the missing tools with version… | |||||
staniek: Very good. | |||||
| 503 | message(WARNING "Unable to find the qhelpgenerator utility - API dox QCH file will not be generated!") | ||||
| 504 | elseif(NOT PERL_FOUND) | ||||
| 505 | message(WARNING "Unable to find the perl utility - API dox QCH file will not be generated!") | ||||
| 506 | else() | ||||
| 507 | configure_file( | ||||
| 508 | "${_doxygenconfig_template_file}" | ||||
| 509 | "${_doxygenconfig_file}" | ||||
| 510 | @ONLY | ||||
| 511 | ) | ||||
| 512 | | ||||
| 513 | set(_qch_INSTALLPATH ${ARGS_QCH_INSTALL_DESTINATION}) | ||||
| 514 | set(_tags_INSTALLPATH ${ARGS_TAGFILE_INSTALL_DESTINATION}) | ||||
| 515 | file(RELATIVE_PATH _relative_qch_file ${CMAKE_BINARY_DIR} ${_qch_buildpath}) | ||||
| 516 | file(RELATIVE_PATH _relative_tags_file ${CMAKE_BINARY_DIR} ${_tags_buildpath}) | ||||
| 517 | add_custom_command( | ||||
| 518 | OUTPUT ${_qch_buildpath} ${_tags_buildpath} | ||||
| 519 | COMMENT "Generating ${_relative_qch_file}, ${_relative_tags_file}" | ||||
| 520 | COMMAND cmake -E remove_directory "${ECM_DOXYGENQCH_OUTPUTDIR}" | ||||
| 521 | COMMAND cmake -E make_directory "${ECM_DOXYGENQCH_OUTPUTDIR}" | ||||
| 522 | COMMAND ${DOXYGEN_EXECUTABLE} "${_doxygenconfig_file}" | ||||
| 523 | DEPENDS ${_doxygenconfig_file} ${_sources} ${_dep_tagfiles} ${_dep_qch_targets} | ||||
| 524 | ) | ||||
| 525 | add_custom_target(${target_name} ALL DEPENDS ${_qch_buildpath} ${_tags_buildpath}) | ||||
| 526 | set_target_properties(${target_name} PROPERTIES | ||||
| 527 | DOXYGEN_TAGFILE "${_qch_INSTALLPATH}/${_tags_file_basename}" | ||||
| 528 | DOXYGEN_TAGFILE_BUILD "${_tags_buildpath}" | ||||
| 529 | QHP_NAMESPACE "${_namespace}" | ||||
| 530 | QHP_NAMESPACE_VERSIONED "${_versioned_namespace}" | ||||
| 531 | QHP_VIRTUALFOLDER "${ECM_DOXYGENQCH_VIRTUALFOLDER}" | ||||
| 532 | ) | ||||
| 533 | | ||||
| 534 | install(FILES | ||||
| 535 | ${_qch_buildpath} | ||||
| 536 | DESTINATION ${_qch_INSTALLPATH} | ||||
| 537 | COMPONENT Devel | ||||
| 538 | ) | ||||
| 539 | | ||||
| 540 | install(FILES | ||||
| 541 | ${_tags_buildpath} | ||||
| 542 | DESTINATION ${_tags_INSTALLPATH} | ||||
| 543 | COMPONENT Devel | ||||
| 544 | ) | ||||
| 545 | endif() | ||||
| 546 | | ||||
| 547 | endfunction() | ||||
| 548 | | ||||
| 549 | | ||||
| 550 | function(kdb_install_qch_export) | ||||
| 551 | set(options ) | ||||
| 552 | set(oneValueArgs FILE DESTINATION COMPONENT) | ||||
| 553 | set(multiValueArgs TARGETS) | ||||
| 554 | | ||||
| 555 | cmake_parse_arguments(ARGS "${options}" "${oneValueArgs}" "${multiValueArgs}" ${ARGN}) | ||||
| 556 | | ||||
| 557 | if(NOT DEFINED ARGS_FILE) | ||||
| 558 | message(FATAL_ERROR "FILE needs to be defined when calling kdb_install_qch_export().") | ||||
| 559 | endif() | ||||
| 560 | | ||||
| 561 | if(NOT DEFINED ARGS_DESTINATION) | ||||
| 562 | message(FATAL_ERROR "DESTINATION needs to be defined when calling kdb_install_qch_export().") | ||||
| 563 | endif() | ||||
| 564 | | ||||
| 565 | if(NOT DEFINED ARGS_TARGETS) | ||||
| 566 | message(FATAL_ERROR "TARGETS needs to be defined when calling kdb_install_qch_export().") | ||||
| 567 | endif() | ||||
| 568 | | ||||
| 569 | set(_content | ||||
| 570 | "# Generated by kdb_install_qch_export() | ||||
| 571 | # Any changes to this file will be overwritten by the next CMake run. | ||||
| 572 | " | ||||
| 573 | ) | ||||
| 574 | | ||||
| 575 | foreach(_target IN LISTS ARGS_TARGETS) | ||||
| 576 | set(_target_usable TRUE) | ||||
| 577 | | ||||
| 578 | if (NOT TARGET ${_target}) | ||||
| 579 | message(STATUS "No such target ${_target} when calling kdb_install_qch_export().") | ||||
| 580 | set(_target_usable FALSE) | ||||
| 581 | else() | ||||
| 582 | foreach(_propertyname | ||||
| 583 | DOXYGEN_TAGFILE | ||||
| 584 | QHP_NAMESPACE | ||||
| 585 | QHP_NAMESPACE_VERSIONED | ||||
| 586 | QHP_VIRTUALFOLDER | ||||
| 587 | ) | ||||
| 588 | get_target_property(_property ${_target} ${_propertyname}) | ||||
| 589 | if(NOT _property) | ||||
| 590 | message(STATUS "No property ${_propertyname} set on ${_target} when calling kdb_install_qch_export(). <${_property}>") | ||||
| 591 | set(_target_usable FALSE) | ||||
| 592 | endif() | ||||
| 593 | endforeach() | ||||
| 594 | endif() | ||||
| 595 | if(_target_usable) | ||||
| 596 | get_target_property(_tagfile ${_target} DOXYGEN_TAGFILE) | ||||
| 597 | get_target_property(_namespace ${_target} QHP_NAMESPACE) | ||||
| 598 | get_target_property(_namespace_versioned ${_target} QHP_NAMESPACE_VERSIONED) | ||||
| 599 | get_target_property(_virtualfolder ${_target} QHP_VIRTUALFOLDER) | ||||
| 600 | set(_content "${_content} | ||||
| 601 | if (NOT TARGET ${_target}) | ||||
| 602 | | ||||
| 603 | add_custom_target(${_target}) | ||||
| 604 | set_target_properties(${_target} PROPERTIES | ||||
| 605 | DOXYGEN_TAGFILE \"${_tagfile}\" | ||||
| 606 | QHP_NAMESPACE \"${_namespace}\" | ||||
| 607 | QHP_NAMESPACE_VERSIONED \"${_namespace_versioned}\" | ||||
| 608 | QHP_VIRTUALFOLDER \"${_virtualfolder}\" | ||||
| 609 | IMPORTED TRUE | ||||
| 610 | ) | ||||
| 611 | | ||||
| 612 | endif() | ||||
| 613 | " | ||||
| 614 | ) | ||||
| 615 | else() | ||||
| 616 | message(STATUS "No target exported for ${_target}.") | ||||
| 617 | endif() | ||||
| 618 | endforeach() | ||||
| 619 | | ||||
| 620 | if (NOT IS_ABSOLUTE ${ARGS_FILE}) | ||||
| 621 | set(ARGS_FILE "${CMAKE_CURRENT_BINARY_DIR}/${ARGS_FILE}") | ||||
| 622 | endif() | ||||
| 623 | | ||||
| 624 | file(GENERATE | ||||
| 625 | OUTPUT "${ARGS_FILE}" | ||||
| 626 | CONTENT "${_content}" | ||||
| 627 | ) | ||||
| 628 | | ||||
| 629 | if (DEFINED ARGS_COMPONENT) | ||||
| 630 | set(_component COMPONENT ${ARGS_COMPONENT}) | ||||
| 631 | endif() | ||||
| 632 | install( | ||||
| 633 | FILES "${ARGS_FILE}" | ||||
| 634 | DESTINATION "${ARGS_DESTINATION}" | ||||
| 635 | ${_component} | ||||
| 636 | ) | ||||
| 637 | | ||||
| 638 | endfunction() | ||||
QCH uppercase? What's this convention?