Differential D3514 Diff 8587 cmake/modules/KPropertyAddQCH.cmake

Changeset View

Standalone View

View Options

cmake/modules/KPropertyAddQCH.cmake

  • This file was added.
1​#.rst:
2​# KPropertyAddQCH
3​# ------------------
4​#
5​# This module provides the ``kproperty_add_qch`` function for generating API
6​# documentation files in the QCH format, and the ``kproperty_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​# kproperty_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 ``kproperty_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 kproperty_install_qch_export().
54​# To enable the use of the target <name> as item for LINK_QCHS or
55​# LINK_QCHS_VERSIONED in further ``kproperty_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, ``kproperty_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 kproperty_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 ``kproperty_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 kproperty_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 ``kproperty_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​# kproperty_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​# kproperty_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​# kproperty_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​# kproperty_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 ``kproperty_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​# kproperty_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 KPROPERTY_QTQCH_FULL_INSTALL_DIR
270​include(KDEInstallDirs) # for KDE_INSTALL_USE_QT_SYS_PATHS & KDE_INSTALL_FULL_DATAROOTDIR
271​include("${_module_dir}/KPropertyQueryQmake.cmake")
272​if(KDE_INSTALL_USE_QT_SYS_PATHS)
273​ query_qmake(qt_docs_dir QT_INSTALL_DOCS)
274​ set(KPROPERTY_QTQCH_FULL_INSTALL_DIR "${qt_docs_dir}")
275​else()
276​ set(KPROPERTY_QTQCH_FULL_INSTALL_DIR "${KDE_INSTALL_FULL_DATAROOTDIR}/doc")
277​endif()
278​
279​include(CMakeParseArguments)
280​
281​function(kproperty_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 kproperty_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 kproperty_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 kproperty_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 kproperty_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}/KPropertyDoxygenQCH.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}/KPropertyDoxygenQCHLayout.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 kproperty_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 kproperty_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)
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(kproperty_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 kproperty_install_qch_export().")
559​ endif()
560​
561​ if(NOT DEFINED ARGS_DESTINATION)
562​ message(FATAL_ERROR "DESTINATION needs to be defined when calling kproperty_install_qch_export().")
563​ endif()
564​
565​ # TARGETS may be empty (and ARGS_TARGETS will not be defined then by cmake_parse_arguments)
566​
567​ set(_content
568​"# Generated by kproperty_install_qch_export()
569​# Any changes to this file will be overwritten by the next CMake run.
570​"
571​ )
572​
573​ foreach(_target IN LISTS ARGS_TARGETS)
574​ set(_target_usable TRUE)
575​
576​ if (NOT TARGET ${_target})
577​ message(STATUS "No such target ${_target} when calling kproperty_install_qch_export().")
578​ set(_target_usable FALSE)
579​ else()
580​ foreach(_propertyname
581​ DOXYGEN_TAGFILE
582​ QHP_NAMESPACE
583​ QHP_NAMESPACE_VERSIONED
584​ QHP_VIRTUALFOLDER
585​ )
586​ get_target_property(_property ${_target} ${_propertyname})
587​ if(NOT _property)
588​ message(STATUS "No property ${_propertyname} set on ${_target} when calling kproperty_install_qch_export(). <${_property}>")
589​ set(_target_usable FALSE)
590​ endif()
591​ endforeach()
592​ endif()
593​ if(_target_usable)
594​ get_target_property(_tagfile ${_target} DOXYGEN_TAGFILE)
595​ get_target_property(_namespace ${_target} QHP_NAMESPACE)
596​ get_target_property(_namespace_versioned ${_target} QHP_NAMESPACE_VERSIONED)
597​ get_target_property(_virtualfolder ${_target} QHP_VIRTUALFOLDER)
598​ set(_content "${_content}
599​if (NOT TARGET ${_target})
600​
601​add_custom_target(${_target})
602​set_target_properties(${_target} PROPERTIES
603​ DOXYGEN_TAGFILE \"${_tagfile}\"
604​ QHP_NAMESPACE \"${_namespace}\"
605​ QHP_NAMESPACE_VERSIONED \"${_namespace_versioned}\"
606​ QHP_VIRTUALFOLDER \"${_virtualfolder}\"
607​ IMPORTED TRUE
608​)
609​
610​endif()
611​"
612​ )
613​ else()
614​ message(STATUS "No target exported for ${_target}.")
615​ endif()
616​ endforeach()
617​
618​ if (NOT IS_ABSOLUTE ${ARGS_FILE})
619​ set(ARGS_FILE "${CMAKE_CURRENT_BINARY_DIR}/${ARGS_FILE}")
620​ endif()
621​
622​ file(GENERATE
623​ OUTPUT "${ARGS_FILE}"
624​ CONTENT "${_content}"
625​ )
626​
627​ if (DEFINED ARGS_COMPONENT)
628​ set(_component COMPONENT ${ARGS_COMPONENT})
629​ endif()
630​ install(
631​ FILES "${ARGS_FILE}"
632​ DESTINATION "${ARGS_DESTINATION}"
633​ ${_component}
634​ )
635​
636​endfunction()