Differential D2854 Diff 14671 modules/ECMAddQch.cmake

Changeset View

Standalone View

View Options

modules/ECMAddQch.cmake

  • This file was added.
1​#.rst:
2​# ECMAddQch
3​# ------------------
4​#
5​# This module provides the ``ecm_add_qch`` function for generating API
6​# documentation files in the QCH format, and the ``ecm_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​# ecm_add_qch(<target_name>
14​# NAME <name>
15​# VERSION <version>
16​# QCH_INSTALL_DESTINATION <qchfile_install_path>
17​# TAGFILE_INSTALL_DESTINATION <tagsfile_install_path>
18​# [COMPONENT <component>]
19​# [BASE_NAME <basename>]
20​# [SOURCE_DIRS <dir> [<dir2> [...]]]
21​# [SOURCES <file> [<file2> [...]]]
22​# |MD_MAINPAGE <md_file>]
23​# [IMAGE_DIRS <idir> [<idir2> [...]]]
24​# [EXAMPLE_DIRS <edir> [<edir2> [...]]]
25​# [ORG_DOMAIN <domain>]
26​# [NAMESPACE <namespace>]
27​# [LINK_QCHS <qch> [<qch2> [...]]]
28​# [BLANK_MACROS <macro> [<macro2> [...]]]
29​# [CONFIG_TEMPLATE <configtemplate_file>]
30​# [VERBOSE]
31​# )
32​#
33​# This macro adds a target called <target_name> for the creation of an API
34​# documentation manual in the QCH format from the 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, which enables creating links from other documentation into the
39​# 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 ``ecm_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, QHP_VIRTUALFOLDER and LINK_QCHS to the respective
53​# values, to allow other code access to them, e.g. the macro
54​# ``ecm_install_qch_export``.
55​# To enable the use of the target <target_name> as item for LINK_QCHS
56​# in further ``ecm_add_qch`` calls in the current build,
57​# additionally a target property DOXYGEN_TAGFILE_BUILD is set, with the path
58​# of the created doxygen tag file in the build dir.
59​# If existing, ``ecm_add_qch`` will use this property instead of
60​# DOXYGEN_TAGFILE for access to the tags file.
61​#
62​# NAME specifies the name for the generated documentation.
63​#
64​# VERSION specifies the version of the library for which the documentation is
65​# created.
66​#
67​# BASE_NAME specifies the base name for the generated files.
68​# The default basename is ``<name>``.
69​#
70​# SOURCE_DIRS specifies the dirs (incl. subdirs) with the source files for
71​# which the API documentation should be generated. Dirs can be relative to
72​# the current source dir. Dependencies to the files in the dirs are not
73​# tracked currently, other than with the SOURCES argument. So do not use for
74​# sources generated during the build.
75​# Needs to be used when SOURCES or CONFIG_TEMPLATE are not used.
76​#
77​# SOURCES specifies the source files for which the API documentation should be
78​# generated.
79​# Needs to be used when SOURCE_DIRS or CONFIG_TEMPLATE are not used.
80​#
81​# MD_MAINPAGE specifies a file in Markdown format that should be used as main
82​# page. This page will overrule any ``\mainpage`` command in the included
83​# sources.
84​#
85​# IMAGE_DIRS specifies the dirs which contain images that are included in the
86​# documentation. Dirs can be relative to the current source dir.
87​#
88​# EXAMPLE_DIRS specifies the dirs which contain examples that are included in
89​# the documentation. Dirs can be relative to the current source dir.
90​#
91​# QCH_INSTALL_DESTINATION specifies where the generated QCH file will be
92​# installed.
93​#
94​# TAGFILE_INSTALL_DESTINATION specifies where the generated tag file will be
95​# installed.
96​#
97​# COMPONENT specifies the installation component name with which the install
98​# rules for the generated QCH file and tag file are associated.
99​#
100​# NAMESPACE can be used to set a custom namespace <namespace> of the generated
101​# QCH file. The namepspace is used as the unique id by QHelpEngine (cmp.
102​# http://doc.qt.io/qt-5/qthelpproject.html#namespace).
103​# The default namespace is ``<domain>.<name>``.
104​# Needs to be used when ORG_DOMAIN is not used.
105​#
106​# ORG_DOMAIN can be used to define the organization domain prefix for the
107​# default namespace of the generated QCH file.
108​# Needs to be used when NAMESPACE is not used.
109​#
110​# LINK_QCHS specifies a list of other QCH targets which should be used for
111​# creating references to API documenation of code in external libraries.
112​# For each target <qch> in the list these target properties are expected to be
113​# defined: DOXYGEN_TAGFILE, QHP_NAMESPACE and QHP_VIRTUALFOLDER.
114​# If any of these is not existing, <qch> will be ignored.
115​# Use the macro ``ecm_install_qch_export`` for exporting a target with these
116​# properties with the CMake config of a library.
117​# Any target <qch> can also be one created before in the same buildsystem by
118​# another call of ``ecm_add_qch``.
119​#
120​# BLANK_MACROS specifies a list of C/C++ macro names which should be ignored by
121​# the API dox generation tool and handled as if they resolve to empty strings.
122​# Examples are export macros only defined in generated files, so whose
123​# definition might be not available to the tool.
124​#
125​# CONFIG_TEMPLATE specifies a custom cmake template file for the config file
126​# that is created to control the execution of the API dox generation tool.
127​# The following CMake variables need to be used:
128​# ECM_QCH_DOXYGEN_PERL_EXECUTABLE, ECM_QCH_DOXYGEN_QHELPGENERATOR_EXECUTABLE,
129​# ECM_QCH_DOXYGEN_FILEPATH, ECM_QCH_DOXYGEN_TAGFILE.
130​# The following CMake variables can be used:
131​# ECM_QCH_DOXYGEN_PROJECTNAME, ECM_QCH_DOXYGEN_PROJECTVERSION,
132​# ECM_QCH_DOXYGEN_VIRTUALFOLDER, ECM_QCH_DOXYGEN_FULLNAMESPACE,
133​# ECM_QCH_DOXYGEN_TAGFILES,
134​# ECM_QCH_DOXYGEN_WARN_LOGFILE, ECM_QCH_DOXYGEN_QUIET.
135​# There is no guarantue that the other CMake variables currently used in the
136​# default config file template will also be present with the same semantics
137​# in future versions of this macro.
138​#
139​# VERBOSE tells the API dox generation tool to be more verbose about its
140​# activity.
141​#
142​# Example usage:
143​#
144​# .. code-block:: cmake
145​#
146​# ecm_add_qch(
147​# MyLib_QCH
148​# NAME MyLib
149​# VERSION "0.42.0"
150​# ORG_DOMAIN org.myorg
151​# SOURCE_DIRS
152​# src
153​# LINK_QCHS
154​# Qt5Core_QCH
155​# Qt5Xml_QCH
156​# Qt5Gui_QCH
157​# Qt5Widgets_QCH
158​# BLANK_MACROS
159​# MyLib_EXPORT
160​# MyLib_DEPRECATED
161​# TAGFILE_INSTALL_DESTINATION ${CMAKE_INSTALL_PREFIX}/share/docs/tags
162​# QCH_INSTALL_DESTINATION ${CMAKE_INSTALL_PREFIX}/share/docs/qch
163​# COMPONENT Devel
164​# )
165​#
166​# Example usage (with two QCH files, second linking first):
167​#
168​# .. code-block:: cmake
169​#
170​# ecm_add_qch(
171​# MyLib_QCH
172​# NAME MyLib
173​# VERSION ${MyLib_VERSION}
174​# ORG_DOMAIN org.myorg
175​# SOURCES ${MyLib_PUBLIC_HEADERS}
176​# MD_MAINPAGE src/mylib/README.md
177​# LINK_QCHS Qt5Core_QCH
178​# TAGFILE_INSTALL_DESTINATION ${CMAKE_INSTALL_PREFIX}/share/docs/tags
179​# QCH_INSTALL_DESTINATION ${CMAKE_INSTALL_PREFIX}/share/docs/qch
180​# COMPONENT Devel
181​# )
182​# ecm_add_qch(
183​# MyOtherLib_QCH
184​# NAME MyOtherLib
185​# VERSION ${MyOtherLib_VERSION}
186​# ORG_DOMAIN org.myorg
187​# SOURCES ${MyOtherLib_PUBLIC_HEADERS}
188​# MD_MAINPAGE src/myotherlib/README.md
189​# LINK_QCHS Qt5Core_QCH MyLib_QCH
190​# TAGFILE_INSTALL_DESTINATION ${CMAKE_INSTALL_PREFIX}/share/docs/tags
191​# QCH_INSTALL_DESTINATION ${CMAKE_INSTALL_PREFIX}/share/docs/qch
192​# COMPONENT Devel
193​# )
194​#
195​# ::
196​#
197​# ecm_install_qch_export(
198​# TARGETS [<name> [<name2> [...]]]
199​# FILE <file>
200​# DESTINATION <dest>
201​# [COMPONENT <component>]
202​# )
203​#
204​# This macro creates and installs a CMake file <file> which exports the given
205​# QCH targets <name> etc., so they can be picked up by CMake-based builds of
206​# other software that also generate QCH files (using ``ecm_add_qch``) and
207​# which should include links to the QCH files created by the given targets.
208​# The installed CMake file <file> is expected to be included by the CMake
209​# config file created for the software the related QCH files are documenting.
210​#
211​# TARGETS specifies the QCH targets which should be exported. If a target does
212​# not exist or does not have all needed properties, a warning will be
213​# generated and the target skipped.
214​# This behaviour might change in future versions to result in a fail instead.
215​#
216​# FILE specifies the name of the created CMake file, typically with a .cmake
217​# extension.
218​#
219​# DESTINATION specifies the directory on disk to which the file will be
220​# installed. It usually is the same as the one where the CMake config files
221​# for this software are installed.
222​#
223​# COMPONENT specifies the the installation component name with which the
224​# install rule is associated.
225​#
226​# Example usage:
227​#
228​# .. code-block:: cmake
229​#
230​# ecm_install_qch_export(
231​# TARGETS MyLib_QCH
232​# FILE MyLibQCHTargets.cmake
233​# DESTINATION "${CMAKE_INSTALL_PREFIX}/lib/cmake/MyLib"
234​# COMPONENT Devel
235​# )
236​#
237​# Since 5.36.0.
238​
239​#=============================================================================
240​# Copyright 2016-2017 Friedrich W. H. Kossebau <kossebau@kde.org>
241​#
242​# Redistribution and use in source and binary forms, with or without
243​# modification, are permitted provided that the following conditions
244​# are met:
245​#
246​# 1. Redistributions of source code must retain the copyright
247​# notice, this list of conditions and the following disclaimer.
248​# 2. Redistributions in binary form must reproduce the copyright
249​# notice, this list of conditions and the following disclaimer in the
250​# documentation and/or other materials provided with the distribution.
251​# 3. The name of the author may not be used to endorse or promote products
252​# derived from this software without specific prior written permission.
253​#
254​# THIS SOFTWARE IS PROVIDED BY THE AUTHOR ``AS IS'' AND ANY EXPRESS OR
255​# IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
256​# OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED.
257​# IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY DIRECT, INDIRECT,
258​# INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT
259​# NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
260​# DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
261​# THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
262​# (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF
263​# THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
264​
265​include(CMakeParseArguments)
266​include(ECMQueryQmake)
267​
268​
269​# Helper method: adding the LINK_QCHS property to a Qt QCH targets, from module base names ("Core" etc.)
270​macro(_ecm_setup_qt_qch_links _module)
271​ set(_linkqchs)
272​ foreach(_linkqch ${ARGN})
273​ list(APPEND _linkqchs "Qt5${_linkqch}_QCH")
274​ endforeach()
275​ set_property(TARGET Qt5${_module}_QCH PROPERTY LINK_QCHS ${_linkqchs})
276​endmacro()
277​
278​# Helper method: ensure Qt QCH targets are created
279​function(_ecm_ensure_qt_qch_targets)
280​ # create QCH targets for Qt
281​ # Ideally one day Qt CMake Config files provide these
282​ if(NOT TARGET Qt5Core_QCH)
283​ # get Qt version, if any
284​ find_package(Qt5Core CONFIG QUIET)
285​ # lookup tag files
286​ query_qmake(qt_docs_dir QT_INSTALL_DOCS)
287​ find_path(_qtcoreTagsPath qtcore/qtcore.tags
288​ PATHS
289​ ${qt_docs_dir}
290​ )
291​
292​ if(Qt5Core_FOUND AND _qtcoreTagsPath)
293​ string(REPLACE "." "" _version ${Qt5Core_VERSION})
294​ # TODO: properly find each tag file
295​ # TODO: complete list of Qt modules
296​ foreach(_module
297​ 3D Bluetooth Concurrent Core DBus Gui Location
298​ Network Positioning PrintSupport Qml Quick Sensors SerialPort Sql Svg
299​ WebChannel WebEngine WebSockets Widgets Xml XmlPatterns
300​ )
301​ string(TOLOWER ${_module} _lowermodule)
302​
303​ add_custom_target(Qt5${_module}_QCH)
304​ set_target_properties(Qt5${_module}_QCH PROPERTIES
305​ DOXYGEN_TAGFILE "${_qtcoreTagsPath}/qt${_lowermodule}/qt${_lowermodule}.tags"
306​ QHP_NAMESPACE "org.qt-project.qt${_lowermodule}"
307​ QHP_NAMESPACE_VERSIONED "org.qt-project.qt${_lowermodule}.${_version}"
308​ QHP_VIRTUALFOLDER "qt${_lowermodule}"
309​ IMPORTED TRUE
310​ )
311​ endforeach()
312​ _ecm_setup_qt_qch_links(3D Gui Core)
313​ _ecm_setup_qt_qch_links(Bluetooth DBus Core)
314​ _ecm_setup_qt_qch_links(Concurrent Gui Core)
315​ _ecm_setup_qt_qch_links(DBus Core)
316​ _ecm_setup_qt_qch_links(Gui Core)
317​ _ecm_setup_qt_qch_links(Location Positioning Gui Core)
318​ _ecm_setup_qt_qch_links(Network Core)
319​ _ecm_setup_qt_qch_links(Positioning Core)
320​ _ecm_setup_qt_qch_links(PrintSupport Widgets Gui Core)
321​ _ecm_setup_qt_qch_links(Qml Network Core)
322​ _ecm_setup_qt_qch_links(Quick Qml Network Gui Core)
323​ _ecm_setup_qt_qch_links(Sensors Core)
324​ _ecm_setup_qt_qch_links(SerialPort Core)
325​ _ecm_setup_qt_qch_links(Sql Core)
326​ _ecm_setup_qt_qch_links(Svg Widgets Gui Core)
327​ _ecm_setup_qt_qch_links(WebChannel Qml Core)
328​ _ecm_setup_qt_qch_links(WebEngine Quick Qml Gui Core)
329​ _ecm_setup_qt_qch_links(WebSockets Network Core)
330​ _ecm_setup_qt_qch_links(Widgets Gui Core)
331​ _ecm_setup_qt_qch_links(Xml Core)
332​ _ecm_setup_qt_qch_links(XmlPatterns Network Core)
333​ endif()
334​ endif()
335​endfunction()
336​
337​# Helper method: collect all qch targets from the LINK_QCHS dependency tree and set result to <var>
338​function(_ecm_collect_linkable_qch_targets name)
339​ set(_candidate_qchs ${ARGN})
340​ set(_handled_qchs)
341​ set(_good_qchs)
342​ # while unhandled qch targets
343​ while(_candidate_qchs)
344​ # get another unhandled qch target
345​ list(GET _candidate_qchs 0 _qch)
346​ list(REMOVE_AT _candidate_qchs 0)
347​ list(FIND _handled_qchs ${_qch} _index)
348​ # if not already handled
349​ if(_index EQUAL -1)
350​ list(APPEND _handled_qchs ${_qch})
351​ if(TARGET ${_qch})
352​ # always look at other linked qch targets, also for incomplete targets
353​ get_property(_link_qchs TARGET ${_qch} PROPERTY LINK_QCHS)
354​ if(_link_qchs)
355​ list(APPEND _candidate_qchs ${_link_qchs})
356​ endif()
357​ # check if this target has all needed properties
358​ set(_target_usable TRUE)
359​ foreach(_propertyname
360​ DOXYGEN_TAGFILE
361​ QHP_NAMESPACE
362​ QHP_VIRTUALFOLDER
363​ )
364​ get_target_property(_property ${_qch} ${_propertyname})
365​ if(NOT _property)
366​ message(STATUS "No property ${_propertyname} set on ${_qch} when calling ecm_add_qch(). <<${_property}>>")
367​ set(_target_usable FALSE)
368​ elseif(_propertyname STREQUAL DOXYGEN_TAGFILE AND NOT EXISTS ${_property})
369​ message(STATUS "No such tag file \"${_property}\" found for ${_qch} when calling ecm_add_qch().")
370​ set(_target_usable FALSE)
371​ endif()
372​ endforeach()
373​ if(_target_usable)
374​ list(APPEND _good_qchs ${_qch})
375​ else()
376​ message(WARNING "No linking to API dox of ${_qch}.")
377​ endif()
378​ else()
379​ message(STATUS "No such target ${_qch} defined when calling ecm_add_qch(), ignored.")
380​ endif()
381​ endif()
382​ endwhile()
383​ set(${name} ${_good_qchs} PARENT_SCOPE)
384​endfunction()
385​
386​
387​function(ecm_add_qch target_name)
388​ # Parse arguments
389​ set(options VERBOSE)
390​ set(oneValueArgs NAME BASE_NAME QCH_INSTALL_DESTINATION TAGFILE_INSTALL_DESTINATION COMPONENT VERSION NAMESPACE MD_MAINPAGE ORG_DOMAIN CONFIG_TEMPLATE)
391​ set(multiValueArgs SOURCE_DIRS SOURCES IMAGE_DIRS EXAMPLE_DIRS BLANK_MACROS LINK_QCHS)
392​ cmake_parse_arguments(ARGS "${options}" "${oneValueArgs}" "${multiValueArgs}" ${ARGN})
393​
394​ # check required args
395​ foreach(_arg_name NAME QCH_INSTALL_DESTINATION TAGFILE_INSTALL_DESTINATION VERSION)
396​ if(NOT DEFINED ARGS_${_arg_name})
397​ message(FATAL_ERROR "${_arg_name} needs to be defined when calling ecm_add_qch")
398​ endif()
399​ endforeach()
400​ if(NOT DEFINED ARGS_SOURCE_DIRS AND NOT DEFINED ARGS_SOURCES AND NOT DEFINED ARGS_CONFIG_TEMPLATE)
401​ message(FATAL_ERROR "SOURCE_DIRS or SOURCES needs to be defined when calling ecm_add_qch")
402​ endif()
403​ if(DEFINED ARGS_SOURCE_DIRS AND DEFINED ARGS_SOURCES)
404​ message(FATAL_ERROR "Either SOURCE_DIRS or SOURCES, not both, needs to be defined when calling ecm_add_qch")
405​ endif()
406​ if(NOT DEFINED ARGS_ORG_DOMAIN AND NOT DEFINED ARGS_NAMESPACE)
407​ message(FATAL_ERROR "ORG_DOMAIN or NAMESPACE needs to be defined when calling ecm_add_qch")
408​ endif()
409​
410​ # find required tools
411​ # TODO: check with doxygen author if perl is really still required, PERL_PATH seems unused in doxygen
412​ find_package(Perl)
413​ set_package_properties(Perl PROPERTIES
414​ PURPOSE "Needed for API dox QCH file generation"
415​ TYPE OPTIONAL
416​ )
417​ if (NOT DOXYGEN_PATCHED_JSFILESADDED)
418​ set(REQUIRED_DOXYGEN_VERSION 1.8.13)
419​ endif()
420​ find_package(Doxygen ${REQUIRED_DOXYGEN_VERSION})
421​ if (NOT DOXYGEN_FOUND AND NOT DOXYGEN_PATCHED_JSFILESADDED)
422​ set(doxygen_description_addition " (Or older version patched with https://github.com/doxygen/doxygen/commit/bf9415698e53d79b, pass -DDOXYGEN_PATCHED_JSFILESADDED=ON to cmake if patched)")
423​ endif()
424​ set_package_properties(Doxygen PROPERTIES
425​ TYPE OPTIONAL
426​ PURPOSE "Needed for API dox QCH file generation${doxygen_description_addition}"
427​ )
428​ find_package(QHelpGenerator)
429​ set_package_properties(QHelpGenerator PROPERTIES
430​ TYPE OPTIONAL
431​ PURPOSE "Needed for API dox QCH file generation"
432​ DESCRIPTION "Part of Qt5 tools"
433​ )
434​ set(_missing_tools)
435​ if (NOT PERL_FOUND)
436​ list(APPEND _missing_tools "Perl")
437​ endif()
438​ if (NOT DOXYGEN_FOUND)
439​ list(APPEND _missing_tools "Doxygen")
440​ endif()
441​ if (NOT QHelpGenerator_FOUND)
442​ list(APPEND _missing_tools "qhelpgenerator")
443​ endif()
444​
445​ if (_missing_tools)
446​ message(WARNING "API dox QCH file will not be generated, tools missing: ${_missing_tools}!")
447​ else()
448​ _ecm_ensure_qt_qch_targets()
449​
450​ # prepare base dirs, working file names and other vars
451​ if (DEFINED ARGS_BASE_NAME)
452​ set(_basename ${ARGS_BASE_NAME})
453​ else()
454​ set(_basename ${ARGS_NAME})
455​ endif()
456​ set(_qch_file_basename "${_basename}.qch")
457​ set(_tags_file_basename "${_basename}.tags")
458​ set(_qch_buildpath "${CMAKE_CURRENT_BINARY_DIR}/${_qch_file_basename}")
459​ set(_tags_buildpath "${CMAKE_CURRENT_BINARY_DIR}/${_tags_file_basename}")
460​ set(_apidox_builddir "${CMAKE_CURRENT_BINARY_DIR}/${_basename}_ECMQchDoxygen")
461​ if (DEFINED ARGS_NAMESPACE)
462​ set(_namespace "${ARGS_NAMESPACE}")
463​ else()
464​ set(_namespace "${ARGS_ORG_DOMAIN}.${ARGS_NAME}")
465​ endif()
466​ string(REPLACE "." "_" _dotLessVersion ${ARGS_VERSION})
467​ set(_versioned_namespace "${_namespace}.${_dotLessVersion}")
468​ set(_sources)
469​ set(_dep_tagfiles)
470​ set(_dep_qch_targets)
471​
472​ ### Create doxygen config file
473​ set(_doxygenconfig_file "${CMAKE_CURRENT_BINARY_DIR}/${_basename}_ECMQchDoxygen.config")
474​ if (DEFINED ARGS_CONFIG_TEMPLATE)
475​ set(_doxygenconfig_template_file "${ARGS_CONFIG_TEMPLATE}")
476​ else()
477​ set(_doxygenconfig_template_file "${ECM_MODULE_DIR}/ECMQchDoxygen.config.in")
478​ endif()
479​ # Setup variables used in config file template, ECM_QCH_DOXYGEN_*
480​ set(ECM_QCH_DOXYGEN_OUTPUTDIR "\"${_apidox_builddir}\"")
481​ set(ECM_QCH_DOXYGEN_TAGFILE "\"${_tags_buildpath}\"")
482​ set(ECM_QCH_DOXYGEN_LAYOUTFILE "\"${ECM_MODULE_DIR}/ECMQchDoxygenLayout.xml\"")
483​ set(ECM_QCH_DOXYGEN_IMAGEDIRS)
484​ foreach(_image_DIR IN LISTS ARGS_IMAGE_DIRS)
485​ if (NOT IS_ABSOLUTE ${_image_DIR})
486​ set(_image_DIR "${CMAKE_CURRENT_SOURCE_DIR}/${_image_DIR}")
487​ endif()
488​ # concat dirs separated by a break, it is no issue that first has also a leading break
489​ set(ECM_QCH_DOXYGEN_IMAGEDIRS "${ECM_QCH_DOXYGEN_IMAGEDIRS} \\\n\"${_image_DIR}\"")
490​ endforeach()
491​ set(ECM_QCH_DOXYGEN_EXAMPLEDIRS)
492​ foreach(_example_DIR IN LISTS ARGS_EXAMPLE_DIRS)
493​ if (NOT IS_ABSOLUTE ${_example_DIR})
494​ set(_example_DIR "${CMAKE_CURRENT_SOURCE_DIR}/${_example_DIR}")
495​ endif()
496​ # concat dirs separated by a break, it is no issue that first has also a leading break
497​ set(ECM_QCH_DOXYGEN_EXAMPLEDIRS "${ECM_QCH_DOXYGEN_EXAMPLEDIRS} \\\n\"${_example_DIR}\"")
498​ endforeach()
499​ if (ARGS_MD_MAINPAGE)
500​ if (NOT IS_ABSOLUTE ${ARGS_MD_MAINPAGE})
501​ set(ARGS_MD_MAINPAGE "${CMAKE_CURRENT_SOURCE_DIR}/${ARGS_MD_MAINPAGE}")
502​ endif()
503​ set(ECM_QCH_DOXYGEN_MAINPAGE_MDFILE "\"${ARGS_MD_MAINPAGE}\"")
504​ else()
505​ set(ECM_QCH_DOXYGEN_MAINPAGE_MDFILE)
506​ endif()
507​ set(ECM_QCH_DOXYGEN_INPUT)
508​ if (ARGS_SOURCE_DIRS)
509​ foreach(_source_DIR IN LISTS ARGS_SOURCE_DIRS)
510​ if (NOT IS_ABSOLUTE ${_source_DIR})
511​ set(_source_DIR "${CMAKE_CURRENT_SOURCE_DIR}/${_source_DIR}")
512​ endif()
513​ # concat dirs separated by a break, it is no issue that first has also a leading break
514​ set(ECM_QCH_DOXYGEN_INPUT "${ECM_QCH_DOXYGEN_INPUT} \\\n\"${_source_DIR}\"")
515​ endforeach()
516​ if (ARGS_MD_MAINPAGE)
517​ set(ECM_QCH_DOXYGEN_INPUT "${ECM_QCH_DOXYGEN_INPUT} \\\n\"${ARGS_MD_MAINPAGE}\"")
518​ endif()
519​ set(ECM_QCH_DOXYGEN_FILE_PATTERNS "*.h *.cpp *.hpp *.hh *.cc *.h++ *.c++ *.hxx *.cxx *.dox *.md")
520​ else()
521​ foreach(_source IN LISTS ARGS_SOURCES)
522​ if (NOT IS_ABSOLUTE ${_source})
523​ set(_source "${CMAKE_CURRENT_SOURCE_DIR}/${_source}")
524​ endif()
525​ list(APPEND _sources "${_source}")
526​ endforeach()
527​ if (ARGS_MD_MAINPAGE)
528​ list(FIND _sources ${ARGS_MD_MAINPAGE} _mainpage_index)
529​ if (_mainpage_index STREQUAL -1)
530​ list(APPEND _sources "${ARGS_MD_MAINPAGE}")
531​ endif()
532​ endif()
533​ foreach(_source IN LISTS _sources)
534​ # concat sources separated by a break, it is no issue that first has also a leading break
535​ set(ECM_QCH_DOXYGEN_INPUT "${ECM_QCH_DOXYGEN_INPUT} \\\n\"${_source}\"")
536​ endforeach()
537​ set(ECM_QCH_DOXYGEN_FILE_PATTERNS "")
538​ endif()
539​
540​ set(ECM_QCH_DOXYGEN_PROJECTNAME ${ARGS_NAME})
541​ file(RELATIVE_PATH _builddirrelative_filepath "${_apidox_builddir}/html" ${_qch_buildpath})
542​ set(ECM_QCH_DOXYGEN_FILEPATH "\"${_builddirrelative_filepath}\"")
543​ set(ECM_QCH_DOXYGEN_PROJECTVERSION ${ARGS_VERSION})
544​ string(TOLOWER ${ARGS_NAME} ECM_QCH_DOXYGEN_VIRTUALFOLDER)
545​ set(ECM_QCH_DOXYGEN_FULLNAMESPACE ${_versioned_namespace})
546​ set(ECM_QCH_DOXYGEN_BLANK_MACROS)
547​ foreach(_macro IN LISTS ARGS_BLANK_MACROS)
548​ # concat dirs separated by a break, it is no issue that first has also a leading break
549​ set(ECM_QCH_DOXYGEN_BLANK_MACROS "${ECM_QCH_DOXYGEN_BLANK_MACROS} \\\n${_macro}=\"\"")
550​ endforeach()
551​
552​ # create list of tag files for linking other QCH files
553​ set(ECM_QCH_DOXYGEN_TAGFILES)
554​ _ecm_collect_linkable_qch_targets(_link_qchs ${ARGS_LINK_QCHS})
555​ foreach(_link_qch IN LISTS _link_qchs)
556​ list(APPEND _dep_qch_targets ${_link_qch})
557​ get_target_property(_link_qch_tagfile ${_link_qch} DOXYGEN_TAGFILE)
558​ get_target_property(_link_qch_tagfile_build ${_link_qch} DOXYGEN_TAGFILE_BUILD)
559​ get_target_property(_link_qch_namespace ${_link_qch} QHP_NAMESPACE)
560​ get_target_property(_link_qch_virtualfolder ${_link_qch} QHP_VIRTUALFOLDER)
561​ # if same build, then prefer build version over any installed one
562​ if (_link_qch_tagfile_build)
563​ set(_link_qch_tagfile ${_link_qch_tagfile_build})
564​ list(APPEND _dep_tagfiles "${_link_qch_tagfile}")
565​ endif()
566​ get_property(_linkqchs TARGET ${_link_qch} PROPERTY LINK_QCHS)
567​ set(_tagfile_entry "\"${_link_qch_tagfile}=qthelp://${_link_qch_namespace}/${_link_qch_virtualfolder}/\"")
568​ # concat dirs separated by a break, it is no issue that first has also a leading break
569​ set(ECM_QCH_DOXYGEN_TAGFILES "${ECM_QCH_DOXYGEN_TAGFILES} \\\n${_tagfile_entry}")
570​ endforeach()
571​
572​ set(ECM_QCH_DOXYGEN_WARN_LOGFILE "\"${_doxygenconfig_file}.log\"")
573​ if(ARGS_VERBOSE)
574​ set(ECM_QCH_DOXYGEN_QUIET "NO")
575​ else()
576​ set(ECM_QCH_DOXYGEN_QUIET "YES")
577​ endif()
578​ set(ECM_QCH_DOXYGEN_PERL_EXECUTABLE "${PERL_EXECUTABLE}")
579​ set(ECM_QCH_DOXYGEN_QHELPGENERATOR_EXECUTABLE ${QHelpGenerator_EXECUTABLE})
580​
581​ # finally create doxygen config file
582​ configure_file(
583​ "${_doxygenconfig_template_file}"
584​ "${_doxygenconfig_file}"
585​ @ONLY
586​ )
587​
588​ # setup make target
589​ set(_qch_INSTALLPATH ${ARGS_QCH_INSTALL_DESTINATION})
590​ set(_tags_INSTALLPATH ${ARGS_TAGFILE_INSTALL_DESTINATION})
591​ file(RELATIVE_PATH _relative_qch_file ${CMAKE_BINARY_DIR} ${_qch_buildpath})
592​ file(RELATIVE_PATH _relative_tags_file ${CMAKE_BINARY_DIR} ${_tags_buildpath})
593​ add_custom_command(
594​ OUTPUT ${_qch_buildpath} ${_tags_buildpath}
595​ COMMENT "Generating ${_relative_qch_file}, ${_relative_tags_file}"
596​ COMMAND cmake -E remove_directory "${ECM_QCH_DOXYGEN_OUTPUTDIR}"
597​ COMMAND cmake -E make_directory "${ECM_QCH_DOXYGEN_OUTPUTDIR}"
598​ COMMAND ${DOXYGEN_EXECUTABLE} "${_doxygenconfig_file}"
599​ DEPENDS ${_doxygenconfig_file} ${_sources} ${_dep_tagfiles} ${_dep_qch_targets}
600​ )
601​ add_custom_target(${target_name} ALL DEPENDS ${_qch_buildpath} ${_tags_buildpath})
602​ set_target_properties(${target_name} PROPERTIES
603​ DOXYGEN_TAGFILE "${_qch_INSTALLPATH}/${_tags_file_basename}"
604​ DOXYGEN_TAGFILE_NAME "${_tags_file_basename}"
605​ DOXYGEN_TAGFILE_INSTALLDIR "${_qch_INSTALLPATH}"
606​ DOXYGEN_TAGFILE_BUILD "${_tags_buildpath}"
607​ QHP_NAMESPACE "${_namespace}"
608​ QHP_NAMESPACE_VERSIONED "${_versioned_namespace}"
609​ QHP_VIRTUALFOLDER "${ECM_QCH_DOXYGEN_VIRTUALFOLDER}"
610​ )
611​ # list as value does not work with set_target_properties
612​ set_property(TARGET ${target_name} PROPERTY LINK_QCHS "${ARGS_LINK_QCHS}")
613​
614​ if (DEFINED ARGS_COMPONENT)
615​ set(_component COMPONENT ${ARGS_COMPONENT})
616​ else()
617​ set(_component)
618​ endif()
619​
620​ # setup installation
621​ install(FILES
622​ ${_qch_buildpath}
623​ DESTINATION ${_qch_INSTALLPATH}
624​ ${_component}
625​ )
626​
627​ install(FILES
628​ ${_tags_buildpath}
629​ DESTINATION ${_tags_INSTALLPATH}
630​ ${_component}
631​ )
632​ endif()
633​
634​endfunction()
635​
636​
637​function(ecm_install_qch_export)
638​ set(options )
639​ set(oneValueArgs FILE DESTINATION COMPONENT)
640​ set(multiValueArgs TARGETS)
641​
642​ cmake_parse_arguments(ARGS "${options}" "${oneValueArgs}" "${multiValueArgs}" ${ARGN})
643​
644​ if(NOT DEFINED ARGS_FILE)
645​ message(FATAL_ERROR "FILE needs to be defined when calling ecm_install_qch_export().")
646​ endif()
647​
648​ if(NOT DEFINED ARGS_DESTINATION)
649​ message(FATAL_ERROR "DESTINATION needs to be defined when calling ecm_install_qch_export().")
650​ endif()
651​
652​ # TARGETS may be empty (and ARGS_TARGETS will not be defined then by cmake_parse_arguments)
653​
654​ set(_content
655​"# This file was generated by ecm_install_qch_export(). DO NOT EDIT!
656​"
657​ )
658​
659​ foreach(_target IN LISTS ARGS_TARGETS)
660​ set(_target_usable TRUE)
661​
662​ if (NOT TARGET ${_target})
663​ message(STATUS "No such target ${_target} when calling ecm_install_qch_export().")
664​ set(_target_usable FALSE)
665​ else()
666​ foreach(_propertyname
667​ DOXYGEN_TAGFILE_NAME
668​ DOXYGEN_TAGFILE_INSTALLDIR
669​ QHP_NAMESPACE
670​ QHP_NAMESPACE_VERSIONED
671​ QHP_VIRTUALFOLDER
672​ )
673​ get_target_property(_property ${_target} ${_propertyname})
674​ if(NOT _property)
675​ message(STATUS "No property ${_propertyname} set on ${_target} when calling ecm_install_qch_export(). <${_property}>")
676​ set(_target_usable FALSE)
677​ endif()
678​ endforeach()
679​ endif()
680​ if(_target_usable)
681​ get_target_property(_tagfile_name ${_target} DOXYGEN_TAGFILE_NAME)
682​ get_target_property(_tagfile_installdir ${_target} DOXYGEN_TAGFILE_INSTALLDIR)
683​ if (NOT IS_ABSOLUTE ${_tagfile_installdir})
684​ set(_tagfile_installdir "${CMAKE_INSTALL_PREFIX}/${_tagfile_installdir}")
685​ endif()
686​ get_target_property(_namespace ${_target} QHP_NAMESPACE)
687​ get_target_property(_namespace_versioned ${_target} QHP_NAMESPACE_VERSIONED)
688​ get_target_property(_virtualfolder ${_target} QHP_VIRTUALFOLDER)
689​ get_property(_linkqchs TARGET ${_target} PROPERTY LINK_QCHS)
690​ set(_content "${_content}
691​if (NOT TARGET ${_target})
692​
693​add_custom_target(${_target})
694​set_target_properties(${_target} PROPERTIES
695​ DOXYGEN_TAGFILE \"${_tagfile_installdir}/${_tagfile_name}\"
696​ QHP_NAMESPACE \"${_namespace}\"
697​ QHP_NAMESPACE_VERSIONED \"${_namespace_versioned}\"
698​ QHP_VIRTUALFOLDER \"${_virtualfolder}\"
699​ IMPORTED TRUE
700​)
701​set_property(TARGET ${_target} PROPERTY LINK_QCHS ${_linkqchs})
702​
703​endif()
704​"
705​ )
706​ else()
707​ message(STATUS "No target exported for ${_target}.")
708​ endif()
709​ endforeach()
710​
711​ if (NOT IS_ABSOLUTE ${ARGS_FILE})
712​ set(ARGS_FILE "${CMAKE_CURRENT_BINARY_DIR}/${ARGS_FILE}")
713​ endif()
714​
715​ file(GENERATE
716​ OUTPUT "${ARGS_FILE}"
717​ CONTENT "${_content}"
718​ )
719​
720​ if (DEFINED ARGS_COMPONENT)
721​ set(_component COMPONENT ${ARGS_COMPONENT})
722​ else()
723​ set(_component)
724​ endif()
725​ install(
726​ FILES "${ARGS_FILE}"
727​ DESTINATION "${ARGS_DESTINATION}"
728​ ${_component}
729​ )
730​
731​endfunction()