Index: modules/ECMDoxygenQCH.config.in =================================================================== --- /dev/null +++ modules/ECMDoxygenQCH.config.in @@ -0,0 +1,233 @@ +#--------------------------------------------------------------------------- +# Project related configuration options +#--------------------------------------------------------------------------- +PROJECT_NAME = @ECM_DOXYGENQCH_PROJECTNAME@ +PROJECT_NUMBER = @ECM_DOXYGENQCH_PROJECTVERSION@ +OUTPUT_DIRECTORY = @ECM_DOXYGENQCH_OUTPUTDIR@ +GENERATE_TAGFILE = @ECM_DOXYGENQCH_TAGFILE@ +CREATE_SUBDIRS = NO +OUTPUT_LANGUAGE = English +# Put the brief description in the same place as the detailed one +BRIEF_MEMBER_DESC = NO +REPEAT_BRIEF = YES +ABBREVIATE_BRIEF = "The \$name class" \ + "The \$name widget" \ + "The \$name file" \ + is \ + provides \ + specifies \ + contains \ + represents \ + a \ + an \ + the +ALWAYS_DETAILED_SEC = Yes +INLINE_INHERITED_MEMB = NO +FULL_PATH_NAMES = NO +STRIP_FROM_PATH = +STRIP_FROM_INC_PATH = +SHORT_NAMES = NO +JAVADOC_AUTOBRIEF = YES +MULTILINE_CPP_IS_BRIEF = NO +INHERIT_DOCS = YES +SEPARATE_MEMBER_PAGES = NO +TAB_SIZE = 8 +OPTIMIZE_OUTPUT_FOR_C = NO +OPTIMIZE_OUTPUT_JAVA = NO +BUILTIN_STL_SUPPORT = NO +DISTRIBUTE_GROUP_DOC = NO +SUBGROUPING = YES +#--------------------------------------------------------------------------- +# Build related configuration options +#--------------------------------------------------------------------------- +EXTRACT_ALL = NO +EXTRACT_PRIVATE = NO +EXTRACT_STATIC = YES +EXTRACT_LOCAL_CLASSES = NO +EXTRACT_LOCAL_METHODS = NO +EXTRACT_ANON_NSPACES = NO +# Require classes to be documented to appear in apidox, but always document all +# public and protected members (even if static) +HIDE_UNDOC_MEMBERS = NO +HIDE_UNDOC_CLASSES = YES +HIDE_FRIEND_COMPOUNDS = YES +HIDE_IN_BODY_DOCS = NO +INTERNAL_DOCS = NO +CASE_SENSE_NAMES = YES +HIDE_SCOPE_NAMES = NO +SHOW_INCLUDE_FILES = NO +INLINE_INFO = YES +SORT_MEMBER_DOCS = YES +SORT_MEMBERS_CTORS_1ST = YES +SORT_BRIEF_DOCS = YES +SORT_BY_SCOPE_NAME = NO +GENERATE_TODOLIST = NO +GENERATE_TESTLIST = NO +GENERATE_BUGLIST = NO +GENERATE_DEPRECATEDLIST = YES +ENABLED_SECTIONS = +MAX_INITIALIZER_LINES = 30 +SHOW_USED_FILES = NO +SHOW_FILES = NO +FILE_VERSION_FILTER = +#--------------------------------------------------------------------------- +# configuration options related to warning and progress messages +#--------------------------------------------------------------------------- +QUIET = @ECM_DOXYGENQCH_QUIET@ +WARNINGS = YES +WARN_IF_UNDOCUMENTED = YES +WARN_IF_DOC_ERROR = YES +WARN_NO_PARAMDOC = YES +WARN_FORMAT = "\$file:\$line: \$text" +WARN_LOGFILE = @ECM_DOXYGENQCH_WARN_LOGFILE@ +#--------------------------------------------------------------------------- +# configuration options related to the input files +#--------------------------------------------------------------------------- +INPUT = @ECM_DOXYGENQCH_INPUT@ +FILE_PATTERNS = @ECM_DOXYGENQCH_FILE_PATTERNS@ +RECURSIVE = YES +EXCLUDE = +EXCLUDE_SYMLINKS = NO +EXCLUDE_PATTERNS = */.svn/* \ + */.git/* \ + */cmake/* \ + *.moc.* \ + moc* \ + *.all_cpp.* \ + *unload.* \ + */test/* \ + */tests/* \ + */autotests/* \ + *_p.cpp \ + *_p.h +# Symbols from Qt that show up occassionlly and we don't want to see +EXCLUDE_SYMBOLS = iterator const_iterator +EXAMPLE_PATH = +EXAMPLE_PATTERNS = * +EXAMPLE_RECURSIVE = NO +IMAGE_PATH = @ECM_DOXYGENQCH_IMAGEDIRS@ +INPUT_FILTER = +FILTER_PATTERNS = +FILTER_SOURCE_FILES = NO +USE_MDFILE_AS_MAINPAGE = README.md +#--------------------------------------------------------------------------- +# configuration options related to the alphabetical class index +#--------------------------------------------------------------------------- +ALPHABETICAL_INDEX = NO +COLS_IN_ALPHA_INDEX = 5 +IGNORE_PREFIX = +#--------------------------------------------------------------------------- +# do NOT generate any formats other than qhp +#--------------------------------------------------------------------------- +SOURCE_BROWSER = NO +GENERATE_HTML = YES +GENERATE_LATEX = NO +GENERATE_MAN = NO +GENERATE_RTF = NO +GENERATE_XML = NO +GENERATE_AUTOGEN_DEF = NO +GENERATE_PERLMOD = NO +DISABLE_INDEX = YES +#--------------------------------------------------------------------------- +# configuration options related to the qhp output +#--------------------------------------------------------------------------- +GENERATE_QHP = YES +QCH_FILE = @ECM_DOXYGENQCH_FILEPATH@ +QHP_NAMESPACE = @ECM_DOXYGENQCH_FULLNAMESPACE@ +QHP_VIRTUAL_FOLDER = @ECM_DOXYGENQCH_VIRTUALFOLDER@ +QHG_LOCATION = @ECM_DOXYGENQCH_QHELPGENERATOR_EXECUTABLE@ +#--------------------------------------------------------------------------- +# Configuration options related to the preprocessor +#--------------------------------------------------------------------------- +ENABLE_PREPROCESSING = YES +MACRO_EXPANSION = YES +EXPAND_ONLY_PREDEF = NO +SEARCH_INCLUDES = YES +INCLUDE_PATH = +INCLUDE_FILE_PATTERNS = +PREDEFINED = +EXPAND_AS_DEFINED = +SKIP_FUNCTION_MACROS = YES +#--------------------------------------------------------------------------- +# Configuration::additions related to external references +#--------------------------------------------------------------------------- +ALLEXTERNALS = NO +EXTERNAL_GROUPS = YES +TAGFILES = @ECM_DOXYGENQCH_TAGFILES@ +PERL_PATH = @ECM_DOXYGENQCH_PERL_EXECUTABLE@ +#--------------------------------------------------------------------------- +# Configuration options related to the dot tool +#--------------------------------------------------------------------------- +CLASS_DIAGRAMS = NO +HIDE_UNDOC_RELATIONS = YES +HAVE_DOT = NO +CLASS_GRAPH = NO +COLLABORATION_GRAPH = NO +GROUP_GRAPHS = NO +UML_LOOK = NO +TEMPLATE_RELATIONS = NO +INCLUDE_GRAPH = NO +INCLUDED_BY_GRAPH = YES +CALL_GRAPH = NO +CALLER_GRAPH = NO +GRAPHICAL_HIERARCHY = NO +DIRECTORY_GRAPH = NO +GENERATE_LEGEND = NO +#--------------------------------------------------------------------------- +# Configuration::additions related to the search engine +#--------------------------------------------------------------------------- +SEARCHENGINE = NO + + +### KDE Settings +ALIASES = "intern=\parInternal use only." \ + "reimp=\parReimplemented from superclass." \ + "obsolete=@deprecated" \ + "feature=\xrefitem features \"Feature(s)\" \"Features\"" \ + "unmaintained=\xrefitem unmaintained \"Unmaintained\" \"Unmaintained\"" \ + "requirement=\xrefitem requirements \"Requirement(s)\" \"Requirements\"" \ + "faq=\xrefitem FAQ \"F.A.Q.\" \"F.A.Q.\"" \ + "authors=\xrefitem authors \"Author(s)\" \"Authors\"" \ + "maintainers=\xrefitem maintainers \"Maintainer(s)\" \"Maintainers\"" \ + "glossary=\xrefitem glossary \"Glossary\" \"Glossary\"" \ + "acronym=\b " \ + "licenses=\xrefitem licenses \"License(s)\" \"Licenses\"" \ + "FIXME=\xrefitem fixme \"Fixme\" \"Fixme\"" \ + "bc=\xrefitem bc \"Binary Compatible\" \"Binary Compatible\"" \ + "threadsafe=\xrefitem threadsafe \"Threadsafe\" \"Threadsafe\"" \ + "artistic=Artistic" \ + "bsd=BSD" \ + "x11=X11" \ + "gpl=GPLv2" \ + "lgpl=LGPLv2" \ + "mit=MIT" \ + "qpl=QPL" + +PREDEFINED = DOXYGEN_SHOULD_SKIP_THIS \ +\ + Q_WS_X11="" \ + Q_WS_WIN="" \ + Q_WS_MAC="" \ + Q_WS_QWS="" \ + Q_WS_MAEMO_5="" \ + Q_OS_LINUX="" \ + Q_OS_UNIX="" \ + Q_OS_WIN="" \ + Q_OS_MAC="" \ + Q_OS_MACX="" \ + Q_OS_DARWIN="" \ + Q_OS_FREEBSD="" \ + Q_OS_NETBSD="" \ + Q_OS_OPENBSD="" \ + Q_OS_BSD4="" \ + Q_OS_SOLARIS="" \ + Q_OS_IRIX="" \ +\ + Q_SLOTS="slots" \ + Q_SIGNALS="signals" \ + Q_DECL_CONSTEXPR="constexpr" \ + Q_DECL_FINAL="final" \ + Q_DECL_NULLPTR="0" \ + Q_DECL_OVERRIDE="override" \ + Q_DECL_HIDDEN=""\ + @ECM_DOXYGENQCH_BLANK_MACROS@ Index: modules/ECMGenerateApiDox.cmake =================================================================== --- /dev/null +++ modules/ECMGenerateApiDox.cmake @@ -0,0 +1,407 @@ +#.rst: +# ECMGenerateApiDox +# ------------------ +# +# Generate API documentation in the QCH format. +# +# :: +# +# ecm_generate_qch( +# VERSION +# QCH_INSTALL_DESTINATION +# TAGS_INSTALL_DESTINATION +# [SOURCE_DIRS [ [...]]] +# [SOURCES [ [...]]] +# [IMAGE_DIRS [ [...]]] +# [ORG_DOMAIN ] +# [NAMESPACE ] +# [EXTERN [ [...]]] +# [EXTERN_VERSIONED [ [...]]] +# [BLANK_MACROS [ [...]]] +# [CONFIG_TEMPLATE ] +# [VERBOSE] +# ) +# +# This macro creates and installs an API documentation manual named ``.qch`` +# in the QCH format from the sources in the given directories. It currently uses doxygen, +# future versions might optionally also allow other tools. +# It is recommended to make the use of this and the related macros optional, by depending +# the calls on a CMake variable, with a name like BUILD_APIDOX and being off by default. +# This enables to build the project without the required dependencies installed intially +# and also saves resources on normal development builds. +# +# Using tag files it will also allow to create links to documentation of external API +# like classes or methods in other libaries. +# Currently such links to external API is bound to the specific version of that +# external code, due to the version being part of the references. So upgrading +# some library including it's API manual will result in broken links. +# +# The macro will export the variables _APIDOX_TAGSFILE, _APIDOX_QHP_NAMESPACE, +# _APIDOX_QHP_NAMESPACE_VERSIONED and _APIDOX_QHP_VIRTUALFOLDER. This enables +# the macro ecm_generate_package_apidox_file() to automatically pick up the respective +# values. It also allows to use as item for EXTERN or EXTERN_VERSIONED in +# further ecm_generate_qch() calls in the current build system. +# +# VERSION specifies the version of the library for which the documentation is created. +# +# SOURCE_DIRS specifies the dirs (incl. subdirs) with the source files for which the +# API documentation should be generated. Dirs can be relative to the current source dir. +# Needs to be used when SOURCES is not used. +# +# SOURCES specifies the source files for which the API documentation should be generated +# Needs to be used when SOURCE_DIRS is not used. +# +# IMAGE_DIRS specifies the dirs which contain images that are to be included in the +# documentation. Dirs can be relative to the current source dir. +# +# QCH_INSTALL_DESTINATION specifies where the generated QCH file will be installed. +# +# TAGS_INSTALL_DESTINATION specifies where the generated tags file will be installed. +# +# NAMESPACE can be used to set a custom namespace of the generated QCH file. +# The namepspace is used as the unique id by QHelpEngine (cmp. +# http://doc.qt.io/qt-5/qthelpproject.html#namespace). +# The default namespace is ``.``. +# Needs to be used when ORG_DOMAIN is not used. +# +# ORG_DOMAIN can be used to define the organization domain prefix for the default namespace +# of the generated QCH file. +# Needs to be used when NAMESPACE is not used. +# +# EXTERN specifies a list of external API documentation which should be used for creating +# references to API documenation of code in external libraries. +# For each in the list three CMake variables are expected to be defined: +# _APIDOX_TAGSFILE, _APIDOX_QHP_NAMESPACE and _APIDOX_QHP_VIRTUALFOLDER. +# If any of these is not existing, will be ignored. +# Use the macro ecm_generate_package_apidox_file for adding the definition of these +# variables to the CMake config of a library. +# +# EXTERN_VERSIONED does basically the same as EXTERN, but binds the links to a certain version. +# For each in the list CMake variables are expected to be defined: +# _APIDOX_TAGSFILE, _APIDOX_QHP_NAMESPACE_VERSIONED and _APIDOX_QHP_VIRTUALFOLDER. +# If any of these is not existing, will be ignored. +# Use the macro ecm_generate_package_apidox_file for adding the definition of these +# variables to the CMake config of a library. +# +# BLANK_MACROS specifies a list of C/C++ macro names which should be ignored by the +# API dox generation tool and handled as if they resolve to empty strings. +# Examples are export macros only defined in generated files, so whose definition +# might be not available to the tool. +# +# CONFIG_TEMPLATE specifies a custom cmake template file for the config file +# that is created to control the execution of the API dox generation tool. +# There is no guarantue that the currently used CMake variables in the default config +# file template will also be the same in future versions. So when using a custom config +# file template, it is recommended to use also only custom variables in it. +# +# VERBOSE tells the API dox generation tool to be more verbose about its activity. +# +# +# Example usage: +# +# .. code-block:: cmake +# +# ecm_generate_qch( +# MyLib +# VERSION "0.42.0" +# ORG_DOMAIN org.myorg +# SOURCE_DIRS +# ${CMAKE_SOURCE_DIR}/src +# EXTERN +# Qt5Core +# Qt5Xml +# Qt5Gui +# Qt5Widgets +# BLANK_MACROS +# MyLib_EXPORT +# MyLib_DEPRECATED +# TAGS_INSTALL_DESTINATION ${CMAKE_INSTALL_PREFIX}/share/docs/tags +# QCH_INSTALL_DESTINATION ${CMAKE_INSTALL_PREFIX}/share/docs/qch +# ) +# ecm_generate_package_apidox_file( +# ${CMAKE_CURRENT_BINARY_DIR}/MyLibConfigApiDox.cmake +# NAME Marble +# ) +# install(FILES ${CMAKE_CURRENT_BINARY_DIR}/MyLibConfigApiDox.cmake +# DESTINATION ${CMAKE_INSTALL_PREFIX}/lib/cmake/MyLib +# COMPONENT Devel) +# +# Since 5.28.0. + +#============================================================================= +# Copyright 2016 Friedrich W. H. Kossebau +# +# Redistribution and use in source and binary forms, with or without +# modification, are permitted provided that the following conditions +# are met: +# +# 1. Redistributions of source code must retain the copyright +# notice, this list of conditions and the following disclaimer. +# 2. Redistributions in binary form must reproduce the copyright +# notice, this list of conditions and the following disclaimer in the +# documentation and/or other materials provided with the distribution. +# 3. The name of the author may not be used to endorse or promote products +# derived from this software without specific prior written permission. +# +# THIS SOFTWARE IS PROVIDED BY THE AUTHOR ``AS IS'' AND ANY EXPRESS OR +# IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES +# OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. +# IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY DIRECT, INDIRECT, +# INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT +# NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, +# DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY +# THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT +# (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF +# THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. + +include(CMakeParseArguments) + +function(ecm_generate_qch name) + # Parse arguments + set(options VERBOSE) + set(oneValueArgs QCH_INSTALL_DESTINATION TAGS_INSTALL_DESTINATION VERSION NAMESPACE ORG_DOMAIN CONFIG_TEMPLATE) + set(multiValueArgs SOURCE_DIRS SOURCES IMAGE_DIRS BLANK_MACROS EXTERN EXTERN_VERSIONED) + cmake_parse_arguments(ARGS "${options}" "${oneValueArgs}" "${multiValueArgs}" ${ARGN}) + + # check required args + foreach(_arg_name QCH_INSTALL_DESTINATION TAGS_INSTALL_DESTINATION VERSION) + if(NOT DEFINED ARGS_${_arg_name}) + message(FATAL_ERROR "${_arg_name} needs to be defined when calling ecm_generate_qch") + endif() + endforeach() + if(NOT DEFINED ARGS_SOURCE_DIRS AND NOT DEFINED ARGS_SOURCES) + message(FATAL_ERROR "SOURCE_DIRS or SOURCES needs to be defined when calling ecm_generate_qch") + endif() + if(DEFINED ARGS_SOURCE_DIRS AND DEFINED ARGS_SOURCES) + message(FATAL_ERROR "Either SOURCE_DIRS or SOURCES, not both, needs to be defined when calling ecm_generate_qch") + endif() + if(NOT DEFINED ARGS_ORG_DOMAIN AND NOT DEFINED ARGS_NAMESPACE) + message(FATAL_ERROR "ORG_DOMAIN or NAMESPACE needs to be defined when calling ecm_generate_qch") + endif() + + # create APIDOX vars for Qt + # Ideally one day Qt CMake Config files provide these + if(NOT DEFINED Qt5Core_APIDOX_TAGSFILE) + # get Qt version, if any + find_package(Qt5Core CONFIG QUIET) + # lookup tag files + find_path(_qtcoreTagsPath qtcore/qtcore.tags + PATHS + /usr/share/doc/packages/qt5/ + ) + + # TODO: if not found, try qmake -query QT_INSTALL_DOCS. or perhaps try that first + if(Qt5Core_FOUND AND _qtcoreTagsPath) + string(REPLACE "." "" _version ${Qt5Core_VERSION}) + # TODO: properly find each tag file + # TODO: complete list of Qt modules + foreach(_module + Bluetooth Concurrent Core DBus Gui Location Multimedia MultimediaWidgets + Network Positioning PrintSupport Qml Quick Sensors SerialPort Sql Svg + WebEngine WebView Widgets Xml XmlPatterns + ) + string(TOLOWER ${_module} _lowermodule) + set(Qt5${_module}_APIDOX_TAGSFILE "${_qtcoreTagsPath}/qt${_lowermodule}/qt${_lowermodule}.tags") + set(Qt5${_module}_APIDOX_QHP_NAMESPACE "org.qt-project.qt${_lowermodule}") + set(Qt5${_module}_APIDOX_QHP_NAMESPACE_VERSIONED "${Qt5${_module}_APIDOX_QHP_NAMESPACE}.${_version}") + set(Qt5${_module}_APIDOX_QHP_VIRTUALFOLDER "qt${_lowermodule}") + endforeach() + endif() + endif() + + # find required tools + find_program(ECM_DOXYGENQCH_PERL_EXECUTABLE NAMES perl) + find_program(ECM_DOXYGENQCH_QHELPGENERATOR_EXECUTABLE NAMES qhelpgenerator-qt5 qhelpgenerator) + find_program(ECM_DOXYGENQCH_DOXYGEN_EXECUTABLE NAMES doxygen) + + # + set(_qch_file_basename "${name}.qch") + set(_tags_file_basename "${name}.tags") + set(_apidox_builddir "${CMAKE_CURRENT_BINARY_DIR}/${name}_ECMDoxygenQCH") + if (DEFINED ARGS_NAMESPACE) + set(_namespace "${ARGS_NAMESPACE}") + else() + set(_namespace "${ARGS_ORG_DOMAIN}.${name}") + endif() + string(REPLACE "." "" _dotLessVersion ${ARGS_VERSION}) + set(_versioned_namespace "${_namespace}.${_dotLessVersion}") + + ### Create doxygen config file + set(_doxygenconfig_file "${CMAKE_CURRENT_BINARY_DIR}/${name}_ECMDoxygenQCH.config") + if (DEFINED ARGS_CONFIG_TEMPLATE) + set(_doxygenconfig_template_file "${ARGS_CONFIG_TEMPLATE}") + else() + set(_doxygenconfig_template_file "${ECM_MODULE_DIR}/ECMDoxygenQCH.config.in") + endif() + # Setup variables used in config file template, ECM_DOXYGENQCH_* + set(ECM_DOXYGENQCH_OUTPUTDIR "\"${_apidox_builddir}\"") + set(ECM_DOXYGENQCH_TAGFILE "\"${_apidox_builddir}/${_tags_file_basename}\"") + set(ECM_DOXYGENQCH_INPUT) + if (ARGS_SOURCE_DIRS) + foreach(_source_DIR IN LISTS ARGS_SOURCE_DIRS) + if (NOT IS_ABSOLUTE ${_source_DIR}) + set(_source_DIR "${CMAKE_CURRENT_SOURCE_DIR}/${_source_DIR}") + endif() + # concat dirs separated by a break, it is no issue that first has also a leading break + set(ECM_DOXYGENQCH_INPUT "${ECM_DOXYGENQCH_INPUT} \\\n\"${_source_DIR}\"") + endforeach() + set(ECM_DOXYGENQCH_FILE_PATTERNS "*.h *.cpp *.hpp *.hh *.cc *.h++ *.c++ *.hxx *.cxx *.dox *.md") + else() + foreach(_source IN LISTS ARGS_SOURCES) + if (NOT IS_ABSOLUTE ${_source}) + set(_source "${CMAKE_CURRENT_SOURCE_DIR}/${_source}") + endif() + # concat sources separated by a break, it is no issue that first has also a leading break + set(ECM_DOXYGENQCH_INPUT "${ECM_DOXYGENQCH_INPUT} \\\n\"${_source}\"") + endforeach() + set(ECM_DOXYGENQCH_FILE_PATTERNS "") + endif() + set(ECM_DOXYGENQCH_IMAGEDIRS) + foreach(_image_DIR IN LISTS ARGS_IMAGE_DIRS) + if (NOT IS_ABSOLUTE ${_image_DIR}) + set(_image_DIR "${CMAKE_CURRENT_SOURCE_DIR}/${_image_DIR}") + endif() + # concat dirs separated by a break, it is no issue that first has also a leading break + set(ECM_DOXYGENQCH_IMAGEDIRS "${ECM_DOXYGENQCH_IMAGEDIRS} \\\n\"${_image_DIR}\"") + endforeach() + set(ECM_DOXYGENQCH_PROJECTNAME ${name}) + set(ECM_DOXYGENQCH_FILEPATH "\"../${_qch_file_basename}\"") + set(ECM_DOXYGENQCH_PROJECTVERSION ${ARGS_VERSION}) + set(ECM_DOXYGENQCH_VIRTUALFOLDER "${name}") + set(ECM_DOXYGENQCH_FULLNAMESPACE ${_versioned_namespace}) + set(ECM_DOXYGENQCH_BLANK_MACROS) + foreach(_macro IN LISTS ARGS_BLANK_MACROS) + # concat dirs separated by a break, it is no issue that first has also a leading break + set(ECM_DOXYGENQCH_BLANK_MACROS "${ECM_DOXYGENQCH_BLANK_MACROS} \\\n${_macro}=\"\"") + endforeach() + set(ECM_DOXYGENQCH_TAGFILES) + foreach(_versioned_postfix "" "_VERSIONED") + foreach(_extern IN LISTS ARGS_EXTERN${_versioned_postfix}) + set(_tags_usable TRUE) + foreach(_postfix _APIDOX_TAGSFILE _APIDOX_QHP_NAMESPACE${_versioned_postfix} _APIDOX_QHP_VIRTUALFOLDER) + if(NOT DEFINED ${_extern}${_postfix}) + message(STATUS "${_extern}${_postfix} not defined for ${_extern} when calling ecm_generate_qch()") + set(_tags_usable FALSE) + endif() + endforeach() + if(_tags_usable) + set(_tagfile "\"${${_extern}_APIDOX_TAGSFILE}=qthelp://${${_extern}_APIDOX_QHP_NAMESPACE${_versioned_postfix}}/${${_extern}_APIDOX_QHP_VIRTUALFOLDER}/\"") + # concat dirs separated by a break, it is no issue that first has also a leading break + set(ECM_DOXYGENQCH_TAGFILES "${ECM_DOXYGENQCH_TAGFILES} \\\n${_tagfile}") + else() + message(WARNING "No linking to API dox of ${_extern}.") + endif() + endforeach() + endforeach() + + set(ECM_DOXYGENQCH_WARN_LOGFILE "\"${_doxygenconfig_file}.log\"") + if(ARGS_VERBOSE) + set(ECM_DOXYGENQCH_QUIET "NO") + else() + set(ECM_DOXYGENQCH_QUIET "YES") + endif() + + if (NOT ECM_DOXYGENQCH_DOXYGEN_EXECUTABLE) + message(STATUS "Unable to find the doxygen utility - API dox QCH file will not be generated!") + elseif(NOT ECM_DOXYGENQCH_QHELPGENERATOR_EXECUTABLE) + message(STATUS "Unable to find the qhelpgenerator utility - API dox QCH file will not be generated!") + elseif(NOT ECM_DOXYGENQCH_PERL_EXECUTABLE) + message(STATUS "Unable to find the perl utility - API dox QCH file will not be generated!") + else() + configure_file( + "${_doxygenconfig_template_file}" + "${_doxygenconfig_file}" + @ONLY + ) + + set(_qch_BUILDPATH "${_apidox_builddir}/${_qch_file_basename}") + set(_qch_INSTALLPATH ${ARGS_QCH_INSTALL_DESTINATION}) + set(_tags_BUILDPATH "${_apidox_builddir}/${_tags_file_basename}") + set(_tags_INSTALLPATH ${ARGS_TAGS_INSTALL_DESTINATION}) + + # Right now we do not have the information which files are used by doxygen + # so not setting any DEPENDS, requiring the user to remove the qch file to trigger a rebuild + add_custom_command( + OUTPUT ${_qch_BUILDPATH} ${_tags_BUILDPATH} + COMMENT "Generating ${_qch_file_basename}" + COMMAND cmake -E remove_directory "${ECM_DOXYGENQCH_OUTPUTDIR}" + COMMAND cmake -E make_directory "${ECM_DOXYGENQCH_OUTPUTDIR}" + COMMAND ${ECM_DOXYGENQCH_DOXYGEN_EXECUTABLE} "${_doxygenconfig_file}" + DEPENDS ${_doxygenconfig_file} + ) + add_custom_target(${name}_qch ALL DEPENDS ${_qch_BUILDPATH} ${_tags_BUILDPATH}) + + install(FILES + ${_qch_BUILDPATH} + DESTINATION ${_qch_INSTALLPATH} + COMPONENT Devel + ) + + install(FILES + ${_tags_BUILDPATH} + DESTINATION ${_tags_INSTALLPATH} + COMPONENT Devel + ) + + # export variables + set(${name}_APIDOX_TAGSFILE "${_qch_INSTALLPATH}/${_tags_file_basename}" PARENT_SCOPE) + set(${name}_APIDOX_QHP_NAMESPACE "${_namespace}" PARENT_SCOPE) + set(${name}_APIDOX_QHP_NAMESPACE_VERSIONED "${_versioned_namespace}" PARENT_SCOPE) + set(${name}_APIDOX_QHP_VIRTUALFOLDER "${ECM_DOXYGENQCH_VIRTUALFOLDER}" PARENT_SCOPE) + endif() +endfunction() + + +function(ecm_generate_package_apidox_file apidox_filename) + set(options ) + set(oneValueArgs) + set(multiValueArgs NAMES) + + cmake_parse_arguments(ARGS "${options}" "${oneValueArgs}" "${multiValueArgs}" ${ARGN}) + + if(NOT DEFINED ARGS_NAMES) + message(FATAL_ERROR "NAMES needs to be defined when calling ecm_generate_package_apidox_file().") + endif() + + set(_content +"# Generated by ecm_generate_package_apidox_file() +# Any changes to this file will be overwritten by the next CMake run +" + ) + + foreach(_name IN LISTS ARGS_NAMES) + set(_name_usable TRUE) + + foreach(_postfix + _APIDOX_TAGSFILE + _APIDOX_QHP_NAMESPACE + _APIDOX_QHP_NAMESPACE_VERSIONED + _APIDOX_QHP_VIRTUALFOLDER + ) + if(NOT DEFINED "${_name}${_postfix}") + message(STATUS "No ${_name}${_postfix} defined when calling ecm_generate_package_apidox_file().") + set(_name_usable FALSE) + endif() + endforeach() + if(_name_usable) + set(_content "${_content} +set(${_name}_APIDOX_TAGSFILE \"${${_name}_APIDOX_TAGSFILE}\") +set(${_name}_APIDOX_QHP_NAMESPACE \"${${_name}_APIDOX_QHP_NAMESPACE}\") +set(${_name}_APIDOX_QHP_NAMESPACE_VERSIONED \"${${_name}_APIDOX_QHP_NAMESPACE_VERSIONED}\") +set(${_name}_APIDOX_QHP_VIRTUALFOLDER \"${${_name}_APIDOX_QHP_VIRTUALFOLDER}\") +" + ) + else() + message(STATUS "Not apidox config written for ${_name}.") + set(_content "${_content} +# No API dox generated for ${_name} as part of build +" + ) + endif() + endforeach() + + file(GENERATE + OUTPUT "${apidox_filename}" + CONTENT "${_content}" + ) +endfunction()