diff options
| author | Friedrich W. H. Kossebau <kossebau@kde.org> | 2021-04-17 11:02:00 +0200 |
|---|---|---|
| committer | Friedrich W. H. Kossebau <kossebau@kde.org> | 2021-04-23 17:49:14 +0000 |
| commit | 5512e03562694ebfe571a3b6068a7d35d9ddfd7a (patch) | |
| tree | 3caca041d3526c8427ec3065642b41a52ad8578c | |
| parent | 38b5d046c4d42232d45bf4464167b2e6feea4cf7 (diff) | |
| download | extra-cmake-modules-5512e03562694ebfe571a3b6068a7d35d9ddfd7a.tar.gz extra-cmake-modules-5512e03562694ebfe571a3b6068a7d35d9ddfd7a.tar.bz2 | |
Modules docs: move rst docs into bracket comments
CMake >= 3.0 supports bracket comments, and the reStructuredText
integration code in sphinx/ext/ecm.py already supports extracting
the docs from a bracket comment instead.
Editing documentation without leading line comment markers is more simple,
e,g. when reflowing text over lines.
With ECM meanwhile requiring CMake 3.5 now it is possible to switch
(and thus follow also the approach used by cmake itself).
NO_CHANGELOG
74 files changed, 4134 insertions, 4169 deletions
diff --git a/cmake/FindQCollectionGenerator.cmake b/cmake/FindQCollectionGenerator.cmake index b7ff0c83..c350dae8 100644 --- a/cmake/FindQCollectionGenerator.cmake +++ b/cmake/FindQCollectionGenerator.cmake @@ -1,36 +1,35 @@ -#.rst: -# FindQCollectionGenerator -# ------------------------ -# -# Try to find the Qt help collection generator. -# -# This will define the following variables: -# -# ``QCollectionGenerator_FOUND`` -# True if (the requested version of) Sphinx is available -# ``QCollectionGenerator_VERSION`` -# The version of the Qt help collection generator. Note that this not the -# same as the version of Qt it is provided by. -# ``QCollectionGenerator_QT_VERSION`` -# The version of Qt that the Qt help collection generator is from. -# ``QCollectionGenerator_EXECUTABLE`` -# The path to the Qt help collection generator executable. -# -# If ``QCollectionGenerator_FOUND`` is TRUE, it will also define the following -# imported target: -# -# ``QCollectionGenerator::Generator`` -# The Qt help collection generator. -# -# In general we recommend using the imported target, as it is easier to use. -# -# Since 5.17.0. - -#============================================================================= # SPDX-FileCopyrightText: 2015 Alex Merry <alex.merry@kde.org> # # SPDX-License-Identifier: BSD-3-Clause -#============================================================================= + +#[=======================================================================[.rst: +FindQCollectionGenerator +------------------------ + +Try to find the Qt help collection generator. + +This will define the following variables: + +``QCollectionGenerator_FOUND`` + True if (the requested version of) Sphinx is available +``QCollectionGenerator_VERSION`` + The version of the Qt help collection generator. Note that this not the + same as the version of Qt it is provided by. +``QCollectionGenerator_QT_VERSION`` + The version of Qt that the Qt help collection generator is from. +``QCollectionGenerator_EXECUTABLE`` + The path to the Qt help collection generator executable. + +If ``QCollectionGenerator_FOUND`` is TRUE, it will also define the following +imported target: + +``QCollectionGenerator::Generator`` + The Qt help collection generator. + +In general we recommend using the imported target, as it is easier to use. + +Since 5.17.0. +#]=======================================================================] find_program(QCollectionGenerator_EXECUTABLE NAMES diff --git a/cmake/FindSphinx.cmake b/cmake/FindSphinx.cmake index dc83ec6d..a25a8e10 100644 --- a/cmake/FindSphinx.cmake +++ b/cmake/FindSphinx.cmake @@ -1,32 +1,31 @@ -#.rst: -# FindSphinx -# ---------- -# -# Try to find the Sphinx documentation builder. -# -# This will define the following variables: -# -# ``Sphinx_FOUND`` -# True if (the requested version of) Sphinx is available -# ``Sphinx_VERSION`` -# The version of the Sphinx documentation builder. -# ``Sphinx_BUILD_EXECUTABLE`` -# The path to the Sphinx documentation builder executable. -# -# If ``Sphinx_FOUND`` is TRUE, it will also define the following imported target: -# -# ``Sphinx::Build`` -# The Sphinx documentation builder. -# -# In general we recommend using the imported target, as it is easier to use. -# -# Since 5.17.0. - -#============================================================================= # SPDX-FileCopyrightText: 2015 Alex Merry <alex.merry@kde.org> # # SPDX-License-Identifier: BSD-3-Clause -#============================================================================= + +#[=======================================================================[.rst: +FindSphinx +---------- + +Try to find the Sphinx documentation builder. + +This will define the following variables: + +``Sphinx_FOUND`` + True if (the requested version of) Sphinx is available +``Sphinx_VERSION`` + The version of the Sphinx documentation builder. +``Sphinx_BUILD_EXECUTABLE`` + The path to the Sphinx documentation builder executable. + +If ``Sphinx_FOUND`` is TRUE, it will also define the following imported target: + +``Sphinx::Build`` + The Sphinx documentation builder. + +In general we recommend using the imported target, as it is easier to use. + +Since 5.17.0. +#]=======================================================================] # Distros sometimes rename Python executables to allow for parallel # installation of Python2 and Python3 versions diff --git a/docs/manual/ecm-developer.7.rst b/docs/manual/ecm-developer.7.rst index 8054306f..b12cc83d 100644 --- a/docs/manual/ecm-developer.7.rst +++ b/docs/manual/ecm-developer.7.rst @@ -17,33 +17,25 @@ devoted to find modules. This guide will only highlight things that are particular to the Extra CMake Modules project. Most of these are stylistic points. For example, the license header for a module -in ECM should look like:: +in ECM should look like: - #============================================================================= - # Copyright 20XX Your Name <your.email@example.com> - # - # Redistribution and use in source and binary forms, with or without - # modification, are permitted provided that the following conditions - # are met: - # - # 1. Redistributions of source code must retain the copyright - # notice, this list of conditions and the following disclaimer. - # 2. Redistributions in binary form must reproduce the copyright - # notice, this list of conditions and the following disclaimer in the - # documentation and/or other materials provided with the distribution. - # 3. The name of the author may not be used to endorse or promote products - # derived from this software without specific prior written permission. +.. code-block:: cmake + + # SPDX-FileCopyrightText: 20XX Your Name <your.email@example.com> # - # THIS SOFTWARE IS PROVIDED BY THE AUTHOR ``AS IS'' AND ANY EXPRESS OR - # IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES - # OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. - # IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY DIRECT, INDIRECT, - # INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT - # NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, - # DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY - # THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT - # (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF - # THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. + # SPDX-License-Identifier: BSD-3-Clause + +Documentation is written in reStructuredText format and put inside a bracket +comment with a ``.rst:`` id after the opening bracket: + +.. code-block:: cmake + + #[=======================================================================[.rst: + The docs + #]=======================================================================] + +(docs/sphinx/ext/ecm.py has code to extract the rst text from a comment with +such wrapping) Functions should be used instead of macros unless there is a good reason not to (and that reason should be noted in a comment), and lowercase should be used for @@ -60,38 +52,41 @@ follow the same pattern. Find Modules ------------ -A good template for find module documentation is:: +A good template for find module documentation is: - #.rst: - # FindFoo - # ------- - # - # Finds the Foo library. - # - # This will define the following variables: - # - # ``Foo_FOUND`` - # True if (the requested version of) Foo is available - # ``Foo_VERSION`` - # The version of Foo, if it is found - # ``Foo_LIBRARIES`` - # This can be passed to target_link_libraries() instead of the ``Foo::Foo`` - # target - # ``Foo_INCLUDE_DIRS`` - # This should be passed to target_include_directories() if the target is not - # used for linking - # ``Foo_DEFINITIONS`` - # This should be passed to target_compile_options() if the target is not - # used for linking - # - # If ``Foo_FOUND`` is TRUE, it will also define the following imported target: - # - # ``Foo::Foo`` - # The Foo library - # - # In general we recommend using the imported target, as it is easier to use. - # Bear in mind, however, that if the target is in the link interface of an - # exported library, it must be made available by the package config file. +.. code-block:: cmake + + #[=======================================================================[.rst: + FindFoo + ------- + + Finds the Foo library. + + This will define the following variables: + + ``Foo_FOUND`` + True if (the requested version of) Foo is available + ``Foo_VERSION`` + The version of Foo, if it is found + ``Foo_LIBRARIES`` + This can be passed to target_link_libraries() instead of the ``Foo::Foo`` + target + ``Foo_INCLUDE_DIRS`` + This should be passed to target_include_directories() if the target is not + used for linking + ``Foo_DEFINITIONS`` + This should be passed to target_compile_options() if the target is not + used for linking + + If ``Foo_FOUND`` is TRUE, it will also define the following imported target: + + ``Foo::Foo`` + The Foo library + + In general we recommend using the imported target, as it is easier to use. + Bear in mind, however, that if the target is in the link interface of an + exported library, it must be made available by the package config file. + #]=======================================================================] Note the use of definition lists for the variables. diff --git a/find-modules/FindCanberra.cmake b/find-modules/FindCanberra.cmake index bda73aca..c54adf99 100644 --- a/find-modules/FindCanberra.cmake +++ b/find-modules/FindCanberra.cmake @@ -1,38 +1,37 @@ -#.rst: -# FindCanberra -# ------------ -# -# Try to find Canberra event sound library. -# -# This will define the following variables: -# -# ``Canberra_FOUND`` -# True if (the requested version of) Canberra is available -# ``Canberra_VERSION`` -# The version of Canberra -# ``Canberra_LIBRARIES`` -# The libraries of Canberra for use with target_link_libraries() -# ``Canberra_INCLUDE_DIRS`` -# The include dirs of Canberra for use with target_include_directories() -# -# If ``Canberra_FOUND`` is TRUE, it will also define the following imported -# target: -# -# ``Canberra::Canberra`` -# The Canberra library -# -# In general we recommend using the imported target, as it is easier to use. -# Bear in mind, however, that if the target is in the link interface of an -# exported library, it must be made available by the package config file. -# -# Since 5.56.0. - -#============================================================================= # SPDX-FileCopyrightText: 2012 Raphael Kubo da Costa <rakuco@FreeBSD.org> # SPDX-FileCopyrightText: 2019 Harald Sitter <sitter@kde.org> # # SPDX-License-Identifier: BSD-3-Clause -#============================================================================= + +#[=======================================================================[.rst: +FindCanberra +------------ + +Try to find Canberra event sound library. + +This will define the following variables: + +``Canberra_FOUND`` + True if (the requested version of) Canberra is available +``Canberra_VERSION`` + The version of Canberra +``Canberra_LIBRARIES`` + The libraries of Canberra for use with target_link_libraries() +``Canberra_INCLUDE_DIRS`` + The include dirs of Canberra for use with target_include_directories() + +If ``Canberra_FOUND`` is TRUE, it will also define the following imported +target: + +``Canberra::Canberra`` + The Canberra library + +In general we recommend using the imported target, as it is easier to use. +Bear in mind, however, that if the target is in the link interface of an +exported library, it must be made available by the package config file. + +Since 5.56.0. +#]=======================================================================] find_package(PkgConfig QUIET) pkg_check_modules(PC_Canberra libcanberra QUIET) diff --git a/find-modules/FindEGL.cmake b/find-modules/FindEGL.cmake index 1350f630..7589dc74 100644 --- a/find-modules/FindEGL.cmake +++ b/find-modules/FindEGL.cmake @@ -1,43 +1,42 @@ -#.rst: -# FindEGL -# ------- -# -# Try to find EGL. -# -# This will define the following variables: -# -# ``EGL_FOUND`` -# True if (the requested version of) EGL is available -# ``EGL_VERSION`` -# The version of EGL; note that this is the API version defined in the -# headers, rather than the version of the implementation (eg: Mesa) -# ``EGL_LIBRARIES`` -# This can be passed to target_link_libraries() instead of the ``EGL::EGL`` -# target -# ``EGL_INCLUDE_DIRS`` -# This should be passed to target_include_directories() if the target is not -# used for linking -# ``EGL_DEFINITIONS`` -# This should be passed to target_compile_options() if the target is not -# used for linking -# -# If ``EGL_FOUND`` is TRUE, it will also define the following imported target: -# -# ``EGL::EGL`` -# The EGL library -# -# In general we recommend using the imported target, as it is easier to use. -# Bear in mind, however, that if the target is in the link interface of an -# exported library, it must be made available by the package config file. -# -# Since pre-1.0.0. - -#============================================================================= # SPDX-FileCopyrightText: 2014 Alex Merry <alex.merry@kde.org> # SPDX-FileCopyrightText: 2014 Martin Gräßlin <mgraesslin@kde.org> # # SPDX-License-Identifier: BSD-3-Clause -#============================================================================= + +#[=======================================================================[.rst: +FindEGL +------- + +Try to find EGL. + +This will define the following variables: + +``EGL_FOUND`` + True if (the requested version of) EGL is available +``EGL_VERSION`` + The version of EGL; note that this is the API version defined in the + headers, rather than the version of the implementation (eg: Mesa) +``EGL_LIBRARIES`` + This can be passed to target_link_libraries() instead of the ``EGL::EGL`` + target +``EGL_INCLUDE_DIRS`` + This should be passed to target_include_directories() if the target is not + used for linking +``EGL_DEFINITIONS`` + This should be passed to target_compile_options() if the target is not + used for linking + +If ``EGL_FOUND`` is TRUE, it will also define the following imported target: + +``EGL::EGL`` + The EGL library + +In general we recommend using the imported target, as it is easier to use. +Bear in mind, however, that if the target is in the link interface of an +exported library, it must be made available by the package config file. + +Since pre-1.0.0. +#]=======================================================================] include(${CMAKE_CURRENT_LIST_DIR}/ECMFindModuleHelpersStub.cmake) include(CheckCXXSourceCompiles) diff --git a/find-modules/FindFontconfig.cmake b/find-modules/FindFontconfig.cmake index ee68b8fa..db5f1830 100644 --- a/find-modules/FindFontconfig.cmake +++ b/find-modules/FindFontconfig.cmake @@ -1,34 +1,33 @@ -#.rst: -# FindFontconfig -# -------------- -# -# Try to find Fontconfig. -# Once done this will define the following variables: -# -# ``Fontconfig_FOUND`` -# True if Fontconfig is available -# ``Fontconfig_INCLUDE_DIRS`` -# The include directory to use for the Fontconfig headers -# ``Fontconfig_LIBRARIES`` -# The Fontconfig libraries for linking -# ``Fontconfig_DEFINITIONS`` -# Compiler switches required for using Fontconfig -# ``Fontconfig_VERSION`` -# The version of Fontconfig that has been found -# -# If ``Fontconfig_FOUND`` is TRUE, it will also define the following -# imported target: -# -# ``Fontconfig::Fontconfig`` -# -# Since 5.57.0. - -#============================================================================= # SPDX-FileCopyrightText: 2006, 2007 Laurent Montel <montel@kde.org> # SPDX-FileCopyrightText: 2018 Volker Krause <vkrause@kde.org> # # SPDX-License-Identifier: BSD-3-Clause -#============================================================================= + +#[=======================================================================[.rst: +FindFontconfig +-------------- + +Try to find Fontconfig. +Once done this will define the following variables: + +``Fontconfig_FOUND`` + True if Fontconfig is available +``Fontconfig_INCLUDE_DIRS`` + The include directory to use for the Fontconfig headers +``Fontconfig_LIBRARIES`` + The Fontconfig libraries for linking +``Fontconfig_DEFINITIONS`` + Compiler switches required for using Fontconfig +``Fontconfig_VERSION`` + The version of Fontconfig that has been found + +If ``Fontconfig_FOUND`` is TRUE, it will also define the following +imported target: + +``Fontconfig::Fontconfig`` + +Since 5.57.0. +#]=======================================================================] # use pkg-config to get the directories and then use these values # in the FIND_PATH() and FIND_LIBRARY() calls diff --git a/find-modules/FindGLIB2.cmake b/find-modules/FindGLIB2.cmake index 454da9b6..67a018f5 100644 --- a/find-modules/FindGLIB2.cmake +++ b/find-modules/FindGLIB2.cmake @@ -1,34 +1,33 @@ -#.rst: -# FindGLIB2 -# --------- -# -# Try to locate the GLib2 library. -# If found, this will define the following variables: -# -# ``GLIB2_FOUND`` -# True if the GLib2 library is available -# ``GLIB2_INCLUDE_DIRS`` -# The GLib2 include directories -# ``GLIB2_LIBRARIES`` -# The GLib2 libraries for linking -# ``GLIB2_INCLUDE_DIR`` -# Deprecated, use ``GLIB2_INCLUDE_DIRS`` -# ``GLIB2_LIBRARY`` -# Deprecated, use ``GLIB2_LIBRARIES`` -# -# If ``GLIB2_FOUND`` is TRUE, it will also define the following -# imported target: -# -# ``GLIB2::GLIB2`` -# The GLIB2 library -# -# Since 5.41.0. - -#============================================================================= # SPDX-FileCopyrightText: 2008 Laurent Montel <montel@kde.org> # # SPDX-License-Identifier: BSD-3-Clause -#============================================================================= + +#[=======================================================================[.rst: +FindGLIB2 +--------- + +Try to locate the GLib2 library. +If found, this will define the following variables: + +``GLIB2_FOUND`` + True if the GLib2 library is available +``GLIB2_INCLUDE_DIRS`` + The GLib2 include directories +``GLIB2_LIBRARIES`` + The GLib2 libraries for linking +``GLIB2_INCLUDE_DIR`` + Deprecated, use ``GLIB2_INCLUDE_DIRS`` +``GLIB2_LIBRARY`` + Deprecated, use ``GLIB2_LIBRARIES`` + +If ``GLIB2_FOUND`` is TRUE, it will also define the following +imported target: + +``GLIB2::GLIB2`` + The GLIB2 library + +Since 5.41.0. +#]=======================================================================] find_package(PkgConfig) pkg_check_modules(PC_GLIB2 QUIET glib-2.0) diff --git a/find-modules/FindGperf.cmake b/find-modules/FindGperf.cmake index 10bb9cda..78dacb4b 100644 --- a/find-modules/FindGperf.cmake +++ b/find-modules/FindGperf.cmake @@ -1,51 +1,51 @@ -#.rst: -# FindGperf -# ----------- -# -# Try to find GNU gperf. -# -# If the gperf executable is not in your PATH, you can provide -# an alternative name or full path location with the ``Gperf_EXECUTABLE`` -# variable. -# -# This will define the following variables: -# -# ``Gperf_FOUND`` -# True if gperf is available. -# -# ``Gperf_EXECUTABLE`` -# The gperf executable. -# -# If ``Gperf_FOUND`` is TRUE, it will also define the following imported -# target: -# -# ``GPerf::Gperf`` -# The gperf executable. -# -# and the following public function: -# -# ecm_gperf_generate(<GperfInput> <OutputFile> <OutputVariable> -# [GENERATION_FLAGS <flags>]) -# -# Run ``gperf`` on ``<GperfInput>`` to generate ``<OutputFile>``, adding it to -# the ``<OutputVariable>`` variable which contains the source for the target -# where ``<OutputFile>`` is going to be built. The optional -# ``GENERATION_FLAGS`` argument is needed to pass extra parameters to -# ``gperf`` (note you cannot override that way the output file). -# -# A simple invocation would be: -# -# .. code-block:: cmake -# -# ecm_gperf_generate(simple.gperf ${CMAKE_CURRENT_BINARY_DIR}/simple.h MySources) -# -# Since 5.35.0. - -#============================================================================= # SPDX-FileCopyrightText: 2016-2017 Pino Toscano <pino@kde.org> # # SPDX-License-Identifier: BSD-3-Clause -#============================================================================= + +#[=======================================================================[.rst: +FindGperf +----------- + +Try to find GNU gperf. + +If the gperf executable is not in your PATH, you can provide +an alternative name or full path location with the ``Gperf_EXECUTABLE`` +variable. + +This will define the following variables: + +``Gperf_FOUND`` + True if gperf is available. + +``Gperf_EXECUTABLE`` + The gperf executable. + +If ``Gperf_FOUND`` is TRUE, it will also define the following imported +target: + +``GPerf::Gperf`` + The gperf executable. + +and the following public function: +:: + + ecm_gperf_generate(<GperfInput> <OutputFile> <OutputVariable> + [GENERATION_FLAGS <flags>]) + +Run ``gperf`` on ``<GperfInput>`` to generate ``<OutputFile>``, adding it to +the ``<OutputVariable>`` variable which contains the source for the target +where ``<OutputFile>`` is going to be built. The optional +``GENERATION_FLAGS`` argument is needed to pass extra parameters to +``gperf`` (note you cannot override that way the output file). + +A simple invocation would be: + +.. code-block:: cmake + + ecm_gperf_generate(simple.gperf ${CMAKE_CURRENT_BINARY_DIR}/simple.h MySources) + +Since 5.35.0. +#]=======================================================================] include(${CMAKE_CURRENT_LIST_DIR}/ECMFindModuleHelpersStub.cmake) diff --git a/find-modules/FindGradle.cmake b/find-modules/FindGradle.cmake index 414ea661..6d8d6929 100644 --- a/find-modules/FindGradle.cmake +++ b/find-modules/FindGradle.cmake @@ -1,30 +1,31 @@ -#.rst: -# FindGradle -# ---------- -# -# Provides the ability to build Android AAR libraries using Gradle. -# -# This relies on the Qt provided Gradle, so a Qt for Android installation -# is required. -# -# gradle_add_aar(<target> -# BUIDLFILE build.gradle -# NAME <aar-name>) -# -# This builds an Android AAR library using the given ``build.gradle`` file. -# -# gradle_install_aar(<target> -# DESTINATION <dest>) -# -# Installs a Android AAR library that has been created with ``gradle_add_aar``. -# -# Since 5.76.0. - -#============================================================================= # SPDX-FileCopyrightText: 2019 Volker Krause <vkrause@kde.org> # # SPDX-License-Identifier: BSD-3-Clause -#============================================================================= + +#[=======================================================================[.rst: +FindGradle +---------- + +Provides the ability to build Android AAR libraries using Gradle. + +This relies on the Qt provided Gradle, so a Qt for Android installation +is required. +:: + + gradle_add_aar(<target> + BUIDLFILE build.gradle + NAME <aar-name>) + +This builds an Android AAR library using the given ``build.gradle`` file. +:: + + gradle_install_aar(<target> + DESTINATION <dest>) + +Installs a Android AAR library that has been created with ``gradle_add_aar``. + +Since 5.76.0. +#]=======================================================================] include(CMakeParseArguments) include(FindPackageHandleStandardArgs) diff --git a/find-modules/FindIcoTool.cmake b/find-modules/FindIcoTool.cmake index 40a45913..11243cd4 100644 --- a/find-modules/FindIcoTool.cmake +++ b/find-modules/FindIcoTool.cmake @@ -1,35 +1,34 @@ -#.rst: -# FindIcoTool -# ----------- -# -# Try to find icotool. -# -# If the icotool executable is not in your PATH, you can provide -# an alternative name or full path location with the ``IcoTool_EXECUTABLE`` -# variable. -# -# This will define the following variables: -# -# ``IcoTool_FOUND`` -# True if icotool is available. -# -# ``IcoTool_EXECUTABLE`` -# The icotool executable. -# -# If ``IcoTool_FOUND`` is TRUE, it will also define the following imported -# target: -# -# ``IcoTool::IcoTool`` -# The icotool executable. -# -# Since 5.49. - -#============================================================================= # SPDX-FileCopyrightText: 2017 Vincent Pinon <vpinon@kde.org> # SPDX-FileCopyrightText: 2014 Alex Merry <alex.merry@kde.org> # # SPDX-License-Identifier: BSD-3-Clause -#============================================================================= + +#[=======================================================================[.rst: +FindIcoTool +----------- + +Try to find icotool. + +If the icotool executable is not in your PATH, you can provide +an alternative name or full path location with the ``IcoTool_EXECUTABLE`` +variable. + +This will define the following variables: + +``IcoTool_FOUND`` + True if icotool is available. + +``IcoTool_EXECUTABLE`` + The icotool executable. + +If ``IcoTool_FOUND`` is TRUE, it will also define the following imported +target: + +``IcoTool::IcoTool`` + The icotool executable. + +Since 5.49. +#]=======================================================================] include(${CMAKE_CURRENT_LIST_DIR}/ECMFindModuleHelpersStub.cmake) ecm_find_package_version_check(IcoTool) diff --git a/find-modules/FindInotify.cmake b/find-modules/FindInotify.cmake index dd021c7f..a5a7c710 100644 --- a/find-modules/FindInotify.cmake +++ b/find-modules/FindInotify.cmake @@ -1,33 +1,32 @@ -#.rst: -# FindInotify -# -------------- -# -# Try to find inotify on this system. This finds: -# - libinotify on Unix like systems, or -# - the kernel's inotify on Linux systems. -# -# This will define the following variables: -# -# ``Inotify_FOUND`` -# True if inotify is available -# ``Inotify_LIBRARIES`` -# This has to be passed to target_link_libraries() -# ``Inotify_INCLUDE_DIRS`` -# This has to be passed to target_include_directories() -# -# On Linux, the libraries and include directories are empty, -# even though ``Inotify_FOUND`` may be set to TRUE. This is because -# no special includes or libraries are needed. On other systems -# these may be needed to use inotify. -# -# Since 5.32.0. - -#============================================================================= # SPDX-FileCopyrightText: 2016 Tobias C. Berner <tcberner@FreeBSD.org> # SPDX-FileCopyrightText: 2017 Adriaan de Groot <groot@kde.org> # # SPDX-License-Identifier: BSD-2-Clause -#============================================================================= + +#[=======================================================================[.rst: +FindInotify +-------------- + +Try to find inotify on this system. This finds: + - libinotify on Unix like systems, or + - the kernel's inotify on Linux systems. + +This will define the following variables: + +``Inotify_FOUND`` + True if inotify is available +``Inotify_LIBRARIES`` + This has to be passed to target_link_libraries() +``Inotify_INCLUDE_DIRS`` + This has to be passed to target_include_directories() + +On Linux, the libraries and include directories are empty, +even though ``Inotify_FOUND`` may be set to TRUE. This is because +no special includes or libraries are needed. On other systems +these may be needed to use inotify. + +Since 5.32.0. +#]=======================================================================] find_path(Inotify_INCLUDE_DIRS sys/inotify.h) diff --git a/find-modules/FindIsoCodes.cmake b/find-modules/FindIsoCodes.cmake index 607a2e7e..5d1051b9 100644 --- a/find-modules/FindIsoCodes.cmake +++ b/find-modules/FindIsoCodes.cmake @@ -1,24 +1,24 @@ -#.rst: -# FindIsoCodes -# ------------ -# -# Try to find iso-codes data files. -# Once done this will define: -# ``IsoCodes_FOUND`` -# Whether the system has iso-codes -# ``IsoCodes_PREFIX`` -# The location in which the iso-codes data files are found -# ``IsoCodes_DOMAINS`` -# The available domains provided by iso-codes -# -# Since 5.80.0. - -#============================================================================= # SPDX-FileCopyrightText: 2016 Pino Toscano <pino@kde.org> # SPDX-FileCopyrightText: 2021 Volker Krause <vkrause@kde.org> # # SPDX-License-Identifier: BSD-3-Clause -#============================================================================= + +#[=======================================================================[.rst: +FindIsoCodes +------------ + +Try to find iso-codes data files. +Once done this will define: + +``IsoCodes_FOUND`` + Whether the system has iso-codes +``IsoCodes_PREFIX`` + The location in which the iso-codes data files are found +``IsoCodes_DOMAINS`` + The available domains provided by iso-codes + +Since 5.80.0. +#]=======================================================================] find_package(PkgConfig) pkg_check_modules(PKG_iso_codes QUIET iso-codes) diff --git a/find-modules/FindKF5.cmake b/find-modules/FindKF5.cmake index c4221467..42c55bab 100644 --- a/find-modules/FindKF5.cmake +++ b/find-modules/FindKF5.cmake @@ -1,30 +1,29 @@ -#.rst: -# FindKF5 -# ------- -# -# Find KDE Frameworks 5 with a single find_package() call. -# -# This will use the package config files provided by the individual frameworks. -# For example, if you wish to find KArchive, which presents itself to CMake as -# KF5Archive (ie: you would do ``find_package(KF5Archive)`` to find it -# directly), you can do -# -# .. code-block:: cmake -# -# find_package(KF5 COMPONENTS Archive) -# -# If all the required components (those given in the COMPONENTS argument, but -# not those given in the OPTIONAL_COMPONENTS argument) are found, ``KF5_FOUND`` -# will be set to true. Otherwise, it will be set to false. -# -# Since pre-1.0.0. - -#============================================================================= # SPDX-FileCopyrightText: 2014 Alex Merry <alex.merry@kde.org> # SPDX-FileCopyrightText: 2013 Stephen Kelly <steveire@gmail.com> # # SPDX-License-Identifier: BSD-3-Clause -#============================================================================= + +#[=======================================================================[.rst: +FindKF5 +------- + +Find KDE Frameworks 5 with a single find_package() call. + +This will use the package config files provided by the individual frameworks. +For example, if you wish to find KArchive, which presents itself to CMake as +KF5Archive (ie: you would do ``find_package(KF5Archive)`` to find it +directly), you can do + +.. code-block:: cmake + + find_package(KF5 COMPONENTS Archive) + +If all the required components (those given in the COMPONENTS argument, but +not those given in the OPTIONAL_COMPONENTS argument) are found, ``KF5_FOUND`` +will be set to true. Otherwise, it will be set to false. + +Since pre-1.0.0. +#]=======================================================================] include(${CMAKE_CURRENT_LIST_DIR}/ECMFindModuleHelpersStub.cmake) diff --git a/find-modules/FindLibExiv2.cmake b/find-modules/FindLibExiv2.cmake index 93f77ff0..fa1bc6b8 100644 --- a/find-modules/FindLibExiv2.cmake +++ b/find-modules/FindLibExiv2.cmake @@ -1,44 +1,43 @@ -#.rst: -# FindLibExiv2 -# ------------ -# -# Try to find the Exiv2 library. -# -# This will define the following variables: -# -# ``LibExiv2_FOUND`` -# True if (the requested version of) Exiv2 is available -# -# ``LibExiv2_VERSION`` -# The version of Exiv2 -# -# ``LibExiv2_INCLUDE_DIRS`` -# The include dirs of Exiv2 for use with target_include_directories() -# -# ``LibExiv2_LIBRARIES`` -# The Exiv2 library for use with target_link_libraries(). -# This can be passed to target_link_libraries() instead of -# the ``LibExiv2::LibExiv2`` target -# -# If ``LibExiv2_FOUND`` is TRUE, it will also define the following imported -# target: -# -# ``LibExiv2::LibExiv2`` -# The Exiv2 library -# -# In general we recommend using the imported target, as it is easier to use. -# Bear in mind, however, that if the target is in the link interface of an -# exported library, it must be made available by the package config file. -# -# Since 5.53.0. -# -#============================================================================= # SPDX-FileCopyrightText: 2018 Christophe Giboudeaux <christophe@krop.fr> # SPDX-FileCopyrightText: 2010 Alexander Neundorf <neundorf@kde.org> # SPDX-FileCopyrightText: 2008 Gilles Caulier <caulier.gilles@gmail.com> # # SPDX-License-Identifier: BSD-3-Clause -#============================================================================= + +#[=======================================================================[.rst: +FindLibExiv2 +------------ + +Try to find the Exiv2 library. + +This will define the following variables: + +``LibExiv2_FOUND`` + True if (the requested version of) Exiv2 is available + +``LibExiv2_VERSION`` + The version of Exiv2 + +``LibExiv2_INCLUDE_DIRS`` + The include dirs of Exiv2 for use with target_include_directories() + +``LibExiv2_LIBRARIES`` + The Exiv2 library for use with target_link_libraries(). + This can be passed to target_link_libraries() instead of + the ``LibExiv2::LibExiv2`` target + +If ``LibExiv2_FOUND`` is TRUE, it will also define the following imported +target: + +``LibExiv2::LibExiv2`` + The Exiv2 library + +In general we recommend using the imported target, as it is easier to use. +Bear in mind, however, that if the target is in the link interface of an +exported library, it must be made available by the package config file. + +Since 5.53.0. +#]=======================================================================] find_package(PkgConfig QUIET) pkg_check_modules(PC_EXIV2 QUIET exiv2) diff --git a/find-modules/FindLibGit2.cmake b/find-modules/FindLibGit2.cmake index 4f823013..9ab6ef34 100644 --- a/find-modules/FindLibGit2.cmake +++ b/find-modules/FindLibGit2.cmake @@ -1,43 +1,42 @@ -#.rst: -# FindLibGit2 -# ----------- -# -# Try to find libgit2 on a Unix system. -# -# This will define the following variables: -# -# ``LIBGIT2_FOUND`` -# True if (the requested version of) libgit2 is available -# ``LIBGIT2_VERSION`` -# The version of libgit2 -# ``LIBGIT2_LIBRARIES`` -# This can be passed to target_link_libraries() instead of the ``LibGit2::LibGit2`` -# target -# ``LIBGIT2_INCLUDE_DIRS`` -# This should be passed to target_include_directories() if the target is not -# used for linking -# ``LIBGIT2_DEFINITIONS`` -# This should be passed to target_compile_options() if the target is not -# used for linking -# -# If ``LIBGIT2_FOUND`` is TRUE, it will also define the following imported target: -# -# ``LibGit2::LibGit2`` -# The libgit2 library -# -# In general we recommend using the imported target, as it is easier to use. -# Bear in mind, however, that if the target is in the link interface of an -# exported library, it must be made available by the package config file. -# -# Since 1.3.0. - -#============================================================================= # SPDX-FileCopyrightText: 2014 Alex Merry <alex.merry@kde.org> # SPDX-FileCopyrightText: 2014 Martin Gräßlin <mgraesslin@kde.org> # SPDX-FileCopyrightText: 2014 Christoph Cullmann <cullmann@kde.org> # # SPDX-License-Identifier: BSD-3-Clause -#============================================================================= + +#[=======================================================================[.rst: +FindLibGit2 +----------- + +Try to find libgit2 on a Unix system. + +This will define the following variables: + +``LIBGIT2_FOUND`` + True if (the requested version of) libgit2 is available +``LIBGIT2_VERSION`` + The version of libgit2 +``LIBGIT2_LIBRARIES`` + This can be passed to target_link_libraries() instead of the ``LibGit2::LibGit2`` + target +``LIBGIT2_INCLUDE_DIRS`` + This should be passed to target_include_directories() if the target is not + used for linking +``LIBGIT2_DEFINITIONS`` + This should be passed to target_compile_options() if the target is not + used for linking + +If ``LIBGIT2_FOUND`` is TRUE, it will also define the following imported target: + +``LibGit2::LibGit2`` + The libgit2 library + +In general we recommend using the imported target, as it is easier to use. +Bear in mind, however, that if the target is in the link interface of an +exported library, it must be made available by the package config file. + +Since 1.3.0. +#]=======================================================================] include(${CMAKE_CURRENT_LIST_DIR}/ECMFindModuleHelpersStub.cmake) diff --git a/find-modules/FindLibcap.cmake b/find-modules/FindLibcap.cmake index a9fc2112..2433a76d 100644 --- a/find-modules/FindLibcap.cmake +++ b/find-modules/FindLibcap.cmake @@ -1,25 +1,26 @@ -#.rst: -# FindLibcap -# ---------- -# Try to find the setcap binary and cap libraries -# -# This will define: -# -# Libcap_FOUND - system has the cap library and setcap binary -# Libcap_LIBRARIES - cap libraries to link against -# SETCAP_EXECUTABLE - path of the setcap binary -# -# In addition, the following targets are defined: -# -# Libcap::SetCapabilities -# -# Since 5.80.0 -# -#===================================================================== # SPDX-FileCopyrightText: 2014 Hrvoje Senjan <hrvoje.senjan@gmail.com> # # SPDX-License-Identifier: BSD-3-Clause -#===================================================================== + +#[=======================================================================[.rst: +FindLibcap +---------- +Try to find the setcap binary and cap libraries + +This will define: + +``Libcap_FOUND`` + system has the cap library and setcap binary +``Libcap_LIBRARIES`` + cap libraries to link against +``SETCAP_EXECUTABLE`` + path of the setcap binary + +In addition, the following targets are defined: + ``Libcap::SetCapabilities`` + +Since 5.80.0 +#]=======================================================================] find_program(SETCAP_EXECUTABLE NAMES setcap DOC "The setcap executable") diff --git a/find-modules/FindOpenEXR.cmake b/find-modules/FindOpenEXR.cmake index 6245b42c..5b14c5c3 100644 --- a/find-modules/FindOpenEXR.cmake +++ b/find-modules/FindOpenEXR.cmake @@ -1,37 +1,36 @@ -#.rst: -# FindOpenEXR -# ----------- -# -# Try to find the OpenEXR libraries. -# -# This will define the following variables: -# -# ``OpenEXR_FOUND`` -# True if OpenEXR is available -# ``OpenEXR_LIBRARIES`` -# Link to these to use OpenEXR -# ``OpenEXR_INCLUDE_DIRS`` -# Include directory for OpenEXR -# ``OpenEXR_DEFINITIONS`` -# Compiler flags required to link against OpenEXR -# -# and the following imported targets: -# -# ``OpenEXR::IlmImf`` -# The OpenEXR core library -# -# In general we recommend using the imported target, as it is easier to use. -# Bear in mind, however, that if the target is in the link interface of an -# exported library, it must be made available by the package config file. -# -# Since pre-1.0.0. - -#============================================================================= # SPDX-FileCopyrightText: 2013-2014 Alex Merry <alex.merry@kdemail.net> # SPDX-FileCopyrightText: 2006 Alexander Neundorf <neundorf@kde.org> # # SPDX-License-Identifier: BSD-3-Clause -#============================================================================= + +#[=======================================================================[.rst: +FindOpenEXR +----------- + +Try to find the OpenEXR libraries. + +This will define the following variables: + +``OpenEXR_FOUND`` + True if OpenEXR is available +``OpenEXR_LIBRARIES`` + Link to these to use OpenEXR +``OpenEXR_INCLUDE_DIRS`` + Include directory for OpenEXR +``OpenEXR_DEFINITIONS`` + Compiler flags required to link against OpenEXR + +and the following imported targets: + +``OpenEXR::IlmImf`` + The OpenEXR core library + +In general we recommend using the imported target, as it is easier to use. +Bear in mind, however, that if the target is in the link interface of an +exported library, it must be made available by the package config file. + +Since pre-1.0.0. +#]=======================================================================] include(${CMAKE_CURRENT_LIST_DIR}/ECMFindModuleHelpersStub.cmake) diff --git a/find-modules/FindPhoneNumber.cmake b/find-modules/FindPhoneNumber.cmake index 76e1039e..303aaa14 100644 --- a/find-modules/FindPhoneNumber.cmake +++ b/find-modules/FindPhoneNumber.cmake @@ -1,37 +1,36 @@ -#.rst: -# FindPhoneNumber -# --------------- -# -# Try to find PhoneNumber. -# -# This is a component-based find module, which makes use of the COMPONENTS and -# OPTIONAL_COMPONENTS arguments to find_module. The following components are -# available:: -# -# PhoneNumber GeoCoding -# -# If no components are specified, this module will act as though all components -# were passed to OPTIONAL_COMPONENTS. -# -# This module will define the following variables, independently of the -# components searched for or found: -# -# ``PhoneNumber_FOUND`` -# True if (the requestion version of) PhoneNumber is available -# -# For each searched-for components, ``PhoneNumber_<component>_FOUND`` will be set to -# TRUE if the corresponding library was found, and FALSE otherwise. If -# ``PhoneNumber_<component>_FOUND`` is TRUE, the imported target ``PhoneNumber::<component>`` -# will be defined. -# -# Since 5.54.0. - -#============================================================================= # SPDX-FileCopyrightText: 2017 Klaralvdalens Datakonsult AB, a KDAB Group company <info@kdab.com> # SPDX-FileCopyrightText: 2018 Volker Krause <vkrause@kde.org> # # SPDX-License-Identifier: BSD-3-Clause -#============================================================================= + +#[=======================================================================[.rst: +FindPhoneNumber +--------------- + +Try to find PhoneNumber. + +This is a component-based find module, which makes use of the COMPONENTS and +OPTIONAL_COMPONENTS arguments to find_module. The following components are +available:: + + PhoneNumber GeoCoding + +If no components are specified, this module will act as though all components +were passed to OPTIONAL_COMPONENTS. + +This module will define the following variables, independently of the +components searched for or found: + +``PhoneNumber_FOUND`` + True if (the requestion version of) PhoneNumber is available + +For each searched-for components, ``PhoneNumber_<component>_FOUND`` will be set to +TRUE if the corresponding library was found, and FALSE otherwise. If +``PhoneNumber_<component>_FOUND`` is TRUE, the imported target ``PhoneNumber::<component>`` +will be defined. + +Since 5.54.0. +#]=======================================================================] include(ECMFindModuleHelpersStub) diff --git a/find-modules/FindPoppler.cmake b/find-modules/FindPoppler.cmake index 35cfdb4f..d93980fd 100644 --- a/find-modules/FindPoppler.cmake +++ b/find-modules/FindPoppler.cmake @@ -1,57 +1,57 @@ -#.rst: -# FindPoppler -# ----------- -# -# Try to find Poppler. -# -# This is a component-based find module, which makes use of the COMPONENTS -# and OPTIONAL_COMPONENTS arguments to find_module. The following components -# are available:: -# -# Core Cpp Qt5 Qt4 Glib -# -# If no components are specified, this module will act as though all components -# were passed to OPTIONAL_COMPONENTS. -# -# This module will define the following variables, independently of the -# components searched for or found: -# -# ``Poppler_FOUND`` -# TRUE if (the requested version of) Poppler is available -# ``Poppler_VERSION`` -# Found Poppler version -# ``Poppler_TARGETS`` -# A list of all targets imported by this module (note that there may be more -# than the components that were requested) -# ``Poppler_LIBRARIES`` -# This can be passed to target_link_libraries() instead of the imported -# targets -# ``Poppler_INCLUDE_DIRS`` -# This should be passed to target_include_directories() if the targets are -# not used for linking -# ``Poppler_DEFINITIONS`` -# This should be passed to target_compile_options() if the targets are not -# used for linking -# -# For each searched-for components, ``Poppler_<component>_FOUND`` will be set to -# TRUE if the corresponding Poppler library was found, and FALSE otherwise. If -# ``Poppler_<component>_FOUND`` is TRUE, the imported target -# ``Poppler::<component>`` will be defined. This module will also attempt to -# determine ``Poppler_*_VERSION`` variables for each imported target, although -# ``Poppler_VERSION`` should normally be sufficient. -# -# In general we recommend using the imported targets, as they are easier to use -# and provide more control. Bear in mind, however, that if any target is in the -# link interface of an exported library, it must be made available by the -# package config file. -# -# Since 5.19 - -#============================================================================= # SPDX-FileCopyrightText: 2015 Alex Richardson <arichardson.kde@gmail.com> # # SPDX-License-Identifier: BSD-3-Clause -#============================================================================= + +#[=======================================================================[.rst: +FindPoppler +----------- + +Try to find Poppler. + +This is a component-based find module, which makes use of the COMPONENTS +and OPTIONAL_COMPONENTS arguments to find_module. The following components +are available:: + + Core Cpp Qt5 Qt4 Glib + +If no components are specified, this module will act as though all components +were passed to OPTIONAL_COMPONENTS. + +This module will define the following variables, independently of the +components searched for or found: + +``Poppler_FOUND`` + TRUE if (the requested version of) Poppler is available +``Poppler_VERSION`` + Found Poppler version +``Poppler_TARGETS`` + A list of all targets imported by this module (note that there may be more + than the components that were requested) +``Poppler_LIBRARIES`` + This can be passed to target_link_libraries() instead of the imported + targets +``Poppler_INCLUDE_DIRS`` + This should be passed to target_include_directories() if the targets are + not used for linking +``Poppler_DEFINITIONS`` + This should be passed to target_compile_options() if the targets are not + used for linking + +For each searched-for components, ``Poppler_<component>_FOUND`` will be set to +TRUE if the corresponding Poppler library was found, and FALSE otherwise. If +``Poppler_<component>_FOUND`` is TRUE, the imported target +``Poppler::<component>`` will be defined. This module will also attempt to +determine ``Poppler_*_VERSION`` variables for each imported target, although +``Poppler_VERSION`` should normally be sufficient. + +In general we recommend using the imported targets, as they are easier to use +and provide more control. Bear in mind, however, that if any target is in the +link interface of an exported library, it must be made available by the +package config file. + +Since 5.19 +#]=======================================================================] + include(${CMAKE_CURRENT_LIST_DIR}/ECMFindModuleHelpersStub.cmake) ecm_find_package_version_check(Poppler) diff --git a/find-modules/FindPulseAudio.cmake b/find-modules/FindPulseAudio.cmake index f8dc1a10..173ee98f 100644 --- a/find-modules/FindPulseAudio.cmake +++ b/find-modules/FindPulseAudio.cmake @@ -1,41 +1,40 @@ -#.rst: -# FindPulseAudio -# -------------- -# -# Try to locate the PulseAudio library. -# If found, this will define the following variables: -# -# ``PulseAudio_FOUND`` -# True if the system has the PulseAudio library of at least -# the minimum version specified by either the version parameter -# to find_package() or the variable PulseAudio_MINIMUM_VERSION -# ``PulseAudio_INCLUDE_DIRS`` -# The PulseAudio include directory -# ``PulseAudio_LIBRARIES`` -# The PulseAudio libraries for linking -# ``PulseAudio_MAINLOOP_LIBRARY`` -# The libraries needed to use PulseAudio Mainloop -# ``PulseAudio_VERSION`` -# The version of PulseAudio that was found -# ``PulseAudio_INCLUDE_DIR`` -# Deprecated, use ``PulseAudio_INCLUDE_DIRS`` -# ``PulseAudio_LIBRARY`` -# Deprecated, use ``PulseAudio_LIBRARIES`` -# -# If ``PulseAudio_FOUND`` is TRUE, it will also define the following -# imported target: -# -# ``PulseAudio::PulseAudio`` -# The PulseAudio library -# -# Since 5.41.0. - -#============================================================================= # SPDX-FileCopyrightText: 2008 Matthias Kretz <kretz@kde.org> # SPDX-FileCopyrightText: 2009 Marcus Hufgard <Marcus.Hufgard@hufgard.de> # # SPDX-License-Identifier: BSD-3-Clause -#============================================================================= + +#[=======================================================================[.rst: +FindPulseAudio +-------------- + +Try to locate the PulseAudio library. +If found, this will define the following variables: + +``PulseAudio_FOUND`` + True if the system has the PulseAudio library of at least + the minimum version specified by either the version parameter + to find_package() or the variable PulseAudio_MINIMUM_VERSION +``PulseAudio_INCLUDE_DIRS`` + The PulseAudio include directory +``PulseAudio_LIBRARIES`` + The PulseAudio libraries for linking +``PulseAudio_MAINLOOP_LIBRARY`` + The libraries needed to use PulseAudio Mainloop +``PulseAudio_VERSION`` + The version of PulseAudio that was found +``PulseAudio_INCLUDE_DIR`` + Deprecated, use ``PulseAudio_INCLUDE_DIRS`` +``PulseAudio_LIBRARY`` + Deprecated, use ``PulseAudio_LIBRARIES`` + +If ``PulseAudio_FOUND`` is TRUE, it will also define the following +imported target: + +``PulseAudio::PulseAudio`` + The PulseAudio library + +Since 5.41.0. +#]=======================================================================] # Support PulseAudio_MINIMUM_VERSION for compatibility: if(NOT PulseAudio_FIND_VERSION) diff --git a/find-modules/FindPythonModuleGeneration.cmake b/find-modules/FindPythonModuleGeneration.cmake index 083b7676..210ba662 100644 --- a/find-modules/FindPythonModuleGeneration.cmake +++ b/find-modules/FindPythonModuleGeneration.cmake @@ -1,66 +1,63 @@ -#.rst: -# FindPythonModuleGeneration -# -------------------------- -# -# This module is experimental and internal. The interface will likely -# change in the coming releases. -# -# Tools and macros for generating python bindings -# -# This will define the following public function: -# -# ecm_generate_python_binding(TARGET <target> -# PYTHONNAMESPACE <namespace> -# MODULENAME <modulename> -# RULES_FILE <rulesfile> -# SIP_DEPENDS <dependencies> -# SIP_INCLUDES <includes> -# HEADERS <headers>) -# -# Invoking the function will create bindings for the <target> for python 2 and 3, -# if available. The bindings will be put in the namespace <namespace> in python, -# and will be available from the module <modulename>. -# -# The optional rules file specifies the rules for creating the bindings -# -# A simple invocation would be: -# -# ecm_generate_python_binding(TARGET KMyTarget -# PYTHONNAMESPACE PyKF5 -# MODULENAME MyTarget -# SIP_DEPENDS QtCore/QtCoremod.sip -# HEADERS ${myTargetHeaders} -# ) -# -# which can then be used from python as -# -# import PyKF5.MyTarget -# -# Inclusion of this module defines the following variables: -# -# ``KDE_INSTALL_PYTHON2DIR``, ``KDE_INSTALL_PYTHON3DIR`` -# destination for generated bindings -# ``KDE_INSTALL_FULL_PYTHON2DIR``, ``KDE_INSTALL_FULL_PYTHON3DIR`` -# corresponding absolute path -# -# If ``KDE_INSTALL_USE_PYTHON2_SYS_PATHS`` is set to TRUE before including this -# module, the default value for ``KDE_INSTALL_PYTHON2DIR`` is instead queried from -# pythons distutil.sysconfig.get_python_lib(). -# If not set, it will default to TRUE if pythons ``sysconfig.PREFIX`` is the same -# as ``CMAKE_INSTALL_PREFIX``, otherwise it defaults to FALSE. -# This variable should NOT be set from within CMakeLists.txt files, instead it -# is intended to be set manually when configuring a project which uses this -# module (e.g. by packagers). -# -# Likewise for ``KDE_INSTALL_USE_PYTHON3_SYS_PATHS`` and ``KDE_INSTALL_PYTHON3DIR``. -# - -#============================================================================= # SPDX-FileCopyrightText: 2016 Stephen Kelly <steveire@gmail.com> # # SPDX-License-Identifier: BSD-3-Clause -#============================================================================= +#[=======================================================================[.rst: +FindPythonModuleGeneration +-------------------------- + +This module is experimental and internal. The interface will likely +change in the coming releases. + +Tools and macros for generating python bindings + +This will define the following public function: + + ecm_generate_python_binding(TARGET <target> + PYTHONNAMESPACE <namespace> + MODULENAME <modulename> + RULES_FILE <rulesfile> + SIP_DEPENDS <dependencies> + SIP_INCLUDES <includes> + HEADERS <headers>) + +Invoking the function will create bindings for the <target> for python 2 and 3, +if available. The bindings will be put in the namespace <namespace> in python, +and will be available from the module <modulename>. + +The optional rules file specifies the rules for creating the bindings + +A simple invocation would be: + + ecm_generate_python_binding(TARGET KMyTarget + PYTHONNAMESPACE PyKF5 + MODULENAME MyTarget + SIP_DEPENDS QtCore/QtCoremod.sip + HEADERS ${myTargetHeaders} + ) + +which can then be used from python as + + import PyKF5.MyTarget + +Inclusion of this module defines the following variables: + +``KDE_INSTALL_PYTHON2DIR``, ``KDE_INSTALL_PYTHON3DIR`` + destination for generated bindings +``KDE_INSTALL_FULL_PYTHON2DIR``, ``KDE_INSTALL_FULL_PYTHON3DIR`` + corresponding absolute path + +If ``KDE_INSTALL_USE_PYTHON2_SYS_PATHS`` is set to TRUE before including this +module, the default value for ``KDE_INSTALL_PYTHON2DIR`` is instead queried from +pythons distutil.sysconfig.get_python_lib(). +If not set, it will default to TRUE if pythons ``sysconfig.PREFIX`` is the same +as ``CMAKE_INSTALL_PREFIX``, otherwise it defaults to FALSE. +This variable should NOT be set from within CMakeLists.txt files, instead it +is intended to be set manually when configuring a project which uses this +module (e.g. by packagers). + +Likewise for ``KDE_INSTALL_USE_PYTHON3_SYS_PATHS`` and ``KDE_INSTALL_PYTHON3DIR``. +#]=======================================================================] macro(_find_python version minor_version) set(_CURRENT_VERSION ${version}.${minor_version}) diff --git a/find-modules/FindQHelpGenerator.cmake b/find-modules/FindQHelpGenerator.cmake index e3cae717..1dbd8e41 100644 --- a/find-modules/FindQHelpGenerator.cmake +++ b/find-modules/FindQHelpGenerator.cmake @@ -1,16 +1,16 @@ -# WARNING: FOR ECM-INTERNAL USE ONLY, DO NOT USE IN OWN PROJECTS -# THIS FILE MIGHT DISAPPEAR IN FUTURE VERSIONS OF ECM. - -# Finds the Qt5 QHelpGenerator -# -# QHelpGenerator_FOUND - True if QHelpGenerator found. -# QHelpGenerator_EXECUTABLE - Path to executable - -#============================================================================= # SPDX-FileCopyrightText: 2016 Friedrich W. H. Kossebau <kossebau@kde.org> # # SPDX-License-Identifier: BSD-3-Clause -#============================================================================= + +#[=======================================================================[.rst: +WARNING: FOR ECM-INTERNAL USE ONLY, DO NOT USE IN OWN PROJECTS +THIS FILE MIGHT DISAPPEAR IN FUTURE VERSIONS OF ECM. + +Finds the Qt5 QHelpGenerator + + QHelpGenerator_FOUND - True if QHelpGenerator found. + QHelpGenerator_EXECUTABLE - Path to executable +#]=======================================================================] find_package(Qt5Help QUIET) if (TARGET Qt5::qhelpgenerator) diff --git a/find-modules/FindQtWaylandScanner.cmake b/find-modules/FindQtWaylandScanner.cmake index efbbe87a..684ea8b8 100644 --- a/find-modules/FindQtWaylandScanner.cmake +++ b/find-modules/FindQtWaylandScanner.cmake @@ -1,68 +1,67 @@ -#.rst: -# FindQtWaylandScanner -# -------------------- -# -# Try to find qtwaylandscanner. -# -# If the qtwaylandscanner executable is not in your PATH, you can provide -# an alternative name or full path location with the ``QtWaylandScanner_EXECUTABLE`` -# variable. -# -# This will define the following variables: -# -# ``QtWaylandScanner_FOUND`` -# True if qtwaylandscanner is available -# -# ``QtWaylandScanner_EXECUTABLE`` -# The qtwaylandscanner executable. -# -# If ``QtWaylandScanner_FOUND`` is TRUE, it will also define the following imported -# target: -# -# ``Wayland::QtScanner`` -# The qtwaylandscanner executable. -# -# This module provides the following functions to generate C++ protocol -# implementations: -# -# - ``ecm_add_qtwayland_client_protocol`` -# - ``ecm_add_qtwayland_server_protocol`` -# -# :: -# -# ecm_add_qtwayland_client_protocol(<source_files_var> -# PROTOCOL <xmlfile> -# BASENAME <basename> -# [PREFIX <prefix>]) -# -# Generate C++ wrapper to Wayland client protocol files from ``<xmlfile>`` -# XML definition for the ``<basename>`` interface and append those files -# to ``<source_files_var>``. Pass the ``<prefix>`` argument if the interface -# names don't start with ``qt_`` or ``wl_``. -# -# WaylandScanner is required and will be searched for. -# -# :: -# -# ecm_add_qtwayland_server_protocol(<source_files_var> -# PROTOCOL <xmlfile> -# BASENAME <basename> -# [PREFIX <prefix>]) -# -# Generate C++ wrapper to Wayland server protocol files from ``<xmlfile>`` -# XML definition for the ``<basename>`` interface and append those files -# to ``<source_files_var>``. Pass the ``<prefix>`` argument if the interface -# names don't start with ``qt_`` or ``wl_``. -# -# WaylandScanner is required and will be searched for. -# -# Since 1.4.0. - -#============================================================================= # SPDX-FileCopyrightText: 2012-2014 Pier Luigi Fiorini <pierluigi.fiorini@gmail.com> # # SPDX-License-Identifier: BSD-3-Clause -#============================================================================= + +#[=======================================================================[.rst: +FindQtWaylandScanner +-------------------- + +Try to find qtwaylandscanner. + +If the qtwaylandscanner executable is not in your PATH, you can provide +an alternative name or full path location with the ``QtWaylandScanner_EXECUTABLE`` +variable. + +This will define the following variables: + +``QtWaylandScanner_FOUND`` + True if qtwaylandscanner is available + +``QtWaylandScanner_EXECUTABLE`` + The qtwaylandscanner executable. + +If ``QtWaylandScanner_FOUND`` is TRUE, it will also define the following imported +target: + +``Wayland::QtScanner`` + The qtwaylandscanner executable. + +This module provides the following functions to generate C++ protocol +implementations: + + - ``ecm_add_qtwayland_client_protocol`` + - ``ecm_add_qtwayland_server_protocol`` + +:: + + ecm_add_qtwayland_client_protocol(<source_files_var> + PROTOCOL <xmlfile> + BASENAME <basename> + [PREFIX <prefix>]) + +Generate C++ wrapper to Wayland client protocol files from ``<xmlfile>`` +XML definition for the ``<basename>`` interface and append those files +to ``<source_files_var>``. Pass the ``<prefix>`` argument if the interface +names don't start with ``qt_`` or ``wl_``. + +WaylandScanner is required and will be searched for. + +:: + + ecm_add_qtwayland_server_protocol(<source_files_var> + PROTOCOL <xmlfile> + BASENAME <basename> + [PREFIX <prefix>]) + +Generate C++ wrapper to Wayland server protocol files from ``<xmlfile>`` +XML definition for the ``<basename>`` interface and append those files +to ``<source_files_var>``. Pass the ``<prefix>`` argument if the interface +names don't start with ``qt_`` or ``wl_``. + +WaylandScanner is required and will be searched for. + +Since 1.4.0. +#]=======================================================================] include(${CMAKE_CURRENT_LIST_DIR}/ECMFindModuleHelpersStub.cmake) include("${ECM_MODULE_DIR}/ECMQueryQmake.cmake") diff --git a/find-modules/FindReuseTool.cmake b/find-modules/FindReuseTool.cmake index adceeeb9..67254639 100644 --- a/find-modules/FindReuseTool.cmake +++ b/find-modules/FindReuseTool.cmake @@ -1,16 +1,16 @@ -# WARNING: FOR ECM-INTERNAL USE ONLY, DO NOT USE IN OWN PROJECTS -# THIS FILE MIGHT DISAPPEAR IN FUTURE VERSIONS OF ECM. - -# Finds the REUSE Tool by FSFE: https://github.com/fsfe/reuse-tool -# -# REUSETOOL_FOUND - True if REUSE tool is found. -# REUSETOOL_EXECUTABLE - Path to executable - -#============================================================================= # SPDX-FileCopyrightText: 2020 Andreas Cord-Landwehr <cordlandwehr@kde.org> # # SPDX-License-Identifier: BSD-3-Clause -#============================================================================= + +#[=======================================================================[.rst: +WARNING: FOR ECM-INTERNAL USE ONLY, DO NOT USE IN OWN PROJECTS +THIS FILE MIGHT DISAPPEAR IN FUTURE VERSIONS OF ECM. + +Finds the REUSE Tool by FSFE: https://github.com/fsfe/reuse-tool + + REUSETOOL_FOUND - True if REUSE tool is found. + REUSETOOL_EXECUTABLE - Path to executable +#]=======================================================================] find_program(REUSETOOL_EXECUTABLE NAMES reuse) diff --git a/find-modules/FindSasl2.cmake b/find-modules/FindSasl2.cmake index b89b0884..7693b0e9 100644 --- a/find-modules/FindSasl2.cmake +++ b/find-modules/FindSasl2.cmake @@ -1,40 +1,38 @@ -#.rst: -# FindSasl2 -# --------- -# -# Try to find the SASL2 library. -# -# This will define the following variables: -# -# ``Sasl2_FOUND`` -# System has SASL2. -# -# ``Sasl2_VERSION`` -# The version of SASL2. -# -# ``Sasl2_INCLUDE_DIRS`` -# This should be passed to target_include_directories() if -# the target is not used for linking. -# -# ``Sasl2_LIBRARIES`` -# The SASL2 library. -# This can be passed to target_link_libraries() instead of -# the ``Sasl2::Sasl2`` target -# -# If ``Sasl2_FOUND`` is TRUE, the following imported target -# will be available: -# -# ``Sasl2::Sasl2`` -# The SASL2 library -# -# Since 5.41.0. -# -#============================================================================= # SPDX-FileCopyrightText: 2006, 2007 Laurent Montel <montel@kde.org> # -# # SPDX-License-Identifier: BSD-3-Clause -#============================================================================= + +#[=======================================================================[.rst: +FindSasl2 +--------- + +Try to find the SASL2 library. + +This will define the following variables: + +``Sasl2_FOUND`` + System has SASL2. + +``Sasl2_VERSION`` + The version of SASL2. + +``Sasl2_INCLUDE_DIRS`` + This should be passed to target_include_directories() if + the target is not used for linking. + +``Sasl2_LIBRARIES`` + The SASL2 library. + This can be passed to target_link_libraries() instead of + the ``Sasl2::Sasl2`` target + +If ``Sasl2_FOUND`` is TRUE, the following imported target +will be available: + +``Sasl2::Sasl2`` + The SASL2 library + +Since 5.41.0. +#]=======================================================================] # NOTE: libsasl2.pc doesn't export the include dir. find_package(PkgConfig QUIET) diff --git a/find-modules/FindSeccomp.cmake b/find-modules/FindSeccomp.cmake index fe9dca8f..26b29dea 100644 --- a/find-modules/FindSeccomp.cmake +++ b/find-modules/FindSeccomp.cmake @@ -1,32 +1,31 @@ -#.rst: -# FindSeccomp -# ----------- -# -# Try to locate the libseccomp library. -# -# This will define the following variables: -# -# ``Seccomp_FOUND`` -# True if the seccomp library is available -# ``Seccomp_INCLUDE_DIRS`` -# The seccomp include directories -# ``Seccomp_LIBRARIES`` -# The seccomp libraries for linking -# -# If ``Seccomp_FOUND`` is TRUE, it will also define the following -# imported target: -# -# ``Seccomp::Seccomp`` -# The Seccomp library -# -# Since 5.44.0. - -#============================================================================= # SPDX-FileCopyrightText: 2017 Martin Flöser <mgraesslin@kde.org> # SPDX-FileCopyrightText: 2017 David Kahles <david.kahles96@gmail.com> # # SPDX-License-Identifier: BSD-3-Clause -#============================================================================= + +#[=======================================================================[.rst: +FindSeccomp +----------- + +Try to locate the libseccomp library. + +This will define the following variables: + +``Seccomp_FOUND`` + True if the seccomp library is available +``Seccomp_INCLUDE_DIRS`` + The seccomp include directories +``Seccomp_LIBRARIES`` + The seccomp libraries for linking + +If ``Seccomp_FOUND`` is TRUE, it will also define the following +imported target: + +``Seccomp::Seccomp`` + The Seccomp library + +Since 5.44.0. +#]=======================================================================] find_package(PkgConfig QUIET) pkg_check_modules(PKG_Libseccomp QUIET libseccomp) diff --git a/find-modules/FindSharedMimeInfo.cmake b/find-modules/FindSharedMimeInfo.cmake index 0b8dec9c..39fba669 100644 --- a/find-modules/FindSharedMimeInfo.cmake +++ b/find-modules/FindSharedMimeInfo.cmake @@ -1,37 +1,36 @@ -#.rst: -# FindSharedMimeInfo -# ------------------ -# -# Try to find the shared-mime-info package. -# -# This will define the following variables: -# -# ``SharedMimeInfo_FOUND`` -# True if system has the shared-mime-info package -# ``UPDATE_MIME_DATABASE_EXECUTABLE`` -# The update-mime-database executable -# -# and the following imported targets: -# -# ``SharedMimeInfo::UpdateMimeDatabase`` -# The update-mime-database executable -# -# The follow macro is available:: -# -# update_xdg_mimetypes(<path>) -# -# Updates the XDG mime database at install time (unless the ``$DESTDIR`` -# environment variable is set, in which case it is up to package managers to -# perform this task). -# -# Since pre-1.0.0. - -#============================================================================= # SPDX-FileCopyrightText: 2013-2014 Alex Merry <alex.merry@kdemail.net> # SPDX-FileCopyrightText: 2007 Pino Toscano <toscano.pino@tiscali.it> # # SPDX-License-Identifier: BSD-3-Clause -#============================================================================= + +#[=======================================================================[.rst: +FindSharedMimeInfo +------------------ + +Try to find the shared-mime-info package. + +This will define the following variables: + +``SharedMimeInfo_FOUND`` + True if system has the shared-mime-info package +``UPDATE_MIME_DATABASE_EXECUTABLE`` + The update-mime-database executable + +and the following imported targets: + +``SharedMimeInfo::UpdateMimeDatabase`` + The update-mime-database executable + +The follow macro is available:: + + update_xdg_mimetypes(<path>) + +Updates the XDG mime database at install time (unless the ``$DESTDIR`` +environment variable is set, in which case it is up to package managers to +perform this task). + +Since pre-1.0.0. +#]=======================================================================] include(${CMAKE_CURRENT_LIST_DIR}/ECMFindModuleHelpersStub.cmake) diff --git a/find-modules/FindTaglib.cmake b/find-modules/FindTaglib.cmake index ad14c79c..2fd4500e 100644 --- a/find-modules/FindTaglib.cmake +++ b/find-modules/FindTaglib.cmake @@ -1,34 +1,36 @@ -#.rst: -# FindTaglib -# ---------- -# -# Try to find the Taglib library. -# -# This will define the following variables: -# -# ``Taglib_FOUND`` -# True if the system has the taglib library of at least the minimum -# version specified by the version parameter to find_package() -# ``Taglib_INCLUDE_DIRS`` -# The taglib include dirs for use with target_include_directories -# ``Taglib_LIBRARIES`` -# The taglib libraries for use with target_link_libraries() -# ``Taglib_VERSION`` -# The version of taglib that was found -# -# If ``Taglib_FOUND`` is TRUE, it will also define the following imported -# target: -# -# ``Taglib::Taglib`` -# The Taglib library -# -# Since 5.72.0 -# # SPDX-FileCopyrightText: 2006 Laurent Montel <montel@kde.org> # SPDX-FileCopyrightText: 2019 Heiko Becker <heirecka@exherbo.org> # SPDX-FileCopyrightText: 2020 Elvis Angelaccio <elvis.angelaccio@kde.org> +# # SPDX-License-Identifier: BSD-3-Clause +#[=======================================================================[.rst: +FindTaglib +---------- + +Try to find the Taglib library. + +This will define the following variables: + +``Taglib_FOUND`` + True if the system has the taglib library of at least the minimum + version specified by the version parameter to find_package() +``Taglib_INCLUDE_DIRS`` + The taglib include dirs for use with target_include_directories +``Taglib_LIBRARIES`` + The taglib libraries for use with target_link_libraries() +``Taglib_VERSION`` + The version of taglib that was found + +If ``Taglib_FOUND`` is TRUE, it will also define the following imported +target: + +``Taglib::Taglib`` + The Taglib library + +Since 5.72.0 +#]=======================================================================] + find_package(PkgConfig QUIET) pkg_search_module(PC_TAGLIB QUIET taglib) diff --git a/find-modules/FindUDev.cmake b/find-modules/FindUDev.cmake index e3d584cb..1ad3832c 100644 --- a/find-modules/FindUDev.cmake +++ b/find-modules/FindUDev.cmake @@ -1,37 +1,36 @@ -#.rst: -# FindUDev -# -------- -# -# Try to find the UDev library. -# -# This will define the following variables: -# -# ``UDev_FOUND`` -# System has UDev. -# -# ``UDev_INCLUDE_DIRS`` -# The libudev include directory. -# -# ``UDev_LIBRARIES`` -# The libudev libraries. -# -# ``UDev_VERSION`` -# The libudev version. -# -# If ``UDev_FOUND`` is TRUE, it will also define the following imported -# target: -# -# ``UDev::UDev`` -# The UDev library -# -# Since 5.57.0. - -#============================================================================= # SPDX-FileCopyrightText: 2010 Rafael Fernández López <ereslibre@kde.org> # SPDX-FileCopyrightText: 2019 Volker Krause <vkrause@kde.org> # # SPDX-License-Identifier: BSD-3-Clause -#============================================================================= + +#[=======================================================================[.rst: +FindUDev +-------- + +Try to find the UDev library. + +This will define the following variables: + +``UDev_FOUND`` + System has UDev. + +``UDev_INCLUDE_DIRS`` + The libudev include directory. + +``UDev_LIBRARIES`` + The libudev libraries. + +``UDev_VERSION`` + The libudev version. + +If ``UDev_FOUND`` is TRUE, it will also define the following imported +target: + +``UDev::UDev`` + The UDev library + +Since 5.57.0. +#]=======================================================================] find_package(PkgConfig QUIET) pkg_check_modules(PC_UDEV QUIET libudev) diff --git a/find-modules/FindWayland.cmake b/find-modules/FindWayland.cmake index 919b2aaa..4b6eb403 100644 --- a/find-modules/FindWayland.cmake +++ b/find-modules/FindWayland.cmake @@ -1,61 +1,60 @@ -#.rst: -# FindWayland -# ----------- -# -# Try to find Wayland. -# -# This is a component-based find module, which makes use of the COMPONENTS -# and OPTIONAL_COMPONENTS arguments to find_module. The following components -# are available:: -# -# Client Server Cursor Egl -# -# If no components are specified, this module will act as though all components -# were passed to OPTIONAL_COMPONENTS. -# -# This module will define the following variables, independently of the -# components searched for or found: -# -# ``Wayland_FOUND`` -# TRUE if (the requested version of) Wayland is available -# ``Wayland_VERSION`` -# Found Wayland version -# ``Wayland_TARGETS`` -# A list of all targets imported by this module (note that there may be more -# than the components that were requested) -# ``Wayland_LIBRARIES`` -# This can be passed to target_link_libraries() instead of the imported -# targets -# ``Wayland_INCLUDE_DIRS`` -# This should be passed to target_include_directories() if the targets are -# not used for linking -# ``Wayland_DEFINITIONS`` -# This should be passed to target_compile_options() if the targets are not -# used for linking -# ``Wayland_DATADIR`` -# The core wayland protocols data directory -# Since 5.73.0 -# -# For each searched-for components, ``Wayland_<component>_FOUND`` will be set to -# TRUE if the corresponding Wayland library was found, and FALSE otherwise. If -# ``Wayland_<component>_FOUND`` is TRUE, the imported target -# ``Wayland::<component>`` will be defined. This module will also attempt to -# determine ``Wayland_*_VERSION`` variables for each imported target, although -# ``Wayland_VERSION`` should normally be sufficient. -# -# In general we recommend using the imported targets, as they are easier to use -# and provide more control. Bear in mind, however, that if any target is in the -# link interface of an exported library, it must be made available by the -# package config file. -# -# Since pre-1.0.0. - -#============================================================================= # SPDX-FileCopyrightText: 2014 Alex Merry <alex.merry@kde.org> # SPDX-FileCopyrightText: 2014 Martin Gräßlin <mgraesslin@kde.org> # # SPDX-License-Identifier: BSD-3-Clause -#============================================================================= + +#[=======================================================================[.rst: +FindWayland +----------- + +Try to find Wayland. + +This is a component-based find module, which makes use of the COMPONENTS +and OPTIONAL_COMPONENTS arguments to find_module. The following components +are available:: + + Client Server Cursor Egl + +If no components are specified, this module will act as though all components +were passed to OPTIONAL_COMPONENTS. + +This module will define the following variables, independently of the +components searched for or found: + +``Wayland_FOUND`` + TRUE if (the requested version of) Wayland is available +``Wayland_VERSION`` + Found Wayland version +``Wayland_TARGETS`` + A list of all targets imported by this module (note that there may be more + than the components that were requested) +``Wayland_LIBRARIES`` + This can be passed to target_link_libraries() instead of the imported + targets +``Wayland_INCLUDE_DIRS`` + This should be passed to target_include_directories() if the targets are + not used for linking +``Wayland_DEFINITIONS`` + This should be passed to target_compile_options() if the targets are not + used for linking +``Wayland_DATADIR`` + The core wayland protocols data directory + Since 5.73.0 + +For each searched-for components, ``Wayland_<component>_FOUND`` will be set to +TRUE if the corresponding Wayland library was found, and FALSE otherwise. If +``Wayland_<component>_FOUND`` is TRUE, the imported target +``Wayland::<component>`` will be defined. This module will also attempt to +determine ``Wayland_*_VERSION`` variables for each imported target, although +``Wayland_VERSION`` should normally be sufficient. + +In general we recommend using the imported targets, as they are easier to use +and provide more control. Bear in mind, however, that if any target is in the +link interface of an exported library, it must be made available by the +package config file. + +Since pre-1.0.0. +#]=======================================================================] include(${CMAKE_CURRENT_LIST_DIR}/ECMFindModuleHelpersStub.cmake) diff --git a/find-modules/FindWaylandProtocols.cmake b/find-modules/FindWaylandProtocols.cmake index b314cadd..7730c119 100644 --- a/find-modules/FindWaylandProtocols.cmake +++ b/find-modules/FindWaylandProtocols.cmake @@ -1,23 +1,22 @@ -#.rst: -# FindWaylandProtocols -# -------------------- -# -# Try to find wayland-protocols on a Unix system. -# -# This will define the following variables: -# -# ``WaylandProtocols_FOUND`` -# True if (the requested version of) wayland-protocols is available -# ``WaylandProtocols_VERSION`` -# The version of wayland-protocols -# ``WaylandProtocols_DATADIR`` -# The wayland protocols data directory - -#============================================================================= # SPDX-FileCopyrightText: 2019 Vlad Zahorodnii <vlad.zahorodnii@kde.org> # # SPDX-License-Identifier: BSD-3-Clause -#============================================================================= + +#[=======================================================================[.rst: +FindWaylandProtocols +-------------------- + +Try to find wayland-protocols on a Unix system. + +This will define the following variables: + +``WaylandProtocols_FOUND`` + True if (the requested version of) wayland-protocols is available +``WaylandProtocols_VERSION`` + The version of wayland-protocols +``WaylandProtocols_DATADIR`` + The wayland protocols data directory +#]=======================================================================] find_package(PkgConfig) pkg_check_modules(PKG_wayland_protocols QUIET wayland-protocols) diff --git a/find-modules/FindWaylandScanner.cmake b/find-modules/FindWaylandScanner.cmake index e0e68c45..7b493d81 100644 --- a/find-modules/FindWaylandScanner.cmake +++ b/find-modules/FindWaylandScanner.cmake @@ -1,60 +1,59 @@ -#.rst: -# FindWaylandScanner -# ------------------ -# -# Try to find wayland-scanner. -# -# If the wayland-scanner executable is not in your PATH, you can provide -# an alternative name or full path location with the ``WaylandScanner_EXECUTABLE`` -# variable. -# -# This will define the following variables: -# -# ``WaylandScanner_FOUND`` -# True if wayland-scanner is available. -# -# ``WaylandScanner_EXECUTABLE`` -# The wayland-scanner executable. -# -# If ``WaylandScanner_FOUND`` is TRUE, it will also define the following imported -# target: -# -# ``Wayland::Scanner`` -# The wayland-scanner executable. -# -# This module provides the following functions to generate C protocol -# implementations: -# -# - ``ecm_add_wayland_client_protocol`` -# - ``ecm_add_wayland_server_protocol`` -# -# :: -# -# ecm_add_wayland_client_protocol(<source_files_var> -# PROTOCOL <xmlfile> -# BASENAME <basename>) -# -# Generate Wayland client protocol files from ``<xmlfile>`` XML -# definition for the ``<basename>`` interface and append those files -# to ``<source_files_var>``. -# -# :: -# -# ecm_add_wayland_server_protocol(<source_files_var> -# PROTOCOL <xmlfile> -# BASENAME <basename>) -# -# Generate Wayland server protocol files from ``<xmlfile>`` XML -# definition for the ``<basename>`` interface and append those files -# to ``<source_files_var>``. -# -# Since 1.4.0. - -#============================================================================= # SPDX-FileCopyrightText: 2012-2014 Pier Luigi Fiorini <pierluigi.fiorini@gmail.com> # # SPDX-License-Identifier: BSD-3-Clause -#============================================================================= + +#[=======================================================================[.rst: +FindWaylandScanner +------------------ + +Try to find wayland-scanner. + +If the wayland-scanner executable is not in your PATH, you can provide +an alternative name or full path location with the ``WaylandScanner_EXECUTABLE`` +variable. + +This will define the following variables: + +``WaylandScanner_FOUND`` + True if wayland-scanner is available. + +``WaylandScanner_EXECUTABLE`` + The wayland-scanner executable. + +If ``WaylandScanner_FOUND`` is TRUE, it will also define the following imported +target: + +``Wayland::Scanner`` + The wayland-scanner executable. + +This module provides the following functions to generate C protocol +implementations: + + - ``ecm_add_wayland_client_protocol`` + - ``ecm_add_wayland_server_protocol`` + +:: + + ecm_add_wayland_client_protocol(<source_files_var> + PROTOCOL <xmlfile> + BASENAME <basename>) + +Generate Wayland client protocol files from ``<xmlfile>`` XML +definition for the ``<basename>`` interface and append those files +to ``<source_files_var>``. + +:: + + ecm_add_wayland_server_protocol(<source_files_var> + PROTOCOL <xmlfile> + BASENAME <basename>) + +Generate Wayland server protocol files from ``<xmlfile>`` XML +definition for the ``<basename>`` interface and append those files +to ``<source_files_var>``. + +Since 1.4.0. +#]=======================================================================] include(${CMAKE_CURRENT_LIST_DIR}/ECMFindModuleHelpersStub.cmake) diff --git a/find-modules/FindX11_XCB.cmake b/find-modules/FindX11_XCB.cmake index 589e2560..a04d1c37 100644 --- a/find-modules/FindX11_XCB.cmake +++ b/find-modules/FindX11_XCB.cmake @@ -1,46 +1,45 @@ -#.rst: -# FindX11_XCB -# ----------- -# -# Try to find the X11 XCB compatibility library. -# -# This will define the following variables: -# -# ``X11_XCB_FOUND`` -# True if (the requested version of) libX11-xcb is available -# ``X11_XCB_VERSION`` -# The version of libX11-xcb (this is not guaranteed to be set even when -# X11_XCB_FOUND is true) -# ``X11_XCB_LIBRARIES`` -# This can be passed to target_link_libraries() instead of the ``EGL::EGL`` -# target -# ``X11_XCB_INCLUDE_DIR`` -# This should be passed to target_include_directories() if the target is not -# used for linking -# ``X11_XCB_DEFINITIONS`` -# This should be passed to target_compile_options() if the target is not -# used for linking -# -# If ``X11_XCB_FOUND`` is TRUE, it will also define the following imported -# target: -# -# ``X11::XCB`` -# The X11 XCB compatibility library -# -# In general we recommend using the imported target, as it is easier to use. -# Bear in mind, however, that if the target is in the link interface of an -# exported library, it must be made available by the package config file. -# -# Since pre-1.0.0. - -#============================================================================= # SPDX-FileCopyrightText: 2014 Alex Merry <alex.merry@kde.org> # SPDX-FileCopyrightText: 2011 Fredrik Höglund <fredrik@kde.org> # SPDX-FileCopyrightText: 2008 Helio Chissini de Castro <helio@kde.org> # SPDX-FileCopyrightText: 2007 Matthias Kretz <kretz@kde.org> # # SPDX-License-Identifier: BSD-3-Clause -#============================================================================= + +#[=======================================================================[.rst: +FindX11_XCB +----------- + +Try to find the X11 XCB compatibility library. + +This will define the following variables: + +``X11_XCB_FOUND`` + True if (the requested version of) libX11-xcb is available +``X11_XCB_VERSION`` + The version of libX11-xcb (this is not guaranteed to be set even when + X11_XCB_FOUND is true) +``X11_XCB_LIBRARIES`` + This can be passed to target_link_libraries() instead of the ``EGL::EGL`` + target +``X11_XCB_INCLUDE_DIR`` + This should be passed to target_include_directories() if the target is not + used for linking +``X11_XCB_DEFINITIONS`` + This should be passed to target_compile_options() if the target is not + used for linking + +If ``X11_XCB_FOUND`` is TRUE, it will also define the following imported +target: + +``X11::XCB`` + The X11 XCB compatibility library + +In general we recommend using the imported target, as it is easier to use. +Bear in mind, however, that if the target is in the link interface of an +exported library, it must be made available by the package config file. + +Since pre-1.0.0. +#]=======================================================================] include(${CMAKE_CURRENT_LIST_DIR}/ECMFindModuleHelpersStub.cmake) diff --git a/find-modules/FindXCB.cmake b/find-modules/FindXCB.cmake index 101605c5..81d5fc0a 100644 --- a/find-modules/FindXCB.cmake +++ b/find-modules/FindXCB.cmake @@ -1,67 +1,66 @@ -#.rst: -# FindXCB -# ------- -# -# Try to find XCB. -# -# This is a component-based find module, which makes use of the COMPONENTS and -# OPTIONAL_COMPONENTS arguments to find_module. The following components are -# available:: -# -# XCB -# ATOM AUX COMPOSITE CURSOR DAMAGE -# DPMS DRI2 DRI3 EVENT EWMH -# GLX ICCCM IMAGE KEYSYMS PRESENT -# RANDR RECORD RENDER RENDERUTIL RES -# SCREENSAVER SHAPE SHM SYNC UTIL -# XEVIE XF86DRI XFIXES XINERAMA XINPUT -# XKB XPRINT XTEST XV XVMC -# -# If no components are specified, this module will act as though all components -# except XINPUT (which is considered unstable) were passed to -# OPTIONAL_COMPONENTS. -# -# This module will define the following variables, independently of the -# components searched for or found: -# -# ``XCB_FOUND`` -# True if (the requestion version of) xcb is available -# ``XCB_VERSION`` -# Found xcb version -# ``XCB_TARGETS`` -# A list of all targets imported by this module (note that there may be more -# than the components that were requested) -# ``XCB_LIBRARIES`` -# This can be passed to target_link_libraries() instead of the imported -# targets -# ``XCB_INCLUDE_DIRS`` -# This should be passed to target_include_directories() if the targets are -# not used for linking -# ``XCB_DEFINITIONS`` -# This should be passed to target_compile_options() if the targets are not -# used for linking -# -# For each searched-for components, ``XCB_<component>_FOUND`` will be set to -# true if the corresponding xcb library was found, and false otherwise. If -# ``XCB_<component>_FOUND`` is true, the imported target ``XCB::<component>`` -# will be defined. This module will also attempt to determine -# ``XCB_*_VERSION`` variables for each imported target, although -# ``XCB_VERSION`` should normally be sufficient. -# -# In general we recommend using the imported targets, as they are easier to use -# and provide more control. Bear in mind, however, that if any target is in the -# link interface of an exported library, it must be made available by the -# package config file. -# -# Since pre-1.0.0. - -#============================================================================= # SPDX-FileCopyrightText: 2011 Fredrik Höglund <fredrik@kde.org> # SPDX-FileCopyrightText: 2013 Martin Gräßlin <mgraesslin@kde.org> # SPDX-FileCopyrightText: 2014-2015 Alex Merry <alex.merry@kde.org> # # SPDX-License-Identifier: BSD-3-Clause -#============================================================================= + +#[=======================================================================[.rst: +FindXCB +------- + +Try to find XCB. + +This is a component-based find module, which makes use of the COMPONENTS and +OPTIONAL_COMPONENTS arguments to find_module. The following components are +available:: + + XCB + ATOM AUX COMPOSITE CURSOR DAMAGE + DPMS DRI2 DRI3 EVENT EWMH + GLX ICCCM IMAGE KEYSYMS PRESENT + RANDR RECORD RENDER RENDERUTIL RES + SCREENSAVER SHAPE SHM SYNC UTIL + XEVIE XF86DRI XFIXES XINERAMA XINPUT + XKB XPRINT XTEST XV XVMC + +If no components are specified, this module will act as though all components +except XINPUT (which is considered unstable) were passed to +OPTIONAL_COMPONENTS. + +This module will define the following variables, independently of the +components searched for or found: + +``XCB_FOUND`` + True if (the requestion version of) xcb is available +``XCB_VERSION`` + Found xcb version +``XCB_TARGETS`` + A list of all targets imported by this module (note that there may be more + than the components that were requested) +``XCB_LIBRARIES`` + This can be passed to target_link_libraries() instead of the imported + targets +``XCB_INCLUDE_DIRS`` + This should be passed to target_include_directories() if the targets are + not used for linking +``XCB_DEFINITIONS`` + This should be passed to target_compile_options() if the targets are not + used for linking + +For each searched-for components, ``XCB_<component>_FOUND`` will be set to +true if the corresponding xcb library was found, and false otherwise. If +``XCB_<component>_FOUND`` is true, the imported target ``XCB::<component>`` +will be defined. This module will also attempt to determine +``XCB_*_VERSION`` variables for each imported target, although +``XCB_VERSION`` should normally be sufficient. + +In general we recommend using the imported targets, as they are easier to use +and provide more control. Bear in mind, however, that if any target is in the +link interface of an exported library, it must be made available by the +package config file. + +Since pre-1.0.0. +#]=======================================================================] include(${CMAKE_CURRENT_LIST_DIR}/ECMFindModuleHelpersStub.cmake) diff --git a/find-modules/Findepoxy.cmake b/find-modules/Findepoxy.cmake index 548be5bc..3882b9ba 100644 --- a/find-modules/Findepoxy.cmake +++ b/find-modules/Findepoxy.cmake @@ -1,41 +1,42 @@ -#.rst: -# Findepoxy -# --------- -# -# Try to find libepoxy on a Unix system. -# -# This will define the following variables: -# -# ``epoxy_FOUND`` -# True if (the requested version of) libepoxy is available -# ``epoxy_VERSION`` -# The version of libepoxy -# ``epoxy_LIBRARIES`` -# This should be passed to target_link_libraries() if the target is not -# used for linking -# ``epoxy_INCLUDE_DIRS`` -# This should be passed to target_include_directories() if the target is not -# used for linking -# ``epoxy_DEFINITIONS`` -# This should be passed to target_compile_options() if the target is not -# used for linking -# ``epoxy_HAS_GLX`` -# True if GLX support is available -# -# If ``epoxy_FOUND`` is TRUE, it will also define the following imported target: -# -# ``epoxy::epoxy`` -# The epoxy library -# -# In general we recommend using the imported target, as it is easier to use. -# Bear in mind, however, that if the target is in the link interface of an -# exported library, it must be made available by the package config file. - # SPDX-FileCopyrightText: 2014 Fredrik Höglund <fredrik@kde.org> # SPDX-FileCopyrightText: 2020 Vlad Zahorodnii <vlad.zahorodnii@kde.org> # # SPDX-License-Identifier: BSD-3-Clause +#[=======================================================================[.rst: +Findepoxy +--------- + +Try to find libepoxy on a Unix system. + +This will define the following variables: + +``epoxy_FOUND`` + True if (the requested version of) libepoxy is available +``epoxy_VERSION`` + The version of libepoxy +``epoxy_LIBRARIES`` + This should be passed to target_link_libraries() if the target is not + used for linking +``epoxy_INCLUDE_DIRS`` + This should be passed to target_include_directories() if the target is not + used for linking +``epoxy_DEFINITIONS`` + This should be passed to target_compile_options() if the target is not + used for linking +``epoxy_HAS_GLX`` + True if GLX support is available + +If ``epoxy_FOUND`` is TRUE, it will also define the following imported target: + +``epoxy::epoxy`` + The epoxy library + +In general we recommend using the imported target, as it is easier to use. +Bear in mind, however, that if the target is in the link interface of an +exported library, it must be made available by the package config file. +#]=======================================================================] + find_package(PkgConfig) pkg_check_modules(PKG_epoxy QUIET epoxy) diff --git a/kde-modules/KDECMakeSettings.cmake b/kde-modules/KDECMakeSettings.cmake index f640dca7..d33daa7a 100644 --- a/kde-modules/KDECMakeSettings.cmake +++ b/kde-modules/KDECMakeSettings.cmake @@ -1,106 +1,3 @@ -#.rst: -# KDECMakeSettings -# ---------------- -# -# Changes various CMake settings to what the KDE community views as more -# sensible defaults. -# -# It is recommended to include this module with the NO_POLICY_SCOPE flag, -# otherwise you may get spurious warnings with some versions of CMake. -# -# It is split into three parts, which can be independently disabled if desired. -# -# Runtime Paths -# ~~~~~~~~~~~~~ -# -# The default runtime path (used on Unix systems to search for -# dynamically-linked libraries) is set to include the location that libraries -# will be installed to (as set in LIB_INSTALL_DIR or, if the former is not set, -# KDE_INSTALL_LIBDIR), and also the linker search path. -# -# Note that ``LIB_INSTALL_DIR`` or alternatively ``KDE_INSTALL_LIBDIR`` needs -# to be set before including this module. -# Typically, this is done by including the :kde-module:`KDEInstallDirs` module. -# -# This section can be disabled by setting ``KDE_SKIP_RPATH_SETTINGS`` to TRUE -# before including this module. -# -# -# Testing -# ~~~~~~~ -# -# Testing is enabled by default, and an option (BUILD_TESTING) is provided for -# users to control this. See the CTest module documentation in the CMake manual -# for more details. -# -# This section can be disabled by setting ``KDE_SKIP_TEST_SETTINGS`` to TRUE -# before including this module. -# -# -# Build Settings -# ~~~~~~~~~~~~~~ -# -# Various CMake build defaults are altered, such as searching source and build -# directories for includes first, enabling automoc by default. -# -# When find_package(ECM 5.38) or higher is called, this also selects -# a layout for the build dir that helps running executables without installing: -# all executables are built into a toplevel "bin" dir, making it possible to find -# helper binaries, and to find uninstalled plugins (provided that you use -# kcoreaddons_add_plugin or set LIBRARY_OUTPUT_DIRECTORY as documented on -# https://community.kde.org/Guidelines_and_HOWTOs/Making_apps_run_uninstalled). -# -# This section can be disabled by setting ``KDE_SKIP_BUILD_SETTINGS`` to TRUE -# before including this module. -# -# This section also provides an "uninstall" target that can be individually -# disabled by setting ``KDE_SKIP_UNINSTALL_TARGET`` to TRUE before including -# this module. -# -# By default on OS X, X11 and XCB related detections are disabled. However if -# the need would arise to use these technologies, the detection can be enabled -# by setting ``APPLE_FORCE_X11`` to ``ON``. -# -# A warning is printed for the developer to know that the detection is disabled on OS X. -# This message can be turned off by setting ``APPLE_SUPPRESS_X11_WARNING`` to ``ON``. -# -# Since pre-1.0.0. -# -# ``ENABLE_CLAZY`` option is added (OFF by default) when clang is being used. -# Turning this option on will force clang to load the clazy plugins for richer -# warnings on Qt-related code. -# -# If clang is not being used, this won't have an effect. -# See https://commits.kde.org/clazy?path=README.md -# -# Since 5.17.0 -# -# - Uninstall target functionality since 1.7.0. -# - ``APPLE_FORCE_X11`` option since 5.14.0 (detecting X11 was previously the default behavior) -# - ``APPLE_SUPPRESS_X11_WARNING`` option since 5.14.0 -# - CMAKE_AUTORCC enabled by default when supported by cmake (>= 3.0) since 5.62.0 -# -# Translations -# ~~~~~~~~~~~~ -# A fetch-translations target will be set up that will download translations -# for projects using l10n.kde.org. -# -# ``KDE_L10N_BRANCH`` will be responsible for choosing which l10n branch to use -# for the translations. -# -# ``KDE_L10N_AUTO_TRANSLATIONS`` (OFF by default) will indicate whether translations -# should be downloaded when building the project. -# -# Since 5.34.0 -# -# ``KDE_L10N_SYNC_TRANSLATIONS`` (OFF by default) will download the translations at configuration -# time instead of build time. -# -# Since 5.50.0 -# -# - -#============================================================================= # SPDX-FileCopyrightText: 2014 Alex Merry <alex.merry@kde.org> # SPDX-FileCopyrightText: 2013 Aleix Pol <aleixpol@kde.org> # SPDX-FileCopyrightText: 2012-2013 Stephen Kelly <steveire@gmail.com> @@ -110,6 +7,107 @@ # # SPDX-License-Identifier: BSD-3-Clause +#[=======================================================================[.rst: +KDECMakeSettings +---------------- + +Changes various CMake settings to what the KDE community views as more +sensible defaults. + +It is recommended to include this module with the NO_POLICY_SCOPE flag, +otherwise you may get spurious warnings with some versions of CMake. + +It is split into three parts, which can be independently disabled if desired. + +Runtime Paths +~~~~~~~~~~~~~ + +The default runtime path (used on Unix systems to search for +dynamically-linked libraries) is set to include the location that libraries +will be installed to (as set in LIB_INSTALL_DIR or, if the former is not set, +KDE_INSTALL_LIBDIR), and also the linker search path. + +Note that ``LIB_INSTALL_DIR`` or alternatively ``KDE_INSTALL_LIBDIR`` needs +to be set before including this module. +Typically, this is done by including the :kde-module:`KDEInstallDirs` module. + +This section can be disabled by setting ``KDE_SKIP_RPATH_SETTINGS`` to TRUE +before including this module. + + +Testing +~~~~~~~ + +Testing is enabled by default, and an option (BUILD_TESTING) is provided for +users to control this. See the CTest module documentation in the CMake manual +for more details. + +This section can be disabled by setting ``KDE_SKIP_TEST_SETTINGS`` to TRUE +before including this module. + + +Build Settings +~~~~~~~~~~~~~~ + +Various CMake build defaults are altered, such as searching source and build +directories for includes first, enabling automoc by default. + +When find_package(ECM 5.38) or higher is called, this also selects +a layout for the build dir that helps running executables without installing: +all executables are built into a toplevel "bin" dir, making it possible to find +helper binaries, and to find uninstalled plugins (provided that you use +kcoreaddons_add_plugin or set LIBRARY_OUTPUT_DIRECTORY as documented on +https://community.kde.org/Guidelines_and_HOWTOs/Making_apps_run_uninstalled). + +This section can be disabled by setting ``KDE_SKIP_BUILD_SETTINGS`` to TRUE +before including this module. + +This section also provides an "uninstall" target that can be individually +disabled by setting ``KDE_SKIP_UNINSTALL_TARGET`` to TRUE before including +this module. + +By default on OS X, X11 and XCB related detections are disabled. However if +the need would arise to use these technologies, the detection can be enabled +by setting ``APPLE_FORCE_X11`` to ``ON``. + +A warning is printed for the developer to know that the detection is disabled on OS X. +This message can be turned off by setting ``APPLE_SUPPRESS_X11_WARNING`` to ``ON``. + +Since pre-1.0.0. + +``ENABLE_CLAZY`` option is added (OFF by default) when clang is being used. +Turning this option on will force clang to load the clazy plugins for richer +warnings on Qt-related code. + +If clang is not being used, this won't have an effect. +See https://commits.kde.org/clazy?path=README.md + +Since 5.17.0 + +- Uninstall target functionality since 1.7.0. +- ``APPLE_FORCE_X11`` option since 5.14.0 (detecting X11 was previously the default behavior) +- ``APPLE_SUPPRESS_X11_WARNING`` option since 5.14.0 +- CMAKE_AUTORCC enabled by default when supported by cmake (>= 3.0) since 5.62.0 + +Translations +~~~~~~~~~~~~ +A fetch-translations target will be set up that will download translations +for projects using l10n.kde.org. + +``KDE_L10N_BRANCH`` will be responsible for choosing which l10n branch to use +for the translations. + +``KDE_L10N_AUTO_TRANSLATIONS`` (OFF by default) will indicate whether translations +should be downloaded when building the project. + +Since 5.34.0 + +``KDE_L10N_SYNC_TRANSLATIONS`` (OFF by default) will download the translations at configuration +time instead of build time. + +Since 5.50.0 +#]=======================================================================] + ################# RPATH handling ################################## if(NOT KDE_SKIP_RPATH_SETTINGS) diff --git a/kde-modules/KDEClangFormat.cmake b/kde-modules/KDEClangFormat.cmake index 7889fde0..9fd467e8 100644 --- a/kde-modules/KDEClangFormat.cmake +++ b/kde-modules/KDEClangFormat.cmake @@ -1,54 +1,54 @@ -#.rst: -# KDEClangFormat -# -------------------- -# -# This module provides a functionality to format the source -# code of your repository according to a predefined KDE -# clang-format file. -# -# This module provides the following function: -# -# :: -# -# kde_clang_format(<files>) -# -# Using this function will create a clang-format target that will format all -# ``<files>`` passed to the function with the predefined KDE clang-format style. -# To format the files you have to invoke the target with ``make clang-format`` or ``ninja clang-format``. -# Once the project is formatted it is recommended to enforce the formatting using a pre-commit hook, -# this can be done using :kde-module:`KDEGitCommitHooks`. -# -# The ``.clang-format`` file from ECM will be copied to the source directory. This file should not be -# added to version control. It is recommended to add it to the ``.gitignore`` file: ``/.clang-format``. -# -# Since 5.79: If the source folder already contains a .clang-format file it is not overwritten. -# Since version 5.80 this function is called by default in KDEFrameworkCompilerSettings. If directories should be excluded from -# the formatting a .clang-format file with "DisableFormat: true" and "SortIncludes: false" should be created. -# -# Example usage: -# -# .. code-block:: cmake -# -# include(KDEClangFormat) -# file(GLOB_RECURSE ALL_CLANG_FORMAT_SOURCE_FILES *.cpp *.h) -# kde_clang_format(${ALL_CLANG_FORMAT_SOURCE_FILES}) -# -# To exclude directories from the formatting add a ``.clang-format`` -# file in the directory with the following contents: -# -# .. code-block:: yaml -# -# DisableFormat: true -# SortIncludes: false -# -# Since 5.64 - -#============================================================================= # SPDX-FileCopyrightText: 2019 Christoph Cullmann <cullmann@kde.org> # SPDX-FileCopyrightText: 2021 Alexander Lohnau <alexander.lohnau@gmx.de> # # SPDX-License-Identifier: BSD-3-Clause +#[=======================================================================[.rst: +KDEClangFormat +-------------------- + +This module provides a functionality to format the source +code of your repository according to a predefined KDE +clang-format file. + +This module provides the following function: + +:: + + kde_clang_format(<files>) + +Using this function will create a clang-format target that will format all +``<files>`` passed to the function with the predefined KDE clang-format style. +To format the files you have to invoke the target with ``make clang-format`` or ``ninja clang-format``. +Once the project is formatted it is recommended to enforce the formatting using a pre-commit hook, +this can be done using :kde-module:`KDEGitCommitHooks`. + +The ``.clang-format`` file from ECM will be copied to the source directory. This file should not be +added to version control. It is recommended to add it to the ``.gitignore`` file: ``/.clang-format``. + +Since 5.79: If the source folder already contains a .clang-format file it is not overwritten. +Since version 5.80 this function is called by default in KDEFrameworkCompilerSettings. If directories should be excluded from +the formatting a .clang-format file with "DisableFormat: true" and "SortIncludes: false" should be created. + +Example usage: + +.. code-block:: cmake + + include(KDEClangFormat) + file(GLOB_RECURSE ALL_CLANG_FORMAT_SOURCE_FILES *.cpp *.h) + kde_clang_format(${ALL_CLANG_FORMAT_SOURCE_FILES}) + +To exclude directories from the formatting add a ``.clang-format`` +file in the directory with the following contents: + +.. code-block:: yaml + + DisableFormat: true + SortIncludes: false + +Since 5.64 +#]=======================================================================] + # try to find clang-format in path find_program(KDE_CLANG_FORMAT_EXECUTABLE clang-format) diff --git a/kde-modules/KDECompilerSettings.cmake b/kde-modules/KDECompilerSettings.cmake index fcd80f30..7fd905cf 100644 --- a/kde-modules/KDECompilerSettings.cmake +++ b/kde-modules/KDECompilerSettings.cmake @@ -1,41 +1,3 @@ -#.rst: -# KDECompilerSettings -# ------------------- -# -# Set useful compile and link flags for C++ (and C) code. -# -# Enables many more warnings than the default, and sets stricter modes -# for some compiler features. By default, exceptions are disabled; -# kde_target_enable_exceptions() can be used to re-enable them for a -# specific target. -# -# NB: it is recommended to include this module with the NO_POLICY_SCOPE -# flag, otherwise you may get spurious warnings with some versions of CMake. -# -# This module provides the following functions:: -# -# kde_source_files_enable_exceptions([file1 [file2 [...]]]) -# -# Enables exceptions for specific source files. This should not be -# used on source files in a language other than C++. -# -# :: -# -# kde_target_enable_exceptions(target <INTERFACE|PUBLIC|PRIVATE>) -# -# Enables exceptions for a specific target. This should not be used -# on a target that has source files in a language other than C++. -# -# :: -# -# kde_enable_exceptions() -# -# Enables exceptions for C++ source files compiled for the -# CMakeLists.txt file in the current directory and all subdirectories. -# -# Since pre-1.0.0. - -#============================================================================= # SPDX-FileCopyrightText: 2014 Alex Merry <alex.merry@kde.org> # SPDX-FileCopyrightText: 2013 Stephen Kelly <steveire@gmail.com> # SPDX-FileCopyrightText: 2012-2013 Raphael Kubo da Costa <rakuco@FreeBSD.org> @@ -45,6 +7,44 @@ # # SPDX-License-Identifier: BSD-3-Clause +#[=======================================================================[.rst: +KDECompilerSettings +------------------- + +Set useful compile and link flags for C++ (and C) code. + +Enables many more warnings than the default, and sets stricter modes +for some compiler features. By default, exceptions are disabled; +kde_target_enable_exceptions() can be used to re-enable them for a +specific target. + +NB: it is recommended to include this module with the NO_POLICY_SCOPE +flag, otherwise you may get spurious warnings with some versions of CMake. + +This module provides the following functions:: + + kde_source_files_enable_exceptions([file1 [file2 [...]]]) + +Enables exceptions for specific source files. This should not be +used on source files in a language other than C++. + +:: + + kde_target_enable_exceptions(target <INTERFACE|PUBLIC|PRIVATE>) + +Enables exceptions for a specific target. This should not be used +on a target that has source files in a language other than C++. + +:: + + kde_enable_exceptions() + +Enables exceptions for C++ source files compiled for the +CMakeLists.txt file in the current directory and all subdirectories. + +Since pre-1.0.0. +#]=======================================================================] + include("${ECM_MODULE_DIR}/ECMSourceVersionControl.cmake") ############################################################ diff --git a/kde-modules/KDEFrameworkCompilerSettings.cmake b/kde-modules/KDEFrameworkCompilerSettings.cmake index 478039da..fca643d4 100644 --- a/kde-modules/KDEFrameworkCompilerSettings.cmake +++ b/kde-modules/KDEFrameworkCompilerSettings.cmake @@ -1,23 +1,3 @@ -#.rst: -# KDEFrameworkCompilerSettings -# ---------------------------- -# -# Set stricter compile and link flags for KDE Frameworks modules. -# -# The KDECompilerSettings module is included and, in addition, various -# defines that affect the Qt libraries are set to enforce certain -# conventions. -# -# For example, constructions like QString("foo") are prohibited, instead -# forcing the use of QLatin1String or QStringLiteral, and some -# Qt-defined keywords like signals and slots will not be defined. -# -# NB: it is recommended to include this module with the NO_POLICY_SCOPE -# flag, otherwise you may get spurious warnings with some versions of CMake. -# -# Since pre-1.0.0. - -#============================================================================= # SPDX-FileCopyrightText: 2013 Albert Astals Cid <aacid@kde.org> # SPDX-FileCopyrightText: 2007 Matthias Kretz <kretz@kde.org> # SPDX-FileCopyrightText: 2006-2007 Laurent Montel <montel@kde.org> @@ -25,6 +5,26 @@ # # SPDX-License-Identifier: BSD-3-Clause +#[=======================================================================[.rst: +KDEFrameworkCompilerSettings +---------------------------- + +Set stricter compile and link flags for KDE Frameworks modules. + +The KDECompilerSettings module is included and, in addition, various +defines that affect the Qt libraries are set to enforce certain +conventions. + +For example, constructions like QString("foo") are prohibited, instead +forcing the use of QLatin1String or QStringLiteral, and some +Qt-defined keywords like signals and slots will not be defined. + +NB: it is recommended to include this module with the NO_POLICY_SCOPE +flag, otherwise you may get spurious warnings with some versions of CMake. + +Since pre-1.0.0. +#]=======================================================================] + include(KDECompilerSettings NO_POLICY_SCOPE) add_definitions(-DQT_NO_CAST_TO_ASCII diff --git a/kde-modules/KDEGitCommitHooks.cmake b/kde-modules/KDEGitCommitHooks.cmake index 7bbd024c..761175f1 100644 --- a/kde-modules/KDEGitCommitHooks.cmake +++ b/kde-modules/KDEGitCommitHooks.cmake @@ -1,44 +1,44 @@ -#.rst: -# KDEGitCommitHooks -# -------------------- -# -# This module provides a functionality to enforce formatting -# or in the future other QS checks. -# -# This module provides the following function: -# -# :: -# -# kde_configure_pre_commit_hook( -# CHECKS <check1> [<check2> [...]] -# ) -# -# This function will create a pre-commit hook which contains all the given checks. -# -# Checks: -# -# - ``CLANG_FORMAT`` With this check enabled the ``git clang-format`` tool will be used to make sure that -# the changed parts are properly formatted. In case the changes are not properly formatted an error -# message with the command to preview the formatting changes and to format the files in place -# will be displayed. This tool will reuse the exsting ``.clang-format`` file, in case you -# want to use the one provided by ECM you can include ``include(KDEClangFormat)`` which will copy -# the file to the source dir. It is also recommended to reformat the entire project before enforcing -# the formatting using this commit hook. -# -# Example usage: -# -# .. code-block:: cmake -# -# include(KDEGitCommitHooks) -# kde_configure_git_pre_commit_hook(CHECKS CLANG_FORMAT) -# -# Since 5.79 - -#============================================================================= # SPDX-FileCopyrightText: 2020 Alexander Lohnau <alexander.lohnau@gmx.de> # # SPDX-License-Identifier: BSD-3-Clause +#[=======================================================================[.rst: +KDEGitCommitHooks +-------------------- + +This module provides a functionality to enforce formatting +or in the future other QS checks. + +This module provides the following function: + +:: + + kde_configure_pre_commit_hook( + CHECKS <check1> [<check2> [...]] + ) + +This function will create a pre-commit hook which contains all the given checks. + +Checks: + +- ``CLANG_FORMAT`` With this check enabled the ``git clang-format`` tool will be used to make sure that + the changed parts are properly formatted. In case the changes are not properly formatted an error + message with the command to preview the formatting changes and to format the files in place + will be displayed. This tool will reuse the exsting ``.clang-format`` file, in case you + want to use the one provided by ECM you can include ``include(KDEClangFormat)`` which will copy + the file to the source dir. It is also recommended to reformat the entire project before enforcing + the formatting using this commit hook. + +Example usage: + +.. code-block:: cmake + + include(KDEGitCommitHooks) + kde_configure_git_pre_commit_hook(CHECKS CLANG_FORMAT) + +Since 5.79 +#]=======================================================================] + # try to find clang-format in path find_program(KDE_CLANG_FORMAT_EXECUTABLE clang-format) include(CMakeParseArguments) diff --git a/kde-modules/KDEInstallDirs.cmake b/kde-modules/KDEInstallDirs.cmake index 8b332ff9..628baa06 100644 --- a/kde-modules/KDEInstallDirs.cmake +++ b/kde-modules/KDEInstallDirs.cmake @@ -1,216 +1,3 @@ -#.rst: -# KDEInstallDirs -# -------------- -# -# Define KDE standard installation directories. -# -# Note that none of the variables defined by this module provide any -# information about the location of already-installed KDE software. -# -# Also sets ``CMAKE_INSTALL_PREFIX`` to the installation prefix of ECM, -# unless that variable has been already explicitly set by something else -# (since 5.61 and with CMake >= 3.7). -# -# Inclusion of this module defines the following variables: -# -# ``KDE_INSTALL_<dir>`` -# destination for files of a given type -# ``KDE_INSTALL_FULL_<dir>`` -# corresponding absolute path -# -# where ``<dir>`` is one of (default values in parentheses and alternative, -# deprecated variable name in square brackets): -# -# ``BUNDLEDIR`` -# application bundles (``/Applications/KDE``) [``BUNDLE_INSTALL_DIR``] -# ``EXECROOTDIR`` -# executables and libraries (``<empty>``) [``EXEC_INSTALL_PREFIX``] -# ``BINDIR`` -# user executables (``EXECROOTDIR/bin``) [``BIN_INSTALL_DIR``] -# ``SBINDIR`` -# system admin executables (``EXECROOTDIR/sbin``) [``SBIN_INSTALL_DIR``] -# ``LIBDIR`` -# object code libraries (``EXECROOTDIR/lib``, ``EXECROOTDIR/lib64`` or -# ``EXECROOTDIR/lib/<multiarch-tuple`` on Debian) [``LIB_INSTALL_DIR``] -# ``LIBEXECDIR`` -# executables for internal use by programs and libraries (``BINDIR`` on -# Windows, ``LIBDIR/libexec`` otherwise) [``LIBEXEC_INSTALL_DIR``] -# ``CMAKEPACKAGEDIR`` -# CMake packages, including config files (``LIBDIR/cmake``) -# [``CMAKECONFIG_INSTALL_PREFIX``] -# ``QTPLUGINDIR`` -# Qt plugins (``LIBDIR/plugins`` or qmake-qt5's ``QT_INSTALL_PLUGINS``) [``QT_PLUGIN_INSTALL_DIR``] -# ``PLUGINDIR`` -# Plugins (``QTPLUGINDIR``) [``PLUGIN_INSTALL_DIR``] -# ``QTQUICKIMPORTSDIR`` -# QtQuick1 imports (``QTPLUGINDIR/imports`` or qmake-qt5's ``QT_INSTALL_IMPORTS``) [``IMPORTS_INSTALL_DIR``] -# ``QMLDIR`` -# QtQuick2 imports (``LIBDIR/qml`` or qmake-qt5's ``QT_INSTALL_QML``) [``QML_INSTALL_DIR``] -# ``INCLUDEDIR`` -# C and C++ header files (``include``) [``INCLUDE_INSTALL_DIR``] -# ``LOCALSTATEDIR`` -# modifiable single-machine data (``var``) -# ``SHAREDSTATEDIR`` -# modifiable architecture-independent data (``com``) -# ``DATAROOTDIR`` -# read-only architecture-independent data root (``share``) -# [``SHARE_INSTALL_PREFIX``] -# ``DATADIR`` -# read-only architecture-independent data (``DATAROOTDIR``) -# [``DATA_INSTALL_DIR``] -# ``DOCBUNDLEDIR`` -# documentation bundles generated using kdoctools -# (``DATAROOTDIR/doc/HTML``) [``HTML_INSTALL_DIR``] -# ``KCFGDIR`` -# kconfig description files (``DATAROOTDIR/config.kcfg``) -# [``KCFG_INSTALL_DIR``] -# ``KCONFUPDATEDIR`` -# kconf_update scripts (``DATAROOTDIR/kconf_update``) -# [``KCONF_UPDATE_INSTALL_DIR``] -# ``KSERVICES5DIR`` -# services for KDE Frameworks 5 (``DATAROOTDIR/kservices5``) -# [``SERVICES_INSTALL_DIR``] -# ``KSERVICETYPES5DIR`` -# service types for KDE Frameworks 5 (``DATAROOTDIR/kservicetypes5``) -# [``SERVICETYPES_INSTALL_DIR``] -# ``KXMLGUI5DIR`` -# knotify description files (``DATAROOTDIR/kxmlgui5``) -# [``KXMLGUI_INSTALL_DIR``] -# ``KTEMPLATESDIR`` -# Kapptemplate and Kdevelop templates (``kdevappwizard/templates``) -# ``KNOTIFY5RCDIR`` -# knotify description files (``DATAROOTDIR/knotifications5``) -# [``KNOTIFYRC_INSTALL_DIR``] -# ``ICONDIR`` -# icons (``DATAROOTDIR/icons``) [``ICON_INSTALL_DIR``] -# ``LOCALEDIR`` -# knotify description files (``DATAROOTDIR/locale``) -# [``LOCALE_INSTALL_DIR``] -# ``SOUNDDIR`` -# sound files (``DATAROOTDIR/sounds``) [``SOUND_INSTALL_DIR``] -# ``TEMPLATEDIR`` -# templates (``DATAROOTDIR/templates``) [``TEMPLATES_INSTALL_DIR``] -# ``WALLPAPERDIR`` -# desktop wallpaper images (``DATAROOTDIR/wallpapers``) -# [``WALLPAPER_INSTALL_DIR``] -# ``APPDIR`` -# application desktop files (``DATAROOTDIR/applications``) Since 1.1.0. -# [``XDG_APPS_INSTALL_DIR``] -# ``DESKTOPDIR`` -# desktop directories (``DATAROOTDIR/desktop-directories``) -# [``XDG_DIRECTORY_INSTALL_DIR``] -# ``MIMEDIR`` -# mime description files (``DATAROOTDIR/mime/packages``) -# [``XDG_MIME_INSTALL_DIR``] -# ``METAINFODIR`` -# AppStream component metadata files (``DATAROOTDIR/metainfo``) -# ``QTQCHDIR`` -# documentation bundles in QCH format for Qt-extending libraries (``DATAROOTDIR/doc/qch`` or qmake-qt5's ``QT_INSTALL_DOCS``) Since 5.36.0. -# ``QCHDIR`` -# documentation bundles in QCH format (``DATAROOTDIR/doc/qch``) Since 5.36.0. -# ``MANDIR`` -# man documentation (``DATAROOTDIR/man``) [``MAN_INSTALL_DIR``] -# ``INFODIR`` -# info documentation (``DATAROOTDIR/info``) -# ``DBUSDIR`` -# D-Bus (``DATAROOTDIR/dbus-1``) -# ``DBUSINTERFACEDIR`` -# D-Bus interfaces (``DBUSDIR/interfaces``) -# [``DBUS_INTERFACES_INSTALL_DIR``] -# ``DBUSSERVICEDIR`` -# D-Bus session services (``DBUSDIR/services``) -# [``DBUS_SERVICES_INSTALL_DIR``] -# ``DBUSSYSTEMSERVICEDIR`` -# D-Bus system services (``DBUSDIR/system-services``) -# [``DBUS_SYSTEM_SERVICES_INSTALL_DIR``] -# ``SYSCONFDIR`` -# read-only single-machine data -# (``etc``, or ``/etc`` if ``CMAKE_INSTALL_PREFIX`` is ``/usr``) -# [``SYSCONF_INSTALL_DIR``] -# ``CONFDIR`` -# application configuration files (``SYSCONFDIR/xdg``) -# [``CONFIG_INSTALL_DIR``] -# ``AUTOSTARTDIR`` -# autostart files (``CONFDIR/autostart``) [``AUTOSTART_INSTALL_DIR``] -# ``LOGGINGCATEGORIESDIR`` -# Qt logging categories files directory (``DATAROOTDIR/qlogging-categories5``) Since 5.59.0 -# ``JARDIR`` -# Java AAR/JAR files for Android. Since 5.62.0 -# ``SYSTEMDUNITDIR`` -# Systemd Units (``lib/systemd``) -# [``SYSTEMD_UNIT_INSTALL_DIR``]. Since 5.65 -# ``SYSTEMDUSERUNITDIR`` -# Systemd User Units (``lib/systemd/user``) -# [``SYSTEMD_USER_UNIT_INSTALL_DIR``]. Since 5.65 -# -# If ``KDE_INSTALL_USE_QT_SYS_PATHS`` is set to TRUE before including this -# module, the default values for some variables are instead queried from -# Qt5's qmake (where mentioned in the parentheses above). -# If not set, it will default to TRUE if Qt5's qmake is found and -# it's ``QT_INSTALL_PREFIX`` is the same as ``CMAKE_INSTALL_PREFIX``, -# otherwise default to FALSE. -# This variable should NOT be set from within CMakeLists.txt files, instead -# is intended to be set manually when configuring a project which uses -# KDEInstallDirs (e.g. by packagers). -# -# If ``KDE_INSTALL_DIRS_NO_DEPRECATED`` is set to TRUE before including this -# module, the deprecated variables (listed in the square brackets above) are -# not defined. -# -# In addition, for each ``KDE_INSTALL_*`` variable, an equivalent -# ``CMAKE_INSTALL_*`` variable is defined. If -# ``KDE_INSTALL_DIRS_NO_DEPRECATED`` is set to TRUE, only those variables -# defined by the ``GNUInstallDirs`` module (shipped with CMake) are defined. -# If ``KDE_INSTALL_DIRS_NO_CMAKE_VARIABLES`` is set to TRUE, no variables with -# a ``CMAKE_`` prefix will be defined by this module (other than -# CMAKE_INSTALL_DEFAULT_COMPONENT_NAME - see below). -# -# The ``KDE_INSTALL_<dir>`` variables (or their ``CMAKE_INSTALL_<dir>`` or -# deprecated counterparts) may be passed to the DESTINATION options of -# ``install()`` commands for the corresponding file type. They are set in the -# CMake cache, and so the defaults above can be overridden by users. -# -# Note that the ``KDE_INSTALL_<dir>``, ``CMAKE_INSTALL_<dir>`` or deprecated -# form of the variable can be changed using CMake command line variable -# definitions; in either case, all forms of the variable will be affected. The -# effect of passing multiple forms of the same variable on the command line -# (such as ``KDE_INSTALL_BINDIR`` and ``CMAKE_INSTALL_BINDIR`` is undefined. -# -# The variable ``KDE_INSTALL_TARGETS_DEFAULT_ARGS`` is also defined (along with -# the deprecated form ``INSTALL_TARGETS_DEFAULT_ARGS``). This should be used -# when libraries or user-executable applications are installed, in the -# following manner: -# -# .. code-block:: cmake -# -# install(TARGETS mylib myapp ${KDE_INSTALL_TARGETS_DEFAULT_ARGS}) -# -# It MUST NOT be used for installing plugins, system admin executables or -# executables only intended for use internally by other code. Those should use -# ``KDE_INSTALL_PLUGINDIR``, ``KDE_INSTALL_SBINDIR`` or -# ``KDE_INSTALL_LIBEXECDIR`` respectively. -# -# Additionally, ``CMAKE_INSTALL_DEFAULT_COMPONENT_NAME`` will be set to -# ``${PROJECT_NAME}`` to provide a sensible default for this CMake option. -# -# Note that mixing absolute and relative paths, particularly for ``BINDIR``, -# ``LIBDIR`` and ``INCLUDEDIR``, can cause issues with exported targets. Given -# that the default values for these are relative paths, relative paths should -# be used on the command line when possible (eg: use -# ``-DKDE_INSTALL_LIBDIR=lib64`` instead of -# ``-DKDE_INSTALL_LIBDIR=/usr/lib/lib64`` to override the library directory). -# -# Since pre-1.0.0. -# -# NB: The variables starting ``KDE_INSTALL_`` are available since 1.6.0, -# unless otherwise noted with the variable. -# -# The ``KDE_INSTALL_PREFIX_SCRIPT`` option will install a ${CMAKE_INSTALL_PREFIX}/prefix.sh -# file that allows to easily incorporate the necessary environment variables -# for the prefix into a process. -# - -#============================================================================= # SPDX-FileCopyrightText: 2014-2015 Alex Merry <alex.merry@kde.org> # SPDX-FileCopyrightText: 2013 Stephen Kelly <steveire@gmail.com> # SPDX-FileCopyrightText: 2012 David Faure <faure@kde.org> @@ -220,6 +7,218 @@ # # SPDX-License-Identifier: BSD-3-Clause +#[=======================================================================[.rst: +KDEInstallDirs +-------------- + +Define KDE standard installation directories. + +Note that none of the variables defined by this module provide any +information about the location of already-installed KDE software. + +Also sets ``CMAKE_INSTALL_PREFIX`` to the installation prefix of ECM, +unless that variable has been already explicitly set by something else +(since 5.61 and with CMake >= 3.7). + +Inclusion of this module defines the following variables: + +``KDE_INSTALL_<dir>`` + destination for files of a given type +``KDE_INSTALL_FULL_<dir>`` + corresponding absolute path + +where ``<dir>`` is one of (default values in parentheses and alternative, +deprecated variable name in square brackets): + +``BUNDLEDIR`` + application bundles (``/Applications/KDE``) [``BUNDLE_INSTALL_DIR``] +``EXECROOTDIR`` + executables and libraries (``<empty>``) [``EXEC_INSTALL_PREFIX``] +``BINDIR`` + user executables (``EXECROOTDIR/bin``) [``BIN_INSTALL_DIR``] +``SBINDIR`` + system admin executables (``EXECROOTDIR/sbin``) [``SBIN_INSTALL_DIR``] +``LIBDIR`` + object code libraries (``EXECROOTDIR/lib``, ``EXECROOTDIR/lib64`` or + ``EXECROOTDIR/lib/<multiarch-tuple`` on Debian) [``LIB_INSTALL_DIR``] +``LIBEXECDIR`` + executables for internal use by programs and libraries (``BINDIR`` on + Windows, ``LIBDIR/libexec`` otherwise) [``LIBEXEC_INSTALL_DIR``] +``CMAKEPACKAGEDIR`` + CMake packages, including config files (``LIBDIR/cmake``) + [``CMAKECONFIG_INSTALL_PREFIX``] +``QTPLUGINDIR`` + Qt plugins (``LIBDIR/plugins`` or qmake-qt5's ``QT_INSTALL_PLUGINS``) [``QT_PLUGIN_INSTALL_DIR``] +``PLUGINDIR`` + Plugins (``QTPLUGINDIR``) [``PLUGIN_INSTALL_DIR``] +``QTQUICKIMPORTSDIR`` + QtQuick1 imports (``QTPLUGINDIR/imports`` or qmake-qt5's ``QT_INSTALL_IMPORTS``) [``IMPORTS_INSTALL_DIR``] +``QMLDIR`` + QtQuick2 imports (``LIBDIR/qml`` or qmake-qt5's ``QT_INSTALL_QML``) [``QML_INSTALL_DIR``] +``INCLUDEDIR`` + C and C++ header files (``include``) [``INCLUDE_INSTALL_DIR``] +``LOCALSTATEDIR`` + modifiable single-machine data (``var``) +``SHAREDSTATEDIR`` + modifiable architecture-independent data (``com``) +``DATAROOTDIR`` + read-only architecture-independent data root (``share``) + [``SHARE_INSTALL_PREFIX``] +``DATADIR`` + read-only architecture-independent data (``DATAROOTDIR``) + [``DATA_INSTALL_DIR``] +``DOCBUNDLEDIR`` + documentation bundles generated using kdoctools + (``DATAROOTDIR/doc/HTML``) [``HTML_INSTALL_DIR``] +``KCFGDIR`` + kconfig description files (``DATAROOTDIR/config.kcfg``) + [``KCFG_INSTALL_DIR``] +``KCONFUPDATEDIR`` + kconf_update scripts (``DATAROOTDIR/kconf_update``) + [``KCONF_UPDATE_INSTALL_DIR``] +``KSERVICES5DIR`` + services for KDE Frameworks 5 (``DATAROOTDIR/kservices5``) + [``SERVICES_INSTALL_DIR``] +``KSERVICETYPES5DIR`` + service types for KDE Frameworks 5 (``DATAROOTDIR/kservicetypes5``) + [``SERVICETYPES_INSTALL_DIR``] +``KXMLGUI5DIR`` + knotify description files (``DATAROOTDIR/kxmlgui5``) + [``KXMLGUI_INSTALL_DIR``] +``KTEMPLATESDIR`` + Kapptemplate and Kdevelop templates (``kdevappwizard/templates``) +``KNOTIFY5RCDIR`` + knotify description files (``DATAROOTDIR/knotifications5``) + [``KNOTIFYRC_INSTALL_DIR``] +``ICONDIR`` + icons (``DATAROOTDIR/icons``) [``ICON_INSTALL_DIR``] +``LOCALEDIR`` + knotify description files (``DATAROOTDIR/locale``) + [``LOCALE_INSTALL_DIR``] +``SOUNDDIR`` + sound files (``DATAROOTDIR/sounds``) [``SOUND_INSTALL_DIR``] +``TEMPLATEDIR`` + templates (``DATAROOTDIR/templates``) [``TEMPLATES_INSTALL_DIR``] +``WALLPAPERDIR`` + desktop wallpaper images (``DATAROOTDIR/wallpapers``) + [``WALLPAPER_INSTALL_DIR``] +``APPDIR`` + application desktop files (``DATAROOTDIR/applications``) Since 1.1.0. + [``XDG_APPS_INSTALL_DIR``] +``DESKTOPDIR`` + desktop directories (``DATAROOTDIR/desktop-directories``) + [``XDG_DIRECTORY_INSTALL_DIR``] +``MIMEDIR`` + mime description files (``DATAROOTDIR/mime/packages``) + [``XDG_MIME_INSTALL_DIR``] +``METAINFODIR`` + AppStream component metadata files (``DATAROOTDIR/metainfo``) +``QTQCHDIR`` + documentation bundles in QCH format for Qt-extending libraries (``DATAROOTDIR/doc/qch`` or qmake-qt5's ``QT_INSTALL_DOCS``) Since 5.36.0. +``QCHDIR`` + documentation bundles in QCH format (``DATAROOTDIR/doc/qch``) Since 5.36.0. +``MANDIR`` + man documentation (``DATAROOTDIR/man``) [``MAN_INSTALL_DIR``] +``INFODIR`` + info documentation (``DATAROOTDIR/info``) +``DBUSDIR`` + D-Bus (``DATAROOTDIR/dbus-1``) +``DBUSINTERFACEDIR`` + D-Bus interfaces (``DBUSDIR/interfaces``) + [``DBUS_INTERFACES_INSTALL_DIR``] +``DBUSSERVICEDIR`` + D-Bus session services (``DBUSDIR/services``) + [``DBUS_SERVICES_INSTALL_DIR``] +``DBUSSYSTEMSERVICEDIR`` + D-Bus system services (``DBUSDIR/system-services``) + [``DBUS_SYSTEM_SERVICES_INSTALL_DIR``] +``SYSCONFDIR`` + read-only single-machine data + (``etc``, or ``/etc`` if ``CMAKE_INSTALL_PREFIX`` is ``/usr``) + [``SYSCONF_INSTALL_DIR``] +``CONFDIR`` + application configuration files (``SYSCONFDIR/xdg``) + [``CONFIG_INSTALL_DIR``] +``AUTOSTARTDIR`` + autostart files (``CONFDIR/autostart``) [``AUTOSTART_INSTALL_DIR``] +``LOGGINGCATEGORIESDIR`` + Qt logging categories files directory (``DATAROOTDIR/qlogging-categories5``) Since 5.59.0 +``JARDIR`` + Java AAR/JAR files for Android. Since 5.62.0 +``SYSTEMDUNITDIR`` + Systemd Units (``lib/systemd``) + [``SYSTEMD_UNIT_INSTALL_DIR``]. Since 5.65 +``SYSTEMDUSERUNITDIR`` + Systemd User Units (``lib/systemd/user``) + [``SYSTEMD_USER_UNIT_INSTALL_DIR``]. Since 5.65 + +If ``KDE_INSTALL_USE_QT_SYS_PATHS`` is set to TRUE before including this +module, the default values for some variables are instead queried from +Qt5's qmake (where mentioned in the parentheses above). +If not set, it will default to TRUE if Qt5's qmake is found and +it's ``QT_INSTALL_PREFIX`` is the same as ``CMAKE_INSTALL_PREFIX``, +otherwise default to FALSE. +This variable should NOT be set from within CMakeLists.txt files, instead +is intended to be set manually when configuring a project which uses +KDEInstallDirs (e.g. by packagers). + +If ``KDE_INSTALL_DIRS_NO_DEPRECATED`` is set to TRUE before including this +module, the deprecated variables (listed in the square brackets above) are +not defined. + +In addition, for each ``KDE_INSTALL_*`` variable, an equivalent +``CMAKE_INSTALL_*`` variable is defined. If +``KDE_INSTALL_DIRS_NO_DEPRECATED`` is set to TRUE, only those variables +defined by the ``GNUInstallDirs`` module (shipped with CMake) are defined. +If ``KDE_INSTALL_DIRS_NO_CMAKE_VARIABLES`` is set to TRUE, no variables with +a ``CMAKE_`` prefix will be defined by this module (other than +CMAKE_INSTALL_DEFAULT_COMPONENT_NAME - see below). + +The ``KDE_INSTALL_<dir>`` variables (or their ``CMAKE_INSTALL_<dir>`` or +deprecated counterparts) may be passed to the DESTINATION options of +``install()`` commands for the corresponding file type. They are set in the +CMake cache, and so the defaults above can be overridden by users. + +Note that the ``KDE_INSTALL_<dir>``, ``CMAKE_INSTALL_<dir>`` or deprecated +form of the variable can be changed using CMake command line variable +definitions; in either case, all forms of the variable will be affected. The +effect of passing multiple forms of the same variable on the command line +(such as ``KDE_INSTALL_BINDIR`` and ``CMAKE_INSTALL_BINDIR`` is undefined. + +The variable ``KDE_INSTALL_TARGETS_DEFAULT_ARGS`` is also defined (along with +the deprecated form ``INSTALL_TARGETS_DEFAULT_ARGS``). This should be used +when libraries or user-executable applications are installed, in the +following manner: + +.. code-block:: cmake + + install(TARGETS mylib myapp ${KDE_INSTALL_TARGETS_DEFAULT_ARGS}) + +It MUST NOT be used for installing plugins, system admin executables or +executables only intended for use internally by other code. Those should use +``KDE_INSTALL_PLUGINDIR``, ``KDE_INSTALL_SBINDIR`` or +``KDE_INSTALL_LIBEXECDIR`` respectively. + +Additionally, ``CMAKE_INSTALL_DEFAULT_COMPONENT_NAME`` will be set to +``${PROJECT_NAME}`` to provide a sensible default for this CMake option. + +Note that mixing absolute and relative paths, particularly for ``BINDIR``, +``LIBDIR`` and ``INCLUDEDIR``, can cause issues with exported targets. Given +that the default values for these are relative paths, relative paths should +be used on the command line when possible (eg: use +``-DKDE_INSTALL_LIBDIR=lib64`` instead of +``-DKDE_INSTALL_LIBDIR=/usr/lib/lib64`` to override the library directory). + +Since pre-1.0.0. + +NB: The variables starting ``KDE_INSTALL_`` are available since 1.6.0, +unless otherwise noted with the variable. + +The ``KDE_INSTALL_PREFIX_SCRIPT`` option will install a ${CMAKE_INSTALL_PREFIX}/prefix.sh +file that allows to easily incorporate the necessary environment variables +for the prefix into a process. +#]=======================================================================] + # Figure out what the default install directory for libraries should be. # This is based on the logic in GNUInstallDirs, but simplified (the # GNUInstallDirs code deals with re-configuring, but that is dealt with diff --git a/kde-modules/KDEPackageAppTemplates.cmake b/kde-modules/KDEPackageAppTemplates.cmake index ae4284be..951fcee1 100644 --- a/kde-modules/KDEPackageAppTemplates.cmake +++ b/kde-modules/KDEPackageAppTemplates.cmake @@ -1,66 +1,3 @@ -#.rst: -# KDETemplateGenerator -# -------------------- -# -# Packages KApptemplate/KDevelop compatible application templates -# -# This module provides a functionality to package in a tarball and -# install project templates compatible with the format used by -# KApptemplate and KDevelop. Useful for providing minimal examples -# for the usage of the KDE Frameworks. -# -# This module provides the following function: -# -# :: -# -# kde_package_app_templates(TEMPLATES <template> [<template> [...]] -# INSTALL_DIR <directory>) -# -# INSTALL_DIR is the directory to install the template package to. -# In most cases you will want to use the variable KDE_INSTALL_KTEMPLATESDIR -# from :kde-module:`KDEInstallDirs`. -# -# TEMPLATES lists subdirectories containing template files; -# each ``<template>`` directory will be packaged into a file named -# ``<template>.tar.bz2`` and installed to the appropriate location. -# -# The template is a minimal source tree of an application as if it was -# an application project by itself, with names (file names or text inside) -# the text files replaced by the following placeholders when needed: -# -# ``%{PROJECTDIRNAME}`` -# name of generated project base folder ex: %{APPNAMELC} for KAppTemplate -# ``%{APPNAME}`` -# project name as entered by user ex: MyKApp -# ``%{APPNAMELC}`` -# project name in lower case ex: mykapp -# ``%{APPNAMEUC}`` -# project name in upper case ex: MYKAPP -# -# ``%{CPP_TEMPLATE}`` -# license header for cpp file -# ``%{H_TEMPLATE}`` -# license header for h file -# -# ``%{AUTHOR}`` -# author name ex: George Ignacious -# ``%{EMAIL}`` -# author email ex: foo@bar.org -# ``%{VERSION}`` -# project version ex: 0.1 -# -# Deprecated: -# -# ``%{dest}`` -# path of generated project base folder, used in .kdevtemplate with the ShowFilesAfterGeneration entry -# KDevelop >= 5.1.1 supports relative paths with that entry, making this placeholder obsolete -# -# Multiple templates can be passed at once. -# -# -# Since 5.18 - -#============================================================================= # SPDX-FileCopyrightText: 2015 Marco Martin <mart@kde.org> # SPDX-FileCopyrightText: 2014 Simon Wächter <waechter.simon@gmail.com> # SPDX-FileCopyrightText: 2013 Nico Kruber <nico.kruber@gmail.com> @@ -68,6 +5,69 @@ # # SPDX-License-Identifier: BSD-3-Clause +#[=======================================================================[.rst: +KDETemplateGenerator +-------------------- + +Packages KApptemplate/KDevelop compatible application templates + +This module provides a functionality to package in a tarball and +install project templates compatible with the format used by +KApptemplate and KDevelop. Useful for providing minimal examples +for the usage of the KDE Frameworks. + +This module provides the following function: + +:: + + kde_package_app_templates(TEMPLATES <template> [<template> [...]] + INSTALL_DIR <directory>) + +INSTALL_DIR is the directory to install the template package to. +In most cases you will want to use the variable KDE_INSTALL_KTEMPLATESDIR +from :kde-module:`KDEInstallDirs`. + +TEMPLATES lists subdirectories containing template files; +each ``<template>`` directory will be packaged into a file named +``<template>.tar.bz2`` and installed to the appropriate location. + +The template is a minimal source tree of an application as if it was +an application project by itself, with names (file names or text inside) +the text files replaced by the following placeholders when needed: + +``%{PROJECTDIRNAME}`` + name of generated project base folder ex: %{APPNAMELC} for KAppTemplate +``%{APPNAME}`` + project name as entered by user ex: MyKApp +``%{APPNAMELC}`` + project name in lower case ex: mykapp +``%{APPNAMEUC}`` + project name in upper case ex: MYKAPP + +``%{CPP_TEMPLATE}`` + license header for cpp file +``%{H_TEMPLATE}`` + license header for h file + +``%{AUTHOR}`` + author name ex: George Ignacious +``%{EMAIL}`` + author email ex: foo@bar.org +``%{VERSION}`` + project version ex: 0.1 + +Deprecated: + +``%{dest}`` + path of generated project base folder, used in .kdevtemplate with the ShowFilesAfterGeneration entry + KDevelop >= 5.1.1 supports relative paths with that entry, making this placeholder obsolete + +Multiple templates can be passed at once. + + +Since 5.18 +#]=======================================================================] + include(CMakeParseArguments) function(kde_package_app_templates) 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) diff --git a/toolchain/Android.cmake b/toolchain/Android.cmake index db70de50..3f2443c6 100644 --- a/toolchain/Android.cmake +++ b/toolchain/Android.cmake @@ -1,137 +1,137 @@ -#.rst: -# AndroidToolchain -# ---------------- -# -# Enable easy compilation of cmake projects on Android. -# -# By using this android toolchain, the projects will be set up to compile the -# specified project targeting an Android platform, depending on its input. -# Furthermore, if desired, an APK can be directly generated by using the -# `androiddeployqt <https://doc.qt.io/qt-5/deployment-android.html>`_ tool. -# -# CMake upstream has Android support now. This module will still give us some -# useful features offering androiddeployqt integration and adequate executables -# format for our Android applications. -# -# Since we are using CMake Android support, any information from CMake documentation -# still applies: -# https://cmake.org/cmake/help/v3.7/manual/cmake-toolchains.7.html#cross-compiling-for-android -# -# .. note:: -# -# This module requires CMake 3.18. -# -# Since 1.7.0. -# -# Usage -# ===== -# -# To use this file, you need to set the ``CMAKE_TOOLCHAIN_FILE`` to point to -# ``Android.cmake`` on the command line:: -# -# cmake -DCMAKE_TOOLCHAIN_FILE=/usr/share/ECM/toolchain/Android.cmake -# -# You will also need to provide the locations of the Android NDK and SDK. This -# can be done on the commandline or with environment variables; in either case -# the variable names are: -# -# ``CMAKE_ANDROID_NDK`` -# The NDK root path. -# ``ANDROID_SDK_ROOT`` -# The SDK root path. -# -# Additional options are specified as cache variables (eg: on the command line): -# -# ``ANDROID_ABI`` -# The ABI to use. See the ``sources/cxx-stl/gnu-libstdc++/*/libs`` -# directories in the NDK. Default: ``armeabi-v7a``. -# ``ANDROID_SDK_COMPILE_API`` -# The platform API level to compile against. May be different from the NDK -# target. Default: newest installed version (e.g. android-30). -# ``ANDROID_SDK_BUILD_TOOLS_REVISION`` -# The build tools version to use. -# Default: newest installed version (e.g. ``30.0.2``). -# ``ANDROID_EXTRA_LIBS`` -# The ";"-separated list of full paths to libs to include in resulting APK. -# -# For integrating other libraries which are not part of the Android toolchain, -# like Qt5, and installed to a separate prefix on the host system, the install -# prefixes of those libraries would be passed as alternative roots as list via -# ``ECM_ADDITIONAL_FIND_ROOT_PATH``. Since 5.30.0. -# -# For example, for integrating a Qt5 for Android present at -# ``~/Qt/5.14.2/android/`` and some other libraries installed to -# the prefix ``/opt/android/foo``, you would use:: -# -# cmake \ -# -DCMAKE_TOOLCHAIN_FILE=/usr/share/ECM/toolchain/Android.cmake \ -# -DECM_ADDITIONAL_FIND_ROOT_PATH="~/Qt/5.14.2/android/;/opt/android/foo" -# -# If your project uses ``find_package()`` to locate build tools on the host -# system, make sure to pass ``CMAKE_FIND_ROOT_PATH_BOTH`` or -# ``NO_CMAKE_FIND_ROOT_PATH`` as argument in the call. See the -# ``find_package()`` documentation for more details. -# -# Deploying Qt Applications -# ========================= -# -# After building the application, you will need to generate an APK that can be -# deployed to an Android device. This module integrates androiddeployqt support -# to help with this for Qt-based projects. To enable this, set the -# ``QTANDROID_EXPORTED_TARGET`` variable to the targets you wish to export as an -# APK (in a ;-separed list), as well as ``ANDROID_APK_DIR`` to a directory -# containing some basic information. This will create a ``create-apk-<target>`` -# target that will generate the APK file. See the `Qt on Android deployment -# documentation <https://doc.qt.io/qt-5/deployment-android.html>`_ for more -# information. -# -# For example, you could do:: -# -# cmake \ -# -DCMAKE_TOOLCHAIN_FILE=/usr/share/ECM/toolchain/Android.cmake \ -# -DQTANDROID_EXPORTED_TARGET=myapp \ -# -DANDROID_APK_DIR=myapp-apk -# make -# make create-apk-myapp -# -# You can specify the APK output directory by setting ``ANDROID_APK_OUTPUT_DIR``. -# Otherwise the APK can be found in ``myapp_build_apk/`` in the build directory. -# -# The create-apk-myapp target will be able to take an ARGS parameter with further -# arguments for androiddeployqt. For example, one can use:: -# -# make create-apk-myapp ARGS="--install" -# -# To install the apk to test. To generate a signed apk, one can do it with the -# following syntax:: -# -# make create-apk-myapp ARGS="--sign ~/my.keystore alias_name" -# -# In case it's needed for your application to set the APK directory from cmake -# scripting you can also set the directory as the ANDROID_APK_DIR property of -# the create-apk-myapp target. -# -# See Android documentation on how to create a keystore to use -# -# Advanced Options -# ================ -# -# The following packaging options are mainly interesting for automation or integration -# with CI/CD pipelines: -# ``ANDROID_APK_OUTPUT_DIR`` -# Specifies a folder where the generated APK files should be placed. -# ``ANDROID_FASTLANE_METADATA_OUTPUT_DIR`` -# Specifies a folder where the generated metadata for the F-Droid store -# should be placed. -# ``ANDROIDDEPLOYQT_EXTRA_ARGS`` -# Allows to pass additional arguments to `androiddeployqt`. This is an alternative to -# the `ARGS=` argument for `make` and unlike that works with all CMake generators. - -# ============================================================================= # SPDX-FileCopyrightText: 2014 Aleix Pol i Gonzalez <aleixpol@kde.org> # # SPDX-License-Identifier: BSD-3-Clause +#[=======================================================================[.rst: +AndroidToolchain +---------------- + +Enable easy compilation of cmake projects on Android. + +By using this android toolchain, the projects will be set up to compile the +specified project targeting an Android platform, depending on its input. +Furthermore, if desired, an APK can be directly generated by using the +`androiddeployqt <https://doc.qt.io/qt-5/deployment-android.html>`_ tool. + +CMake upstream has Android support now. This module will still give us some +useful features offering androiddeployqt integration and adequate executables +format for our Android applications. + +Since we are using CMake Android support, any information from CMake documentation +still applies: +https://cmake.org/cmake/help/v3.7/manual/cmake-toolchains.7.html#cross-compiling-for-android + +.. note:: + + This module requires CMake 3.18. + +Since 1.7.0. + +Usage +===== + +To use this file, you need to set the ``CMAKE_TOOLCHAIN_FILE`` to point to +``Android.cmake`` on the command line:: + + cmake -DCMAKE_TOOLCHAIN_FILE=/usr/share/ECM/toolchain/Android.cmake + +You will also need to provide the locations of the Android NDK and SDK. This +can be done on the commandline or with environment variables; in either case +the variable names are: + +``CMAKE_ANDROID_NDK`` + The NDK root path. +``ANDROID_SDK_ROOT`` + The SDK root path. + +Additional options are specified as cache variables (eg: on the command line): + +``ANDROID_ABI`` + The ABI to use. See the ``sources/cxx-stl/gnu-libstdc++/*/libs`` + directories in the NDK. Default: ``armeabi-v7a``. +``ANDROID_SDK_COMPILE_API`` + The platform API level to compile against. May be different from the NDK + target. Default: newest installed version (e.g. android-30). +``ANDROID_SDK_BUILD_TOOLS_REVISION`` + The build tools version to use. + Default: newest installed version (e.g. ``30.0.2``). +``ANDROID_EXTRA_LIBS`` + The ";"-separated list of full paths to libs to include in resulting APK. + +For integrating other libraries which are not part of the Android toolchain, +like Qt5, and installed to a separate prefix on the host system, the install +prefixes of those libraries would be passed as alternative roots as list via +``ECM_ADDITIONAL_FIND_ROOT_PATH``. Since 5.30.0. + +For example, for integrating a Qt5 for Android present at +``~/Qt/5.14.2/android/`` and some other libraries installed to +the prefix ``/opt/android/foo``, you would use:: + + cmake \ + -DCMAKE_TOOLCHAIN_FILE=/usr/share/ECM/toolchain/Android.cmake \ + -DECM_ADDITIONAL_FIND_ROOT_PATH="~/Qt/5.14.2/android/;/opt/android/foo" + +If your project uses ``find_package()`` to locate build tools on the host +system, make sure to pass ``CMAKE_FIND_ROOT_PATH_BOTH`` or +``NO_CMAKE_FIND_ROOT_PATH`` as argument in the call. See the +``find_package()`` documentation for more details. + +Deploying Qt Applications +========================= + +After building the application, you will need to generate an APK that can be +deployed to an Android device. This module integrates androiddeployqt support +to help with this for Qt-based projects. To enable this, set the +``QTANDROID_EXPORTED_TARGET`` variable to the targets you wish to export as an +APK (in a ;-separed list), as well as ``ANDROID_APK_DIR`` to a directory +containing some basic information. This will create a ``create-apk-<target>`` +target that will generate the APK file. See the `Qt on Android deployment +documentation <https://doc.qt.io/qt-5/deployment-android.html>`_ for more +information. + +For example, you could do:: + + cmake \ + -DCMAKE_TOOLCHAIN_FILE=/usr/share/ECM/toolchain/Android.cmake \ + -DQTANDROID_EXPORTED_TARGET=myapp \ + -DANDROID_APK_DIR=myapp-apk + make + make create-apk-myapp + +You can specify the APK output directory by setting ``ANDROID_APK_OUTPUT_DIR``. +Otherwise the APK can be found in ``myapp_build_apk/`` in the build directory. + +The create-apk-myapp target will be able to take an ARGS parameter with further +arguments for androiddeployqt. For example, one can use:: + + make create-apk-myapp ARGS="--install" + +To install the apk to test. To generate a signed apk, one can do it with the +following syntax:: + + make create-apk-myapp ARGS="--sign ~/my.keystore alias_name" + +In case it's needed for your application to set the APK directory from cmake +scripting you can also set the directory as the ANDROID_APK_DIR property of +the create-apk-myapp target. + +See Android documentation on how to create a keystore to use + +Advanced Options +================ + +The following packaging options are mainly interesting for automation or integration +with CI/CD pipelines: +``ANDROID_APK_OUTPUT_DIR`` + Specifies a folder where the generated APK files should be placed. +``ANDROID_FASTLANE_METADATA_OUTPUT_DIR`` + Specifies a folder where the generated metadata for the F-Droid store + should be placed. +``ANDROIDDEPLOYQT_EXTRA_ARGS`` + Allows to pass additional arguments to `androiddeployqt`. This is an alternative to + the `ARGS=` argument for `make` and unlike that works with all CMake generators. +#]=======================================================================] + cmake_minimum_required(VERSION "3.18") macro(set_deprecated_variable actual_variable deprecated_variable default_value) |