oracular (7) ecm-kde-modules.7.gz

Provided by: extra-cmake-modules_6.6.0-0ubuntu2_amd64 bug

NAME

       ecm-kde-modules - ECM KDE Modules Reference

INTRODUCTION

       Extra  CMake  Modules  (ECM)  provides  several  modules that provide default settings (like installation
       directories, compiler flags and other CMake options) aimed at software produced by the KDE modules; these
       are  documented  here.  ECM  also  provides  modules  with  more  general  functionality,  documented  in
       ecm-modules(7), and ones that extend  the  functionality  of  the  find_package  command,  documented  in
       ecm-find-modules(7).

       To  use  these  modules,  you  need  to  tell  CMake  to  find  the  ECM  package,  and  then  add either
       ${ECM_MODULE_PATH} or ${ECM_KDE_MODULE_DIR} to the CMAKE_MODULE_PATH variable:

          find_package(ECM REQUIRED NO_MODULE)
          set(CMAKE_MODULE_PATH ${ECM_MODULE_DIR})

       Using ${ECM_MODULE_PATH} will also make the other types of modules available.

ALL KDE MODULES

   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:
          LIB_INSTALL_DIR  or  alternatively  KDE_INSTALL_LIBDIR  needs  to be set before including this module.
          Typically, this is done by including the 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 (deprecated)
       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

       All  KDE_L10N_*  options have been deprecated since 5.102.0, as translations are meanwhile present inside
       the source code repositories.

   KDEClangFormat
       This module provides a functionality to format  the  source  code  of  your  repository  according  to  a
       predefined KDE clang-format file.

       This module provides the following function:

          kde_clang_format(<files>)

       Using this function will create a clang-format target that will format all <files> passed to the function
       with the predefined KDE clang-format style.  To format the files you have to invoke the target with  make
       clang-format  or  ninja  clang-format.   Once  the  project is formatted it is recommended to enforce the
       formatting using a pre-commit hook, this can be done using 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:

          include(KDEClangFormat)
          file(GLOB_RECURSE ALL_CLANG_FORMAT_SOURCE_FILES *.cpp *.h *.hpp *.c)
          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:

          DisableFormat: true
          SortIncludes: false

       Since 5.64

   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.

       NOTE:
          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 5.85 newer settings are controlled by a variable KDE_COMPILERSETTINGS_LEVEL, taking an ECM  version
       as  value. That version can not be greater than the minimum required ECM version.  The settings which are
       default at that version will then be used, but can be  overridden  by  more  fine-grained  controls  (see
       respective  settings).  This variable needs to be set before including this module, otherwise defaults to
       the minimum required ECM version.

   Modern code
       The following CMake C standard default variables are set:

       For KDE_COMPILERSETTINGS_LEVEL >= 5.85:

       • CMAKE_C_STANDARD: 99CMAKE_C_STANDARD_REQUIRED: TRUECMAKE_C_EXTENSIONS: OFF

       Otherwise:

       • CMAKE_C_STANDARD: 90CMAKE_C_STANDARD_REQUIRED: not modified

       • CMAKE_C_EXTENSIONS: not modified

       If the variable CMAKE_C_STANDARD is already set when including this module, none of the  above  variables
       will be modified.

       The following CMake C++ standard default variables are set:

       For KDE_COMPILERSETTINGS_LEVEL >= 5.85:

       • CMAKE_CXX_STANDARD: 17CMAKE_CXX_STANDARD_REQUIRED: TRUECMAKE_CXX_EXTENSIONS: OFF

       Otherwise:

       • CMAKE_CXX_STANDARD: 11CMAKE_CXX_STANDARD_REQUIRED: TRUECMAKE_CXX_EXTENSIONS: not modified.

       If the variable CMAKE_CXX_STANDARD is already set when including this module, none of the above variables
       will be modified.

       The following C++ compiler flags are set:

       • -pedantic (GNU and Clang compilers, since 5.85)

         Can be disabled by setting KDE_SKIP_PEDANTIC_WARNINGS_SETTINGS to TRUE  before  including  this  module
         (default is FALSE for KDE_COMPILERSETTINGS_LEVEL >= 5.85, TRUE otherwise).

       • -Wmissing-include-dirs (GNU compilers, since 5.85)

         Can  be  disabled  by  setting KDE_SKIP_MISSING_INCLUDE_DIRS_WARNINGS_SETTINGS to TRUE before including
         this module (default is FALSE for KDE_COMPILERSETTINGS_LEVEL >= 5.85, TRUE otherwise).

       • -Wzero-as-null-pointer-constant (GNU and Clang compilers, since 5.85)

         Can be disabled by setting KDE_SKIP_NULLPTR_WARNINGS_SETTINGS to  TRUE  before  including  this  module
         (default is FALSE for KDE_COMPILERSETTINGS_LEVEL >= 5.85, TRUE otherwise).

       • -Werror=undef (GNU and Clang compilers, since 5.96.0)

       • Qt related preprocessor definitions (since 5.85.0):

         • -DQT_NO_CAST_TO_ASCII-DQT_NO_CAST_FROM_ASCII-DQT_NO_URL_CAST_FROM_STRING-DQT_NO_CAST_FROM_BYTEARRAY-DQT_USE_QSTRINGBUILDER-DQT_NO_NARROWING_CONVERSIONS_IN_CONNECT-DQT_NO_KEYWORDS-DQT_NO_FOREACH-DQT_STRICT_ITERATORS

           Strict  iterators are not enabled on Windows, because they lead to a link error when application code
           iterates over a QVector<QPoint> for instance, unless Qt itself was also built with strict  iterators.
           See example at https://bugreports.qt.io/browse/AUTOSUITE-946

         Can be controlled by setting KDE_QT_MODERNCODE_DEFINITIONS_LEVEL to the version of ECM where the wanted
         set of definitions has been added before including this module (default is KDE_COMPILERSETTINGS_LEVEL).
         To  disable  individual  definitions  instead  use  remove_definitions()  directly after including this
         module.

   Functions
       This module provides the following functions:

          kde_source_files_enable_exceptions([file1 [file2 [...]]])

       Enables exceptions for specific source files.  This should not be used on  source  files  in  a  language
       other than C++.

          kde_target_enable_exceptions(target <INTERFACE|PUBLIC|PRIVATE>)

       Enables exceptions for a specific target.  This should not be used on a target that has source files in a
       language other than C++.

          kde_enable_exceptions()

       Enables exceptions for C++ source files compiled for the CMakeLists.txt file in the current directory and
       all subdirectories.

   Variables
       Inclusion of this module defines the following variables:

       ENABLE_BSYMBOLICFUNCTIONS
              indicates  whether  we  make  use  of -Bsymbolic-functions for linking.  It ensures libraries bind
              global function references locally rather than at runtime.  This option  only  has  an  effect  on
              ELF-based systems.

              The  option  is  disabled  by  default  except  when using KDEFrameworkCompilerSettings where it’s
              enabled. Projects can enable it by calling set(ENABLE_BSYMBOLICFUNCTIONS ON) or  passing  -DENABLE
              BSYMBOLICFUNCTIONS=ON when configuring the build directory.

              Since 5.85

       Example usages:

          # needing some macro/feature only available with ECM 5.80.0
          find_package(ECM 5.80.0 NO_MODULE)

          # requiring ECM 5.80.0 above will default KDE_COMPILERSETTINGS_LEVEL also to 5.80.0,
          # thus not activate any newer settings
          include(KDECompilerSettings NO_POLICY_SCOPE)

          # needing some macro/feature only available with ECM 5.87.0
          find_package(ECM 5.87.0 NO_MODULE)

          # project uses settings default as of KDECompilerSettings in ECM 5.85.0
          set(KDE_COMPILERSETTINGS_LEVEL 5.85.0)
          include(KDECompilerSettings NO_POLICY_SCOPE)

          # needing some macro/feature only available with ECM 5.87.0
          find_package(ECM 5.87.0 NO_MODULE)

          # project mainly uses settings default as of KDECompilerSettings in ECM 5.85.0
          # with some small twisting
          set(KDE_COMPILERSETTINGS_LEVEL 5.85.0)
          # not ready yet for pedantic compilers
          set(KDE_SKIP_PEDANTIC_WARNINGS_SETTINGS TRUE)
          # avoid any Qt definitions
          set(KDE_QT_MODERNCODE_DEFINITIONS_LEVEL 5.84.0)
          include(KDECompilerSettings NO_POLICY_SCOPE)

          # needing some macro/feature only available with ECM 5.85.0
          find_package(ECM 5.85.0 NO_MODULE)

          # requiring ECM 5.85.0 above will default KDE_COMPILERSETTINGS_LEVEL also to 5.85.0,
          # which again defaults KDE_QT_MODERNCODE_DEFINITIONS_LEVEL also to 5.85.0
          include(KDECompilerSettings NO_POLICY_SCOPE)
          # project is fine with almost all added Qt definitions as of 5.85.0, but not these ones:
          remove_definitions(
              -DQT_NO_KEYWORDS
              -DQT_NO_FOREACH
          )

       Since pre-1.0.0.

   KDEFrameworkCompilerSettings
       Set stricter compile and link flags for KDE Frameworks modules.

       WARNING:
          Do  not  use  this module for software which is not part of KDE-Frameworks.  There is no guarantee for
          backward-compatibility in newer versions.

       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.

       NOTE:
          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.

   KDEGitCommitHooks
       This module provides a functionality to enforce formatting or in the future other QS checks.

       This module provides the following function:

          kde_configure_git_pre_commit_hook(
             CHECKS <check1> [<check2> [...]
             [CUSTOM_SCRIPTS [<script paths> [<script paths> ...]]] # since 5.109
          )

       This  function  will  create a pre-commit hook which contains all the given checks.  In addition to that,
       you can pass in paths to custom scripts that will be run as the  pre-commit  hook.   If  a  custom  hooks
       directory is set via core.hooksPath, a warning is issued.

       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.   -
         JSON_SCHEMA Since 5.110, uses the check-jsonschema CLI tool to ensure that all files are valid JSON and
         match the KPluginMetaData spec. This only applied if the JSON file has a “KPlugin” object in its  root.
         To  ignore  invalid  files,  for example for testing error handling, given files can be exlcuded in the
         .kde-ci.yml file Define Options.json-validate-ignore with an array of the files you want to ignore

       Example usage:

          include(KDEGitCommitHooks)
          kde_configure_git_pre_commit_hook(CHECKS JSON_SCHEMA CLANG_FORMAT)

       Since 5.79

   KDEInstallDirs
       Compatibility wrapper around KDEInstallDirs5.

       Since 5.82.0, prior to that equivalent to KDEInstallDirs5.

   KDEInstallDirs5
       Define KDE standard installation directories for Qt5/KF5 based software.

       Note that none of the variables defined by this module provide any  information  about  the  location  of
       already-installed KDE software.

       Also  sets  CMAKE_INSTALL_PREFIX to the installation prefix of ECM, unless that variable has been already
       explicitly set by something else (since 5.61 and with CMake >= 3.7).

       Inclusion of this module defines the following variables:

       KDE_INSTALL_<dir>
              destination for files of a given type

       KDE_INSTALL_FULL_<dir>
              corresponding absolute path

       where <dir> is one of (default values in parentheses and alternative, deprecated variable name in  square
       brackets):

       BUNDLEDIR
              application bundles (/Applications/KDE) [BUNDLE_INSTALL_DIR]

       EXECROOTDIR
              executables and libraries (<empty>) [EXEC_INSTALL_PREFIX]

       BINDIR user executables (EXECROOTDIR/bin) [BIN_INSTALL_DIR]

       SBINDIR
              system admin executables (EXECROOTDIR/sbin) [SBIN_INSTALL_DIR]

       LIBDIR object  code  libraries (EXECROOTDIR/lib, EXECROOTDIR/lib64 or EXECROOTDIR/lib/<multiarch-tuple on
              Debian) [LIB_INSTALL_DIR]

       LIBEXECDIR
              executables for internal  use  by  programs  and  libraries  (BINDIR  on  Windows,  LIBDIR/libexec
              otherwise) [LIBEXEC_INSTALL_DIR]

       CMAKEPACKAGEDIR
              CMake packages, including config files (LIBDIR/cmake) [CMAKECONFIG_INSTALL_PREFIX]

       QTPLUGINDIR
              Qt plugins (LIBDIR/plugins or qmake-qt5’s QT_INSTALL_PLUGINS) [QT_PLUGIN_INSTALL_DIR]

       PLUGINDIR
              Plugins (QTPLUGINDIR) [PLUGIN_INSTALL_DIR]

       QTQUICKIMPORTSDIR
              QtQuick1 imports (QTPLUGINDIR/imports or qmake-qt5’s QT_INSTALL_IMPORTS) [IMPORTS_INSTALL_DIR]

       QMLDIR QtQuick2 imports (LIBDIR/qml or qmake-qt5’s QT_INSTALL_QML) [QML_INSTALL_DIR]

       INCLUDEDIR
              C and C++ header files (include) [INCLUDE_INSTALL_DIR]

       LOCALSTATEDIR
              modifiable single-machine data (var)

       SHAREDSTATEDIR
              modifiable architecture-independent data (com)

       DATAROOTDIR
              read-only   architecture-independent   data   root   (BINDIR/data  on  Windows,  share  otherwise)
              [SHARE_INSTALL_PREFIX]

       DATADIR
              read-only architecture-independent data (DATAROOTDIR) [DATA_INSTALL_DIR]

       DOCBUNDLEDIR
              documentation bundles generated using kdoctools (DATAROOTDIR/doc/HTML) [HTML_INSTALL_DIR]

       KCFGDIR
              kconfig description files (DATAROOTDIR/config.kcfg) [KCFG_INSTALL_DIR]

       KCONFUPDATEDIR
              kconf_update scripts (DATAROOTDIR/kconf_update) [KCONF_UPDATE_INSTALL_DIR]

       KSERVICES5DIR or (since 5.89) KSERVICESDIR
              services for KDE Frameworks 5 (DATAROOTDIR/kservices5) [SERVICES_INSTALL_DIR]

       KSERVICETYPES5DIR or (since 5.89) KSERVICETYPESDIR
              service types for KDE Frameworks 5 (DATAROOTDIR/kservicetypes5) [SERVICETYPES_INSTALL_DIR]

       KXMLGUI5DIR or (since 5.89) KXMLGUIDIR
              kxmlgui .rc files (DATAROOTDIR/kxmlgui5) [KXMLGUI_INSTALL_DIR]

       KAPPTEMPLATESDIR
              KAppTemplate       and       KDevelop       templates        (DATAROOTDIR/kdevappwizard/templates)
              [KDE_INSTALL_KTEMPLATESDIR] Since 5.77.

       KFILETEMPLATESDIR
              KDevelop file templates (DATAROOTDIR/kdevfiletemplates/templates) Since 5.77.

       KNOTIFY5RCDIR or (since 5.89) KNOTIFYRCDIR
              knotify description files (DATAROOTDIR/knotifications5) [KNOTIFYRC_INSTALL_DIR]

       ICONDIR
              icons (DATAROOTDIR/icons) [ICON_INSTALL_DIR]

       LOCALEDIR
              locale-dependent data (DATAROOTDIR/locale) [LOCALE_INSTALL_DIR]

       SOUNDDIR
              sound files (DATAROOTDIR/sounds) [SOUND_INSTALL_DIR]

       TEMPLATEDIR
              templates (DATAROOTDIR/templates) [TEMPLATES_INSTALL_DIR]

       WALLPAPERDIR
              desktop wallpaper images (DATAROOTDIR/wallpapers) [WALLPAPER_INSTALL_DIR]

       APPDIR application desktop files (DATAROOTDIR/applications) Since 1.1.0.  [XDG_APPS_INSTALL_DIR]

       DESKTOPDIR
              desktop directories (DATAROOTDIR/desktop-directories) [XDG_DIRECTORY_INSTALL_DIR]

       MIMEDIR
              mime description files (DATAROOTDIR/mime/packages) [XDG_MIME_INSTALL_DIR]

       METAINFODIR
              AppStream component metadata files (DATAROOTDIR/metainfo)

       QTQCHDIR
              documentation bundles in QCH format for Qt-extending libraries (DATAROOTDIR/doc/qch or qmake-qt5’s
              QT_INSTALL_DOCS) Since 5.36.0.

       QCHDIR documentation bundles in QCH format (DATAROOTDIR/doc/qch) Since 5.36.0.

       MANDIR man documentation (DATAROOTDIR/man) [MAN_INSTALL_DIR]

       INFODIR
              info documentation (DATAROOTDIR/info)

       DBUSDIR
              D-Bus (DATAROOTDIR/dbus-1)

       DBUSINTERFACEDIR
              D-Bus interfaces (DBUSDIR/interfaces) [DBUS_INTERFACES_INSTALL_DIR]

       DBUSSERVICEDIR
              D-Bus session services (DBUSDIR/services) [DBUS_SERVICES_INSTALL_DIR]

       DBUSSYSTEMSERVICEDIR
              D-Bus system services (DBUSDIR/system-services) [DBUS_SYSTEM_SERVICES_INSTALL_DIR]

       SYSCONFDIR
              read-only single-machine data (etc, or /etc if CMAKE_INSTALL_PREFIX is /usr) [SYSCONF_INSTALL_DIR]

       CONFDIR
              application configuration files (SYSCONFDIR/xdg) [CONFIG_INSTALL_DIR]

       AUTOSTARTDIR
              autostart files (CONFDIR/autostart) [AUTOSTART_INSTALL_DIR]

       LOGGINGCATEGORIESDIR
              Qt logging categories files directory (DATAROOTDIR/qlogging-categories5) Since 5.59.0

       JARDIR Java AAR/JAR files for Android. Since 5.62.0

       SYSTEMDUNITDIR
              Systemd Units (lib/systemd) [SYSTEMD_UNIT_INSTALL_DIR]. Since 5.65

       SYSTEMDUSERUNITDIR
              Systemd User Units (lib/systemd/user) [SYSTEMD_USER_UNIT_INSTALL_DIR]. Since 5.65

       ZSHAUTOCOMPLETEDIR
              Zsh functions and autocompletion definitions (zsh/site-functions) Since 5.101

       If KDE_INSTALL_USE_QT_SYS_PATHS is set to TRUE before including this module, the default values for  some
       variables  are  instead queried from Qt5’s qmake (where mentioned in the parentheses above).  If not set,
       it  will  default  to  TRUE  if  Qt5’s  qmake  is  found  and  it’s  QT_INSTALL_PREFIX  is  the  same  as
       CMAKE_INSTALL_PREFIX,  otherwise  default  to  FALSE.   This  variable  should  NOT  be  set  from within
       CMakeLists.txt files, instead is intended to be set  manually  when  configuring  a  project  which  uses
       KDEInstallDirs (e.g. by packagers).

       If  KDE_INSTALL_DIRS_NO_DEPRECATED  is set to TRUE before including this module, the deprecated variables
       (listed in the square brackets above) are not defined.

       In addition, for each KDE_INSTALL_* variable, an  equivalent  CMAKE_INSTALL_*  variable  is  defined.  If
       KDE_INSTALL_DIRS_NO_DEPRECATED  is set to TRUE, only those variables defined by the GNUInstallDirs module
       (shipped with CMake) are defined.  If KDE_INSTALL_DIRS_NO_CMAKE_VARIABLES is set to  TRUE,  no  variables
       with  a  CMAKE_  prefix will be defined by this module (other than CMAKE_INSTALL_DEFAULT_COMPONENT_NAME -
       see below).

       The KDE_INSTALL_<dir> variables (or their CMAKE_INSTALL_<dir> or deprecated counterparts) may  be  passed
       to  the  DESTINATION  options of install() commands for the corresponding file type.  They are set in the
       CMake cache, and so the defaults above can be overridden by users.

       Note that the KDE_INSTALL_<dir>, CMAKE_INSTALL_<dir> or deprecated form of the variable  can  be  changed
       using  CMake  command  line  variable  definitions;  in  either  case,  all forms of the variable will be
       affected. The effect of passing multiple forms of  the  same  variable  on  the  command  line  (such  as
       KDE_INSTALL_BINDIR and CMAKE_INSTALL_BINDIR is undefined.

       The   variable   KDE_INSTALL_TARGETS_DEFAULT_ARGS  is  also  defined  (along  with  the  deprecated  form
       INSTALL_TARGETS_DEFAULT_ARGS).  This should be used when libraries or  user-executable  applications  are
       installed, in the following manner:

          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 5.82.0, prior to that available as KDEInstallDirs.

       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.

   KDEInstallDirs6
       Define KDE standard installation directories for Qt6/KF6 based software.

       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.

       Inclusion of this module defines the following variables:

       KDE_INSTALL_<dir>
              destination for files of a given type

       KDE_INSTALL_FULL_<dir>
              corresponding absolute path

       where <dir> is one of (default values in parentheses):

       BUNDLEDIR
              application bundles (/Applications/KDE)

       EXECROOTDIR
              executables and libraries (<empty>)

       BINDIR user executables (EXECROOTDIR/bin)

       SBINDIR
              system admin executables (EXECROOTDIR/sbin)

       LIBDIR object  code  libraries (EXECROOTDIR/lib, EXECROOTDIR/lib64 or EXECROOTDIR/lib/<multiarch-tuple on
              Debian)

       LIBEXECDIR
              executables for internal  use  by  programs  and  libraries  (BINDIR  on  Windows,  LIBDIR/libexec
              otherwise)

       CMAKEPACKAGEDIR
              CMake packages, including config files (LIBDIR/cmake)

       QTPLUGINDIR
              Qt plugins (LIBDIR/plugins or qtpaths’s QT_INSTALL_PLUGINS)

       PLUGINDIR
              Plugins (QTPLUGINDIR) [PLUGIN_INSTALL_DIR]

       QMLDIR QtQuick2 imports (LIBDIR/qml or qtpaths’s QT_INSTALL_QML)

       INCLUDEDIR
              C and C++ header files (include)

       LOCALSTATEDIR
              modifiable single-machine data (var)

       SHAREDSTATEDIR
              modifiable architecture-independent data (com)

       DATAROOTDIR
              read-only architecture-independent data root (BINDIR/data on Windows, share otherwise)

       DATADIR
              read-only architecture-independent data (DATAROOTDIR)

       DOCBUNDLEDIR
              documentation bundles generated using kdoctools (DATAROOTDIR/doc/HTML)

       KCFGDIR
              kconfig description files (DATAROOTDIR/config.kcfg)

       KCONFUPDATEDIR
              kconf_update scripts (DATAROOTDIR/kconf_update)

       KXMLGUIDIR
              kxmlgui .rc files (DATAROOTDIR/kxmlgui5)

       KAPPTEMPLATESDIR
              KAppTemplate and KDevelop templates (DATAROOTDIR/kdevappwizard/templates)

       KFILETEMPLATESDIR
              KDevelop file templates (DATAROOTDIR/kdevfiletemplates/templates)

       KNOTIFYRCDIR
              knotify description files (DATAROOTDIR/knotifications6)

       ICONDIR
              icons (DATAROOTDIR/icons)

       LOCALEDIR
              locale-dependent data (DATAROOTDIR/locale)

       SOUNDDIR
              sound files (DATAROOTDIR/sounds)

       TEMPLATEDIR
              templates (DATAROOTDIR/templates)

       WALLPAPERDIR
              desktop wallpaper images (DATAROOTDIR/wallpapers)

       APPDIR application desktop files (DATAROOTDIR/applications)

       DESKTOPDIR
              desktop directories (DATAROOTDIR/desktop-directories)

       MIMEDIR
              mime description files (DATAROOTDIR/mime/packages)

       METAINFODIR
              AppStream component metadata files (DATAROOTDIR/metainfo)

       QTQCHDIR
              documentation  bundles  in QCH format for Qt-extending libraries (DATAROOTDIR/doc/qch or qtpaths’s
              QT_INSTALL_DOCS)

       QCHDIR documentation bundles in QCH format (DATAROOTDIR/doc/qch)

       MANDIR man documentation (DATAROOTDIR/man)

       INFODIR
              info documentation (DATAROOTDIR/info)

       DBUSDIR
              D-Bus (DATAROOTDIR/dbus-1)

       DBUSINTERFACEDIR
              D-Bus interfaces (DBUSDIR/interfaces)

       DBUSSERVICEDIR
              D-Bus session services (DBUSDIR/services)

       DBUSSYSTEMSERVICEDIR
              D-Bus system services (DBUSDIR/system-services)

       SYSCONFDIR
              read-only single-machine data (etc, or /etc if CMAKE_INSTALL_PREFIX is /usr)

       CONFDIR
              application configuration files (SYSCONFDIR/xdg)

       AUTOSTARTDIR
              autostart files (CONFDIR/autostart)

       LOGGINGCATEGORIESDIR
              Qt logging categories files directory (DATAROOTDIR/qlogging-categories6)

       JARDIR Java AAR/JAR files for Android.

       SYSTEMDUNITDIR
              Systemd Units (lib/systemd)

       SYSTEMDUSERUNITDIR
              Systemd User Units (lib/systemd/user)

       If KDE_INSTALL_USE_QT_SYS_PATHS is set to TRUE before including this module, the default values for  some
       variables  are  instead queried from Qt6’s qmake (where mentioned in the parentheses above).  If not set,
       it  will  default  to  TRUE  if  Qt6’s  qmake  is  found  and  it’s  QT_INSTALL_PREFIX  is  the  same  as
       CMAKE_INSTALL_PREFIX,  otherwise  default  to  FALSE.   This  variable  should  NOT  be  set  from within
       CMakeLists.txt files, instead is intended to be set  manually  when  configuring  a  project  which  uses
       KDEInstallDirs (e.g. by packagers).

       In  addition, for each KDE_INSTALL_* variable, an equivalent CMAKE_INSTALL_* variable is defined, if such
       a   variable   is   also   defined   by   the   GNUInstallDirs   module   (shipped   with   CMake).    If
       KDE_INSTALL_DIRS_NO_CMAKE_VARIABLES  is set to TRUE, no variables with a CMAKE_ prefix will be defined by
       this module (other than CMAKE_INSTALL_DEFAULT_COMPONENT_NAME - see below).

       The KDE_INSTALL_<dir> variables may be passed to the DESTINATION options of install()  commands  for  the
       corresponding file type.  They are set in the CMake cache, and so the defaults above can be overridden by
       users.

       Note that the KDE_INSTALL_<dir> or CMAKE_INSTALL_<dir> variables can be changed using CMake command  line
       variable  definitions; in either case, both 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.  This should be used when libraries or
       user-executable applications are installed, in the following manner:

          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).

       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.

   KDEMetaInfoPlatformCheck
       By  including  this module there will be an automatic check between the supported platforms listed in the
       metainfo.yaml file and the current platform that is the target of the build

       If the current platform that is the target of the build is not supported  a  CMake  FATAL_ERROR  will  be
       issued

       The check can be ignored by setting KF_IGNORE_PLATFORM_CHECK to ON.

       Since 5.93

   KDEPackageAppTemplates
       Packages KApptemplate/KDevelop compatible application templates

       This  module  provides  a  functionality to package in a tarball and install project templates compatible
       with the format used by KApptemplate and KDevelop. Useful for providing minimal examples for the usage of
       the KDE Frameworks.

       This module provides the following function:

          kde_package_app_templates(TEMPLATES <template> [<template> [...]]
                                    INSTALL_DIR <directory>)

       INSTALL_DIR  is the directory to install the template package to.  In most cases you will want to use the
       variable KDE_INSTALL_KAPPTEMPLATESDIR from KDEInstallDirs.

       TEMPLATES lists subdirectories containing template files; each <template> directory will be packaged into
       a file named <template>.tar.bz2 and installed to the appropriate location.

       The  template  is  a minimal source tree of an application as if it was an application project by itself,
       with names (file names or text inside) the text files replaced by the following placeholders when needed:

       %{PROJECTDIRNAME}
              name of generated project base folder ex: %{APPNAMELC} for KAppTemplate

       %{APPNAME}
              project name as entered by user ex: MyKApp

       %{APPNAMELC}
              project name in lower case ex: mykapp

       %{APPNAMEUC}
              project name in upper case ex: MYKAPP

       %{CPP_TEMPLATE}
              license header for cpp file

       %{H_TEMPLATE}
              license header for h file

       %{AUTHOR}
              author name ex: George Ignacious

       %{EMAIL}
              author email ex: foo@bar.org

       %{VERSION}
              project version ex: 0.1

       Deprecated:

       %{dest}
              path of generated project base folder, used in  .kdevtemplate  with  the  ShowFilesAfterGeneration
              entry KDevelop >= 5.1.1 supports relative paths with that entry, making this placeholder obsolete

       Multiple templates can be passed at once.

       This function does nothing when cross-compiling.

       Since 5.18

SEE ALSO

       ecm(7), ecm-modules(7), ecm-find-modules(7)

       KDE Developers