diff options
Diffstat (limited to 'modules')
31 files changed, 2343 insertions, 2347 deletions
diff --git a/modules/CheckAtomic.cmake b/modules/CheckAtomic.cmake index 185a6abf..d154b117 100644 --- a/modules/CheckAtomic.cmake +++ b/modules/CheckAtomic.cmake @@ -1,19 +1,18 @@ -#.rst: -# CheckAtomic -# ----------- -# -# Check if the compiler supports std:atomic out of the box or if libatomic is -# needed for atomic support. If it is needed libatomicis added to -# CMAKE_REQUIRED_LIBRARIES. So after running CheckAtomic you can use -# std:atomic. -# -# Since 5.75.0. - -#============================================================================= # SPDX-FileCopyrightText: 2003-2018 University of Illinois at Urbana-Champaign. # # SPDX-License-Identifier: BSD-3-Clause -#============================================================================= + +#[=======================================================================[.rst: +CheckAtomic +----------- + +Check if the compiler supports std:atomic out of the box or if libatomic is +needed for atomic support. If it is needed libatomicis added to +``CMAKE_REQUIRED_LIBRARIES``. So after running CheckAtomic you can use +std:atomic. + +Since 5.75.0. +#]=======================================================================] include(CheckCXXSourceCompiles) include(CheckLibraryExists) diff --git a/modules/ECMAddAppIcon.cmake b/modules/ECMAddAppIcon.cmake index c552c16b..7a674d63 100644 --- a/modules/ECMAddAppIcon.cmake +++ b/modules/ECMAddAppIcon.cmake @@ -1,72 +1,3 @@ -#.rst: -# ECMAddAppIcon -# ------------- -# -# Add icons to executable files and packages. -# -# :: -# -# ecm_add_app_icon(<sources_var> -# ICONS <icon> [<icon> [...]] -# [SIDEBAR_ICONS <icon> [<icon> [...]] # Since 5.49 -# [OUTFILE_BASENAME <name>]) # Since 5.49 -# ) -# -# The given icons, whose names must match the pattern:: -# -# <size>-<other_text>.png -# -# will be added to the executable target whose sources are specified by -# ``<sources_var>`` on platforms that support it (Windows and Mac OS X). -# Other icon files are ignored but on Mac SVG files can be supported and -# it is thus possible to mix those with png files in a single macro call. -# -# ``<size>`` is a numeric pixel size (typically 16, 32, 48, 64, 128 or 256). -# ``<other_text>`` can be any other text. See the platform notes below for any -# recommendations about icon sizes. -# -# ``SIDEBAR_ICONS`` can be used to add Mac OS X sidebar -# icons to the generated iconset. They are used when a folder monitored by the -# application is dragged into Finder's sidebar. Since 5.49. -# -# ``OUTFILE_BASENAME`` will be used as the basename for the icon file. If -# you specify it, the icon file will be called ``<OUTFILE_BASENAME>.icns`` on Mac OS X -# and ``<OUTFILE_BASENAME>.ico`` on Windows. If you don't specify it, it defaults -# to ``<sources_var>.<ext>``. Since 5.49. -# -# -# Windows notes -# * Icons are compiled into the executable using a resource file. -# * Icons may not show up in Windows Explorer if the executable -# target does not have the ``WIN32_EXECUTABLE`` property set. -# * Icotool (see :find-module:`FindIcoTool`) is required. -# * Supported sizes: 16, 24, 32, 48, 64, 128, 256, 512 and 1024. -# -# Mac OS X notes -# * The executable target must have the ``MACOSX_BUNDLE`` property set. -# * Icons are added to the bundle. -# * If the ksvg2icns tool from KIconThemes is available, .svg and .svgz -# files are accepted; the first that is converted successfully to .icns -# will provide the application icon. SVG files are ignored otherwise. -# * The tool iconutil (provided by Apple) is required for bitmap icons. -# * Supported sizes: 16, 32, 64, 128, 256 (and 512, 1024 after OS X 10.9). -# * At least a 128x128px (or an SVG) icon is required. -# * Larger sizes are automatically used to substitute for smaller sizes on -# "Retina" (high-resolution) displays. For example, a 32px icon, if -# provided, will be used as a 32px icon on standard-resolution displays, -# and as a 16px-equivalent icon (with an "@2x" tag) on high-resolution -# displays. That is why you should provide 64px and 1024px icons although -# they are not supported anymore directly. Instead they will be used as -# 32px@2x and 512px@2x. ksvg2icns handles this internally. -# * This function sets the ``MACOSX_BUNDLE_ICON_FILE`` variable to the name -# of the generated icns file, so that it will be used as the -# ``MACOSX_BUNDLE_ICON_FILE`` target property when you call -# ``add_executable``. -# * Sidebar icons should typically provided in 16, 32, 64, 128 and 256px. -# -# Since 1.7.0. - -#============================================================================= # SPDX-FileCopyrightText: 2014 Alex Merry <alex.merry@kde.org> # SPDX-FileCopyrightText: 2014 Ralf Habacker <ralf.habacker@freenet.de> # SPDX-FileCopyrightText: 2006-2009 Alexander Neundorf <neundorf@kde.org> @@ -75,6 +6,75 @@ # # SPDX-License-Identifier: BSD-3-Clause +#[=======================================================================[.rst: +ECMAddAppIcon +------------- + +Add icons to executable files and packages. + +:: + + ecm_add_app_icon(<sources_var> + ICONS <icon> [<icon> [...]] + [SIDEBAR_ICONS <icon> [<icon> [...]] # Since 5.49 + [OUTFILE_BASENAME <name>]) # Since 5.49 + ) + +The given icons, whose names must match the pattern:: + + <size>-<other_text>.png + +will be added to the executable target whose sources are specified by +``<sources_var>`` on platforms that support it (Windows and Mac OS X). +Other icon files are ignored but on Mac SVG files can be supported and +it is thus possible to mix those with png files in a single macro call. + +``<size>`` is a numeric pixel size (typically 16, 32, 48, 64, 128 or 256). +``<other_text>`` can be any other text. See the platform notes below for any +recommendations about icon sizes. + +``SIDEBAR_ICONS`` can be used to add Mac OS X sidebar +icons to the generated iconset. They are used when a folder monitored by the +application is dragged into Finder's sidebar. Since 5.49. + +``OUTFILE_BASENAME`` will be used as the basename for the icon file. If +you specify it, the icon file will be called ``<OUTFILE_BASENAME>.icns`` on Mac OS X +and ``<OUTFILE_BASENAME>.ico`` on Windows. If you don't specify it, it defaults +to ``<sources_var>.<ext>``. Since 5.49. + + +Windows notes + * Icons are compiled into the executable using a resource file. + * Icons may not show up in Windows Explorer if the executable + target does not have the ``WIN32_EXECUTABLE`` property set. + * Icotool (see :find-module:`FindIcoTool`) is required. + * Supported sizes: 16, 24, 32, 48, 64, 128, 256, 512 and 1024. + +Mac OS X notes + * The executable target must have the ``MACOSX_BUNDLE`` property set. + * Icons are added to the bundle. + * If the ksvg2icns tool from KIconThemes is available, .svg and .svgz + files are accepted; the first that is converted successfully to .icns + will provide the application icon. SVG files are ignored otherwise. + * The tool iconutil (provided by Apple) is required for bitmap icons. + * Supported sizes: 16, 32, 64, 128, 256 (and 512, 1024 after OS X 10.9). + * At least a 128x128px (or an SVG) icon is required. + * Larger sizes are automatically used to substitute for smaller sizes on + "Retina" (high-resolution) displays. For example, a 32px icon, if + provided, will be used as a 32px icon on standard-resolution displays, + and as a 16px-equivalent icon (with an "@2x" tag) on high-resolution + displays. That is why you should provide 64px and 1024px icons although + they are not supported anymore directly. Instead they will be used as + 32px@2x and 512px@2x. ksvg2icns handles this internally. + * This function sets the ``MACOSX_BUNDLE_ICON_FILE`` variable to the name + of the generated icns file, so that it will be used as the + ``MACOSX_BUNDLE_ICON_FILE`` target property when you call + ``add_executable``. + * Sidebar icons should typically provided in 16, 32, 64, 128 and 256px. + +Since 1.7.0. +#]=======================================================================] + include(CMakeParseArguments) function(ecm_add_app_icon appsources) diff --git a/modules/ECMAddQch.cmake b/modules/ECMAddQch.cmake index c0580ca8..8ba91768 100644 --- a/modules/ECMAddQch.cmake +++ b/modules/ECMAddQch.cmake @@ -1,258 +1,261 @@ -#.rst: -# ECMAddQch -# ------------------ -# -# This module provides the ``ecm_add_qch`` function for generating API -# documentation files in the QCH format, and the ``ecm_install_qch_export`` -# function for generating and installing exported CMake targets for such -# generated QCH files to enable builds of other software with generation of -# QCH files to create links into the given QCH files. -# -# :: -# -# ecm_add_qch(<target_name> -# NAME <name> -# VERSION <version> -# QCH_INSTALL_DESTINATION <qchfile_install_path> -# TAGFILE_INSTALL_DESTINATION <tagsfile_install_path> -# [COMPONENT <component>] -# [BASE_NAME <basename>] -# [SOURCE_DIRS <dir> [<dir2> [...]]] -# [SOURCES <file> [<file2> [...]]] -# |MD_MAINPAGE <md_file>] -# [INCLUDE_DIRS <incdir> [<incdir2> [...]]] -# [IMAGE_DIRS <idir> [<idir2> [...]]] -# [EXAMPLE_DIRS <edir> [<edir2> [...]]] -# [ORG_DOMAIN <domain>] -# [NAMESPACE <namespace>] -# [LINK_QCHS <qch> [<qch2> [...]]] -# [PREDEFINED_MACROS <macro[=content]> [<macro2[=content]> [...]]] -# [BLANK_MACROS <macro> [<macro2> [...]]] -# [CONFIG_TEMPLATE <configtemplate_file>] -# [VERBOSE] -# ) -# -# This macro adds a target called <target_name> for the creation of an API -# documentation manual in the QCH format from the given sources. -# It currently uses doxygen, future versions might optionally also allow other -# tools. -# Next to the QCH file the target will generate a corresponding doxygen tag -# file, which enables creating links from other documentation into the -# generated QCH file. -# -# It is recommended to make the use of this macro optional, by depending -# the call to ``ecm_add_qch`` on a CMake option being set, with a name like -# ``BUILD_QCH`` and being TRUE by default. This will allow the developers to -# saves resources on normal source development build cycles by setting this -# option to FALSE. -# -# The macro will set the target properties DOXYGEN_TAGFILE, QHP_NAMESPACE, -# QHP_NAMESPACE_VERSIONED, QHP_VIRTUALFOLDER and LINK_QCHS to the respective -# values, to allow other code access to them, e.g. the macro -# ``ecm_install_qch_export``. -# To enable the use of the target <target_name> as item for LINK_QCHS -# in further ``ecm_add_qch`` calls in the current build, -# additionally a target property DOXYGEN_TAGFILE_BUILD is set, with the path -# of the created doxygen tag file in the build dir. -# If existing, ``ecm_add_qch`` will use this property instead of -# DOXYGEN_TAGFILE for access to the tags file. -# -# NAME specifies the name for the generated documentation. -# -# VERSION specifies the version of the library for which the documentation is -# created. -# -# BASE_NAME specifies the base name for the generated files. -# The default basename is ``<name>``. -# -# 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. Dependencies to the files in the dirs are not -# tracked currently, other than with the SOURCES argument. So do not use for -# sources generated during the build. -# Needs to be used when SOURCES or CONFIG_TEMPLATE are not used. -# -# SOURCES specifies the source files for which the API documentation should be -# generated. -# Needs to be used when SOURCE_DIRS or CONFIG_TEMPLATE are not used. -# -# MD_MAINPAGE specifies a file in Markdown format that should be used as main -# page. This page will overrule any ``\mainpage`` command in the included -# sources. -# -# INCLUDE_DIRS specifies the dirs which should be searched for included -# headers. Dirs can be relative to the current source dir. Since 5.63. -# -# IMAGE_DIRS specifies the dirs which contain images that are included in the -# documentation. Dirs can be relative to the current source dir. -# -# EXAMPLE_DIRS specifies the dirs which contain examples that are 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. -# -# TAGFILE_INSTALL_DESTINATION specifies where the generated tag file will be -# installed. -# -# COMPONENT specifies the installation component name with which the install -# rules for the generated QCH file and tag file are associated. -# -# NAMESPACE can be used to set a custom namespace <namespace> of the generated -# QCH file. The namepspace is used as the unique id by QHelpEngine (cmp. -# https://doc.qt.io/qt-5/qthelpproject.html#namespace). -# The default namespace is ``<domain>.<name>``. -# 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. -# -# LINK_QCHS specifies a list of other QCH targets which should be used for -# creating references to API documentation of code in external libraries. -# For each target <qch> in the list these target properties are expected to be -# defined: DOXYGEN_TAGFILE, QHP_NAMESPACE and QHP_VIRTUALFOLDER. -# If any of these is not existing, <qch> will be ignored. -# Use the macro ``ecm_install_qch_export`` for exporting a target with these -# properties with the CMake config of a library. -# Any target <qch> can also be one created before in the same buildsystem by -# another call of ``ecm_add_qch``. -# -# PREDEFINED_MACROS specifies a list of C/C++ macros which should be handled as -# given by the API dox generation tool. -# Examples are macros only defined in generated files, so whose -# definition might be not available to the tool. -# -# 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. -# The following CMake variables need to be used: -# ECM_QCH_DOXYGEN_QHELPGENERATOR_EXECUTABLE, -# ECM_QCH_DOXYGEN_FILEPATH, ECM_QCH_DOXYGEN_TAGFILE. -# The following CMake variables can be used: -# ECM_QCH_DOXYGEN_PROJECTNAME, ECM_QCH_DOXYGEN_PROJECTVERSION, -# ECM_QCH_DOXYGEN_VIRTUALFOLDER, ECM_QCH_DOXYGEN_FULLNAMESPACE, -# ECM_QCH_DOXYGEN_TAGFILES, -# ECM_QCH_DOXYGEN_WARN_LOGFILE, ECM_QCH_DOXYGEN_QUIET. -# There is no guarantue that the other CMake variables currently used in the -# default config file template will also be present with the same semantics -# in future versions of this macro. -# -# VERBOSE tells the API dox generation tool to be more verbose about its -# activity. -# -# The default config file for the API dox generation tool, so the one when not -# using CONFIG_TEMPLATE, allows code to handle the case of being processed by -# the tool by defining the C/C++ preprocessor macro ``K_DOXYGEN`` when run -# (since v5.67.0). For backward-compatibility also the definition -# ``DOXYGEN_SHOULD_SKIP_THIS`` is set, but its usage is deprecated. -# -# Example usage: -# -# .. code-block:: cmake -# -# ecm_add_qch( -# MyLib_QCH -# NAME MyLib -# VERSION "0.42.0" -# ORG_DOMAIN org.myorg -# SOURCE_DIRS -# src -# LINK_QCHS -# Qt5Core_QCH -# Qt5Xml_QCH -# Qt5Gui_QCH -# Qt5Widgets_QCH -# BLANK_MACROS -# MyLib_EXPORT -# MyLib_DEPRECATED -# TAGFILE_INSTALL_DESTINATION ${CMAKE_INSTALL_PREFIX}/share/docs/tags -# QCH_INSTALL_DESTINATION ${CMAKE_INSTALL_PREFIX}/share/docs/qch -# COMPONENT Devel -# ) -# -# Example usage (with two QCH files, second linking first): -# -# .. code-block:: cmake -# -# ecm_add_qch( -# MyLib_QCH -# NAME MyLib -# VERSION ${MyLib_VERSION} -# ORG_DOMAIN org.myorg -# SOURCES ${MyLib_PUBLIC_HEADERS} -# MD_MAINPAGE src/mylib/README.md -# LINK_QCHS Qt5Core_QCH -# TAGFILE_INSTALL_DESTINATION ${CMAKE_INSTALL_PREFIX}/share/docs/tags -# QCH_INSTALL_DESTINATION ${CMAKE_INSTALL_PREFIX}/share/docs/qch -# COMPONENT Devel -# ) -# ecm_add_qch( -# MyOtherLib_QCH -# NAME MyOtherLib -# VERSION ${MyOtherLib_VERSION} -# ORG_DOMAIN org.myorg -# SOURCES ${MyOtherLib_PUBLIC_HEADERS} -# MD_MAINPAGE src/myotherlib/README.md -# LINK_QCHS Qt5Core_QCH MyLib_QCH -# TAGFILE_INSTALL_DESTINATION ${CMAKE_INSTALL_PREFIX}/share/docs/tags -# QCH_INSTALL_DESTINATION ${CMAKE_INSTALL_PREFIX}/share/docs/qch -# COMPONENT Devel -# ) -# -# :: -# -# ecm_install_qch_export( -# TARGETS [<name> [<name2> [...]]] -# FILE <file> -# DESTINATION <dest> -# [COMPONENT <component>] -# ) -# -# This macro creates and installs a CMake file <file> which exports the given -# QCH targets <name> etc., so they can be picked up by CMake-based builds of -# other software that also generate QCH files (using ``ecm_add_qch``) and -# which should include links to the QCH files created by the given targets. -# The installed CMake file <file> is expected to be included by the CMake -# config file created for the software the related QCH files are documenting. -# -# TARGETS specifies the QCH targets which should be exported. If a target does -# not exist or does not have all needed properties, a warning will be -# generated and the target skipped. -# This behaviour might change in future versions to result in a fail instead. -# -# FILE specifies the name of the created CMake file, typically with a .cmake -# extension. -# -# DESTINATION specifies the directory on disk to which the file will be -# installed. It usually is the same as the one where the CMake config files -# for this software are installed. -# -# COMPONENT specifies the installation component name with which the -# install rule is associated. -# -# Example usage: -# -# .. code-block:: cmake -# -# ecm_install_qch_export( -# TARGETS MyLib_QCH -# FILE MyLibQCHTargets.cmake -# DESTINATION "${CMAKE_INSTALL_PREFIX}/lib/cmake/MyLib" -# COMPONENT Devel -# ) -# -# Since 5.36.0. - -#============================================================================= # SPDX-FileCopyrightText: 2016-2017 Friedrich W. H. Kossebau <kossebau@kde.org> # # SPDX-License-Identifier: BSD-3-Clause +#[=======================================================================[.rst: +ECMAddQch +------------------ + +This module provides the ``ecm_add_qch`` function for generating API +documentation files in the QCH format, and the ``ecm_install_qch_export`` +function for generating and installing exported CMake targets for such +generated QCH files to enable builds of other software with generation of +QCH files to create links into the given QCH files. + +:: + + ecm_add_qch(<target_name> + NAME <name> + VERSION <version> + QCH_INSTALL_DESTINATION <qchfile_install_path> + TAGFILE_INSTALL_DESTINATION <tagsfile_install_path> + [COMPONENT <component>] + [BASE_NAME <basename>] + [SOURCE_DIRS <dir> [<dir2> [...]]] + [SOURCES <file> [<file2> [...]]] + |MD_MAINPAGE <md_file>] + [INCLUDE_DIRS <incdir> [<incdir2> [...]]] + [IMAGE_DIRS <idir> [<idir2> [...]]] + [EXAMPLE_DIRS <edir> [<edir2> [...]]] + [ORG_DOMAIN <domain>] + [NAMESPACE <namespace>] + [LINK_QCHS <qch> [<qch2> [...]]] + [PREDEFINED_MACROS <macro[=content]> [<macro2[=content]> [...]]] + [BLANK_MACROS <macro> [<macro2> [...]]] + [CONFIG_TEMPLATE <configtemplate_file>] + [VERBOSE] + ) + +This macro adds a target called <target_name> for the creation of an API +documentation manual in the QCH format from the given sources. +It currently uses doxygen, future versions might optionally also allow other +tools. +Next to the QCH file the target will generate a corresponding doxygen tag +file, which enables creating links from other documentation into the +generated QCH file. + +It is recommended to make the use of this macro optional, by depending +the call to ``ecm_add_qch`` on a CMake option being set, with a name like +``BUILD_QCH`` and being TRUE by default. This will allow the developers to +saves resources on normal source development build cycles by setting this +option to FALSE. + +The macro will set the target properties ``DOXYGEN_TAGFILE``, ``QHP_NAMESPACE``, +``QHP_NAMESPACE_VERSIONED``, ``QHP_VIRTUALFOLDER`` and ``LINK_QCHS`` to the respective +values, to allow other code access to them, e.g. the macro +``ecm_install_qch_export``. +To enable the use of the target <target_name> as item for ``LINK_QCHS`` +in further ``ecm_add_qch`` calls in the current build, +additionally a target property ``DOXYGEN_TAGFILE_BUILD`` is set, with the path +of the created doxygen tag file in the build dir. +If existing, ``ecm_add_qch`` will use this property instead of +``DOXYGEN_TAGFILE`` for access to the tags file. + +``NAME`` specifies the name for the generated documentation. + +``VERSION`` specifies the version of the library for which the documentation is +created. + +``BASE_NAME`` specifies the base name for the generated files. +The default basename is ``<name>``. + +``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. Dependencies to the files in the dirs are not +tracked currently, other than with the ``SOURCES`` argument. So do not use for +sources generated during the build. +Needs to be used when ``SOURCES`` or ``CONFIG_TEMPLATE`` are not used. + +``SOURCES`` specifies the source files for which the API documentation should be +generated. +Needs to be used when ``SOURCE_DIRS`` or ``CONFIG_TEMPLATE`` are not used. + +``MD_MAINPAGE`` specifies a file in Markdown format that should be used as main +page. This page will overrule any ``\mainpage`` command in the included +sources. + +``INCLUDE_DIRS`` specifies the dirs which should be searched for included +headers. Dirs can be relative to the current source dir. Since 5.63. + +``IMAGE_DIRS`` specifies the dirs which contain images that are included in the +documentation. Dirs can be relative to the current source dir. + +``EXAMPLE_DIRS`` specifies the dirs which contain examples that are 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. + +``TAGFILE_INSTALL_DESTINATION`` specifies where the generated tag file will be +installed. + +``COMPONENT`` specifies the installation component name with which the install +rules for the generated QCH file and tag file are associated. + +``NAMESPACE`` can be used to set a custom namespace <namespace> of the generated +QCH file. The namepspace is used as the unique id by QHelpEngine (cmp. +https://doc.qt.io/qt-5/qthelpproject.html#namespace). +The default namespace is ``<domain>.<name>``. +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. + +``LINK_QCHS`` specifies a list of other QCH targets which should be used for +creating references to API documentation of code in external libraries. +For each target <qch> in the list these target properties are expected to be +defined: ``DOXYGEN_TAGFILE``, ``QHP_NAMESPACE`` and ``QHP_VIRTUALFOLDER``. +If any of these is not existing, <qch> will be ignored. +Use the macro ``ecm_install_qch_export`` for exporting a target with these +properties with the CMake config of a library. +Any target <qch> can also be one created before in the same buildsystem by +another call of ``ecm_add_qch``. + +``PREDEFINED_MACROS`` specifies a list of C/C++ macros which should be handled as +given by the API dox generation tool. +Examples are macros only defined in generated files, so whose +definition might be not available to the tool. + +``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. +The following CMake variables need to be used: +- ``ECM_QCH_DOXYGEN_QHELPGENERATOR_EXECUTABLE`` +- ``ECM_QCH_DOXYGEN_FILEPATH, ECM_QCH_DOXYGEN_TAGFILE`` +The following CMake variables can be used: +- ``ECM_QCH_DOXYGEN_PROJECTNAME`` +- ``ECM_QCH_DOXYGEN_PROJECTVERSION`` +- ``ECM_QCH_DOXYGEN_VIRTUALFOLDER`` +- ``ECM_QCH_DOXYGEN_FULLNAMESPACE`` +- ``ECM_QCH_DOXYGEN_TAGFILES`` +- ``ECM_QCH_DOXYGEN_WARN_LOGFILE`` +- ``ECM_QCH_DOXYGEN_QUIET`` +There is no guarantue that the other CMake variables currently used in the +default config file template will also be present with the same semantics +in future versions of this macro. + +``VERBOSE`` tells the API dox generation tool to be more verbose about its +activity. + +The default config file for the API dox generation tool, so the one when not +using ``CONFIG_TEMPLATE``, allows code to handle the case of being processed by +the tool by defining the C/C++ preprocessor macro ``K_DOXYGEN`` when run +(since v5.67.0). For backward-compatibility also the definition +``DOXYGEN_SHOULD_SKIP_THIS`` is set, but its usage is deprecated. + +Example usage: + +.. code-block:: cmake + + ecm_add_qch( + MyLib_QCH + NAME MyLib + VERSION "0.42.0" + ORG_DOMAIN org.myorg + SOURCE_DIRS + src + LINK_QCHS + Qt5Core_QCH + Qt5Xml_QCH + Qt5Gui_QCH + Qt5Widgets_QCH + BLANK_MACROS + MyLib_EXPORT + MyLib_DEPRECATED + TAGFILE_INSTALL_DESTINATION ${CMAKE_INSTALL_PREFIX}/share/docs/tags + QCH_INSTALL_DESTINATION ${CMAKE_INSTALL_PREFIX}/share/docs/qch + COMPONENT Devel + ) + +Example usage (with two QCH files, second linking first): + +.. code-block:: cmake + + ecm_add_qch( + MyLib_QCH + NAME MyLib + VERSION ${MyLib_VERSION} + ORG_DOMAIN org.myorg + SOURCES ${MyLib_PUBLIC_HEADERS} + MD_MAINPAGE src/mylib/README.md + LINK_QCHS Qt5Core_QCH + TAGFILE_INSTALL_DESTINATION ${CMAKE_INSTALL_PREFIX}/share/docs/tags + QCH_INSTALL_DESTINATION ${CMAKE_INSTALL_PREFIX}/share/docs/qch + COMPONENT Devel + ) + ecm_add_qch( + MyOtherLib_QCH + NAME MyOtherLib + VERSION ${MyOtherLib_VERSION} + ORG_DOMAIN org.myorg + SOURCES ${MyOtherLib_PUBLIC_HEADERS} + MD_MAINPAGE src/myotherlib/README.md + LINK_QCHS Qt5Core_QCH MyLib_QCH + TAGFILE_INSTALL_DESTINATION ${CMAKE_INSTALL_PREFIX}/share/docs/tags + QCH_INSTALL_DESTINATION ${CMAKE_INSTALL_PREFIX}/share/docs/qch + COMPONENT Devel + ) + +:: + + ecm_install_qch_export( + TARGETS [<name> [<name2> [...]]] + FILE <file> + DESTINATION <dest> + [COMPONENT <component>] + ) + +This macro creates and installs a CMake file <file> which exports the given +QCH targets <name> etc., so they can be picked up by CMake-based builds of +other software that also generate QCH files (using ``ecm_add_qch``) and +which should include links to the QCH files created by the given targets. +The installed CMake file <file> is expected to be included by the CMake +config file created for the software the related QCH files are documenting. + +``TARGETS`` specifies the QCH targets which should be exported. If a target does +not exist or does not have all needed properties, a warning will be +generated and the target skipped. +This behaviour might change in future versions to result in a fail instead. + +``FILE`` specifies the name of the created CMake file, typically with a .cmake +extension. + +``DESTINATION`` specifies the directory on disk to which the file will be +installed. It usually is the same as the one where the CMake config files +for this software are installed. + +``COMPONENT`` specifies the installation component name with which the +install rule is associated. + +Example usage: + +.. code-block:: cmake + + ecm_install_qch_export( + TARGETS MyLib_QCH + FILE MyLibQCHTargets.cmake + DESTINATION "${CMAKE_INSTALL_PREFIX}/lib/cmake/MyLib" + COMPONENT Devel + ) + +Since 5.36.0. +#]=======================================================================] + include(CMakeParseArguments) include(ECMQueryQmake) diff --git a/modules/ECMAddQtDesignerPlugin.cmake b/modules/ECMAddQtDesignerPlugin.cmake index e4bf4c63..eaf3660f 100644 --- a/modules/ECMAddQtDesignerPlugin.cmake +++ b/modules/ECMAddQtDesignerPlugin.cmake @@ -1,183 +1,183 @@ -#.rst: -# ECMAddQtDesignerPlugin -# ---------------------- -# -# This module provides the ``ecm_add_qtdesignerplugin`` function for generating -# Qt Designer plugins for custom widgets. Each of those widgets is described -# using a second function ``ecm_qtdesignerplugin_widget``. -# -# :: -# -# ecm_add_qtdesignerplugin(<target_name> -# NAME <name> -# WIDGETS <widgetid> [<widgetid2> [...]] -# LINK_LIBRARIES <lib> [<lib2> [...]] -# INSTALL_DESTINATION <install_path> -# [OUTPUT_NAME <output_name>] -# [DEFAULT_GROUP <group>] -# [DEFAULT_HEADER_CASE <SAME_CASE|LOWER_CASE|UPPER_CASE>] -# [DEFAULT_HEADER_EXTENSION <header_extension>] -# [DEFAULT_ICON_DIR <icon_dir>] -# [INCLUDE_FILES <include_file> [<include_file2> [...]]] -# [SOURCES <src> [<src2> [...]]] -# [COMPONENT <component>] -# ) -# -# ``NAME`` specifies the base name to use in the generated sources. -# The default is <target_name>. -# -# ``WIDGETS`` specifies the widgets the plugin should support. Each widget has -# to be defined before by a call of ``ecm_qtdesignerplugin_widget`` with the -# respective <widgetid>, in a scope including the current call. -# -# ``LINK_LIBRARIES`` specifies the libraries to link against. This will be at -# least the library providing the widget class(es). -# -# ``INSTALL_DESTINATION`` specifies where the generated plugin binary will be -# installed. -# -# ``OUTPUT_NAME`` specifies the name of the plugin binary. The default is -# "<target_name>". -# -# ``DEFAULT_GROUP`` specifies the default group in Qt Designer where the -# widgets will be placed. The default is "Custom". -# -# ``DEFAULT_HEADER_CASE`` specifies how the name of the header is derived from -# the widget class name. The default is "LOWER_CASE". -# -# ``DEFAULT_HEADER_EXTENSION`` specifies what file name extension is used for -# the header file derived from the class name. The default is "h". -# -# ``DEFAULT_ICON_DIR`` specifies what file name extension is used for -# the header file derived from the class name. The default is "pics". -# -# ``INCLUDE_FILES`` specifies additional include files to include with the -# generated source file. This can be needed for custom code used in -# initializing or creating widgets. -# -# ``SOURCES`` specifies additional source files to build the plugin from. -# This can be needed to support custom code used in initializing or -# creating widgets. -# -# ``COMPONENT`` specifies the installation component name with which the install -# rules for the generated plugin are associated. -# -# :: -# -# ecm_qtdesignerplugin_widget(<widgetid> -# [CLASS_NAME <class_name>] -# [INCLUDE_FILE <include_file>] -# [CONTAINER] -# [ICON <iconfile>] -# [TOOLTIP <tooltip>] -# [WHATSTHIS <whatsthis>] -# [GROUP <group>] -# [CREATE_WIDGET_CODE_FROM_VARIABLE <create_widget_code_variable>] -# [INITIALIZE_CODE_FROM_VARIABLE <initialize_code_variable] -# [DOM_XML_FROM_VARIABLE <dom_xml_variable>] -# [IMPL_CLASS_NAME <impl_class_name>] -# [CONSTRUCTOR_ARGS_CODE <constructor_args_code>] -# [CONSTRUCTOR_ARGS_CODE_FROM_VARIABLE <constructor_args_code_variable>] -# ) -# -# ``CLASS_NAME`` specifies the name of the widget class, including namespaces. -# The default is "<widgetid>". -# -# ``INCLUDE_FILE`` specifies the include file to use for the class of this -# widget. The default is derived from <class_name> as configured by the -# ``DEFAULT_HEADER_*`` options of ``ecm_add_qtdesignerplugin``, also replacing -# any namespace separators with "/". -# -# ``CONTAINER`` specifies, if set, that this widget is a container -# for other widgets. -# -# ``ICON`` specifies the icon file to use as symbol for this widget. -# The default is "{lowercased <class_name>}.png" in the default icons dir as -# configured by the ``DEFAULT_ICON_DIR`` option of -# ``ecm_add_qtdesignerplugin``, if such a file exists. -# -# ``TOOLTIP`` specifies the tooltip text to use for this widget. Default is -# "<class_name> Widget". -# -# ``WHATSTHIS`` specifies the What's-This text to use for this widget. -# Defaults to the tooltip. -# -# ``GROUP`` specifies the group in Qt Designer where the widget will be placed. -# The default is set as configured by the ``DEFAULT_GROUP`` option of -# ``ecm_add_qtdesignerplugin``. -# -# ``CREATE_WIDGET_CODE_FROM_VARIABLE`` specifies the variable to get from the -# C++ code to use as factory code to create an instance of the widget, -# for the override of -# ``QDesignerCustomWidgetInterface::createWidget(QWidget* parent)``. -# The default is "return new <impl_class_name><constructor_args_code>;". -# -# ``INITIALIZE_CODE_FROM_VARIABLE`` specifies the variable to get from the C++ -# code to use with the override of -# ``QDesignerCustomWidgetInterface::initialize(QDesignerFormEditorInterface* core)``. -# The code has to use the present class member ``m_initialized`` to track and -# update the state. The default code simply sets ``m_initialized`` to -# ``true``, if it was not before. -# -# ``DOM_XML_FROM_VARIABLE`` specifies the variable to get from the string to -# use with the optional override of -# ``QDesignerCustomWidgetInterface::domXml()``. -# Default does not override. -# -# ``IMPL_CLASS_NAME`` specifies the name of the widget class to use for the -# widget instance with Qt Designer. The default is "<class_name>". -# -# ``CONSTRUCTOR_ARGS_CODE`` specifies the C++ code to use for the constructor -# arguments with the default of ``CREATE_WIDGET_CODE_FROM_VARIABLE``. Note -# that the parentheses are required. The default is "(parent)". -# -# ``CONSTRUCTOR_ARGS_CODE_FROM_VARIABLE`` specifies the variable to get from -# the C++ code instead of passing it directly via ``CONSTRUCTOR_ARGS_CODE``. -# This can be needed if the code is more complex and e.g. includes ";" chars. -# -# -# -# Example usage: -# -# .. code-block:: cmake -# -# ecm_qtdesignerplugin_widget(FooWidget -# TOOLTIP "Enables to browse foo." -# GROUP "Views (Foo)" -# ) -# -# set(BarWidget_CREATE_WIDGET_CODE -# " -# auto* widget = new BarWidget(parent); -# widget->setBar("Example bar"); -# return widget; -# ") -# -# ecm_qtdesignerplugin_widget(BarWidget -# TOOLTIP "Displays bars." -# GROUP "Display (Foo)" -# CREATE_WIDGET_CODE_FROM_VARIABLE BarWidget_CREATE_WIDGET_CODE -# ) -# -# ecm_add_qtdesignerplugin(foowidgets -# NAME FooWidgets -# OUTPUT_NAME foo2widgets -# WIDGETS -# FooWidget -# BarWidget -# LINK_LIBRARIES -# Foo::Widgets -# INSTALL_DESTINATION "${KDE_INSTALL_QTPLUGINDIR}/designer" -# COMPONENT Devel -# ) -# -# Since 5.62.0. - -#============================================================================= # SPDX-FileCopyrightText: 2019 Friedrich W. H. Kossebau <kossebau@kde.org> # # SPDX-License-Identifier: BSD-3-Clause +#[=======================================================================[.rst: +ECMAddQtDesignerPlugin +---------------------- + +This module provides the ``ecm_add_qtdesignerplugin`` function for generating +Qt Designer plugins for custom widgets. Each of those widgets is described +using a second function ``ecm_qtdesignerplugin_widget``. + +:: + + ecm_add_qtdesignerplugin(<target_name> + NAME <name> + WIDGETS <widgetid> [<widgetid2> [...]] + LINK_LIBRARIES <lib> [<lib2> [...]] + INSTALL_DESTINATION <install_path> + [OUTPUT_NAME <output_name>] + [DEFAULT_GROUP <group>] + [DEFAULT_HEADER_CASE <SAME_CASE|LOWER_CASE|UPPER_CASE>] + [DEFAULT_HEADER_EXTENSION <header_extension>] + [DEFAULT_ICON_DIR <icon_dir>] + [INCLUDE_FILES <include_file> [<include_file2> [...]]] + [SOURCES <src> [<src2> [...]]] + [COMPONENT <component>] + ) + +``NAME`` specifies the base name to use in the generated sources. +The default is <target_name>. + +``WIDGETS`` specifies the widgets the plugin should support. Each widget has +to be defined before by a call of ``ecm_qtdesignerplugin_widget`` with the +respective <widgetid>, in a scope including the current call. + +``LINK_LIBRARIES`` specifies the libraries to link against. This will be at +least the library providing the widget class(es). + +``INSTALL_DESTINATION`` specifies where the generated plugin binary will be +installed. + +``OUTPUT_NAME`` specifies the name of the plugin binary. The default is +"<target_name>". + +``DEFAULT_GROUP`` specifies the default group in Qt Designer where the +widgets will be placed. The default is "Custom". + +``DEFAULT_HEADER_CASE`` specifies how the name of the header is derived from +the widget class name. The default is "LOWER_CASE". + +``DEFAULT_HEADER_EXTENSION`` specifies what file name extension is used for +the header file derived from the class name. The default is "h". + +``DEFAULT_ICON_DIR`` specifies what file name extension is used for +the header file derived from the class name. The default is "pics". + +``INCLUDE_FILES`` specifies additional include files to include with the +generated source file. This can be needed for custom code used in +initializing or creating widgets. + +``SOURCES`` specifies additional source files to build the plugin from. +This can be needed to support custom code used in initializing or +creating widgets. + +``COMPONENT`` specifies the installation component name with which the install +rules for the generated plugin are associated. + +:: + + ecm_qtdesignerplugin_widget(<widgetid> + [CLASS_NAME <class_name>] + [INCLUDE_FILE <include_file>] + [CONTAINER] + [ICON <iconfile>] + [TOOLTIP <tooltip>] + [WHATSTHIS <whatsthis>] + [GROUP <group>] + [CREATE_WIDGET_CODE_FROM_VARIABLE <create_widget_code_variable>] + [INITIALIZE_CODE_FROM_VARIABLE <initialize_code_variable] + [DOM_XML_FROM_VARIABLE <dom_xml_variable>] + [IMPL_CLASS_NAME <impl_class_name>] + [CONSTRUCTOR_ARGS_CODE <constructor_args_code>] + [CONSTRUCTOR_ARGS_CODE_FROM_VARIABLE <constructor_args_code_variable>] + ) + +``CLASS_NAME`` specifies the name of the widget class, including namespaces. +The default is "<widgetid>". + +``INCLUDE_FILE`` specifies the include file to use for the class of this +widget. The default is derived from <class_name> as configured by the +``DEFAULT_HEADER_*`` options of ``ecm_add_qtdesignerplugin``, also replacing +any namespace separators with "/". + +``CONTAINER`` specifies, if set, that this widget is a container +for other widgets. + +``ICON`` specifies the icon file to use as symbol for this widget. +The default is "{lowercased <class_name>}.png" in the default icons dir as +configured by the ``DEFAULT_ICON_DIR`` option of +``ecm_add_qtdesignerplugin``, if such a file exists. + +``TOOLTIP`` specifies the tooltip text to use for this widget. Default is +"<class_name> Widget". + +``WHATSTHIS`` specifies the What's-This text to use for this widget. +Defaults to the tooltip. + +``GROUP`` specifies the group in Qt Designer where the widget will be placed. +The default is set as configured by the ``DEFAULT_GROUP`` option of +``ecm_add_qtdesignerplugin``. + +``CREATE_WIDGET_CODE_FROM_VARIABLE`` specifies the variable to get from the +C++ code to use as factory code to create an instance of the widget, +for the override of +``QDesignerCustomWidgetInterface::createWidget(QWidget* parent)``. +The default is "return new <impl_class_name><constructor_args_code>;". + +``INITIALIZE_CODE_FROM_VARIABLE`` specifies the variable to get from the C++ +code to use with the override of +``QDesignerCustomWidgetInterface::initialize(QDesignerFormEditorInterface* core)``. +The code has to use the present class member ``m_initialized`` to track and +update the state. The default code simply sets ``m_initialized`` to +``true``, if it was not before. + +``DOM_XML_FROM_VARIABLE`` specifies the variable to get from the string to +use with the optional override of +``QDesignerCustomWidgetInterface::domXml()``. +Default does not override. + +``IMPL_CLASS_NAME`` specifies the name of the widget class to use for the +widget instance with Qt Designer. The default is "<class_name>". + +``CONSTRUCTOR_ARGS_CODE`` specifies the C++ code to use for the constructor +arguments with the default of ``CREATE_WIDGET_CODE_FROM_VARIABLE``. Note +that the parentheses are required. The default is "(parent)". + +``CONSTRUCTOR_ARGS_CODE_FROM_VARIABLE`` specifies the variable to get from +the C++ code instead of passing it directly via ``CONSTRUCTOR_ARGS_CODE``. +This can be needed if the code is more complex and e.g. includes ";" chars. + + + +Example usage: + +.. code-block:: cmake + + ecm_qtdesignerplugin_widget(FooWidget + TOOLTIP "Enables to browse foo." + GROUP "Views (Foo)" + ) + + set(BarWidget_CREATE_WIDGET_CODE + " + auto* widget = new BarWidget(parent); + widget->setBar("Example bar"); + return widget; + ") + + ecm_qtdesignerplugin_widget(BarWidget + TOOLTIP "Displays bars." + GROUP "Display (Foo)" + CREATE_WIDGET_CODE_FROM_VARIABLE BarWidget_CREATE_WIDGET_CODE + ) + + ecm_add_qtdesignerplugin(foowidgets + NAME FooWidgets + OUTPUT_NAME foo2widgets + WIDGETS + FooWidget + BarWidget + LINK_LIBRARIES + Foo::Widgets + INSTALL_DESTINATION "${KDE_INSTALL_QTPLUGINDIR}/designer" + COMPONENT Devel + ) + +Since 5.62.0. +#]=======================================================================] + include(CMakeParseArguments) # helper method diff --git a/modules/ECMAddTests.cmake b/modules/ECMAddTests.cmake index 7e518212..de965f06 100644 --- a/modules/ECMAddTests.cmake +++ b/modules/ECMAddTests.cmake @@ -1,63 +1,63 @@ -#.rst: -# ECMAddTests -# ----------- -# -# Convenience functions for adding tests. -# -# :: -# -# ecm_add_tests(<sources> LINK_LIBRARIES <library> [<library> [...]] -# [NAME_PREFIX <prefix>] -# [GUI] -# [TARGET_NAMES_VAR <target_names_var>] -# [TEST_NAMES_VAR <test_names_var>]) -# -# A convenience function for adding multiple tests, each consisting of a -# single source file. For each file in <sources>, an executable target will be -# created (the name of which will be the basename of the source file). This -# will be linked against the libraries given with LINK_LIBRARIES. Each -# executable will be added as a test with the same name. -# -# If NAME_PREFIX is given, this prefix will be prepended to the test names, but -# not the target names. As a result, it will not prevent clashes between tests -# with the same name in different parts of the project, but it can be used to -# give an indication of where to look for a failing test. -# -# If the flag GUI is passed the test binaries will be GUI executables, otherwise -# the resulting binaries will be console applications (regardless of the value -# of CMAKE_WIN32_EXECUTABLE or CMAKE_MACOSX_BUNDLE). Be aware that this changes -# the executable entry point on Windows (although some frameworks, such as Qt, -# abstract this difference away). -# -# The TARGET_NAMES_VAR and TEST_NAMES_VAR arguments, if given, should specify a -# variable name to receive the list of generated target and test names, -# respectively. This makes it convenient to apply properties to them as a -# whole, for example, using set_target_properties() or set_tests_properties(). -# -# The generated target executables will have the effects of ecm_mark_as_test() -# (from the :module:`ECMMarkAsTest` module) applied to it. -# -# :: -# -# ecm_add_test(<sources> LINK_LIBRARIES <library> [<library> [...]] -# [TEST_NAME <name>] -# [NAME_PREFIX <prefix>] -# [GUI]) -# -# This is a single-test form of ecm_add_tests that allows multiple source files -# to be used for a single test. If using multiple source files, TEST_NAME must -# be given; this will be used for both the target and test names (and, as with -# ecm_add_tests(), the NAME_PREFIX argument will be prepended to the test name). -# -# -# Since pre-1.0.0. - -#============================================================================= # SPDX-FileCopyrightText: 2013 Alexander Richardson <arichardson.kde@gmail.com> # SPDX-FileCopyrightText: 2015 Alex Merry <alex.merry@kde.org> # # SPDX-License-Identifier: BSD-3-Clause +#[=======================================================================[.rst: +ECMAddTests +----------- + +Convenience functions for adding tests. + +:: + + ecm_add_tests(<sources> LINK_LIBRARIES <library> [<library> [...]] + [NAME_PREFIX <prefix>] + [GUI] + [TARGET_NAMES_VAR <target_names_var>] + [TEST_NAMES_VAR <test_names_var>]) + +A convenience function for adding multiple tests, each consisting of a +single source file. For each file in <sources>, an executable target will be +created (the name of which will be the basename of the source file). This +will be linked against the libraries given with LINK_LIBRARIES. Each +executable will be added as a test with the same name. + +If NAME_PREFIX is given, this prefix will be prepended to the test names, but +not the target names. As a result, it will not prevent clashes between tests +with the same name in different parts of the project, but it can be used to +give an indication of where to look for a failing test. + +If the flag GUI is passed the test binaries will be GUI executables, otherwise +the resulting binaries will be console applications (regardless of the value +of CMAKE_WIN32_EXECUTABLE or CMAKE_MACOSX_BUNDLE). Be aware that this changes +the executable entry point on Windows (although some frameworks, such as Qt, +abstract this difference away). + +The TARGET_NAMES_VAR and TEST_NAMES_VAR arguments, if given, should specify a +variable name to receive the list of generated target and test names, +respectively. This makes it convenient to apply properties to them as a +whole, for example, using set_target_properties() or set_tests_properties(). + +The generated target executables will have the effects of ecm_mark_as_test() +(from the :module:`ECMMarkAsTest` module) applied to it. + +:: + + ecm_add_test(<sources> LINK_LIBRARIES <library> [<library> [...]] + [TEST_NAME <name>] + [NAME_PREFIX <prefix>] + [GUI]) + +This is a single-test form of ecm_add_tests that allows multiple source files +to be used for a single test. If using multiple source files, TEST_NAME must +be given; this will be used for both the target and test names (and, as with +ecm_add_tests(), the NAME_PREFIX argument will be prepended to the test name). + + +Since pre-1.0.0. +#]=======================================================================] + include(CMakeParseArguments) include(ECMMarkAsTest) include(ECMMarkNonGuiExecutable) diff --git a/modules/ECMCheckOutboundLicense.cmake b/modules/ECMCheckOutboundLicense.cmake index c49a190d..62a6d1e2 100644 --- a/modules/ECMCheckOutboundLicense.cmake +++ b/modules/ECMCheckOutboundLicense.cmake @@ -1,70 +1,71 @@ -#.rst: -# ECMCheckOutboundLicense -# ----------------------- -# -# Assert that source file licenses are compatible with a desired outbound license -# of a compiled binary artifact (e.g., library, plugin or application). -# -# This module provides the ``ecm_check_outbound_license`` function that -# generates unit tests for checking the compatibility of license statements. -# The license statements in all tested files are required to be added by using -# the SPDX marker ``SPDX-License-Identifier``. -# -# During the CMake configuration of the project, a temporary license bill of -# materials (BOM) in SPDX format is generated by calling the REUSE tool -# (see <https://reuse.software>). That BOM is parsed and license computations -# based on an internal compatibility matrix are performed. -# -# Preconditions for using this module: -# * All tested input source files must contain the SPDX-License-Identifier tag. -# * Python3 must be available. -# * The REUSE tool must be available, which generates the bill-of-materials -# by running ``reuse spdx`` on the tested directory. -# -# When this module is included, a ``SKIP_LICENSE_TESTS`` option is added (default -# OFF). Turning this option on skips the generation of license tests, which might -# be convenient if licenses shall not be tested in all build configurations. -# -# :: -# -# ecm_check_outbound_license(LICENSES <outbound-licenses> -# FILES <source-files> -# [TEST_NAME <name>] -# [WILL_FAIL]) -# -# This method adds a custom unit test to ensure the specified outbound license to be -# compatible with the specified license headers. Note that a convenient way is to use -# the CMake GLOB command of the FILE function. -# -# ``LICENSES`` : List of one or multiple outbound license regarding which the compatibility -# of the source code files shall be tested. Currently, the following values -# are supported (values are SPDX registry identifiers): -# * MIT -# * BSD-2-Clause -# * BSD-3-Clause -# * LGPL-2.0-only -# * LGPL-2.1-only -# * LGPL-3.0-only -# * GPL-2.0-only -# * GPL-3.0-only -# -# ``FILES:`` : List of source files that contain valid SPDX-License-Identifier markers. -# The paths can be relative to the CMake file that generates the test case -# or be absolute paths. -# -# ``TEST_NAME`` : Optional parameter that defines the name of the generated test case. -# If no name is defined, the relative path to the test directory with appended -# license name is used. Every test has ``licensecheck_`` as prefix. -# -# ``WILL_FAIL`` : Optional parameter that inverts the test result. This parameter is usually only -# used for tests of the module. -# -# Since 5.75.0 - -#============================================================================= # SPDX-FileCopyrightText: 2020 Andreas Cord-Landwehr <cordlandwehr@kde.org> +# # SPDX-License-Identifier: BSD-3-Clause +#[=======================================================================[.rst: +ECMCheckOutboundLicense +----------------------- + +Assert that source file licenses are compatible with a desired outbound license +of a compiled binary artifact (e.g., library, plugin or application). + +This module provides the ``ecm_check_outbound_license`` function that +generates unit tests for checking the compatibility of license statements. +The license statements in all tested files are required to be added by using +the SPDX marker ``SPDX-License-Identifier``. + +During the CMake configuration of the project, a temporary license bill of +materials (BOM) in SPDX format is generated by calling the REUSE tool +(see <https://reuse.software>). That BOM is parsed and license computations +based on an internal compatibility matrix are performed. + +Preconditions for using this module: + * All tested input source files must contain the SPDX-License-Identifier tag. + * Python3 must be available. + * The REUSE tool must be available, which generates the bill-of-materials + by running ``reuse spdx`` on the tested directory. + +When this module is included, a ``SKIP_LICENSE_TESTS`` option is added (default +OFF). Turning this option on skips the generation of license tests, which might +be convenient if licenses shall not be tested in all build configurations. + +:: + + ecm_check_outbound_license(LICENSES <outbound-licenses> + FILES <source-files> + [TEST_NAME <name>] + [WILL_FAIL]) + +This method adds a custom unit test to ensure the specified outbound license to be +compatible with the specified license headers. Note that a convenient way is to use +the CMake GLOB command of the FILE function. + +``LICENSES`` : List of one or multiple outbound license regarding which the compatibility + of the source code files shall be tested. Currently, the following values + are supported (values are SPDX registry identifiers): + * MIT + * BSD-2-Clause + * BSD-3-Clause + * LGPL-2.0-only + * LGPL-2.1-only + * LGPL-3.0-only + * GPL-2.0-only + * GPL-3.0-only + +``FILES:`` : List of source files that contain valid SPDX-License-Identifier markers. + The paths can be relative to the CMake file that generates the test case + or be absolute paths. + +``TEST_NAME`` : Optional parameter that defines the name of the generated test case. + If no name is defined, the relative path to the test directory with appended + license name is used. Every test has ``licensecheck_`` as prefix. + +``WILL_FAIL`` : Optional parameter that inverts the test result. This parameter is usually only + used for tests of the module. + +Since 5.75.0 +#]=======================================================================] + include(FeatureSummary) option(SKIP_LICENSE_TESTS "Skip outbound license tests" OFF) diff --git a/modules/ECMConfiguredInstall.cmake b/modules/ECMConfiguredInstall.cmake index b2d8374b..e3e77312 100644 --- a/modules/ECMConfiguredInstall.cmake +++ b/modules/ECMConfiguredInstall.cmake @@ -1,37 +1,35 @@ -#.rst: -# ECMConfiguredInstall -# -------------------- -# -# Takes a list of files, runs configure_file on each and installs the resultant configured files in the given location. -# -# Any suffix of ".in" in the passed file names wil be stripped from the file name at the installed location. -# -# :: -# -# ecm_install_configured_files( -# INPUT <file> [<file2> [...]] -# DESTINATION <INSTALL_DIRECTORY> -# [COPYONLY] -# [ESCAPE_QUOTES] -# [@ONLY] -# [COMPONENT <component>]) -# -# Example usage: -# -# .. code-block:: cmake -# -# ecm_install_configured_files(INPUT foo.txt.in DESTINATION ${KDE_INSTALL_DATADIR} @ONLY) -# -# This wil install the file as foo.txt with any cmake variable replacements made into the data directory. -# -# Since 5.73.0. - -#============================================================================= # SPDX-FileCopyrightText: 2020 David Edmundson <davidedmundson@kde.org> # # SPDX-License-Identifier: BSD-3-Clause -#============================================================================= +#[=======================================================================[.rst: +ECMConfiguredInstall +-------------------- + +Takes a list of files, runs configure_file on each and installs the resultant configured files in the given location. + +Any suffix of ".in" in the passed file names wil be stripped from the file name at the installed location. + +:: + + ecm_install_configured_files( + INPUT <file> [<file2> [...]] + DESTINATION <INSTALL_DIRECTORY> + [COPYONLY] + [ESCAPE_QUOTES] + [@ONLY] + [COMPONENT <component>]) + +Example usage: + +.. code-block:: cmake + + ecm_install_configured_files(INPUT foo.txt.in DESTINATION ${KDE_INSTALL_DATADIR} @ONLY) + +This will install the file as foo.txt with any cmake variable replacements made into the data directory. + +Since 5.73.0. +#]=======================================================================] function(ecm_install_configured_files) set(options COPYONLY ESCAPE_QUOTES @ONLY) diff --git a/modules/ECMCoverageOption.cmake b/modules/ECMCoverageOption.cmake index 16ecc2a5..7a96280e 100644 --- a/modules/ECMCoverageOption.cmake +++ b/modules/ECMCoverageOption.cmake @@ -1,26 +1,26 @@ -#.rst: -# ECMCoverageOption -# -------------------- -# -# Allow users to easily enable GCov code coverage support. -# -# Code coverage allows you to check how much of your codebase is covered by -# your tests. This module makes it easy to build with support for -# `GCov <https://gcc.gnu.org/onlinedocs/gcc/Gcov.html>`_. -# -# When this module is included, a ``BUILD_COVERAGE`` option is added (default -# OFF). Turning this option on enables GCC's coverage instrumentation, and -# links against ``libgcov``. -# -# Note that this will probably break the build if you are not using GCC. -# -# Since 1.3.0. - -#============================================================================= # SPDX-FileCopyrightText: 2014 Aleix Pol Gonzalez <aleixpol@kde.org> # # SPDX-License-Identifier: BSD-3-Clause +#[=======================================================================[.rst: +ECMCoverageOption +-------------------- + +Allow users to easily enable GCov code coverage support. + +Code coverage allows you to check how much of your codebase is covered by +your tests. This module makes it easy to build with support for +`GCov <https://gcc.gnu.org/onlinedocs/gcc/Gcov.html>`_. + +When this module is included, a ``BUILD_COVERAGE`` option is added (default +OFF). Turning this option on enables GCC's coverage instrumentation, and +links against ``libgcov``. + +Note that this will probably break the build if you are not using GCC. + +Since 1.3.0. +#]=======================================================================] + option(BUILD_COVERAGE "Build the project with gcov support" OFF) if(BUILD_COVERAGE) diff --git a/modules/ECMCreateQmFromPoFiles.cmake b/modules/ECMCreateQmFromPoFiles.cmake index 1d9bcb2e..c02ba2c7 100644 --- a/modules/ECMCreateQmFromPoFiles.cmake +++ b/modules/ECMCreateQmFromPoFiles.cmake @@ -1,81 +1,81 @@ -#.rst: -# ECMCreateQmFromPoFiles -# ---------------------- -# -# .. warning:: This module is deprecated and will be removed by ECM 1.0. Use -# ECMPoQmTools instead. -# -# Generate QTranslator (.qm) catalogs from Gettext (.po) catalogs. -# -# :: -# -# ecm_create_qm_from_po_files(PO_FILES <file1>... <fileN> -# [CATALOG_NAME <catalog_name>] -# [INSTALL_DESTINATION <install_destination>]) -# -# Creates the necessary rules to compile .po files into .qm files, and install -# them. -# -# The .qm files are installed in ``<install_destination>/<lang>/LC_MESSAGES``, -# where <install_destination> is the INSTALL_DESTINATION argument and <lang> is -# extracted from the "Language" field inside the .po file. -# -# INSTALL_DESTINATION defaults to ``${LOCALE_INSTALL_DIR}`` if defined, -# otherwise it uses ``${CMAKE_INSTALL_LOCALEDIR}`` if that is defined, otherwise -# it uses ``share/locale``. -# -# CATALOG_NAME defines the name of the installed .qm files. If set, .qm files -# will be installed as ``<catalog_name>.qm``. If not set .qm files will be named -# after the name of their source .po file. -# -# Setting the catalog name is useful when all .po files for a target are kept -# in a single source directory. For example, the "mylib" probject might keep all -# its translations in a "po" directory, like this:: -# -# po/ -# es.po -# fr.po -# -# Without setting CATALOG_NAME, those .po will be turned into .qm and installed -# as:: -# -# share/locale/fr/LC_MESSAGES/fr.qm -# share/locale/es/LC_MESSAGES/es.qm -# -# If CATALOG_NAME is set to "mylib", they will be installed as:: -# -# share/locale/fr/LC_MESSAGES/mylib.qm -# share/locale/es/LC_MESSAGES/mylib.qm -# -# Which is what the loader created by ecm_create_qm_loader() expects. -# -# ecm_create_qm_from_po_files() creates a "translation" target. This target -# builds all .po files into .qm files. -# -# :: -# -# ecm_create_qm_loader(<source_files_var> <catalog_name>) -# -# ecm_create_qm_loader() generates a C++ file which ensures translations are -# automatically loaded at startup. The path of the .cpp file is appended to -# <source_files_var>. Typical usage is like: -# -# .. code-block:: cmake -# -# set(mylib_SRCS foo.cpp bar.cpp) -# ecm_create_qm_loader(mylib_SRCS mylib) -# add_library(mylib ${mylib_SRCS}) -# -# This generates a C++ file which loads "mylib.qm" at startup, assuming it has -# been installed by ecm_create_qm_from_po_files(), and compiles it into ``mylib``. -# -# Since pre-1.0.0. - -#============================================================================= # SPDX-FileCopyrightText: 2014 Aurélien Gâteau <agateau@kde.org> # # SPDX-License-Identifier: BSD-3-Clause +#[=======================================================================[.rst: +ECMCreateQmFromPoFiles +---------------------- + +.. warning:: This module is deprecated and will be removed by ECM 1.0. Use + ECMPoQmTools instead. + +Generate QTranslator (.qm) catalogs from Gettext (.po) catalogs. + +:: + + ecm_create_qm_from_po_files(PO_FILES <file1>... <fileN> + [CATALOG_NAME <catalog_name>] + [INSTALL_DESTINATION <install_destination>]) + +Creates the necessary rules to compile .po files into .qm files, and install +them. + +The .qm files are installed in ``<install_destination>/<lang>/LC_MESSAGES``, +where <install_destination> is the INSTALL_DESTINATION argument and <lang> is +extracted from the "Language" field inside the .po file. + +INSTALL_DESTINATION defaults to ``${LOCALE_INSTALL_DIR}`` if defined, +otherwise it uses ``${CMAKE_INSTALL_LOCALEDIR}`` if that is defined, otherwise +it uses ``share/locale``. + +CATALOG_NAME defines the name of the installed .qm files. If set, .qm files +will be installed as ``<catalog_name>.qm``. If not set .qm files will be named +after the name of their source .po file. + +Setting the catalog name is useful when all .po files for a target are kept +in a single source directory. For example, the "mylib" probject might keep all +its translations in a "po" directory, like this:: + + po/ + es.po + fr.po + +Without setting CATALOG_NAME, those .po will be turned into .qm and installed +as:: + + share/locale/fr/LC_MESSAGES/fr.qm + share/locale/es/LC_MESSAGES/es.qm + +If CATALOG_NAME is set to "mylib", they will be installed as:: + + share/locale/fr/LC_MESSAGES/mylib.qm + share/locale/es/LC_MESSAGES/mylib.qm + +Which is what the loader created by ecm_create_qm_loader() expects. + +ecm_create_qm_from_po_files() creates a "translation" target. This target +builds all .po files into .qm files. + +:: + + ecm_create_qm_loader(<source_files_var> <catalog_name>) + +ecm_create_qm_loader() generates a C++ file which ensures translations are +automatically loaded at startup. The path of the .cpp file is appended to +<source_files_var>. Typical usage is like: + +.. code-block:: cmake + + set(mylib_SRCS foo.cpp bar.cpp) + ecm_create_qm_loader(mylib_SRCS mylib) + add_library(mylib ${mylib_SRCS}) + +This generates a C++ file which loads "mylib.qm" at startup, assuming it has +been installed by ecm_create_qm_from_po_files(), and compiles it into ``mylib``. + +Since pre-1.0.0. +#]=======================================================================] + message(AUTHOR_WARNING "ECMCreateQmFromPoFiles is deprecated and will be removed before the release of Extra CMake Modules 1.0. Use ECMPoQmTools instead.") # Stolen from FindGettext.cmake diff --git a/modules/ECMEnableSanitizers.cmake b/modules/ECMEnableSanitizers.cmake index e04c8311..db368863 100644 --- a/modules/ECMEnableSanitizers.cmake +++ b/modules/ECMEnableSanitizers.cmake @@ -1,79 +1,79 @@ -#.rst: -# ECMEnableSanitizers -# ------------------- -# -# Enable compiler sanitizer flags. -# -# The following sanitizers are supported: -# -# - Address Sanitizer -# - Memory Sanitizer -# - Thread Sanitizer -# - Leak Sanitizer -# - Undefined Behaviour Sanitizer -# -# All of them are implemented in Clang, depending on your version, and -# there is an work in progress in GCC, where some of them are currently -# implemented. -# -# This module will check your current compiler version to see if it -# supports the sanitizers that you want to enable -# -# Usage -# ===== -# -# Simply add:: -# -# include(ECMEnableSanitizers) -# -# to your ``CMakeLists.txt``. Note that this module is included in -# KDECompilerSettings, so projects using that module do not need to also -# include this one. -# -# The sanitizers are not enabled by default. Instead, you must set -# ``ECM_ENABLE_SANITIZERS`` (either in your ``CMakeLists.txt`` or on the -# command line) to a semicolon-separated list of sanitizers you wish to enable. -# The options are: -# -# - address -# - memory -# - thread -# - leak -# - undefined -# - fuzzer -# -# The sanitizers "address", "memory" and "thread" are mutually exclusive. You -# cannot enable two of them in the same build. -# -# "leak" requires the "address" sanitizer. -# -# .. note:: -# -# To reduce the overhead induced by the instrumentation of the sanitizers, it -# is advised to enable compiler optimizations (``-O1`` or higher). -# -# Example -# ======= -# -# This is an example of usage:: -# -# mkdir build -# cd build -# cmake -DECM_ENABLE_SANITIZERS='address;leak;undefined' .. -# -# .. note:: -# -# Most of the sanitizers will require Clang. To enable it, use:: -# -# -DCMAKE_CXX_COMPILER=clang++ -# -# Since 1.3.0. - -#============================================================================= # SPDX-FileCopyrightText: 2014 Mathieu Tarral <mathieu.tarral@gmail.com> # # SPDX-License-Identifier: BSD-3-Clause +#[=======================================================================[.rst: +ECMEnableSanitizers +------------------- + +Enable compiler sanitizer flags. + +The following sanitizers are supported: + +- Address Sanitizer +- Memory Sanitizer +- Thread Sanitizer +- Leak Sanitizer +- Undefined Behaviour Sanitizer + +All of them are implemented in Clang, depending on your version, and +there is an work in progress in GCC, where some of them are currently +implemented. + +This module will check your current compiler version to see if it +supports the sanitizers that you want to enable + +Usage +===== + +Simply add:: + + include(ECMEnableSanitizers) + +to your ``CMakeLists.txt``. Note that this module is included in +KDECompilerSettings, so projects using that module do not need to also +include this one. + +The sanitizers are not enabled by default. Instead, you must set +``ECM_ENABLE_SANITIZERS`` (either in your ``CMakeLists.txt`` or on the +command line) to a semicolon-separated list of sanitizers you wish to enable. +The options are: + +- address +- memory +- thread +- leak +- undefined +- fuzzer + +The sanitizers "address", "memory" and "thread" are mutually exclusive. You +cannot enable two of them in the same build. + +"leak" requires the "address" sanitizer. + +.. note:: + + To reduce the overhead induced by the instrumentation of the sanitizers, it + is advised to enable compiler optimizations (``-O1`` or higher). + +Example +======= + +This is an example of usage:: + + mkdir build + cd build + cmake -DECM_ENABLE_SANITIZERS='address;leak;undefined' .. + +.. note:: + + Most of the sanitizers will require Clang. To enable it, use:: + + -DCMAKE_CXX_COMPILER=clang++ + +Since 1.3.0. +#]=======================================================================] + # MACRO check_compiler_version #----------------------------- macro (check_compiler_version gcc_required_version clang_required_version) diff --git a/modules/ECMFindModuleHelpers.cmake b/modules/ECMFindModuleHelpers.cmake index 5e16b949..41b4b5e6 100644 --- a/modules/ECMFindModuleHelpers.cmake +++ b/modules/ECMFindModuleHelpers.cmake @@ -1,107 +1,107 @@ -#.rst: -# ECMFindModuleHelpers -# -------------------- -# -# Helper macros for find modules: ecm_find_package_version_check(), -# ecm_find_package_parse_components() and -# ecm_find_package_handle_library_components(). -# -# :: -# -# ecm_find_package_version_check(<name>) -# -# Prints warnings if the CMake version or the project's required CMake version -# is older than that required by extra-cmake-modules. -# -# :: -# -# ecm_find_package_parse_components(<name> -# RESULT_VAR <variable> -# KNOWN_COMPONENTS <component1> [<component2> [...]] -# [SKIP_DEPENDENCY_HANDLING]) -# -# This macro will populate <variable> with a list of components found in -# <name>_FIND_COMPONENTS, after checking that all those components are in the -# list of KNOWN_COMPONENTS; if there are any unknown components, it will print -# an error or warning (depending on the value of <name>_FIND_REQUIRED) and call -# return(). -# -# The order of components in <variable> is guaranteed to match the order they -# are listed in the KNOWN_COMPONENTS argument. -# -# If SKIP_DEPENDENCY_HANDLING is not set, for each component the variable -# <name>_<component>_component_deps will be checked for dependent components. -# If <component> is listed in <name>_FIND_COMPONENTS, then all its (transitive) -# dependencies will also be added to <variable>. -# -# :: -# -# ecm_find_package_handle_library_components(<name> -# COMPONENTS <component> [<component> [...]] -# [SKIP_DEPENDENCY_HANDLING]) -# [SKIP_PKG_CONFIG]) -# -# Creates an imported library target for each component. The operation of this -# macro depends on the presence of a number of CMake variables. -# -# The <name>_<component>_lib variable should contain the name of this library, -# and <name>_<component>_header variable should contain the name of a header -# file associated with it (whatever relative path is normally passed to -# '#include'). <name>_<component>_header_subdir variable can be used to specify -# which subdirectory of the include path the headers will be found in. -# ecm_find_package_components() will then search for the library -# and include directory (creating appropriate cache variables) and create an -# imported library target named <name>::<component>. -# -# Additional variables can be used to provide additional information: -# -# If SKIP_PKG_CONFIG, the <name>_<component>_pkg_config variable is set, and -# pkg-config is found, the pkg-config module given by -# <name>_<component>_pkg_config will be searched for and used to help locate the -# library and header file. It will also be used to set -# <name>_<component>_VERSION. -# -# Note that if version information is found via pkg-config, -# <name>_<component>_FIND_VERSION can be set to require a particular version -# for each component. -# -# If SKIP_DEPENDENCY_HANDLING is not set, the INTERFACE_LINK_LIBRARIES property -# of the imported target for <component> will be set to contain the imported -# targets for the components listed in <name>_<component>_component_deps. -# <component>_FOUND will also be set to false if any of the compoments in -# <name>_<component>_component_deps are not found. This requires the components -# in <name>_<component>_component_deps to be listed before <component> in the -# COMPONENTS argument. -# -# The following variables will be set: -# -# ``<name>_TARGETS`` -# the imported targets -# ``<name>_LIBRARIES`` -# the found libraries -# ``<name>_INCLUDE_DIRS`` -# the combined required include directories for the components -# ``<name>_DEFINITIONS`` -# the "other" CFLAGS provided by pkg-config, if any -# ``<name>_VERSION`` -# the value of ``<name>_<component>_VERSION`` for the first component that -# has this variable set (note that components are searched for in the order -# they are passed to the macro), although if it is already set, it will not -# be altered -# -# Note that these variables are never cleared, so if -# ecm_find_package_handle_library_components() is called multiple times with -# different components (typically because of multiple find_package() calls) then -# ``<name>_TARGETS``, for example, will contain all the targets found in any -# call (although no duplicates). -# -# Since pre-1.0.0. - -#============================================================================= # SPDX-FileCopyrightText: 2014 Alex Merry <alex.merry@kde.org> # # SPDX-License-Identifier: BSD-3-Clause +#[=======================================================================[.rst: +ECMFindModuleHelpers +-------------------- + +Helper macros for find modules: ecm_find_package_version_check(), +ecm_find_package_parse_components() and +ecm_find_package_handle_library_components(). + +:: + + ecm_find_package_version_check(<name>) + +Prints warnings if the CMake version or the project's required CMake version +is older than that required by extra-cmake-modules. + +:: + + ecm_find_package_parse_components(<name> + RESULT_VAR <variable> + KNOWN_COMPONENTS <component1> [<component2> [...]] + [SKIP_DEPENDENCY_HANDLING]) + +This macro will populate <variable> with a list of components found in +<name>_FIND_COMPONENTS, after checking that all those components are in the +list of KNOWN_COMPONENTS; if there are any unknown components, it will print +an error or warning (depending on the value of <name>_FIND_REQUIRED) and call +return(). + +The order of components in <variable> is guaranteed to match the order they +are listed in the KNOWN_COMPONENTS argument. + +If SKIP_DEPENDENCY_HANDLING is not set, for each component the variable +<name>_<component>_component_deps will be checked for dependent components. +If <component> is listed in <name>_FIND_COMPONENTS, then all its (transitive) +dependencies will also be added to <variable>. + +:: + + ecm_find_package_handle_library_components(<name> + COMPONENTS <component> [<component> [...]] + [SKIP_DEPENDENCY_HANDLING]) + [SKIP_PKG_CONFIG]) + +Creates an imported library target for each component. The operation of this +macro depends on the presence of a number of CMake variables. + +The <name>_<component>_lib variable should contain the name of this library, +and <name>_<component>_header variable should contain the name of a header +file associated with it (whatever relative path is normally passed to +'#include'). <name>_<component>_header_subdir variable can be used to specify +which subdirectory of the include path the headers will be found in. +ecm_find_package_components() will then search for the library +and include directory (creating appropriate cache variables) and create an +imported library target named <name>::<component>. + +Additional variables can be used to provide additional information: + +If SKIP_PKG_CONFIG, the <name>_<component>_pkg_config variable is set, and +pkg-config is found, the pkg-config module given by +<name>_<component>_pkg_config will be searched for and used to help locate the +library and header file. It will also be used to set +<name>_<component>_VERSION. + +Note that if version information is found via pkg-config, +<name>_<component>_FIND_VERSION can be set to require a particular version +for each component. + +If SKIP_DEPENDENCY_HANDLING is not set, the INTERFACE_LINK_LIBRARIES property +of the imported target for <component> will be set to contain the imported +targets for the components listed in <name>_<component>_component_deps. +<component>_FOUND will also be set to false if any of the compoments in +<name>_<component>_component_deps are not found. This requires the components +in <name>_<component>_component_deps to be listed before <component> in the +COMPONENTS argument. + +The following variables will be set: + +``<name>_TARGETS`` + the imported targets +``<name>_LIBRARIES`` + the found libraries +``<name>_INCLUDE_DIRS`` + the combined required include directories for the components +``<name>_DEFINITIONS`` + the "other" CFLAGS provided by pkg-config, if any +``<name>_VERSION`` + the value of ``<name>_<component>_VERSION`` for the first component that + has this variable set (note that components are searched for in the order + they are passed to the macro), although if it is already set, it will not + be altered + +Note that these variables are never cleared, so if +ecm_find_package_handle_library_components() is called multiple times with +different components (typically because of multiple find_package() calls) then +``<name>_TARGETS``, for example, will contain all the targets found in any +call (although no duplicates). + +Since pre-1.0.0. +#]=======================================================================] + include(CMakeParseArguments) macro(ecm_find_package_version_check module_name) diff --git a/modules/ECMGenerateDBusServiceFile.cmake b/modules/ECMGenerateDBusServiceFile.cmake index 12c37c7b..0b76b5f8 100644 --- a/modules/ECMGenerateDBusServiceFile.cmake +++ b/modules/ECMGenerateDBusServiceFile.cmake @@ -1,60 +1,60 @@ -#.rst: -# ECMGenerateDBusServiceFile -# --------------------------- -# -# This module provides the ``ecm_generate_dbus_service_file`` function for -# generating and installing a D-Bus service file. -# -# :: -# -# ecm_generate_dbus_service_file( -# NAME <service name> -# EXECUTABLE <executable> -# [SYSTEMD_SERVICE <systemd service>] -# DESTINATION <install_path> -# [RENAME <dbus service filename>] # Since 5.75 -# ) -# -# A D-Bus service file ``<service name>.service`` will be generated and installed -# in the relevant D-Bus config location. This filename can be customized with RENAME. -# -# ``<executable>`` must be an absolute path to the installed service executable. When using it with -# ``KDEInstallDirs`` it needs to be the ``_FULL_`` variant of the path variable. -# -# Note: On Windows, the macro will only use the file name part of ``<executable>`` since D-Bus -# service executables are to be installed in the same directory as the D-Bus daemon. -# -# Optionally, a ``<systemd service>`` can be specified to launch the corresponding -# systemd service instead of the ``<executable>`` if the D-Bus daemon is started by systemd. -# -# Example usage: -# -# .. code-block:: cmake -# -# ecm_generate_dbus_service_file( -# NAME org.kde.kded5 -# EXECUTABLE ${KDE_INSTALL_FULL_BINDIR}/kded5 -# DESTINATION ${KDE_INSTALL_DBUSSERVICEDIR} -# ) -# -# .. code-block:: cmake -# -# ecm_generate_dbus_service_file( -# NAME org.kde.kded5 -# EXECUTABLE ${KDE_INSTALL_FULL_BINDIR}/kded5 -# SYSTEMD_SERVICE plasma-kded.service -# DESTINATION ${KDE_INSTALL_DBUSSERVICEDIR} -# RENAME org.kde.daemon.service -# ) -# -# Since 5.73.0. - -#============================================================================= # SPDX-FileCopyrightText: 2020 Kai Uwe Broulik <kde@broulik.de> # SPDX-FileCopyrightText: 2020 Henri Chain <henri.chain@enioka.com> # # SPDX-License-Identifier: BSD-3-Clause +#[=======================================================================[.rst: +ECMGenerateDBusServiceFile +--------------------------- + +This module provides the ``ecm_generate_dbus_service_file`` function for +generating and installing a D-Bus service file. + +:: + + ecm_generate_dbus_service_file( + NAME <service name> + EXECUTABLE <executable> + [SYSTEMD_SERVICE <systemd service>] + DESTINATION <install_path> + [RENAME <dbus service filename>] # Since 5.75 + ) + +A D-Bus service file ``<service name>.service`` will be generated and installed +in the relevant D-Bus config location. This filename can be customized with RENAME. + +``<executable>`` must be an absolute path to the installed service executable. When using it with +``KDEInstallDirs`` it needs to be the ``_FULL_`` variant of the path variable. + +Note: On Windows, the macro will only use the file name part of ``<executable>`` since D-Bus +service executables are to be installed in the same directory as the D-Bus daemon. + +Optionally, a ``<systemd service>`` can be specified to launch the corresponding +systemd service instead of the ``<executable>`` if the D-Bus daemon is started by systemd. + +Example usage: + +.. code-block:: cmake + + ecm_generate_dbus_service_file( + NAME org.kde.kded5 + EXECUTABLE ${KDE_INSTALL_FULL_BINDIR}/kded5 + DESTINATION ${KDE_INSTALL_DBUSSERVICEDIR} + ) + +.. code-block:: cmake + + ecm_generate_dbus_service_file( + NAME org.kde.kded5 + EXECUTABLE ${KDE_INSTALL_FULL_BINDIR}/kded5 + SYSTEMD_SERVICE plasma-kded.service + DESTINATION ${KDE_INSTALL_DBUSSERVICEDIR} + RENAME org.kde.daemon.service + ) + +Since 5.73.0. +#]=======================================================================] + include(CMakeParseArguments) function(ecm_generate_dbus_service_file) diff --git a/modules/ECMGenerateExportHeader.cmake b/modules/ECMGenerateExportHeader.cmake index 0ee3b411..170531e7 100644 --- a/modules/ECMGenerateExportHeader.cmake +++ b/modules/ECMGenerateExportHeader.cmake @@ -1,363 +1,363 @@ -#.rst: -# ECMGenerateExportHeader -# ----------------------- -# -# This module provides the ``ecm_generate_export_header`` function for -# generating export macros for libraries with version-based control over -# visibility of and compiler warnings for deprecated API for the library user, -# as well as over excluding deprecated API and their implementation when -# building the library itself. -# -# For preparing some values useful in the context it also provides a function -# ``ecm_export_header_format_version``. -# -# :: -# -# ecm_generate_export_header(<library_target_name> -# VERSION <version> -# [BASE_NAME <base_name>] -# [GROUP_BASE_NAME <group_base_name>] -# [EXPORT_MACRO_NAME <export_macro_name>] -# [EXPORT_FILE_NAME <export_file_name>] -# [DEPRECATED_MACRO_NAME <deprecated_macro_name>] -# [NO_EXPORT_MACRO_NAME <no_export_macro_name>] -# [INCLUDE_GUARD_NAME <include_guard_name>] -# [STATIC_DEFINE <static_define>] -# [PREFIX_NAME <prefix_name>] -# [DEPRECATED_BASE_VERSION <deprecated_base_version>] -# [DEPRECATION_VERSIONS <deprecation_version> [<deprecation_version2> [...]]] -# [EXCLUDE_DEPRECATED_BEFORE_AND_AT <exclude_deprecated_before_and_at_version>] -# [NO_BUILD_SET_DEPRECATED_WARNINGS_SINCE] -# [NO_DEFINITION_EXPORT_TO_BUILD_INTERFACE] -# [CUSTOM_CONTENT_FROM_VARIABLE <variable>] -# ) -# -# ``VERSION`` specifies the version of the library, given in the format -# "<major>.<minor>.<patchlevel>". -# -# ``GROUP_BASE_NAME`` specifies the name to use for the macros defining -# library group default values. If set, this will generate code supporting -# ``<group_base_name>_NO_DEPRECATED_WARNINGS``, -# ``<group_base_name>_DISABLE_DEPRECATED_BEFORE_AND_AT``, -# ``<group_base_name>_DEPRECATED_WARNINGS_SINCE`` and -# ``<group_base_name>_NO_DEPRECATED`` (see below). -# If not set, the generated code will ignore any such macros. -# -# ``DEPRECATED_BASE_VERSION`` specifies the default version before and at which -# deprecated API is disabled. Possible values are "0", "CURRENT" (which -# resolves to <version>) and a version string in the format -# "<major>.<minor>.<patchlevel>". The default is the value of -# "<exclude_deprecated_before_and_at_version>" if set, or "<major>.0.0", with -# <major> taken from <version>. -# -# ``DEPRECATION_VERSIONS`` specifies versions in "<major>.<minor>" format in -# which API was declared deprecated. Any version used with the generated -# macro ``<prefix_name><base_name>_DEPRECATED_VERSION(major, minor, text)`` -# or ``<prefix_name><base_name>_DEPRECATED_VERSION_BELATED(major, minor, textmajor, textminor, text)`` -# needs to be listed here, otherwise the macro will fail to work. -# -# ``EXCLUDE_DEPRECATED_BEFORE_AND_AT`` specifies the version for which all API -# deprecated before and at should be excluded from the build completely. -# Possible values are "0" (default), "CURRENT" (which resolves to <version>) -# and a version string in the format "<major>.<minor>.<patchlevel>". -# -# ``NO_BUILD_SET_DEPRECATED_WARNINGS_SINCE`` specifies that the definition -# ``<prefix_name><uppercase_base_name>_DEPRECATED_WARNINGS_SINCE`` will -# not be set for the library inside its own build, and thus will be defined -# by either explicit definition in the build system configuration or by the -# default value mechanism (see below). -# The default is that it is set for the build, to the version specified by -# ``EXCLUDE_DEPRECATED_BEFORE_AND_AT``, so no deprecation warnings are -# done for any own deprecated API used in the library implementation itself. -# -# ``NO_DEFINITION_EXPORT_TO_BUILD_INTERFACE`` specifies that the definition -# ``<prefix_name><uppercase_base_name>_DISABLE_DEPRECATED_BEFORE_AND_AT`` will -# not be set in the public interface of the library inside its own build, and -# the same for the definition -# ``<prefix_name><uppercase_base_name>_DEPRECATED_WARNINGS_SINCE`` (if not -# disabled by ``NO_BUILD_SET_DEPRECATED_WARNINGS_SINCE`` already). -# The default is that they are set, to the version specified by -# ``EXCLUDE_DEPRECATED_BEFORE_AND_AT``, so e.g. test and examples part of the -# project automatically build against the full API included in the build and -# without any deprecation warnings for it. -# -# -# The function ``ecm_generate_export_header`` defines C++ preprocessor macros -# in the generated export header, some for use in the sources of the library -# the header is generated for, other for use by projects linking agsinst the -# library. -# -# The macros for use in the library C++ sources are these, next to those also -# defined by `GenerateExportHeader -# <https://cmake.org/cmake/help/latest/module/GenerateExportHeader.html>`_: -# -# ``<prefix_name><uppercase_base_name>_DEPRECATED_VERSION(major, minor, text)`` -# to use to conditionally set a -# ``<prefix_name><uppercase_base_name>_DEPRECATED`` macro for a class, struct -# or function (other elements to be supported in future versions), depending -# on the visibility macro flags set (see below) -# -# ``<prefix_name><uppercase_base_name>_DEPRECATED_VERSION_BELATED(major, minor, textmajor, textminor, text)`` -# to use to conditionally set a -# ``<prefix_name><uppercase_base_name>_DEPRECATED`` macro for a class, struct -# or function (other elements to be supported in future versions), depending -# on the visibility macro flags set (see below), with ``major`` & ``minor`` -# applied for the logic and ``textmajor`` & ``textminor`` for the warnings message. -# Useful for retroactive tagging of API for the compiler without injecting the -# API into the compiler warning conditions of already released versions. -# Since 5.71. -# -# ``<prefix_name><uppercase_base_name>_ENABLE_DEPRECATED_SINCE(major, minor)`` -# evaluates to ``TRUE`` or ``FALSE`` depending on the visibility macro flags -# set (see below). To be used mainly with ``#if``/``#endif`` to mark sections -# of code which should be included depending on the visibility requested. -# -# ``<prefix_name><uppercase_base_name>_BUILD_DEPRECATED_SINCE(major, minor)`` -# evaluates to ``TRUE`` or ``FALSE`` depending on the value of -# ``EXCLUDE_DEPRECATED_BEFORE_AND_AT``. To be used mainly with -# ``#if``/``#endif`` to mark sections of two types of code: implementation -# code for deprecated API and declaration code of deprecated API which only -# may be disabled at build time of the library for BC reasons (e.g. virtual -# methods, see notes below). -# -# ``<prefix_name><uppercase_base_name>_EXCLUDE_DEPRECATED_BEFORE_AND_AT`` -# holds the version used to exclude deprecated API at build time of the -# library. -# -# The macros used to control visibility when building against the library are: -# -# ``<prefix_name><uppercase_base_name>_DISABLE_DEPRECATED_BEFORE_AND_AT`` -# definition to set to a value in single hex number version notation -# (``0x<major><minor><patchlevel>``). -# -# ``<prefix_name><uppercase_base_name>_NO_DEPRECATED`` -# flag to define to disable all deprecated API, being a shortcut for -# settings ``<prefix_name><uppercase_base_name>_DISABLE_DEPRECATED_BEFORE_AND_AT`` -# to the current version. If both are set, this flag overrules. -# -# ``<prefix_name><uppercase_base_name>_DEPRECATED_WARNINGS_SINCE`` -# definition to set to a value in single hex number version notation -# (``0x<major><minor><patchlevel>``). Warnings will be only activated for -# API deprecated up to and including the version. If -# ``<prefix_name><uppercase_base_name>_DISABLE_DEPRECATED_BEFORE_AND_AT`` -# is set (directly or via the group default), it will default to that -# version, resulting in no warnings. Otherwise the default is the current -# version, resulting in warnings for all deprecated API. -# -# ``<prefix_name><uppercase_base_name>_NO_DEPRECATED_WARNINGS`` -# flag to define to disable all deprecation warnings, being a shortcut for -# setting ``<prefix_name><uppercase_base_name>_DEPRECATED_WARNINGS_SINCE`` -# to "0". If both are set, this flag overrules. -# -# When the ``GROUP_BASE_NAME`` has been used, the same macros but with the -# given ``<group_base_name>`` prefix are available to define the defaults of -# these macros, if not explicitly set. -# -# Note: The tricks applied here for hiding deprecated API to the compiler -# when building against a library do not work for all deprecated API: -# -# * virtual methods need to stay visible to the compiler to build proper -# virtual method tables for subclasses -# * enumerators from enums cannot be simply removed, as this changes -# auto values of following enumerators, also can poke holes in enumerator -# series used as index into tables -# -# In such cases the API can be only "hidden" at build time of the library, -# itself, by generated hard coded macro settings, using -# ``<prefix_name><uppercase_base_name>_BUILD_DEPRECATED_SINCE(major, minor)``. -# -# Examples: -# -# Preparing a library "Foo" created by target "foo", which is part of a group -# of libraries "Bar", where some API of "Foo" got deprecated at versions -# 5.0 & 5.12: -# -# .. code-block:: cmake -# -# ecm_generate_export_header(foo -# GROUP_BASE_NAME BAR -# VERSION ${FOO_VERSION} -# DEPRECATION_VERSIONS 5.0 5.12 -# ) -# -# In the library "Foo" sources in the headers the API would be prepared like -# this, using the generated macros ``FOO_ENABLE_DEPRECATED_SINCE`` and -# ``FOO_DEPRECATED_VERSION``: -# -# .. code-block:: cpp -# -# #include <foo_export.h> -# -# #if FOO_ENABLE_DEPRECATED_SINCE(5, 0) -# /** -# * @deprecated Since 5.0 -# */ -# FOO_DEPRECATED_VERSION(5, 0, "Use doFoo2()") -# FOO_EXPORT void doFoo(); -# #endif -# -# #if FOO_ENABLE_DEPRECATED_SINCE(5, 12) -# /** -# * @deprecated Since 5.12 -# */ -# FOO_DEPRECATED_VERSION(5, 12, "Use doBar2()") -# FOO_EXPORT void doBar(); -# #endif -# -# Projects linking against the "Foo" library can control which part of its -# deprecated API should be hidden to the compiler by adding a definition -# using the ``FOO_DISABLE_DEPRECATED_BEFORE_AND_AT`` macro variable set to the -# desired value (in version hex number notation): -# -# .. code-block:: cmake -# -# add_definitions(-DFOO_DISABLE_DEPRECATED_BEFORE_AND_AT=0x050000) -# -# Or using the macro variable of the group: -# -# .. code-block:: cmake -# -# add_definitions(-DBAR_DISABLE_DEPRECATED_BEFORE_AND_AT=0x050000) -# -# If both are specified, ``FOO_DISABLE_DEPRECATED_BEFORE_AND_AT`` will take -# precedence. -# -# To build a variant of a library with some deprecated API completely left -# out from the build, not only optionally invisible to consumers, one uses the -# ``EXCLUDE_DEPRECATED_BEFORE_AND_AT`` parameter. This is best combined with a -# cached CMake variable. -# -# .. code-block:: cmake -# -# set(EXCLUDE_DEPRECATED_BEFORE_AND_AT 0 CACHE STRING "Control the range of deprecated API excluded from the build [default=0].") -# -# ecm_generate_export_header(foo -# VERSION ${FOO_VERSION} -# EXCLUDE_DEPRECATED_BEFORE_AND_AT ${EXCLUDE_DEPRECATED_BEFORE_AND_AT} -# DEPRECATION_VERSIONS 5.0 5.12 -# ) -# -# The macros used in the headers for library consumers are reused for -# disabling the API excluded in the build of the library. For disabling the -# implementation of that API as well as for disabling deprecated API which -# only can be disabled at build time of the library for BC reasons, one -# uses the generated macro ``FOO_BUILD_DEPRECATED_SINCE``, like this: -# -# .. code-block:: cpp -# -# #include <foo_export.h> -# -# enum Bars { -# One, -# #if FOO_BUILD_DEPRECATED_SINCE(5, 0) -# Two, -# #endif -# Three, -# }; -# -# #if FOO_ENABLE_DEPRECATED_SINCE(5, 0) -# /** -# * @deprecated Since 5.0 -# */ -# FOO_DEPRECATED_VERSION(5, 0, "Use doFoo2()") -# FOO_EXPORT void doFoo(); -# #endif -# -# #if FOO_ENABLE_DEPRECATED_SINCE(5, 12) -# /** -# * @deprecated Since 5.12 -# */ -# FOO_DEPRECATED_VERSION(5, 12, "Use doBar2()") -# FOO_EXPORT void doBar(); -# #endif -# -# class FOO_EXPORT Foo { -# public: -# #if FOO_BUILD_DEPRECATED_SINCE(5, 0) -# /** -# * @deprecated Since 5.0 -# */ -# FOO_DEPRECATED_VERSION(5, 0, "Feature removed") -# virtual void doWhat(); -# #endif -# }; -# -# .. code-block:: cpp -# -# #if FOO_BUILD_DEPRECATED_SINCE(5, 0) -# void doFoo() -# { -# // [...] -# } -# #endif -# -# #if FOO_BUILD_DEPRECATED_SINCE(5, 12) -# void doBar() -# { -# // [...] -# } -# #endif -# -# #if FOO_BUILD_DEPRECATED_SINCE(5, 0) -# void Foo::doWhat() -# { -# // [...] -# } -# #endif -# -# So e.g. if ``EXCLUDE_DEPRECATED_BEFORE_AND_AT`` is set to "5.0.0", the -# enumerator ``Two`` as well as the methods ``::doFoo()`` and ``Foo::doWhat()`` -# will be not available to library consumers. The methods will not have been -# compiled into the library binary, and the declarations will be hidden to the -# compiler, ``FOO_DISABLE_DEPRECATED_BEFORE_AND_AT`` also cannot be used to -# reactivate them. -# -# When using the ``NO_DEFINITION_EXPORT_TO_BUILD_INTERFACE`` and the project -# for the "Foo" library includes also tests and examples linking against the -# library and using deprecated API (like tests covering it), one better -# explicitly sets ``FOO_DISABLE_DEPRECATED_BEFORE_AND_AT`` for those targets -# to the version before and at which all deprecated API has been excluded from -# the build. -# Even more when building against other libraries from the same group "Bar" and -# disabling some deprecated API of those libraries using the group macro -# ``BAR_DISABLE_DEPRECATED_BEFORE_AND_AT``, which also works as default for -# ``FOO_DISABLE_DEPRECATED_BEFORE_AND_AT``. -# -# To get the hex number style value the helper macro -# ``ecm_export_header_format_version()`` will be used: -# -# .. code-block:: cmake -# -# set(EXCLUDE_DEPRECATED_BEFORE_AND_AT 0 CACHE STRING "Control what part of deprecated API is excluded from build [default=0].") -# -# ecm_generate_export_header(foo -# VERSION ${FOO_VERSION} -# GROUP_BASE_NAME BAR -# EXCLUDE_DEPRECATED_BEFORE_AND_AT ${EXCLUDE_DEPRECATED_BEFORE_AND_AT} -# NO_DEFINITION_EXPORT_TO_BUILD_INTERFACE -# DEPRECATION_VERSIONS 5.0 5.12 -# ) -# -# ecm_export_header_format_version(${EXCLUDE_DEPRECATED_BEFORE_AND_AT} -# CURRENT_VERSION ${FOO_VERSION} -# HEXNUMBER_VAR foo_no_deprecated_before_and_at -# ) -# -# # disable all deprecated API up to 5.9.0 from all other libs of group "BAR" that we use ourselves -# add_definitions(-DBAR_DISABLE_DEPRECATED_BEFORE_AND_AT=0x050900) -# -# add_executable(app app.cpp) -# target_link_libraries(app foo) -# target_compile_definitions(app -# PRIVATE "FOO_DISABLE_DEPRECATED_BEFORE_AND_AT=${foo_no_deprecated_before_and_at}") -# -# Since 5.64.0. - -#============================================================================= # SPDX-FileCopyrightText: 2019 Friedrich W. H. Kossebau <kossebau@kde.org> # # SPDX-License-Identifier: BSD-3-Clause +#[=======================================================================[.rst: +ECMGenerateExportHeader +----------------------- + +This module provides the ``ecm_generate_export_header`` function for +generating export macros for libraries with version-based control over +visibility of and compiler warnings for deprecated API for the library user, +as well as over excluding deprecated API and their implementation when +building the library itself. + +For preparing some values useful in the context it also provides a function +``ecm_export_header_format_version``. + +:: + + ecm_generate_export_header(<library_target_name> + VERSION <version> + [BASE_NAME <base_name>] + [GROUP_BASE_NAME <group_base_name>] + [EXPORT_MACRO_NAME <export_macro_name>] + [EXPORT_FILE_NAME <export_file_name>] + [DEPRECATED_MACRO_NAME <deprecated_macro_name>] + [NO_EXPORT_MACRO_NAME <no_export_macro_name>] + [INCLUDE_GUARD_NAME <include_guard_name>] + [STATIC_DEFINE <static_define>] + [PREFIX_NAME <prefix_name>] + [DEPRECATED_BASE_VERSION <deprecated_base_version>] + [DEPRECATION_VERSIONS <deprecation_version> [<deprecation_version2> [...]]] + [EXCLUDE_DEPRECATED_BEFORE_AND_AT <exclude_deprecated_before_and_at_version>] + [NO_BUILD_SET_DEPRECATED_WARNINGS_SINCE] + [NO_DEFINITION_EXPORT_TO_BUILD_INTERFACE] + [CUSTOM_CONTENT_FROM_VARIABLE <variable>] + ) + +``VERSION`` specifies the version of the library, given in the format +"<major>.<minor>.<patchlevel>". + +``GROUP_BASE_NAME`` specifies the name to use for the macros defining +library group default values. If set, this will generate code supporting +``<group_base_name>_NO_DEPRECATED_WARNINGS``, +``<group_base_name>_DISABLE_DEPRECATED_BEFORE_AND_AT``, +``<group_base_name>_DEPRECATED_WARNINGS_SINCE`` and +``<group_base_name>_NO_DEPRECATED`` (see below). +If not set, the generated code will ignore any such macros. + +``DEPRECATED_BASE_VERSION`` specifies the default version before and at which +deprecated API is disabled. Possible values are "0", "CURRENT" (which +resolves to <version>) and a version string in the format +"<major>.<minor>.<patchlevel>". The default is the value of +"<exclude_deprecated_before_and_at_version>" if set, or "<major>.0.0", with +<major> taken from <version>. + +``DEPRECATION_VERSIONS`` specifies versions in "<major>.<minor>" format in +which API was declared deprecated. Any version used with the generated +macro ``<prefix_name><base_name>_DEPRECATED_VERSION(major, minor, text)`` +or ``<prefix_name><base_name>_DEPRECATED_VERSION_BELATED(major, minor, textmajor, textminor, text)`` +needs to be listed here, otherwise the macro will fail to work. + +``EXCLUDE_DEPRECATED_BEFORE_AND_AT`` specifies the version for which all API +deprecated before and at should be excluded from the build completely. +Possible values are "0" (default), "CURRENT" (which resolves to <version>) +and a version string in the format "<major>.<minor>.<patchlevel>". + +``NO_BUILD_SET_DEPRECATED_WARNINGS_SINCE`` specifies that the definition +``<prefix_name><uppercase_base_name>_DEPRECATED_WARNINGS_SINCE`` will +not be set for the library inside its own build, and thus will be defined +by either explicit definition in the build system configuration or by the +default value mechanism (see below). +The default is that it is set for the build, to the version specified by +``EXCLUDE_DEPRECATED_BEFORE_AND_AT``, so no deprecation warnings are +done for any own deprecated API used in the library implementation itself. + +``NO_DEFINITION_EXPORT_TO_BUILD_INTERFACE`` specifies that the definition +``<prefix_name><uppercase_base_name>_DISABLE_DEPRECATED_BEFORE_AND_AT`` will +not be set in the public interface of the library inside its own build, and +the same for the definition +``<prefix_name><uppercase_base_name>_DEPRECATED_WARNINGS_SINCE`` (if not +disabled by ``NO_BUILD_SET_DEPRECATED_WARNINGS_SINCE`` already). +The default is that they are set, to the version specified by +``EXCLUDE_DEPRECATED_BEFORE_AND_AT``, so e.g. test and examples part of the +project automatically build against the full API included in the build and +without any deprecation warnings for it. + + +The function ``ecm_generate_export_header`` defines C++ preprocessor macros +in the generated export header, some for use in the sources of the library +the header is generated for, other for use by projects linking agsinst the +library. + +The macros for use in the library C++ sources are these, next to those also +defined by `GenerateExportHeader +<https://cmake.org/cmake/help/latest/module/GenerateExportHeader.html>`_: + +``<prefix_name><uppercase_base_name>_DEPRECATED_VERSION(major, minor, text)`` + to use to conditionally set a + ``<prefix_name><uppercase_base_name>_DEPRECATED`` macro for a class, struct + or function (other elements to be supported in future versions), depending + on the visibility macro flags set (see below) + +``<prefix_name><uppercase_base_name>_DEPRECATED_VERSION_BELATED(major, minor, textmajor, textminor, text)`` + to use to conditionally set a + ``<prefix_name><uppercase_base_name>_DEPRECATED`` macro for a class, struct + or function (other elements to be supported in future versions), depending + on the visibility macro flags set (see below), with ``major`` & ``minor`` + applied for the logic and ``textmajor`` & ``textminor`` for the warnings message. + Useful for retroactive tagging of API for the compiler without injecting the + API into the compiler warning conditions of already released versions. + Since 5.71. + +``<prefix_name><uppercase_base_name>_ENABLE_DEPRECATED_SINCE(major, minor)`` + evaluates to ``TRUE`` or ``FALSE`` depending on the visibility macro flags + set (see below). To be used mainly with ``#if``/``#endif`` to mark sections + of code which should be included depending on the visibility requested. + +``<prefix_name><uppercase_base_name>_BUILD_DEPRECATED_SINCE(major, minor)`` + evaluates to ``TRUE`` or ``FALSE`` depending on the value of + ``EXCLUDE_DEPRECATED_BEFORE_AND_AT``. To be used mainly with + ``#if``/``#endif`` to mark sections of two types of code: implementation + code for deprecated API and declaration code of deprecated API which only + may be disabled at build time of the library for BC reasons (e.g. virtual + methods, see notes below). + +``<prefix_name><uppercase_base_name>_EXCLUDE_DEPRECATED_BEFORE_AND_AT`` + holds the version used to exclude deprecated API at build time of the + library. + +The macros used to control visibility when building against the library are: + +``<prefix_name><uppercase_base_name>_DISABLE_DEPRECATED_BEFORE_AND_AT`` + definition to set to a value in single hex number version notation + (``0x<major><minor><patchlevel>``). + +``<prefix_name><uppercase_base_name>_NO_DEPRECATED`` + flag to define to disable all deprecated API, being a shortcut for + settings ``<prefix_name><uppercase_base_name>_DISABLE_DEPRECATED_BEFORE_AND_AT`` + to the current version. If both are set, this flag overrules. + +``<prefix_name><uppercase_base_name>_DEPRECATED_WARNINGS_SINCE`` + definition to set to a value in single hex number version notation + (``0x<major><minor><patchlevel>``). Warnings will be only activated for + API deprecated up to and including the version. If + ``<prefix_name><uppercase_base_name>_DISABLE_DEPRECATED_BEFORE_AND_AT`` + is set (directly or via the group default), it will default to that + version, resulting in no warnings. Otherwise the default is the current + version, resulting in warnings for all deprecated API. + +``<prefix_name><uppercase_base_name>_NO_DEPRECATED_WARNINGS`` + flag to define to disable all deprecation warnings, being a shortcut for + setting ``<prefix_name><uppercase_base_name>_DEPRECATED_WARNINGS_SINCE`` + to "0". If both are set, this flag overrules. + +When the ``GROUP_BASE_NAME`` has been used, the same macros but with the +given ``<group_base_name>`` prefix are available to define the defaults of +these macros, if not explicitly set. + +Note: The tricks applied here for hiding deprecated API to the compiler +when building against a library do not work for all deprecated API: + +* virtual methods need to stay visible to the compiler to build proper + virtual method tables for subclasses +* enumerators from enums cannot be simply removed, as this changes + auto values of following enumerators, also can poke holes in enumerator + series used as index into tables + +In such cases the API can be only "hidden" at build time of the library, +itself, by generated hard coded macro settings, using +``<prefix_name><uppercase_base_name>_BUILD_DEPRECATED_SINCE(major, minor)``. + +Examples: + +Preparing a library "Foo" created by target "foo", which is part of a group +of libraries "Bar", where some API of "Foo" got deprecated at versions +5.0 & 5.12: + +.. code-block:: cmake + + ecm_generate_export_header(foo + GROUP_BASE_NAME BAR + VERSION ${FOO_VERSION} + DEPRECATION_VERSIONS 5.0 5.12 + ) + +In the library "Foo" sources in the headers the API would be prepared like +this, using the generated macros ``FOO_ENABLE_DEPRECATED_SINCE`` and +``FOO_DEPRECATED_VERSION``: + +.. code-block:: cpp + + #include <foo_export.h> + + #if FOO_ENABLE_DEPRECATED_SINCE(5, 0) + /** + * @deprecated Since 5.0 + */ + FOO_DEPRECATED_VERSION(5, 0, "Use doFoo2()") + FOO_EXPORT void doFoo(); + #endif + + #if FOO_ENABLE_DEPRECATED_SINCE(5, 12) + /** + * @deprecated Since 5.12 + */ + FOO_DEPRECATED_VERSION(5, 12, "Use doBar2()") + FOO_EXPORT void doBar(); + #endif + +Projects linking against the "Foo" library can control which part of its +deprecated API should be hidden to the compiler by adding a definition +using the ``FOO_DISABLE_DEPRECATED_BEFORE_AND_AT`` macro variable set to the +desired value (in version hex number notation): + +.. code-block:: cmake + + add_definitions(-DFOO_DISABLE_DEPRECATED_BEFORE_AND_AT=0x050000) + +Or using the macro variable of the group: + +.. code-block:: cmake + + add_definitions(-DBAR_DISABLE_DEPRECATED_BEFORE_AND_AT=0x050000) + +If both are specified, ``FOO_DISABLE_DEPRECATED_BEFORE_AND_AT`` will take +precedence. + +To build a variant of a library with some deprecated API completely left +out from the build, not only optionally invisible to consumers, one uses the +``EXCLUDE_DEPRECATED_BEFORE_AND_AT`` parameter. This is best combined with a +cached CMake variable. + +.. code-block:: cmake + + set(EXCLUDE_DEPRECATED_BEFORE_AND_AT 0 CACHE STRING "Control the range of deprecated API excluded from the build [default=0].") + + ecm_generate_export_header(foo + VERSION ${FOO_VERSION} + EXCLUDE_DEPRECATED_BEFORE_AND_AT ${EXCLUDE_DEPRECATED_BEFORE_AND_AT} + DEPRECATION_VERSIONS 5.0 5.12 + ) + +The macros used in the headers for library consumers are reused for +disabling the API excluded in the build of the library. For disabling the +implementation of that API as well as for disabling deprecated API which +only can be disabled at build time of the library for BC reasons, one +uses the generated macro ``FOO_BUILD_DEPRECATED_SINCE``, like this: + +.. code-block:: cpp + + #include <foo_export.h> + + enum Bars { + One, + #if FOO_BUILD_DEPRECATED_SINCE(5, 0) + Two, + #endif + Three, + }; + + #if FOO_ENABLE_DEPRECATED_SINCE(5, 0) + /** + * @deprecated Since 5.0 + */ + FOO_DEPRECATED_VERSION(5, 0, "Use doFoo2()") + FOO_EXPORT void doFoo(); + #endif + + #if FOO_ENABLE_DEPRECATED_SINCE(5, 12) + /** + * @deprecated Since 5.12 + */ + FOO_DEPRECATED_VERSION(5, 12, "Use doBar2()") + FOO_EXPORT void doBar(); + #endif + + class FOO_EXPORT Foo { + public: + #if FOO_BUILD_DEPRECATED_SINCE(5, 0) + /** + * @deprecated Since 5.0 + */ + FOO_DEPRECATED_VERSION(5, 0, "Feature removed") + virtual void doWhat(); + #endif + }; + +.. code-block:: cpp + + #if FOO_BUILD_DEPRECATED_SINCE(5, 0) + void doFoo() + { + // [...] + } + #endif + + #if FOO_BUILD_DEPRECATED_SINCE(5, 12) + void doBar() + { + // [...] + } + #endif + + #if FOO_BUILD_DEPRECATED_SINCE(5, 0) + void Foo::doWhat() + { + // [...] + } + #endif + +So e.g. if ``EXCLUDE_DEPRECATED_BEFORE_AND_AT`` is set to "5.0.0", the +enumerator ``Two`` as well as the methods ``::doFoo()`` and ``Foo::doWhat()`` +will be not available to library consumers. The methods will not have been +compiled into the library binary, and the declarations will be hidden to the +compiler, ``FOO_DISABLE_DEPRECATED_BEFORE_AND_AT`` also cannot be used to +reactivate them. + +When using the ``NO_DEFINITION_EXPORT_TO_BUILD_INTERFACE`` and the project +for the "Foo" library includes also tests and examples linking against the +library and using deprecated API (like tests covering it), one better +explicitly sets ``FOO_DISABLE_DEPRECATED_BEFORE_AND_AT`` for those targets +to the version before and at which all deprecated API has been excluded from +the build. +Even more when building against other libraries from the same group "Bar" and +disabling some deprecated API of those libraries using the group macro +``BAR_DISABLE_DEPRECATED_BEFORE_AND_AT``, which also works as default for +``FOO_DISABLE_DEPRECATED_BEFORE_AND_AT``. + +To get the hex number style value the helper macro +``ecm_export_header_format_version()`` will be used: + +.. code-block:: cmake + + set(EXCLUDE_DEPRECATED_BEFORE_AND_AT 0 CACHE STRING "Control what part of deprecated API is excluded from build [default=0].") + + ecm_generate_export_header(foo + VERSION ${FOO_VERSION} + GROUP_BASE_NAME BAR + EXCLUDE_DEPRECATED_BEFORE_AND_AT ${EXCLUDE_DEPRECATED_BEFORE_AND_AT} + NO_DEFINITION_EXPORT_TO_BUILD_INTERFACE + DEPRECATION_VERSIONS 5.0 5.12 + ) + + ecm_export_header_format_version(${EXCLUDE_DEPRECATED_BEFORE_AND_AT} + CURRENT_VERSION ${FOO_VERSION} + HEXNUMBER_VAR foo_no_deprecated_before_and_at + ) + + # disable all deprecated API up to 5.9.0 from all other libs of group "BAR" that we use ourselves + add_definitions(-DBAR_DISABLE_DEPRECATED_BEFORE_AND_AT=0x050900) + + add_executable(app app.cpp) + target_link_libraries(app foo) + target_compile_definitions(app + PRIVATE "FOO_DISABLE_DEPRECATED_BEFORE_AND_AT=${foo_no_deprecated_before_and_at}") + +Since 5.64.0. +#]=======================================================================] + include(GenerateExportHeader) include(CMakeParseArguments) diff --git a/modules/ECMGenerateHeaders.cmake b/modules/ECMGenerateHeaders.cmake index d5332e58..9099cb5a 100644 --- a/modules/ECMGenerateHeaders.cmake +++ b/modules/ECMGenerateHeaders.cmake @@ -1,123 +1,123 @@ -#.rst: -# ECMGenerateHeaders -# ------------------ -# -# Generate C/C++ CamelCase forwarding headers. -# -# :: -# -# ecm_generate_headers(<camelcase_forwarding_headers_var> -# HEADER_NAMES <CamelCaseName> [<CamelCaseName> [...]] -# [ORIGINAL <CAMELCASE|LOWERCASE>] -# [HEADER_EXTENSION <header_extension>] -# [OUTPUT_DIR <output_dir>] -# [PREFIX <prefix>] -# [REQUIRED_HEADERS <variable>] -# [COMMON_HEADER <HeaderName>] -# [RELATIVE <relative_path>]) -# -# For each CamelCase header name passed to HEADER_NAMES, a file of that name -# will be generated that will include a version with ``.h`` or, if set, -# ``.<header_extension>`` appended. -# For example, the generated header ``ClassA`` will include ``classa.h`` (or -# ``ClassA.h``, see ORIGINAL). -# If a CamelCaseName consists of multiple comma-separated files, e.g. -# ``ClassA,ClassB,ClassC``, then multiple camelcase header files will be -# generated which are redirects to the first header file. -# The file locations of these generated headers will be stored in -# <camelcase_forwarding_headers_var>. -# -# ORIGINAL specifies how the name of the original header is written: lowercased -# or also camelcased. The default is LOWERCASE. Since 1.8.0. -# -# HEADER_EXTENSION specifies what file name extension is used for the header -# files. The default is "h". Since 5.48.0. -# -# PREFIX places the generated headers in subdirectories. This should be a -# CamelCase name like ``KParts``, which will cause the CamelCase forwarding -# headers to be placed in the ``KParts`` directory (e.g. ``KParts/Part``). It -# will also, for the convenience of code in the source distribution, generate -# forwarding headers based on the original names (e.g. ``kparts/part.h``). This -# allows includes like ``"#include <kparts/part.h>"`` to be used before -# installation, as long as the include_directories are set appropriately. -# -# OUTPUT_DIR specifies where the files will be generated; this should be within -# the build directory. By default, ``${CMAKE_CURRENT_BINARY_DIR}`` will be used. -# This option can be used to avoid file conflicts. -# -# REQUIRED_HEADERS specifies an output variable name where all the required -# headers will be appended so that they can be installed together with the -# generated ones. This is mostly intended as a convenience so that adding a new -# header to a project only requires specifying the CamelCase variant in the -# CMakeLists.txt file; the original variant will then be added to this -# variable. -# -# COMMON_HEADER generates an additional convenience header which includes all -# other header files. -# -# The RELATIVE argument indicates where the original headers can be found -# relative to CMAKE_CURRENT_SOURCE_DIR. It does not affect the generated -# CamelCase forwarding files, but ecm_generate_headers() uses it when checking -# that the original header exists, and to generate originally named forwarding -# headers when PREFIX is set. -# -# To allow other parts of the source distribution (eg: tests) to use the -# generated headers before installation, it may be desirable to set the -# INCLUDE_DIRECTORIES property for the library target to output_dir. For -# example, if OUTPUT_DIR is CMAKE_CURRENT_BINARY_DIR (the default), you could do -# -# .. code-block:: cmake -# -# target_include_directories(MyLib PUBLIC "$<BUILD_INTERFACE:${CMAKE_CURRENT_BINARY_DIR}>") -# -# Example usage (without PREFIX): -# -# .. code-block:: cmake -# -# ecm_generate_headers( -# MyLib_FORWARDING_HEADERS -# HEADERS -# MLFoo -# MLBar -# # etc -# REQUIRED_HEADERS MyLib_HEADERS -# COMMON_HEADER MLGeneral -# ) -# install(FILES ${MyLib_FORWARDING_HEADERS} ${MyLib_HEADERS} -# DESTINATION ${CMAKE_INSTALL_PREFIX}/include -# COMPONENT Devel) -# -# Example usage (with PREFIX): -# -# .. code-block:: cmake -# -# ecm_generate_headers( -# MyLib_FORWARDING_HEADERS -# HEADERS -# Foo -# # several classes are contained in bar.h, so generate -# # additional files -# Bar,BarList -# # etc -# PREFIX MyLib -# REQUIRED_HEADERS MyLib_HEADERS -# ) -# install(FILES ${MyLib_FORWARDING_HEADERS} -# DESTINATION ${CMAKE_INSTALL_PREFIX}/include/MyLib -# COMPONENT Devel) -# install(FILES ${MyLib_HEADERS} -# DESTINATION ${CMAKE_INSTALL_PREFIX}/include/mylib -# COMPONENT Devel) -# -# Since pre-1.0.0. - -#============================================================================= # SPDX-FileCopyrightText: 2013 Aleix Pol Gonzalez <aleixpol@blue-systems.com> # SPDX-FileCopyrightText: 2014 Alex Merry <alex.merry@kdemail.net> # SPDX-FileCopyrightText: 2015 Patrick Spendrin <patrick.spendrin@kdab.com> # # SPDX-License-Identifier: BSD-3-Clause +#[=======================================================================[.rst: +ECMGenerateHeaders +------------------ + +Generate C/C++ CamelCase forwarding headers. + +:: + + ecm_generate_headers(<camelcase_forwarding_headers_var> + HEADER_NAMES <CamelCaseName> [<CamelCaseName> [...]] + [ORIGINAL <CAMELCASE|LOWERCASE>] + [HEADER_EXTENSION <header_extension>] + [OUTPUT_DIR <output_dir>] + [PREFIX <prefix>] + [REQUIRED_HEADERS <variable>] + [COMMON_HEADER <HeaderName>] + [RELATIVE <relative_path>]) + +For each CamelCase header name passed to HEADER_NAMES, a file of that name +will be generated that will include a version with ``.h`` or, if set, +``.<header_extension>`` appended. +For example, the generated header ``ClassA`` will include ``classa.h`` (or +``ClassA.h``, see ORIGINAL). +If a CamelCaseName consists of multiple comma-separated files, e.g. +``ClassA,ClassB,ClassC``, then multiple camelcase header files will be +generated which are redirects to the first header file. +The file locations of these generated headers will be stored in +<camelcase_forwarding_headers_var>. + +ORIGINAL specifies how the name of the original header is written: lowercased +or also camelcased. The default is LOWERCASE. Since 1.8.0. + +HEADER_EXTENSION specifies what file name extension is used for the header +files. The default is "h". Since 5.48.0. + +PREFIX places the generated headers in subdirectories. This should be a +CamelCase name like ``KParts``, which will cause the CamelCase forwarding +headers to be placed in the ``KParts`` directory (e.g. ``KParts/Part``). It +will also, for the convenience of code in the source distribution, generate +forwarding headers based on the original names (e.g. ``kparts/part.h``). This +allows includes like ``"#include <kparts/part.h>"`` to be used before +installation, as long as the include_directories are set appropriately. + +OUTPUT_DIR specifies where the files will be generated; this should be within +the build directory. By default, ``${CMAKE_CURRENT_BINARY_DIR}`` will be used. +This option can be used to avoid file conflicts. + +REQUIRED_HEADERS specifies an output variable name where all the required +headers will be appended so that they can be installed together with the +generated ones. This is mostly intended as a convenience so that adding a new +header to a project only requires specifying the CamelCase variant in the +CMakeLists.txt file; the original variant will then be added to this +variable. + +COMMON_HEADER generates an additional convenience header which includes all +other header files. + +The RELATIVE argument indicates where the original headers can be found +relative to CMAKE_CURRENT_SOURCE_DIR. It does not affect the generated +CamelCase forwarding files, but ecm_generate_headers() uses it when checking +that the original header exists, and to generate originally named forwarding +headers when PREFIX is set. + +To allow other parts of the source distribution (eg: tests) to use the +generated headers before installation, it may be desirable to set the +INCLUDE_DIRECTORIES property for the library target to output_dir. For +example, if OUTPUT_DIR is CMAKE_CURRENT_BINARY_DIR (the default), you could do + +.. code-block:: cmake + + target_include_directories(MyLib PUBLIC "$<BUILD_INTERFACE:${CMAKE_CURRENT_BINARY_DIR}>") + +Example usage (without PREFIX): + +.. code-block:: cmake + + ecm_generate_headers( + MyLib_FORWARDING_HEADERS + HEADERS + MLFoo + MLBar + # etc + REQUIRED_HEADERS MyLib_HEADERS + COMMON_HEADER MLGeneral + ) + install(FILES ${MyLib_FORWARDING_HEADERS} ${MyLib_HEADERS} + DESTINATION ${CMAKE_INSTALL_PREFIX}/include + COMPONENT Devel) + +Example usage (with PREFIX): + +.. code-block:: cmake + + ecm_generate_headers( + MyLib_FORWARDING_HEADERS + HEADERS + Foo + # several classes are contained in bar.h, so generate + # additional files + Bar,BarList + # etc + PREFIX MyLib + REQUIRED_HEADERS MyLib_HEADERS + ) + install(FILES ${MyLib_FORWARDING_HEADERS} + DESTINATION ${CMAKE_INSTALL_PREFIX}/include/MyLib + COMPONENT Devel) + install(FILES ${MyLib_HEADERS} + DESTINATION ${CMAKE_INSTALL_PREFIX}/include/mylib + COMPONENT Devel) + +Since pre-1.0.0. +#]=======================================================================] + include(CMakeParseArguments) function(ECM_GENERATE_HEADERS camelcase_forwarding_headers_var) diff --git a/modules/ECMGeneratePkgConfigFile.cmake b/modules/ECMGeneratePkgConfigFile.cmake index 65b95285..fde6e5d9 100644 --- a/modules/ECMGeneratePkgConfigFile.cmake +++ b/modules/ECMGeneratePkgConfigFile.cmake @@ -1,84 +1,83 @@ -#.rst: -# ECMGeneratePkgConfigFile -# ------------------------ -# -# Generate a `pkg-config <https://www.freedesktop.org/wiki/Software/pkg-config/>`_ -# file for the benefit of -# `autotools <https://www.gnu.org/software/automake/manual/html_node/Autotools-Introduction.html>`_-based -# projects. -# -# :: -# -# ecm_generate_pkgconfig_file(BASE_NAME <baseName> -# [LIB_NAME <libName>] -# [DEPS "<dep> [<dep> [...]]"] -# [FILENAME_VAR <filename_variable>] -# [INCLUDE_INSTALL_DIR <dir>] -# [LIB_INSTALL_DIR <dir>] -# [DEFINES -D<variable=value>...] -# [DESCRIPTION <library description>] # since 5.41.0 -# [INSTALL]) -# -# ``BASE_NAME`` is the name of the module. It's the name projects will use to -# find the module. -# -# ``LIB_NAME`` is the name of the library that is being exported. If undefined, -# it will default to the ``BASE_NAME``. That means the ``LIB_NAME`` will be set -# as the name field as well as the library to link to. -# -# ``FILENAME_VAR`` is specified with a variable name. This variable will -# receive the location of the generated file will be set, within the build -# directory. This way it can be used in case some processing is required. See -# also ``INSTALL``. -# -# ``INCLUDE_INSTALL_DIR`` specifies where the includes will be installed. If -# it's not specified, it will default to ``INSTALL_INCLUDEDIR``, -# ``CMAKE_INSTALL_INCLUDEDIR`` or just "include/" in case they are specified, -# with the BASE_NAME postfixed. -# -# ``LIB_INSTALL_DIR`` specifies where the library is being installed. If it's -# not specified, it will default to ``LIB_INSTALL_DIR``, -# ``CMAKE_INSTALL_LIBDIR`` or just "lib/" in case they are specified. -# -# ``DEFINES`` is a list of preprocessor defines that it is recommended users of -# the library pass to the compiler when using it. -# -# ``DESCRIPTION`` describes what this library is. If it's not specified, CMake -# will first try to get the description from the metainfo.yaml file or will -# create one based on ``LIB_NAME``. Since 5.41.0. -# -# ``INSTALL`` will cause the module to be installed to the ``pkgconfig`` -# subdirectory of ``LIB_INSTALL_DIR``, unless the ``ECM_PKGCONFIG_INSTALL_DIR`` -# cache variable is set to something different. Note that the first call to -# ecm_generate_pkgconfig_file with the ``INSTALL`` argument will cause -# ``ECM_PKGCONFIG_INSTALL_DIR`` to be set to the cache, and will be used in any -# subsequent calls. -# -# To properly use this macro a version needs to be set. To retrieve it, -# ``ECM_PKGCONFIG_INSTALL_DIR`` uses ``PROJECT_VERSION``. To set it, use the -# project() command (only available since CMake 3.0) or the ecm_setup_version() -# macro. -# -# Example usage: -# -# .. code-block:: cmake -# -# ecm_generate_pkgconfig_file( -# BASE_NAME KF5Archive -# DEPS Qt5Core -# FILENAME_VAR pkgconfig_filename -# INSTALL -# ) -# -# Since 1.3.0. -# - -#============================================================================= # SPDX-FileCopyrightText: 2014 Aleix Pol Gonzalez <aleixpol@kde.org> # SPDX-FileCopyrightText: 2014 David Faure <faure@kde.org> # # SPDX-License-Identifier: BSD-3-Clause +#[=======================================================================[.rst: +ECMGeneratePkgConfigFile +------------------------ + +Generate a `pkg-config <https://www.freedesktop.org/wiki/Software/pkg-config/>`_ +file for the benefit of +`autotools <https://www.gnu.org/software/automake/manual/html_node/Autotools-Introduction.html>`_-based +projects. + +:: + + ecm_generate_pkgconfig_file(BASE_NAME <baseName> + [LIB_NAME <libName>] + [DEPS "<dep> [<dep> [...]]"] + [FILENAME_VAR <filename_variable>] + [INCLUDE_INSTALL_DIR <dir>] + [LIB_INSTALL_DIR <dir>] + [DEFINES -D<variable=value>...] + [DESCRIPTION <library description>] # since 5.41.0 + [INSTALL]) + +``BASE_NAME`` is the name of the module. It's the name projects will use to +find the module. + +``LIB_NAME`` is the name of the library that is being exported. If undefined, +it will default to the ``BASE_NAME``. That means the ``LIB_NAME`` will be set +as the name field as well as the library to link to. + +``FILENAME_VAR`` is specified with a variable name. This variable will +receive the location of the generated file will be set, within the build +directory. This way it can be used in case some processing is required. See +also ``INSTALL``. + +``INCLUDE_INSTALL_DIR`` specifies where the includes will be installed. If +it's not specified, it will default to ``INSTALL_INCLUDEDIR``, +``CMAKE_INSTALL_INCLUDEDIR`` or just "include/" in case they are specified, +with the BASE_NAME postfixed. + +``LIB_INSTALL_DIR`` specifies where the library is being installed. If it's +not specified, it will default to ``LIB_INSTALL_DIR``, +``CMAKE_INSTALL_LIBDIR`` or just "lib/" in case they are specified. + +``DEFINES`` is a list of preprocessor defines that it is recommended users of +the library pass to the compiler when using it. + +``DESCRIPTION`` describes what this library is. If it's not specified, CMake +will first try to get the description from the metainfo.yaml file or will +create one based on ``LIB_NAME``. Since 5.41.0. + +``INSTALL`` will cause the module to be installed to the ``pkgconfig`` +subdirectory of ``LIB_INSTALL_DIR``, unless the ``ECM_PKGCONFIG_INSTALL_DIR`` +cache variable is set to something different. Note that the first call to +ecm_generate_pkgconfig_file with the ``INSTALL`` argument will cause +``ECM_PKGCONFIG_INSTALL_DIR`` to be set to the cache, and will be used in any +subsequent calls. + +To properly use this macro a version needs to be set. To retrieve it, +``ECM_PKGCONFIG_INSTALL_DIR`` uses ``PROJECT_VERSION``. To set it, use the +project() command (only available since CMake 3.0) or the ecm_setup_version() +macro. + +Example usage: + +.. code-block:: cmake + + ecm_generate_pkgconfig_file( + BASE_NAME KF5Archive + DEPS Qt5Core + FILENAME_VAR pkgconfig_filename + INSTALL + ) + +Since 1.3.0. +#]=======================================================================] + function(ECM_GENERATE_PKGCONFIG_FILE) set(options INSTALL) set(oneValueArgs BASE_NAME LIB_NAME FILENAME_VAR INCLUDE_INSTALL_DIR LIB_INSTALL_DIR DESCRIPTION) diff --git a/modules/ECMGeneratePriFile.cmake b/modules/ECMGeneratePriFile.cmake index 0f6cd905..d5d1ce66 100644 --- a/modules/ECMGeneratePriFile.cmake +++ b/modules/ECMGeneratePriFile.cmake @@ -1,81 +1,81 @@ -#.rst: -# ECMGeneratePriFile -# ------------------ -# -# Generate a ``.pri`` file for the benefit of qmake-based projects. -# -# As well as the function below, this module creates the cache variable -# ``ECM_MKSPECS_INSTALL_DIR`` and sets the default value to ``mkspecs/modules``. -# This assumes Qt and the current project are both installed to the same -# non-system prefix. Packagers who use ``-DCMAKE_INSTALL_PREFIX=/usr`` will -# certainly want to set ``ECM_MKSPECS_INSTALL_DIR`` to something like -# ``share/qt5/mkspecs/modules``. -# -# The main thing is that this should be the ``modules`` subdirectory of either -# the default qmake ``mkspecs`` directory or of a directory that will be in the -# ``$QMAKEPATH`` environment variable when qmake is run. -# -# :: -# -# ecm_generate_pri_file(BASE_NAME <baseName> -# LIB_NAME <libName> -# [DEPS "<dep> [<dep> [...]]"] -# [FILENAME_VAR <filename_variable>] -# [INCLUDE_INSTALL_DIR <dir>] -# [LIB_INSTALL_DIR <dir>]) -# -# If your CMake project produces a Qt-based library, you may expect there to be -# applications that wish to use it that use a qmake-based build system, rather -# than a CMake-based one. Creating a ``.pri`` file will make use of your -# library convenient for them, in much the same way that CMake config files make -# things convenient for CMake-based applications. -# -# ecm_generate_pri_file() generates just such a file. It requires the -# ``PROJECT_VERSION_STRING`` variable to be set. This is typically set by -# :module:`ECMSetupVersion`, although the project() command in CMake 3.0.0 and -# later can also set this. -# -# BASE_NAME specifies the name qmake project (.pro) files should use to refer to -# the library (eg: KArchive). LIB_NAME is the name of the actual library to -# link to (ie: the first argument to add_library()). DEPS is a space-separated -# list of the base names of other libraries (for Qt libraries, use the same -# names you use with the ``QT`` variable in a qmake project file, such as "core" -# for QtCore). FILENAME_VAR specifies the name of a variable to store the path -# to the generated file in. -# -# INCLUDE_INSTALL_DIR is the path (relative to ``CMAKE_INSTALL_PREFIX``) that -# include files will be installed to. It defaults to -# ``${INCLUDE_INSTALL_DIR}/<baseName>`` if the ``INCLUDE_INSTALL_DIR`` variable -# is set. If that variable is not set, the ``CMAKE_INSTALL_INCLUDEDIR`` variable -# is used instead, and if neither are set ``include`` is used. LIB_INSTALL_DIR -# operates similarly for the installation location for libraries; it defaults to -# ``${LIB_INSTALL_DIR}``, ``${CMAKE_INSTALL_LIBDIR}`` or ``lib``, in that order. -# -# Example usage: -# -# .. code-block:: cmake -# -# ecm_generate_pri_file( -# BASE_NAME KArchive -# LIB_NAME KF5KArchive -# DEPS "core" -# FILENAME_VAR pri_filename -# ) -# install(FILES ${pri_filename} DESTINATION ${ECM_MKSPECS_INSTALL_DIR}) -# -# A qmake-based project that wished to use this would then do:: -# -# QT += KArchive -# -# in their ``.pro`` file. -# -# Since pre-1.0.0. - -#============================================================================= # SPDX-FileCopyrightText: 2014 David Faure <faure@kde.org> # # SPDX-License-Identifier: BSD-3-Clause +#[=======================================================================[.rst: +ECMGeneratePriFile +------------------ + +Generate a ``.pri`` file for the benefit of qmake-based projects. + +As well as the function below, this module creates the cache variable +``ECM_MKSPECS_INSTALL_DIR`` and sets the default value to ``mkspecs/modules``. +This assumes Qt and the current project are both installed to the same +non-system prefix. Packagers who use ``-DCMAKE_INSTALL_PREFIX=/usr`` will +certainly want to set ``ECM_MKSPECS_INSTALL_DIR`` to something like +``share/qt5/mkspecs/modules``. + +The main thing is that this should be the ``modules`` subdirectory of either +the default qmake ``mkspecs`` directory or of a directory that will be in the +``$QMAKEPATH`` environment variable when qmake is run. + +:: + + ecm_generate_pri_file(BASE_NAME <baseName> + LIB_NAME <libName> + [DEPS "<dep> [<dep> [...]]"] + [FILENAME_VAR <filename_variable>] + [INCLUDE_INSTALL_DIR <dir>] + [LIB_INSTALL_DIR <dir>]) + +If your CMake project produces a Qt-based library, you may expect there to be +applications that wish to use it that use a qmake-based build system, rather +than a CMake-based one. Creating a ``.pri`` file will make use of your +library convenient for them, in much the same way that CMake config files make +things convenient for CMake-based applications. + +ecm_generate_pri_file() generates just such a file. It requires the +``PROJECT_VERSION_STRING`` variable to be set. This is typically set by +:module:`ECMSetupVersion`, although the project() command in CMake 3.0.0 and +later can also set this. + +BASE_NAME specifies the name qmake project (.pro) files should use to refer to +the library (eg: KArchive). LIB_NAME is the name of the actual library to +link to (ie: the first argument to add_library()). DEPS is a space-separated +list of the base names of other libraries (for Qt libraries, use the same +names you use with the ``QT`` variable in a qmake project file, such as "core" +for QtCore). FILENAME_VAR specifies the name of a variable to store the path +to the generated file in. + +INCLUDE_INSTALL_DIR is the path (relative to ``CMAKE_INSTALL_PREFIX``) that +include files will be installed to. It defaults to +``${INCLUDE_INSTALL_DIR}/<baseName>`` if the ``INCLUDE_INSTALL_DIR`` variable +is set. If that variable is not set, the ``CMAKE_INSTALL_INCLUDEDIR`` variable +is used instead, and if neither are set ``include`` is used. LIB_INSTALL_DIR +operates similarly for the installation location for libraries; it defaults to +``${LIB_INSTALL_DIR}``, ``${CMAKE_INSTALL_LIBDIR}`` or ``lib``, in that order. + +Example usage: + +.. code-block:: cmake + + ecm_generate_pri_file( + BASE_NAME KArchive + LIB_NAME KF5KArchive + DEPS "core" + FILENAME_VAR pri_filename + ) + install(FILES ${pri_filename} DESTINATION ${ECM_MKSPECS_INSTALL_DIR}) + +A qmake-based project that wished to use this would then do:: + + QT += KArchive + +in their ``.pro`` file. + +Since pre-1.0.0. +#]=======================================================================] + # Replicate the logic from KDEInstallDirs.cmake as we can't depend on it # Ask qmake if we're using the same prefix as Qt set(_askqmake OFF) diff --git a/modules/ECMGenerateQmlTypes.cmake b/modules/ECMGenerateQmlTypes.cmake index 7e4899de..d6e12426 100644 --- a/modules/ECMGenerateQmlTypes.cmake +++ b/modules/ECMGenerateQmlTypes.cmake @@ -1,32 +1,32 @@ -#.rst: -# ECMGenerateQmlTypes -# ------------------- -# -# Generates plugins.qmltypes files for QML plugins. -# -# :: -# -# ecm_generate_qmltypes(<org.kde.pluginname> 1.3 -# DESTINATION <${KDE_INSTALL_QMLDIR}/org/kde/pluginname>) -# -# Makes it possible to generate plugins.qmltypes files for the QML plugins that -# our project offers. These files offer introspection upon our plugin and are -# useful for integrating with IDE language support of our plugin. It offers -# information about the objects its methods and their argument types. -# -# The developer will be in charge of making sure that these files are up to date. -# The plugin.qmltypes file will sit in the source directory. This function will -# include the code that installs the file in the right place and a small unit -# test named qmltypes-pluginname-version that makes sure that it doesn't need updating. -# -# -# Since 5.33.0 - -#============================================================================= # SPDX-FileCopyrightText: 2017 Aleix Pol Gonzalez <aleixpol@kde.org> # # SPDX-License-Identifier: BSD-3-Clause +#[=======================================================================[.rst: +ECMGenerateQmlTypes +------------------- + +Generates plugins.qmltypes files for QML plugins. + +:: + + ecm_generate_qmltypes(<org.kde.pluginname> 1.3 + DESTINATION <${KDE_INSTALL_QMLDIR}/org/kde/pluginname>) + +Makes it possible to generate plugins.qmltypes files for the QML plugins that +our project offers. These files offer introspection upon our plugin and are +useful for integrating with IDE language support of our plugin. It offers +information about the objects its methods and their argument types. + +The developer will be in charge of making sure that these files are up to date. +The plugin.qmltypes file will sit in the source directory. This function will +include the code that installs the file in the right place and a small unit +test named qmltypes-pluginname-version that makes sure that it doesn't need updating. + + +Since 5.33.0 +#]=======================================================================] + include(CMakeParseArguments) function(ecm_generate_qmltypes) if (NOT TARGET qmltypes) diff --git a/modules/ECMInstallIcons.cmake b/modules/ECMInstallIcons.cmake index e2a1a2d8..49cfc2da 100644 --- a/modules/ECMInstallIcons.cmake +++ b/modules/ECMInstallIcons.cmake @@ -1,69 +1,3 @@ -#.rst: -# ECMInstallIcons -# --------------- -# -# Installs icons, sorting them into the correct directories according to the -# FreeDesktop.org icon naming specification. -# -# :: -# -# ecm_install_icons(ICONS <icon> [<icon> [...]] -# DESTINATION <icon_install_dir> -# [LANG <l10n_code>] -# [THEME <theme>]) -# -# The given icons, whose names must match the pattern:: -# -# <size>-<group>-<name>.<ext> -# -# will be installed to the appropriate subdirectory of DESTINATION according to -# the FreeDesktop.org icon naming scheme. By default, they are installed to the -# "hicolor" theme, but this can be changed using the THEME argument. If the -# icons are localized, the LANG argument can be used to install them in a -# locale-specific directory. -# -# ``<size>`` is a numeric pixel size (typically 16, 22, 32, 48, 64, 128 or 256) -# or ``sc`` for scalable (SVG) files, ``<group>`` is one of the standard -# FreeDesktop.org icon groups (actions, animations, apps, categories, devices, -# emblems, emotes, intl, mimetypes, places, status) and ``<ext>`` is one of -# ``.png``, ``.mng`` or ``.svgz``. -# -# The typical installation directory is ``share/icons``. -# -# .. code-block:: cmake -# -# ecm_install_icons(ICONS 22-actions-menu_new.png -# DESTINATION share/icons) -# -# The above code will install the file ``22-actions-menu_new.png`` as -# ``${CMAKE_INSTALL_PREFIX}/share/icons/<theme>/22x22/actions/menu_new.png`` -# -# Users of the :kde-module:`KDEInstallDirs` module would normally use -# ``${KDE_INSTALL_ICONDIR}`` as the DESTINATION, while users of the GNUInstallDirs -# module should use ``${CMAKE_INSTALL_DATAROOTDIR}/icons``. -# -# An old form of arguments will also be accepted:: -# -# ecm_install_icons(<icon_install_dir> [<l10n_code>]) -# -# This matches files named like:: -# -# <theme><size>-<group>-<name>.<ext> -# -# where ``<theme>`` is one of -# -# * ``hi`` for hicolor -# * ``lo`` for locolor -# * ``cr`` for the Crystal icon theme -# * ``ox`` for the Oxygen icon theme -# * ``br`` for the Breeze icon theme -# -# With this syntax, the file ``hi22-actions-menu_new.png`` would be installed -# into ``<icon_install_dir>/hicolor/22x22/actions/menu_new.png`` -# -# Since pre-1.0.0. - -#============================================================================= # SPDX-FileCopyrightText: 2014 Alex Merry <alex.merry@kde.org> # SPDX-FileCopyrightText: 2013 David Edmundson <kde@davidedmundson.co.uk> # SPDX-FileCopyrightText: 2008 Chusslove Illich <caslav.ilic@gmx.net> @@ -71,6 +5,72 @@ # # SPDX-License-Identifier: BSD-3-Clause +#[=======================================================================[.rst: +ECMInstallIcons +--------------- + +Installs icons, sorting them into the correct directories according to the +FreeDesktop.org icon naming specification. + +:: + + ecm_install_icons(ICONS <icon> [<icon> [...]] + DESTINATION <icon_install_dir> + [LANG <l10n_code>] + [THEME <theme>]) + +The given icons, whose names must match the pattern:: + + <size>-<group>-<name>.<ext> + +will be installed to the appropriate subdirectory of DESTINATION according to +the FreeDesktop.org icon naming scheme. By default, they are installed to the +"hicolor" theme, but this can be changed using the THEME argument. If the +icons are localized, the LANG argument can be used to install them in a +locale-specific directory. + +``<size>`` is a numeric pixel size (typically 16, 22, 32, 48, 64, 128 or 256) +or ``sc`` for scalable (SVG) files, ``<group>`` is one of the standard +FreeDesktop.org icon groups (actions, animations, apps, categories, devices, +emblems, emotes, intl, mimetypes, places, status) and ``<ext>`` is one of +``.png``, ``.mng`` or ``.svgz``. + +The typical installation directory is ``share/icons``. + +.. code-block:: cmake + + ecm_install_icons(ICONS 22-actions-menu_new.png + DESTINATION share/icons) + +The above code will install the file ``22-actions-menu_new.png`` as +``${CMAKE_INSTALL_PREFIX}/share/icons/<theme>/22x22/actions/menu_new.png`` + +Users of the :kde-module:`KDEInstallDirs` module would normally use +``${KDE_INSTALL_ICONDIR}`` as the DESTINATION, while users of the GNUInstallDirs +module should use ``${CMAKE_INSTALL_DATAROOTDIR}/icons``. + +An old form of arguments will also be accepted:: + + ecm_install_icons(<icon_install_dir> [<l10n_code>]) + +This matches files named like:: + + <theme><size>-<group>-<name>.<ext> + +where ``<theme>`` is one of + +* ``hi`` for hicolor +* ``lo`` for locolor +* ``cr`` for the Crystal icon theme +* ``ox`` for the Oxygen icon theme +* ``br`` for the Breeze icon theme + +With this syntax, the file ``hi22-actions-menu_new.png`` would be installed +into ``<icon_install_dir>/hicolor/22x22/actions/menu_new.png`` + +Since pre-1.0.0. +#]=======================================================================] + include(CMakeParseArguments) # A "map" of short type names to the directories. diff --git a/modules/ECMMarkAsTest.cmake b/modules/ECMMarkAsTest.cmake index d30dd1b1..8ac5e8ba 100644 --- a/modules/ECMMarkAsTest.cmake +++ b/modules/ECMMarkAsTest.cmake @@ -1,27 +1,27 @@ -#.rst: -# ECMMarkAsTest -# ------------- -# -# Marks a target as only being required for tests. -# -# :: -# -# ecm_mark_as_test(<target1> [<target2> [...]]) -# -# This will cause the specified targets to not be built unless either -# BUILD_TESTING is set to ON or the user invokes the ``buildtests`` target. -# -# BUILD_TESTING is created as a cache variable by the CTest module and by the -# :kde-module:`KDECMakeSettings` module. -# -# Since pre-1.0.0. - -#============================================================================= # SPDX-FileCopyrightText: 2012 Stephen Kelly <steveire@gmail.com> # SPDX-FileCopyrightText: 2012 Alex Neundorf <neundorf@kde.org> # # SPDX-License-Identifier: BSD-3-Clause +#[=======================================================================[.rst: +ECMMarkAsTest +------------- + +Marks a target as only being required for tests. + +:: + + ecm_mark_as_test(<target1> [<target2> [...]]) + +This will cause the specified targets to not be built unless either +BUILD_TESTING is set to ON or the user invokes the ``buildtests`` target. + +BUILD_TESTING is created as a cache variable by the CTest module and by the +:kde-module:`KDECMakeSettings` module. + +Since pre-1.0.0. +#]=======================================================================] + if (NOT BUILD_TESTING) if(NOT TARGET buildtests) add_custom_target(buildtests) diff --git a/modules/ECMMarkNonGuiExecutable.cmake b/modules/ECMMarkNonGuiExecutable.cmake index fb073e1b..48b4feaa 100644 --- a/modules/ECMMarkNonGuiExecutable.cmake +++ b/modules/ECMMarkNonGuiExecutable.cmake @@ -1,24 +1,24 @@ -#.rst: -# ECMMarkNonGuiExecutable -# ----------------------- -# -# Marks an executable target as not being a GUI application. -# -# :: -# -# ecm_mark_nongui_executable(<target1> [<target2> [...]]) -# -# This will indicate to CMake that the specified targets should not be included -# in a MACOSX_BUNDLE and should not be WIN32_EXECUTABLEs. On platforms other -# than MacOS X or Windows, this will have no effect. -# -# Since pre-1.0.0. - -#============================================================================= # SPDX-FileCopyrightText: 2012 Stephen Kelly <steveire@gmail.com> # # SPDX-License-Identifier: BSD-3-Clause +#[=======================================================================[.rst: +ECMMarkNonGuiExecutable +----------------------- + +Marks an executable target as not being a GUI application. + +:: + + ecm_mark_nongui_executable(<target1> [<target2> [...]]) + +This will indicate to CMake that the specified targets should not be included +in a MACOSX_BUNDLE and should not be WIN32_EXECUTABLEs. On platforms other +than MacOS X or Windows, this will have no effect. + +Since pre-1.0.0. +#]=======================================================================] + function(ecm_mark_nongui_executable) foreach(_target ${ARGN}) set_target_properties(${_target} diff --git a/modules/ECMOptionalAddSubdirectory.cmake b/modules/ECMOptionalAddSubdirectory.cmake index 5450e4e7..0eeb1d41 100644 --- a/modules/ECMOptionalAddSubdirectory.cmake +++ b/modules/ECMOptionalAddSubdirectory.cmake @@ -1,38 +1,38 @@ -#.rst: -# ECMOptionalAddSubdirectory -# -------------------------- -# -# Make subdirectories optional. -# -# :: -# -# ecm_optional_add_subdirectory(<dir>) -# -# This behaves like add_subdirectory(), except that it does not complain if the -# directory does not exist. Additionally, if the directory does exist, it -# creates an option to allow the user to skip it. The option will be named -# BUILD_<dir>. -# -# This is useful for "meta-projects" that combine several mostly-independent -# sub-projects. -# -# If the CMake variable DISABLE_ALL_OPTIONAL_SUBDIRECTORIES is set to TRUE for -# the first CMake run on the project, all optional subdirectories will be -# disabled by default (but can of course be enabled via the respective options). -# For example, the following will disable all optional subdirectories except the -# one named "foo": -# -# .. code-block:: sh -# -# cmake -DDISABLE_ALL_OPTIONAL_SUBDIRECTORIES=TRUE -DBUILD_foo=TRUE myproject -# -# Since pre-1.0.0. - -#============================================================================= # SPDX-FileCopyrightText: 2007 Alexander Neundorf <neundorf@kde.org> # # SPDX-License-Identifier: BSD-3-Clause +#[=======================================================================[.rst: +ECMOptionalAddSubdirectory +-------------------------- + +Make subdirectories optional. + +:: + + ecm_optional_add_subdirectory(<dir>) + +This behaves like add_subdirectory(), except that it does not complain if the +directory does not exist. Additionally, if the directory does exist, it +creates an option to allow the user to skip it. The option will be named +BUILD_<dir>. + +This is useful for "meta-projects" that combine several mostly-independent +sub-projects. + +If the CMake variable DISABLE_ALL_OPTIONAL_SUBDIRECTORIES is set to TRUE for +the first CMake run on the project, all optional subdirectories will be +disabled by default (but can of course be enabled via the respective options). +For example, the following will disable all optional subdirectories except the +one named "foo": + +.. code-block:: sh + + cmake -DDISABLE_ALL_OPTIONAL_SUBDIRECTORIES=TRUE -DBUILD_foo=TRUE myproject + +Since pre-1.0.0. +#]=======================================================================] + function(ECM_OPTIONAL_ADD_SUBDIRECTORY _dir) get_filename_component(_fullPath ${_dir} ABSOLUTE) if(EXISTS ${_fullPath}/CMakeLists.txt) diff --git a/modules/ECMPackageConfigHelpers.cmake b/modules/ECMPackageConfigHelpers.cmake index 8d48772b..6bff6927 100644 --- a/modules/ECMPackageConfigHelpers.cmake +++ b/modules/ECMPackageConfigHelpers.cmake @@ -1,60 +1,60 @@ -#.rst: -# ECMPackageConfigHelpers -# ----------------------- -# -# Helper macros for generating CMake package config files. -# -# ``write_basic_package_version_file()`` is the same as the one provided by the -# `CMakePackageConfigHelpers -# <https://www.cmake.org/cmake/help/v2.8.12/cmake.html#module:CMakePackageConfigHelpers>`_ -# module in CMake; see that module's documentation for -# more information. -# -# :: -# -# ecm_configure_package_config_file(<input> <output> -# INSTALL_DESTINATION <path> -# [PATH_VARS <var1> [<var2> [...]] -# [NO_SET_AND_CHECK_MACRO] -# [NO_CHECK_REQUIRED_COMPONENTS_MACRO]) -# -# -# This behaves in the same way as configure_package_config_file() from CMake -# 2.8.12, except that it adds an extra helper macro: find_dependency(). It is -# highly recommended that you read the `documentation for -# CMakePackageConfigHelpers -# <https://www.cmake.org/cmake/help/v2.8.12/cmake.html#module:CMakePackageConfigHelpers>`_ -# for more information, particularly with regard to the PATH_VARS argument. -# -# Note that there is no argument that will disable the find_dependency() macro; -# if you do not require this macro, you should use -# ``configure_package_config_file`` from the CMakePackageConfigHelpers module. -# -# CMake 3.0 includes a CMakeFindDependencyMacro module that provides the -# find_dependency() macro (which you can ``include()`` in your package config -# file), so this file is only useful for projects wishing to provide config -# files that will work with CMake 2.8.12. -# -# Additional Config File Macros -# ============================= -# -# :: -# -# find_dependency(<dep> [<version> [EXACT]]) -# -# find_dependency() should be used instead of find_package() to find package -# dependencies. It forwards the correct parameters for EXACT, QUIET and -# REQUIRED which were passed to the original find_package() call. It also sets -# an informative diagnostic message if the dependency could not be found. -# -# Since pre-1.0.0. - -#============================================================================= # SPDX-FileCopyrightText: 2014 Alex Merry <alex.merry@kdemail.net> # SPDX-FileCopyrightText: 2013 Stephen Kelly <steveire@gmail.com> # # SPDX-License-Identifier: BSD-3-Clause +#[=======================================================================[.rst: +ECMPackageConfigHelpers +----------------------- + +Helper macros for generating CMake package config files. + +``write_basic_package_version_file()`` is the same as the one provided by the +`CMakePackageConfigHelpers +<https://www.cmake.org/cmake/help/v2.8.12/cmake.html#module:CMakePackageConfigHelpers>`_ +module in CMake; see that module's documentation for +more information. + +:: + + ecm_configure_package_config_file(<input> <output> + INSTALL_DESTINATION <path> + [PATH_VARS <var1> [<var2> [...]] + [NO_SET_AND_CHECK_MACRO] + [NO_CHECK_REQUIRED_COMPONENTS_MACRO]) + + +This behaves in the same way as configure_package_config_file() from CMake +2.8.12, except that it adds an extra helper macro: find_dependency(). It is +highly recommended that you read the `documentation for +CMakePackageConfigHelpers +<https://www.cmake.org/cmake/help/v2.8.12/cmake.html#module:CMakePackageConfigHelpers>`_ +for more information, particularly with regard to the PATH_VARS argument. + +Note that there is no argument that will disable the find_dependency() macro; +if you do not require this macro, you should use +``configure_package_config_file`` from the CMakePackageConfigHelpers module. + +CMake 3.0 includes a CMakeFindDependencyMacro module that provides the +find_dependency() macro (which you can ``include()`` in your package config +file), so this file is only useful for projects wishing to provide config +files that will work with CMake 2.8.12. + +Additional Config File Macros +============================= + +:: + + find_dependency(<dep> [<version> [EXACT]]) + +find_dependency() should be used instead of find_package() to find package +dependencies. It forwards the correct parameters for EXACT, QUIET and +REQUIRED which were passed to the original find_package() call. It also sets +an informative diagnostic message if the dependency could not be found. + +Since pre-1.0.0. +#]=======================================================================] + include(${CMAKE_ROOT}/Modules/CMakePackageConfigHelpers.cmake) set(_ecm_package_config_helpers_included TRUE) diff --git a/modules/ECMPoQmTools.cmake b/modules/ECMPoQmTools.cmake index 6f04181f..d1f90b6b 100644 --- a/modules/ECMPoQmTools.cmake +++ b/modules/ECMPoQmTools.cmake @@ -1,80 +1,80 @@ -#.rst: -# ECMPoQmTools -# ------------ -# -# This module provides the ``ecm_process_po_files_as_qm`` and -# ``ecm_install_po_files_as_qm`` functions for generating QTranslator (.qm) -# catalogs from Gettext (.po) catalogs, and the ``ecm_create_qm_loader`` -# function for generating the necessary code to load them in a Qt application -# or library. -# -# :: -# -# ecm_process_po_files_as_qm(<lang> [ALL] -# [INSTALL_DESTINATION <install_destination>] -# PO_FILES <pofile> [<pofile> [...]]) -# -# Compile .po files into .qm files for the given language. -# -# If INSTALL_DESTINATION is given, the .qm files are installed in -# ``<install_destination>/<lang>/LC_MESSAGES``. Typically, -# ``<install_destination>`` is set to ``share/locale``. -# -# ``ecm_process_po_files_as_qm`` creates a "translations" target. This target -# builds all .po files into .qm files. If ALL is specified, these rules are -# added to the "all" target (and so the .qm files will be built by default). -# -# :: -# -# ecm_create_qm_loader(<source_files_var> <catalog_name>) -# -# Generates C++ code which ensures translations are automatically loaded at -# startup. The generated files are appended to ``<source_files_var>``. -# -# It assumes that the .qm file for the language code ``<lang>`` is installed as -# ``<sharedir>/locale/<lang>/LC_MESSAGES/<catalog_name>.qm``, where -# ``<sharedir>`` is one of the directories given by the ``GenericDataLocation`` -# of ``QStandardPaths``. -# -# Typical usage is like: -# -# .. code-block:: cmake -# -# set(mylib_SRCS foo.cpp bar.cpp) -# ecm_create_qm_loader(mylib_SRCS mylib) -# add_library(mylib ${mylib_SRCS}) -# -# :: -# -# ecm_install_po_files_as_qm(<podir>) -# -# Searches for .po files and installs them to the standard location. -# -# This is a convenience function which relies on all .po files being kept in -# ``<podir>/<lang>/``, where ``<lang>`` is the language the .po files are -# written in. -# -# For example, given the following directory structure:: -# -# po/ -# fr/ -# mylib.po -# -# ``ecm_install_po_files_as_qm(po)`` compiles ``mylib.po`` into ``mylib.qm`` and -# installs it in ``<install_destination>/fr/LC_MESSAGES``. -# ``<install_destination>`` defaults to ``${LOCALE_INSTALL_DIR}`` if defined, -# otherwise it uses ``${CMAKE_INSTALL_LOCALEDIR}`` if that is defined, otherwise -# it uses ``share/locale``. -# -# Since pre-1.0.0. - -#============================================================================= # SPDX-FileCopyrightText: 2007-2009 Kitware, Inc. # SPDX-FileCopyrightText: 2007 Alexander Neundorf <neundorf@kde.org> # SPDX-FileCopyrightText: 2014 Aurélien Gâteau <agateau@kde.org> # # SPDX-License-Identifier: BSD-3-Clause +#[=======================================================================[.rst: +ECMPoQmTools +------------ + +This module provides the ``ecm_process_po_files_as_qm`` and +``ecm_install_po_files_as_qm`` functions for generating QTranslator (.qm) +catalogs from Gettext (.po) catalogs, and the ``ecm_create_qm_loader`` +function for generating the necessary code to load them in a Qt application +or library. + +:: + + ecm_process_po_files_as_qm(<lang> [ALL] + [INSTALL_DESTINATION <install_destination>] + PO_FILES <pofile> [<pofile> [...]]) + +Compile .po files into .qm files for the given language. + +If INSTALL_DESTINATION is given, the .qm files are installed in +``<install_destination>/<lang>/LC_MESSAGES``. Typically, +``<install_destination>`` is set to ``share/locale``. + +``ecm_process_po_files_as_qm`` creates a "translations" target. This target +builds all .po files into .qm files. If ALL is specified, these rules are +added to the "all" target (and so the .qm files will be built by default). + +:: + + ecm_create_qm_loader(<source_files_var> <catalog_name>) + +Generates C++ code which ensures translations are automatically loaded at +startup. The generated files are appended to ``<source_files_var>``. + +It assumes that the .qm file for the language code ``<lang>`` is installed as +``<sharedir>/locale/<lang>/LC_MESSAGES/<catalog_name>.qm``, where +``<sharedir>`` is one of the directories given by the ``GenericDataLocation`` +of ``QStandardPaths``. + +Typical usage is like: + +.. code-block:: cmake + + set(mylib_SRCS foo.cpp bar.cpp) + ecm_create_qm_loader(mylib_SRCS mylib) + add_library(mylib ${mylib_SRCS}) + +:: + + ecm_install_po_files_as_qm(<podir>) + +Searches for .po files and installs them to the standard location. + +This is a convenience function which relies on all .po files being kept in +``<podir>/<lang>/``, where ``<lang>`` is the language the .po files are +written in. + +For example, given the following directory structure:: + + po/ + fr/ + mylib.po + +``ecm_install_po_files_as_qm(po)`` compiles ``mylib.po`` into ``mylib.qm`` and +installs it in ``<install_destination>/fr/LC_MESSAGES``. +``<install_destination>`` defaults to ``${LOCALE_INSTALL_DIR}`` if defined, +otherwise it uses ``${CMAKE_INSTALL_LOCALEDIR}`` if that is defined, otherwise +it uses ``share/locale``. + +Since pre-1.0.0. +#]=======================================================================] + include(CMakeParseArguments) # Copied from FindGettext.cmake diff --git a/modules/ECMQMLModules.cmake b/modules/ECMQMLModules.cmake index 705aac07..58dbde82 100644 --- a/modules/ECMQMLModules.cmake +++ b/modules/ECMQMLModules.cmake @@ -1,35 +1,34 @@ -#.rst: -# ECMQMLModules -# ------------- -# -# Find QML import modules through a find_qmlmodule() call. -# It uses the qmlplugindump application to find the plugins and sets them up as -# runtime dependencies. -# -# This is useful so that when we configure a project we are noified when some -# QML imports are not present in the system, thus having the application compilable -# but fail at runtime. -# -# :: -# -# ecm_find_qmlmodule(<module_name> <version>...) -# -# Any further arguments passed will be forwarded into a find_package() call. See -# find_package() documentation for more information. -# -# Usage example: -# -# .. code-block:: cmake -# -# ecm_find_qmlmodule(org.kde.kirigami 2.1) -# -# Since 5.38.0. -# -#============================================================================= # SPDX-FileCopyrightText: 2015 Aleix Pol Gonzalez <aleixpol@blue-systems.com> # # SPDX-License-Identifier: BSD-3-Clause -#============================================================================= + +#[=======================================================================[.rst: +ECMQMLModules +------------- + +Find QML import modules through a find_qmlmodule() call. +It uses the qmlplugindump application to find the plugins and sets them up as +runtime dependencies. + +This is useful so that when we configure a project we are noified when some +QML imports are not present in the system, thus having the application compilable +but fail at runtime. + +:: + + ecm_find_qmlmodule(<module_name> <version>...) + +Any further arguments passed will be forwarded into a find_package() call. See +find_package() documentation for more information. + +Usage example: + +.. code-block:: cmake + + ecm_find_qmlmodule(org.kde.kirigami 2.1) + +Since 5.38.0. +#]=======================================================================] set(MODULES_DIR ${CMAKE_CURRENT_LIST_DIR}) diff --git a/modules/ECMQtDeclareLoggingCategory.cmake b/modules/ECMQtDeclareLoggingCategory.cmake index a6562333..7de5ae9b 100644 --- a/modules/ECMQtDeclareLoggingCategory.cmake +++ b/modules/ECMQtDeclareLoggingCategory.cmake @@ -1,153 +1,153 @@ -#.rst: -# ECMQtDeclareLoggingCategory -# --------------------------- -# -# This module provides the ``ecm_qt_declare_logging_category`` function for -# generating declarations for logging categories in Qt5, and the -# ``ecm_qt_install_logging_categories`` function for generating and installing -# a file in KDebugSettings format with the info about all those categories, -# as well as a file with info about any renamed categories if defined. -# To include in that file any logging categories that are manually defined -# also a function ``ecm_qt_export_logging_category`` is provided. -# -# :: -# -# ecm_qt_declare_logging_category(<sources_var_name(|target (since 5.80))> -# HEADER <filename> -# IDENTIFIER <identifier> -# CATEGORY_NAME <category_name> -# [OLD_CATEGORY_NAMES <oldest_cat_name> [<second_oldest_cat_name> [...]]] -# [DEFAULT_SEVERITY <Debug|Info|Warning|Critical|Fatal>] -# [EXPORT <exportid>] -# [DESCRIPTION <description>] -# ) -# -# A header file, ``<filename>``, will be generated along with a corresponding -# source file. These will provide a QLoggingCategory category that can be referred -# to from C++ code using ``<identifier>``, and from the logging configuration using -# ``<category_name>``. -# -# The generated source file will be added to the variable with the name -# ``<sources_var_name>``. If the given argument is a target though, instead both the -# generated header file and the generated source file will be added to the target as -# private sources (since 5.80). -# -# If ``<filename>`` is not absolute, it will be taken relative to the current -# binary directory. -# -# If the code is compiled against Qt 5.4 or later, by default it will only log -# output that is at least the severity specified by ``DEFAULT_SEVERITY``, or -# "Info" level if ``DEFAULT_SEVERITY`` is not given. Note that, due to a -# bug in Qt 5.5, "Info" may be treated as more severe than "Fatal". -# -# ``<identifier>`` may include namespaces (eg: ``foo::bar::IDENT``). -# -# If ``EXPORT`` is passed, the category will be registered for the group id -# ``<exportid>``. Info about the categories of that group can then be -# generated in a file and installed by that group id with the -# ``ecm_qt_install_logging_categories`` function. In that case also ``DESCRIPTION`` -# will need to be passed, with ``<description>`` being a short single line text. -# And ``OLD_CATEGORY_NAMES`` can be used to inform about any renamings of the category, -# so user settings can be migrated. Since 5.68.0. -# -# Since 5.14.0. -# -# :: -# -# ecm_qt_export_logging_category( -# IDENTIFIER <identifier> -# CATEGORY_NAME <category_name> -# [OLD_CATEGORY_NAMES <oldest_category_name> [<second_oldest_category_name> [...]]] -# EXPORT <exportid> -# DESCRIPTION <description> -# [DEFAULT_SEVERITY <Debug|Info|Warning|Critical|Fatal>] -# ) -# -# Registers a logging category for being included in the generated and -# installed KDebugSettings files. To be used for categories who are declared by -# manual code or other ways instead of code generated with -# ``ecm_qt_declare_logging_category``. -# -# ``<identifier>`` may include namespaces (eg: ``foo::bar::IDENT``). -# -# ``EXPORT`` specifies the group id with which the category will be registered. -# Info about the categories of that group can then be generated in a file and -# installed by that group id with the ``ecm_qt_install_logging_categories`` function. -# -# ``DESCRIPTION`` specifies a short single line text describing the category. -# -# ``OLD_CATEGORY_NAMES`` can be used to inform about any renamings of the category, -# so user settings can be migrated. -# -# Since 5.68.0. -# -# :: -# -# ecm_qt_install_logging_categories( -# EXPORT <exportid> -# [FILE <filename>] -# DESTINATION <install_path> -# [SORT] -# [COMPONENT <component>] -# ) -# -# Generates and installs a file in KDebugSettings format with the info about all -# the categories registered for the group ``<exportid>``, as well as a file with -# info about any renamed categories, if there are. -# -# The method call needs to be after the last ``ecm_qt_declare_logging_category`` -# call which uses the same ``<exportid>``. This can be in the same directory, or -# any subdirectory or parent directory. -# -# ``EXPORT`` specifies the group id of categories whose information should be -# stored in the file generated and installed. -# -# ``FILE`` specifies the name of the file generated and installed. It will default -# to lower-cased ``<exportid>.categories``. -# -# ``DESTINATION`` specifies where the generated file will be -# installed. -# -# IF ``SORT`` is set, entries will be sorted by identifiers. -# -# ``COMPONENT`` specifies the installation component name with which the install -# rules for the generated file are associated. -# -# Example usage: -# -# .. code-block:: cmake -# -# ecm_qt_declare_logging_category( -# MYPROJECT_SRCS -# HEADER "myproject_debug.h" -# IDENTIFIER "MYPROJECT_DEBUG" -# CATEGORY_NAME "myproject" -# OLD_CATEGORY_NAMES "myprojectlog" -# DESCRIPTION "My project" -# EXPORT MyProject -# ) -# -# ecm_qt_export_logging_category( -# IDENTIFIER "MYPROJECT_SUBMODULE_DEBUG" -# CATEGORY_NAME "myproject.submodule" -# DESCRIPTION "My project - submodule" -# EXPORT MyProject -# ) -# -# ecm_qt_install_logging_categories( -# EXPORT MyProject -# FILE myproject.categories -# DESTINATION "${KDE_INSTALL_LOGGINGCATEGORIESDIR}" -# ) -# -# Since 5.68.0. - -#============================================================================= # SPDX-FileCopyrightText: 2015 Alex Merry <alex.merry@kde.org> # SPDX-FileCopyrightText: 2020 Friedrich W. H. Kossebau <kossebau@kde.org> # # SPDX-License-Identifier: BSD-3-Clause +#[=======================================================================[.rst: +ECMQtDeclareLoggingCategory +--------------------------- + +This module provides the ``ecm_qt_declare_logging_category`` function for +generating declarations for logging categories in Qt5, and the +``ecm_qt_install_logging_categories`` function for generating and installing +a file in KDebugSettings format with the info about all those categories, +as well as a file with info about any renamed categories if defined. +To include in that file any logging categories that are manually defined +also a function ``ecm_qt_export_logging_category`` is provided. + +:: + + ecm_qt_declare_logging_category(<sources_var_name(|target (since 5.80))> + HEADER <filename> + IDENTIFIER <identifier> + CATEGORY_NAME <category_name> + [OLD_CATEGORY_NAMES <oldest_cat_name> [<second_oldest_cat_name> [...]]] + [DEFAULT_SEVERITY <Debug|Info|Warning|Critical|Fatal>] + [EXPORT <exportid>] + [DESCRIPTION <description>] + ) + +A header file, ``<filename>``, will be generated along with a corresponding +source file. These will provide a QLoggingCategory category that can be referred +to from C++ code using ``<identifier>``, and from the logging configuration using +``<category_name>``. + +The generated source file will be added to the variable with the name +``<sources_var_name>``. If the given argument is a target though, instead both the +generated header file and the generated source file will be added to the target as +private sources (since 5.80). + +If ``<filename>`` is not absolute, it will be taken relative to the current +binary directory. + +If the code is compiled against Qt 5.4 or later, by default it will only log +output that is at least the severity specified by ``DEFAULT_SEVERITY``, or +"Info" level if ``DEFAULT_SEVERITY`` is not given. Note that, due to a +bug in Qt 5.5, "Info" may be treated as more severe than "Fatal". + +``<identifier>`` may include namespaces (eg: ``foo::bar::IDENT``). + +If ``EXPORT`` is passed, the category will be registered for the group id +``<exportid>``. Info about the categories of that group can then be +generated in a file and installed by that group id with the +``ecm_qt_install_logging_categories`` function. In that case also ``DESCRIPTION`` +will need to be passed, with ``<description>`` being a short single line text. +And ``OLD_CATEGORY_NAMES`` can be used to inform about any renamings of the category, +so user settings can be migrated. Since 5.68.0. + +Since 5.14.0. + +:: + + ecm_qt_export_logging_category( + IDENTIFIER <identifier> + CATEGORY_NAME <category_name> + [OLD_CATEGORY_NAMES <oldest_category_name> [<second_oldest_category_name> [...]]] + EXPORT <exportid> + DESCRIPTION <description> + [DEFAULT_SEVERITY <Debug|Info|Warning|Critical|Fatal>] + ) + +Registers a logging category for being included in the generated and +installed KDebugSettings files. To be used for categories who are declared by +manual code or other ways instead of code generated with +``ecm_qt_declare_logging_category``. + +``<identifier>`` may include namespaces (eg: ``foo::bar::IDENT``). + +``EXPORT`` specifies the group id with which the category will be registered. +Info about the categories of that group can then be generated in a file and +installed by that group id with the ``ecm_qt_install_logging_categories`` function. + +``DESCRIPTION`` specifies a short single line text describing the category. + +``OLD_CATEGORY_NAMES`` can be used to inform about any renamings of the category, +so user settings can be migrated. + +Since 5.68.0. + +:: + + ecm_qt_install_logging_categories( + EXPORT <exportid> + [FILE <filename>] + DESTINATION <install_path> + [SORT] + [COMPONENT <component>] + ) + +Generates and installs a file in KDebugSettings format with the info about all +the categories registered for the group ``<exportid>``, as well as a file with +info about any renamed categories, if there are. + +The method call needs to be after the last ``ecm_qt_declare_logging_category`` +call which uses the same ``<exportid>``. This can be in the same directory, or +any subdirectory or parent directory. + +``EXPORT`` specifies the group id of categories whose information should be +stored in the file generated and installed. + +``FILE`` specifies the name of the file generated and installed. It will default +to lower-cased ``<exportid>.categories``. + +``DESTINATION`` specifies where the generated file will be +installed. + +IF ``SORT`` is set, entries will be sorted by identifiers. + +``COMPONENT`` specifies the installation component name with which the install +rules for the generated file are associated. + +Example usage: + +.. code-block:: cmake + + ecm_qt_declare_logging_category( + MYPROJECT_SRCS + HEADER "myproject_debug.h" + IDENTIFIER "MYPROJECT_DEBUG" + CATEGORY_NAME "myproject" + OLD_CATEGORY_NAMES "myprojectlog" + DESCRIPTION "My project" + EXPORT MyProject + ) + + ecm_qt_export_logging_category( + IDENTIFIER "MYPROJECT_SUBMODULE_DEBUG" + CATEGORY_NAME "myproject.submodule" + DESCRIPTION "My project - submodule" + EXPORT MyProject + ) + + ecm_qt_install_logging_categories( + EXPORT MyProject + FILE myproject.categories + DESTINATION "${KDE_INSTALL_LOGGINGCATEGORIESDIR}" + ) + +Since 5.68.0. +#]=======================================================================] + include(CMakeParseArguments) set(_ECM_QT_DECLARE_LOGGING_CATEGORY_TEMPLATE_CPP "${CMAKE_CURRENT_LIST_DIR}/ECMQtDeclareLoggingCategory.cpp.in") diff --git a/modules/ECMSetupQtPluginMacroNames.cmake b/modules/ECMSetupQtPluginMacroNames.cmake index e4a03ba5..632149ca 100644 --- a/modules/ECMSetupQtPluginMacroNames.cmake +++ b/modules/ECMSetupQtPluginMacroNames.cmake @@ -1,102 +1,102 @@ -#.rst: -# ECMSetupQtPluginMacroNames -# -------------------------- -# -# Instruct CMake's automoc about C++ preprocessor macros used to define Qt-style plugins. -# -# :: -# -# ecm_setup_qtplugin_macro_names( -# [JSON_NONE <macro_name> [<macro_name> [...]]] -# [JSON_ARG1 <macro_name> [<macro_name> [...]]] -# [JSON_ARG2 <macro_name> [<macro_name> [...]]] -# [JSON_ARG3 <macro_name> [<macro_name> [...]]] -# [CONFIG_CODE_VARIABLE <variable_name>] ) -# -# CMake's automoc needs some support when parsing C++ source files to detect whether moc -# should be run on those files and if there are also dependencies on other files, like those -# with Qt plugin metadata in JSON format. Because automoc just greps overs the raw plain text -# of the sources without any C++ preprocessor-like processing. -# CMake in newer versions provides the variables ``CMAKE_AUTOMOC_DEPEND_FILTERS`` (CMake >= 3.9.0) -# and ``CMAKE_AUTOMOC_MACRO_NAMES`` (CMake >= 3.10) to allow the developer to assist automoc. -# -# This macro cares for the explicit setup needed for those variables for common cases of -# C++ preprocessor macros used for Qt-style plugins. -# -# JSON_NONE lists the names of C++ preprocessor macros for Qt-style plugins which do not refer to -# external files with the plugin metadata. -# -# JSON_ARG1 lists the names of C++ preprocessor macros for Qt-style plugins where the first argument -# to the macro is the name of the external file with the plugin metadata. -# -# JSON_ARG2 is the same as JSON_ARG1 but with the file name being the second argument. -# -# JSON_ARG3 is the same as JSON_ARG1 but with the file name being the third argument. -# -# CONFIG_CODE_VARIABLE specifies the name of the variable which will get set as -# value some generated CMake code for instructing automoc for the given macro names, -# as useful in an installed CMake config file. The variable can then be used as usual in -# the template file for such a CMake config file, by ``@<variable_name>@``. -# -# -# Example usage: -# -# Given some plugin-oriented Qt-based software which defines a custom C++ preprocessor -# macro ``EXPORT_MYPLUGIN`` for declaring the central plugin object: -# -# .. code-block:: c++ -# -# #define EXPORT_MYPLUGIN_WITH_JSON(classname, jsonFile) \ -# class classname : public QObject \ -# { \ -# Q_OBJECT \ -# Q_PLUGIN_METADATA(IID "myplugin" FILE jsonFile) \ -# explicit classname() {} \ -# }; -# -# In the CMake buildsystem of the library one calls -# -# .. code-block:: cmake -# -# ecm_setup_qtplugin_macro_names( -# JSON_ARG2 -# EXPORT_MYPLUGIN_WITH_JSON -# ) -# -# to instruct automoc about the usage of that macro in the sources of the -# library itself. -# -# Given the software installs a library including the header with the macro -# definition and a CMake config file, so 3rd-party can create additional -# plugins by linking against the library, one passes additionally the name of -# a variable which shall be set as value the CMake code needed to instruct -# automoc about the usage of that macro. -# -# .. code-block:: cmake -# -# ecm_setup_qtplugin_macro_names( -# JSON_ARG2 -# EXPORT_MYPLUGIN_WITH_JSON -# CONFIG_CODE_VARIABLE -# PACKAGE_SETUP_AUTOMOC_VARIABLES -# ) -# -# This variable then is used in the template file (e.g. -# ``MyProjectConfig.cmake.in``) for the libary's installed CMake config file -# and that way will ensure that in the 3rd-party plugin's buildsystem -# automoc is instructed as well as needed: -# -# :: -# -# @PACKAGE_SETUP_AUTOMOC_VARIABLES@ -# -# Since 5.45.0. - -#============================================================================= # SPDX-FileCopyrightText: 2018 Friedrich W. H. Kossebau <kossebau@kde.org> # # SPDX-License-Identifier: BSD-3-Clause +#[=======================================================================[.rst: +ECMSetupQtPluginMacroNames +-------------------------- + +Instruct CMake's automoc about C++ preprocessor macros used to define Qt-style plugins. + +:: + + ecm_setup_qtplugin_macro_names( + [JSON_NONE <macro_name> [<macro_name> [...]]] + [JSON_ARG1 <macro_name> [<macro_name> [...]]] + [JSON_ARG2 <macro_name> [<macro_name> [...]]] + [JSON_ARG3 <macro_name> [<macro_name> [...]]] + [CONFIG_CODE_VARIABLE <variable_name>] ) + +CMake's automoc needs some support when parsing C++ source files to detect whether moc +should be run on those files and if there are also dependencies on other files, like those +with Qt plugin metadata in JSON format. Because automoc just greps overs the raw plain text +of the sources without any C++ preprocessor-like processing. +CMake in newer versions provides the variables ``CMAKE_AUTOMOC_DEPEND_FILTERS`` (CMake >= 3.9.0) +and ``CMAKE_AUTOMOC_MACRO_NAMES`` (CMake >= 3.10) to allow the developer to assist automoc. + +This macro cares for the explicit setup needed for those variables for common cases of +C++ preprocessor macros used for Qt-style plugins. + +``JSON_NONE`` lists the names of C++ preprocessor macros for Qt-style plugins which do not refer to +external files with the plugin metadata. + +``JSON_ARG1`` lists the names of C++ preprocessor macros for Qt-style plugins where the first argument +to the macro is the name of the external file with the plugin metadata. + +``JSON_ARG2`` is the same as ``JSON_ARG1`` but with the file name being the second argument. + +``JSON_ARG3`` is the same as ``JSON_ARG1`` but with the file name being the third argument. + +``CONFIG_CODE_VARIABLE`` specifies the name of the variable which will get set as +value some generated CMake code for instructing automoc for the given macro names, +as useful in an installed CMake config file. The variable can then be used as usual in +the template file for such a CMake config file, by ``@<variable_name>@``. + + +Example usage: + +Given some plugin-oriented Qt-based software which defines a custom C++ preprocessor +macro ``EXPORT_MYPLUGIN`` for declaring the central plugin object: + +.. code-block:: c++ + + #define EXPORT_MYPLUGIN_WITH_JSON(classname, jsonFile) \ + class classname : public QObject \ + { \ + Q_OBJECT \ + Q_PLUGIN_METADATA(IID "myplugin" FILE jsonFile) \ + explicit classname() {} \ + }; + +In the CMake buildsystem of the library one calls + +.. code-block:: cmake + + ecm_setup_qtplugin_macro_names( + JSON_ARG2 + EXPORT_MYPLUGIN_WITH_JSON + ) + +to instruct automoc about the usage of that macro in the sources of the +library itself. + +Given the software installs a library including the header with the macro +definition and a CMake config file, so 3rd-party can create additional +plugins by linking against the library, one passes additionally the name of +a variable which shall be set as value the CMake code needed to instruct +automoc about the usage of that macro. + +.. code-block:: cmake + + ecm_setup_qtplugin_macro_names( + JSON_ARG2 + EXPORT_MYPLUGIN_WITH_JSON + CONFIG_CODE_VARIABLE + PACKAGE_SETUP_AUTOMOC_VARIABLES + ) + +This variable then is used in the template file (e.g. +``MyProjectConfig.cmake.in``) for the libary's installed CMake config file +and that way will ensure that in the 3rd-party plugin's buildsystem +automoc is instructed as well as needed: + +:: + + @PACKAGE_SETUP_AUTOMOC_VARIABLES@ + +Since 5.45.0. +#]=======================================================================] + include(CMakePackageConfigHelpers) macro(ecm_setup_qtplugin_macro_names) diff --git a/modules/ECMSetupVersion.cmake b/modules/ECMSetupVersion.cmake index 65c1688a..3164a620 100644 --- a/modules/ECMSetupVersion.cmake +++ b/modules/ECMSetupVersion.cmake @@ -1,88 +1,88 @@ -#.rst: -# ECMSetupVersion -# --------------- -# -# Handle library version information. -# -# :: -# -# ecm_setup_version(<version> -# VARIABLE_PREFIX <prefix> -# [SOVERSION <soversion>] -# [VERSION_HEADER <filename>] -# [PACKAGE_VERSION_FILE <filename> [COMPATIBILITY <compat>]] ) -# -# This parses a version string and sets up a standard set of version variables. -# It can optionally also create a C version header file and a CMake package -# version file to install along with the library. -# -# If the ``<version>`` argument is of the form ``<major>.<minor>.<patch>`` -# (or ``<major>.<minor>.<patch>.<tweak>``), The following CMake variables are -# set:: -# -# <prefix>_VERSION_MAJOR - <major> -# <prefix>_VERSION_MINOR - <minor> -# <prefix>_VERSION_PATCH - <patch> -# <prefix>_VERSION - <version> -# <prefix>_VERSION_STRING - <version> (for compatibility: use <prefix>_VERSION instead) -# <prefix>_SOVERSION - <soversion>, or <major> if SOVERSION was not given -# -# If CMake policy CMP0048 is not NEW, the following CMake variables will also -# be set:: -# -# PROJECT_VERSION_MAJOR - <major> -# PROJECT_VERSION_MINOR - <minor> -# PROJECT_VERSION_PATCH - <patch> -# PROJECT_VERSION - <version> -# PROJECT_VERSION_STRING - <version> (for compatibility: use PROJECT_VERSION instead) -# -# If the VERSION_HEADER option is used, a simple C header is generated with the -# given filename. If filename is a relative path, it is interpreted as relative -# to CMAKE_CURRENT_BINARY_DIR. The generated header contains the following -# macros:: -# -# <prefix>_VERSION_MAJOR - <major> as an integer -# <prefix>_VERSION_MINOR - <minor> as an integer -# <prefix>_VERSION_PATCH - <patch> as an integer -# <prefix>_VERSION_STRING - <version> as a C string -# <prefix>_VERSION - the version as an integer -# -# ``<prefix>_VERSION`` has ``<patch>`` in the bottom 8 bits, ``<minor>`` in the -# next 8 bits and ``<major>`` in the remaining bits. Note that ``<patch>`` and -# ``<minor>`` must be less than 256. -# -# If the PACKAGE_VERSION_FILE option is used, a simple CMake package version -# file is created using the write_basic_package_version_file() macro provided by -# CMake. It should be installed in the same location as the Config.cmake file of -# the library so that it can be found by find_package(). If the filename is a -# relative path, it is interpreted as relative to CMAKE_CURRENT_BINARY_DIR. The -# optional COMPATIBILITY option is forwarded to -# write_basic_package_version_file(), and defaults to AnyNewerVersion. -# -# If CMake policy CMP0048 is NEW, an alternative form of the command is -# available:: -# -# ecm_setup_version(PROJECT -# [VARIABLE_PREFIX <prefix>] -# [SOVERSION <soversion>] -# [VERSION_HEADER <filename>] -# [PACKAGE_VERSION_FILE <filename>] ) -# -# This will use the version information set by the project() command. -# VARIABLE_PREFIX defaults to the project name. Note that PROJECT must be the -# first argument. In all other respects, it behaves like the other form of the -# command. -# -# Since pre-1.0.0. -# -# COMPATIBILITY option available since 1.6.0. - -#============================================================================= # SPDX-FileCopyrightText: 2014 Alex Merry <alex.merry@kde.org> # SPDX-FileCopyrightText: 2012 Alexander Neundorf <neundorf@kde.org> # # SPDX-License-Identifier: BSD-3-Clause +#[=======================================================================[.rst: +ECMSetupVersion +--------------- + +Handle library version information. + +:: + + ecm_setup_version(<version> + VARIABLE_PREFIX <prefix> + [SOVERSION <soversion>] + [VERSION_HEADER <filename>] + [PACKAGE_VERSION_FILE <filename> [COMPATIBILITY <compat>]] ) + +This parses a version string and sets up a standard set of version variables. +It can optionally also create a C version header file and a CMake package +version file to install along with the library. + +If the ``<version>`` argument is of the form ``<major>.<minor>.<patch>`` +(or ``<major>.<minor>.<patch>.<tweak>``), The following CMake variables are +set:: + + <prefix>_VERSION_MAJOR - <major> + <prefix>_VERSION_MINOR - <minor> + <prefix>_VERSION_PATCH - <patch> + <prefix>_VERSION - <version> + <prefix>_VERSION_STRING - <version> (for compatibility: use <prefix>_VERSION instead) + <prefix>_SOVERSION - <soversion>, or <major> if SOVERSION was not given + +If CMake policy CMP0048 is not NEW, the following CMake variables will also +be set:: + + PROJECT_VERSION_MAJOR - <major> + PROJECT_VERSION_MINOR - <minor> + PROJECT_VERSION_PATCH - <patch> + PROJECT_VERSION - <version> + PROJECT_VERSION_STRING - <version> (for compatibility: use PROJECT_VERSION instead) + +If the VERSION_HEADER option is used, a simple C header is generated with the +given filename. If filename is a relative path, it is interpreted as relative +to CMAKE_CURRENT_BINARY_DIR. The generated header contains the following +macros:: + + <prefix>_VERSION_MAJOR - <major> as an integer + <prefix>_VERSION_MINOR - <minor> as an integer + <prefix>_VERSION_PATCH - <patch> as an integer + <prefix>_VERSION_STRING - <version> as a C string + <prefix>_VERSION - the version as an integer + +``<prefix>_VERSION`` has ``<patch>`` in the bottom 8 bits, ``<minor>`` in the +next 8 bits and ``<major>`` in the remaining bits. Note that ``<patch>`` and +``<minor>`` must be less than 256. + +If the PACKAGE_VERSION_FILE option is used, a simple CMake package version +file is created using the write_basic_package_version_file() macro provided by +CMake. It should be installed in the same location as the Config.cmake file of +the library so that it can be found by find_package(). If the filename is a +relative path, it is interpreted as relative to CMAKE_CURRENT_BINARY_DIR. The +optional COMPATIBILITY option is forwarded to +write_basic_package_version_file(), and defaults to AnyNewerVersion. + +If CMake policy CMP0048 is NEW, an alternative form of the command is +available:: + + ecm_setup_version(PROJECT + [VARIABLE_PREFIX <prefix>] + [SOVERSION <soversion>] + [VERSION_HEADER <filename>] + [PACKAGE_VERSION_FILE <filename>] ) + +This will use the version information set by the project() command. +VARIABLE_PREFIX defaults to the project name. Note that PROJECT must be the +first argument. In all other respects, it behaves like the other form of the +command. + +Since pre-1.0.0. + +COMPATIBILITY option available since 1.6.0. +#]=======================================================================] + include(CMakePackageConfigHelpers) # save the location of the header template while CMAKE_CURRENT_LIST_DIR diff --git a/modules/ECMSourceVersionControl.cmake b/modules/ECMSourceVersionControl.cmake index aa8164c4..b61c7069 100644 --- a/modules/ECMSourceVersionControl.cmake +++ b/modules/ECMSourceVersionControl.cmake @@ -1,20 +1,20 @@ -#.rst: -# ECMSourceVersionControl -# -------------------------- -# -# Tries to determine whether the source is under version control (git clone, -# svn checkout, etc). -# -# ``ECM_SOURCE_UNDER_VERSION_CONTROL`` is set when indication is found that -# CMAKE_SOURCE_DIR is under version control. -# -# Since 5.63 - -#============================================================================= # SPDX-FileCopyrightText: 2019 Harald Sitter <sitter@kde.org> # # SPDX-License-Identifier: BSD-3-Clause +#[=======================================================================[.rst: +ECMSourceVersionControl +-------------------------- + +Tries to determine whether the source is under version control (git clone, +svn checkout, etc). + +``ECM_SOURCE_UNDER_VERSION_CONTROL`` is set when indication is found that +CMAKE_SOURCE_DIR is under version control. + +Since 5.63 +#]=======================================================================] + if(EXISTS "${CMAKE_SOURCE_DIR}/.git" OR EXISTS "${CMAKE_SOURCE_DIR}/.svn" OR EXISTS "${CMAKE_SOURCE_DIR}/.hg" OR diff --git a/modules/ECMUninstallTarget.cmake b/modules/ECMUninstallTarget.cmake index 4fe049ff..7298012d 100644 --- a/modules/ECMUninstallTarget.cmake +++ b/modules/ECMUninstallTarget.cmake @@ -1,40 +1,40 @@ -#.rst: -# ECMUninstallTarget -# ------------------ -# -# Add an ``uninstall`` target. -# -# By including this module, an ``uninstall`` target will be added to your CMake -# project. This will remove all files installed (or updated) by a previous -# invocation of the ``install`` target. It will not remove files created or -# modified by an ``install(SCRIPT)`` or ``install(CODE)`` command; you should -# create a custom uninstallation target for these and use ``add_dependency`` to -# make the ``uninstall`` target depend on it: -# -# .. code-block:: cmake -# -# include(ECMUninstallTarget) -# install(SCRIPT install-foo.cmake) -# add_custom_target(uninstall_foo COMMAND ${CMAKE_COMMAND} -P uninstall-foo.cmake) -# add_dependency(uninstall uninstall_foo) -# -# The target will fail if the ``install`` target has not yet been run (so it is -# not possible to run CMake on the project and then immediately run the -# ``uninstall`` target). -# -# .. warning:: -# -# CMake deliberately does not provide an ``uninstall`` target by default on -# the basis that such a target has the potential to remove important files -# from a user's computer. Use with caution. -# -# Since 1.7.0. - -#============================================================================= # SPDX-FileCopyrightText: 2015 Alex Merry <alex.merry@kde.org> # # SPDX-License-Identifier: BSD-3-Clause +#[=======================================================================[.rst: +ECMUninstallTarget +------------------ + +Add an ``uninstall`` target. + +By including this module, an ``uninstall`` target will be added to your CMake +project. This will remove all files installed (or updated) by a previous +invocation of the ``install`` target. It will not remove files created or +modified by an ``install(SCRIPT)`` or ``install(CODE)`` command; you should +create a custom uninstallation target for these and use ``add_dependency`` to +make the ``uninstall`` target depend on it: + +.. code-block:: cmake + + include(ECMUninstallTarget) + install(SCRIPT install-foo.cmake) + add_custom_target(uninstall_foo COMMAND ${CMAKE_COMMAND} -P uninstall-foo.cmake) + add_dependency(uninstall uninstall_foo) + +The target will fail if the ``install`` target has not yet been run (so it is +not possible to run CMake on the project and then immediately run the +``uninstall`` target). + +.. warning:: + + CMake deliberately does not provide an ``uninstall`` target by default on + the basis that such a target has the potential to remove important files + from a user's computer. Use with caution. + +Since 1.7.0. +#]=======================================================================] + if (NOT TARGET uninstall) configure_file( "${CMAKE_CURRENT_LIST_DIR}/ecm_uninstall.cmake.in" diff --git a/modules/ECMUseFindModules.cmake b/modules/ECMUseFindModules.cmake index 34c358d1..d8bcf7b4 100644 --- a/modules/ECMUseFindModules.cmake +++ b/modules/ECMUseFindModules.cmake @@ -1,57 +1,57 @@ -#.rst: -# ECMUseFindModules -# ----------------- -# -# Selectively use some of the find modules provided by extra-cmake-modules. -# -# This module is automatically available once extra-cmake-modules has been -# found, so it is not necessary to ``include(ECMUseFindModules)`` explicitly. -# -# :: -# -# ecm_use_find_modules(DIR <dir> -# MODULES module1.cmake [module2.cmake [...]] -# [NO_OVERRIDE]) -# -# This allows selective use of the find modules provided by ECM, including -# deferring to CMake's versions of those modules if it has them. Rather than -# adding ``${ECM_FIND_MODULE_DIR}`` to ``CMAKE_MODULE_PATH``, you use -# ecm_use_find_modules() to copy the modules you want to a local (build) -# directory, and add that to ``CMAKE_MODULE_PATH``. -# -# The find modules given to MODULES will be copied to the directory given by DIR -# (which should be located in ``${CMAKE_BINARY_DIR}`` and added to -# ``CMAKE_MODULE_PATH``). If NO_OVERRIDE is given, only modules not also -# provided by CMake will be copied. -# -# Example: -# -# .. code-block:: cmake -# -# find_package(ECM REQUIRED) -# ecm_use_find_modules( -# DIR ${CMAKE_BINARY_DIR}/cmake -# MODULES FindEGL.cmake -# NO_OVERRIDE -# ) -# set(CMAKE_MODULE_PATH ${CMAKE_BINARY_DIR}/cmake) -# -# This example will make ``FindEGL.cmake`` available in your project, but only -# as long as it is not yet part of CMake. Calls to ``find_package(EGL)`` will -# then make use of this copied module (or the CMake module if it exists). -# -# Another possible use for this macro is to take copies of find modules that can -# be installed along with config files if they are required as a dependency (for -# example, if targets provided by the find module are in the link interface of a -# library). -# -# Since pre-1.0.0. - -#============================================================================= # SPDX-FileCopyrightText: 2011 Alexander Neundorf <neundorf@kde.org> # # SPDX-License-Identifier: BSD-3-Clause +#[=======================================================================[.rst: +ECMUseFindModules +----------------- + +Selectively use some of the find modules provided by extra-cmake-modules. + +This module is automatically available once extra-cmake-modules has been +found, so it is not necessary to ``include(ECMUseFindModules)`` explicitly. + +:: + + ecm_use_find_modules(DIR <dir> + MODULES module1.cmake [module2.cmake [...]] + [NO_OVERRIDE]) + +This allows selective use of the find modules provided by ECM, including +deferring to CMake's versions of those modules if it has them. Rather than +adding ``${ECM_FIND_MODULE_DIR}`` to ``CMAKE_MODULE_PATH``, you use +ecm_use_find_modules() to copy the modules you want to a local (build) +directory, and add that to ``CMAKE_MODULE_PATH``. + +The find modules given to MODULES will be copied to the directory given by DIR +(which should be located in ``${CMAKE_BINARY_DIR}`` and added to +``CMAKE_MODULE_PATH``). If NO_OVERRIDE is given, only modules not also +provided by CMake will be copied. + +Example: + +.. code-block:: cmake + + find_package(ECM REQUIRED) + ecm_use_find_modules( + DIR ${CMAKE_BINARY_DIR}/cmake + MODULES FindEGL.cmake + NO_OVERRIDE + ) + set(CMAKE_MODULE_PATH ${CMAKE_BINARY_DIR}/cmake) + +This example will make ``FindEGL.cmake`` available in your project, but only +as long as it is not yet part of CMake. Calls to ``find_package(EGL)`` will +then make use of this copied module (or the CMake module if it exists). + +Another possible use for this macro is to take copies of find modules that can +be installed along with config files if they are required as a dependency (for +example, if targets provided by the find module are in the link interface of a +library). + +Since pre-1.0.0. +#]=======================================================================] + include(CMakeParseArguments) function(ecm_use_find_modules) diff --git a/modules/ECMWinResolveSymlinks.cmake b/modules/ECMWinResolveSymlinks.cmake index 47a52fb2..25ab6c90 100644 --- a/modules/ECMWinResolveSymlinks.cmake +++ b/modules/ECMWinResolveSymlinks.cmake @@ -1,32 +1,29 @@ -#.rst: -# ECMWinResolveSymlinks -# -------------------------- -# -# Resolve pseudo-symlinks created by git when cloning on Windows. -# -# :: -# -# ecm_win_resolve_symlinks(<dir>) -# -# When git checks out a repository with UNIX symlinks on Windows machine, -# it creates a text file for each symlink, containing a relative path to the -# real file. -# This function would recursively walk over specified directory and replace -# pseudo-symlinks with corresponding real file's contents. It would then run -# git update-index --assume-unchanged on them to trick git. -# -# This is useful for projects like "breeze-icons" that contain many identical -# icons implemented as symlinks. -# -# Since 5.28 - -#============================================================================= # SPDX-FileCopyrightText: 2016 Gleb Popov <6yearold@gmail.com> # # SPDX-License-Identifier: BSD-3-Clause -#============================================================================= -# (To distribute this file outside of extra-cmake-modules, substitute the full -# License text for the above reference.) + +#[=======================================================================[.rst: +ECMWinResolveSymlinks +-------------------------- + +Resolve pseudo-symlinks created by git when cloning on Windows. + +:: + + ecm_win_resolve_symlinks(<dir>) + +When git checks out a repository with UNIX symlinks on Windows machine, +it creates a text file for each symlink, containing a relative path to the +real file. +This function would recursively walk over specified directory and replace +pseudo-symlinks with corresponding real file's contents. It would then run +git update-index --assume-unchanged on them to trick git. + +This is useful for projects like "breeze-icons" that contain many identical +icons implemented as symlinks. + +Since 5.28 +#]=======================================================================] function(ECM_WIN_RESOLVE_SYMLINKS _dir) get_filename_component(dir ${_dir} ABSOLUTE) |