From 5512e03562694ebfe571a3b6068a7d35d9ddfd7a Mon Sep 17 00:00:00 2001 From: "Friedrich W. H. Kossebau" Date: Sat, 17 Apr 2021 11:02:00 +0200 Subject: 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 --- cmake/FindQCollectionGenerator.cmake | 59 +- cmake/FindSphinx.cmake | 51 +- docs/manual/ecm-developer.7.rst | 107 ++-- find-modules/FindCanberra.cmake | 61 ++- find-modules/FindEGL.cmake | 71 ++- find-modules/FindFontconfig.cmake | 53 +- find-modules/FindGLIB2.cmake | 55 +- find-modules/FindGperf.cmake | 90 ++-- find-modules/FindGradle.cmake | 49 +- find-modules/FindIcoTool.cmake | 55 +- find-modules/FindInotify.cmake | 51 +- find-modules/FindIsoCodes.cmake | 34 +- find-modules/FindKF5.cmake | 45 +- find-modules/FindLibExiv2.cmake | 71 ++- find-modules/FindLibGit2.cmake | 69 ++- find-modules/FindLibcap.cmake | 39 +- find-modules/FindOpenEXR.cmake | 59 +- find-modules/FindPhoneNumber.cmake | 59 +- find-modules/FindPoppler.cmake | 102 ++-- find-modules/FindPulseAudio.cmake | 67 ++- find-modules/FindPythonModuleGeneration.cmake | 115 ++-- find-modules/FindQHelpGenerator.cmake | 20 +- find-modules/FindQtWaylandScanner.cmake | 123 +++-- find-modules/FindReuseTool.cmake | 20 +- find-modules/FindSasl2.cmake | 66 ++- find-modules/FindSeccomp.cmake | 49 +- find-modules/FindSharedMimeInfo.cmake | 59 +- find-modules/FindTaglib.cmake | 54 +- find-modules/FindUDev.cmake | 59 +- find-modules/FindWayland.cmake | 107 ++-- find-modules/FindWaylandProtocols.cmake | 33 +- find-modules/FindWaylandScanner.cmake | 107 ++-- find-modules/FindX11_XCB.cmake | 73 ++- find-modules/FindXCB.cmake | 117 ++-- find-modules/Findepoxy.cmake | 67 +-- kde-modules/KDECMakeSettings.cmake | 204 ++++--- kde-modules/KDEClangFormat.cmake | 92 ++-- kde-modules/KDECompilerSettings.cmake | 76 +-- kde-modules/KDEFrameworkCompilerSettings.cmake | 40 +- kde-modules/KDEGitCommitHooks.cmake | 74 +-- kde-modules/KDEInstallDirs.cmake | 425 ++++++++------- kde-modules/KDEPackageAppTemplates.cmake | 126 ++--- modules/CheckAtomic.cmake | 25 +- modules/ECMAddAppIcon.cmake | 138 ++--- modules/ECMAddQch.cmake | 505 +++++++++--------- modules/ECMAddQtDesignerPlugin.cmake | 352 ++++++------ modules/ECMAddTests.cmake | 110 ++-- modules/ECMCheckOutboundLicense.cmake | 129 ++--- modules/ECMConfiguredInstall.cmake | 58 +- modules/ECMCoverageOption.cmake | 38 +- modules/ECMCreateQmFromPoFiles.cmake | 148 ++--- modules/ECMEnableSanitizers.cmake | 144 ++--- modules/ECMFindModuleHelpers.cmake | 200 +++---- modules/ECMGenerateDBusServiceFile.cmake | 104 ++-- modules/ECMGenerateExportHeader.cmake | 712 ++++++++++++------------- modules/ECMGenerateHeaders.cmake | 228 ++++---- modules/ECMGeneratePkgConfigFile.cmake | 151 +++--- modules/ECMGeneratePriFile.cmake | 148 ++--- modules/ECMGenerateQmlTypes.cmake | 50 +- modules/ECMInstallIcons.cmake | 132 ++--- modules/ECMMarkAsTest.cmake | 38 +- modules/ECMMarkNonGuiExecutable.cmake | 34 +- modules/ECMOptionalAddSubdirectory.cmake | 62 +-- modules/ECMPackageConfigHelpers.cmake | 104 ++-- modules/ECMPoQmTools.cmake | 142 ++--- modules/ECMQMLModules.cmake | 57 +- modules/ECMQtDeclareLoggingCategory.cmake | 290 +++++----- modules/ECMSetupQtPluginMacroNames.cmake | 190 +++---- modules/ECMSetupVersion.cmake | 160 +++--- modules/ECMSourceVersionControl.cmake | 26 +- modules/ECMUninstallTarget.cmake | 66 +-- modules/ECMUseFindModules.cmake | 100 ++-- modules/ECMWinResolveSymlinks.cmake | 49 +- toolchain/Android.cmake | 260 ++++----- 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 # # 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 # # 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 - # - # 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 # - # 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 # SPDX-FileCopyrightText: 2019 Harald Sitter # # 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 # SPDX-FileCopyrightText: 2014 Martin Gräßlin # # 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 # SPDX-FileCopyrightText: 2018 Volker Krause # # 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 # # 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( -# [GENERATION_FLAGS ]) -# -# Run ``gperf`` on ```` to generate ````, adding it to -# the ```` variable which contains the source for the target -# where ```` 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 # # 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( + [GENERATION_FLAGS ]) + +Run ``gperf`` on ```` to generate ````, adding it to +the ```` variable which contains the source for the target +where ```` 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( -# BUIDLFILE build.gradle -# NAME ) -# -# This builds an Android AAR library using the given ``build.gradle`` file. -# -# gradle_install_aar( -# DESTINATION ) -# -# Installs a Android AAR library that has been created with ``gradle_add_aar``. -# -# Since 5.76.0. - -#============================================================================= # SPDX-FileCopyrightText: 2019 Volker Krause # # 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( + BUIDLFILE build.gradle + NAME ) + +This builds an Android AAR library using the given ``build.gradle`` file. +:: + + gradle_install_aar( + DESTINATION ) + +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 # SPDX-FileCopyrightText: 2014 Alex Merry # # 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 # SPDX-FileCopyrightText: 2017 Adriaan de Groot # # 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 # SPDX-FileCopyrightText: 2021 Volker Krause # # 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 # SPDX-FileCopyrightText: 2013 Stephen Kelly # # 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 # SPDX-FileCopyrightText: 2010 Alexander Neundorf # SPDX-FileCopyrightText: 2008 Gilles Caulier # # 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 # SPDX-FileCopyrightText: 2014 Martin Gräßlin # SPDX-FileCopyrightText: 2014 Christoph Cullmann # # 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 # # 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 # SPDX-FileCopyrightText: 2006 Alexander Neundorf # # 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__FOUND`` will be set to -# TRUE if the corresponding library was found, and FALSE otherwise. If -# ``PhoneNumber__FOUND`` is TRUE, the imported target ``PhoneNumber::`` -# will be defined. -# -# Since 5.54.0. - -#============================================================================= # SPDX-FileCopyrightText: 2017 Klaralvdalens Datakonsult AB, a KDAB Group company # SPDX-FileCopyrightText: 2018 Volker Krause # # 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__FOUND`` will be set to +TRUE if the corresponding library was found, and FALSE otherwise. If +``PhoneNumber__FOUND`` is TRUE, the imported target ``PhoneNumber::`` +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__FOUND`` will be set to -# TRUE if the corresponding Poppler library was found, and FALSE otherwise. If -# ``Poppler__FOUND`` is TRUE, the imported target -# ``Poppler::`` 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 # # 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__FOUND`` will be set to +TRUE if the corresponding Poppler library was found, and FALSE otherwise. If +``Poppler__FOUND`` is TRUE, the imported target +``Poppler::`` 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 # SPDX-FileCopyrightText: 2009 Marcus Hufgard # # 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 -# PYTHONNAMESPACE -# MODULENAME -# RULES_FILE -# SIP_DEPENDS -# SIP_INCLUDES -# HEADERS ) -# -# Invoking the function will create bindings for the for python 2 and 3, -# if available. The bindings will be put in the namespace in python, -# and will be available from the module . -# -# 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 # # 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 + PYTHONNAMESPACE + MODULENAME + RULES_FILE + SIP_DEPENDS + SIP_INCLUDES + HEADERS ) + +Invoking the function will create bindings for the for python 2 and 3, +if available. The bindings will be put in the namespace in python, +and will be available from the module . + +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 # # 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( -# PROTOCOL -# BASENAME -# [PREFIX ]) -# -# Generate C++ wrapper to Wayland client protocol files from ```` -# XML definition for the ```` interface and append those files -# to ````. Pass the ```` 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( -# PROTOCOL -# BASENAME -# [PREFIX ]) -# -# Generate C++ wrapper to Wayland server protocol files from ```` -# XML definition for the ```` interface and append those files -# to ````. Pass the ```` 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 # # 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( + PROTOCOL + BASENAME + [PREFIX ]) + +Generate C++ wrapper to Wayland client protocol files from ```` +XML definition for the ```` interface and append those files +to ````. Pass the ```` 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( + PROTOCOL + BASENAME + [PREFIX ]) + +Generate C++ wrapper to Wayland server protocol files from ```` +XML definition for the ```` interface and append those files +to ````. Pass the ```` 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 # # 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 # -# # 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 # SPDX-FileCopyrightText: 2017 David Kahles # # 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() -# -# 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 # SPDX-FileCopyrightText: 2007 Pino Toscano # # 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() + +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 # SPDX-FileCopyrightText: 2019 Heiko Becker # SPDX-FileCopyrightText: 2020 Elvis Angelaccio +# # 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 # SPDX-FileCopyrightText: 2019 Volker Krause # # 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__FOUND`` will be set to -# TRUE if the corresponding Wayland library was found, and FALSE otherwise. If -# ``Wayland__FOUND`` is TRUE, the imported target -# ``Wayland::`` 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 # SPDX-FileCopyrightText: 2014 Martin Gräßlin # # 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__FOUND`` will be set to +TRUE if the corresponding Wayland library was found, and FALSE otherwise. If +``Wayland__FOUND`` is TRUE, the imported target +``Wayland::`` 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 # # 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( -# PROTOCOL -# BASENAME ) -# -# Generate Wayland client protocol files from ```` XML -# definition for the ```` interface and append those files -# to ````. -# -# :: -# -# ecm_add_wayland_server_protocol( -# PROTOCOL -# BASENAME ) -# -# Generate Wayland server protocol files from ```` XML -# definition for the ```` interface and append those files -# to ````. -# -# Since 1.4.0. - -#============================================================================= # SPDX-FileCopyrightText: 2012-2014 Pier Luigi Fiorini # # 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( + PROTOCOL + BASENAME ) + +Generate Wayland client protocol files from ```` XML +definition for the ```` interface and append those files +to ````. + +:: + + ecm_add_wayland_server_protocol( + PROTOCOL + BASENAME ) + +Generate Wayland server protocol files from ```` XML +definition for the ```` interface and append those files +to ````. + +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 # SPDX-FileCopyrightText: 2011 Fredrik Höglund # SPDX-FileCopyrightText: 2008 Helio Chissini de Castro # SPDX-FileCopyrightText: 2007 Matthias Kretz # # 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__FOUND`` will be set to -# true if the corresponding xcb library was found, and false otherwise. If -# ``XCB__FOUND`` is true, the imported target ``XCB::`` -# 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 # SPDX-FileCopyrightText: 2013 Martin Gräßlin # SPDX-FileCopyrightText: 2014-2015 Alex Merry # # 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__FOUND`` will be set to +true if the corresponding xcb library was found, and false otherwise. If +``XCB__FOUND`` is true, the imported target ``XCB::`` +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 # SPDX-FileCopyrightText: 2020 Vlad Zahorodnii # # 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 # SPDX-FileCopyrightText: 2013 Aleix Pol # SPDX-FileCopyrightText: 2012-2013 Stephen Kelly @@ -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() -# -# Using this function will create a clang-format target that will format all -# ```` 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 # SPDX-FileCopyrightText: 2021 Alexander Lohnau # # 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() + +Using this function will create a clang-format target that will format all +```` 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 ) -# -# 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 # SPDX-FileCopyrightText: 2013 Stephen Kelly # SPDX-FileCopyrightText: 2012-2013 Raphael Kubo da Costa @@ -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 ) + +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 # SPDX-FileCopyrightText: 2007 Matthias Kretz # SPDX-FileCopyrightText: 2006-2007 Laurent Montel @@ -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 [ [...]] -# ) -# -# 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 # # 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 [ [...]] + ) + +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_`` -# destination for files of a given type -# ``KDE_INSTALL_FULL_`` -# corresponding absolute path -# -# where ```` 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 (````) [``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/`` variables (or their ``CMAKE_INSTALL_`` 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_``, ``CMAKE_INSTALL_`` 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 # SPDX-FileCopyrightText: 2013 Stephen Kelly # SPDX-FileCopyrightText: 2012 David Faure @@ -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_`` + destination for files of a given type +``KDE_INSTALL_FULL_`` + corresponding absolute path + +where ```` 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 (````) [``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/`` variables (or their ``CMAKE_INSTALL_`` 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_``, ``CMAKE_INSTALL_`` 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