Provided by: extra-cmake-modules_5.44.0-0ubuntu1_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 that 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

   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

   KDECompilerSettings
       Set useful compile and link flags for C++ (and C) code.

       Enables  many  more  warnings  than the default, and sets stricter modes for some compiler
       features.  By default, exceptions are disabled; kde_target_enable_exceptions() can be used
       to re-enable them for a specific target.

       NB:  it is recommended to include this module with the NO_POLICY_SCOPE flag, otherwise you
       may get spurious warnings with some versions of CMake.

       This module provides the following functions:

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

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

          kde_target_enable_exceptions(target <INTERFACE|PUBLIC|PRIVATE>)

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

          kde_enable_exceptions()

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

       Since pre-1.0.0.

   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.

   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.

       Inclusion of this module defines the following variables:

       KDE_INSTALL_<dir>
              destination for files of a given type

       KDE_INSTALL_FULL_<dir>
              corresponding absolute path

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

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

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

       BINDIR user executables (EXECROOTDIR/bin) [BIN_INSTALL_DIR]

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

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

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

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

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

       PLUGINDIR
              Plugins (QTPLUGINDIR) [PLUGIN_INSTALL_DIR]

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

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

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

       LOCALSTATEDIR
              modifiable single-machine data (var)

       SHAREDSTATEDIR
              modifiable architecture-independent data (com)

       DATAROOTDIR
              read-only architecture-independent data root (share) [SHARE_INSTALL_PREFIX]

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

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

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

       KCONFUPDATEDIR
              kconf_update scripts (DATAROOTDIR/kconf_update) [KCONF_UPDATE_INSTALL_DIR]

       KSERVICES5DIR
              services for KDE Frameworks 5 (DATAROOTDIR/kservices5) [SERVICES_INSTALL_DIR]

       KSERVICETYPES5DIR
              service    types    for    KDE    Frameworks     5     (DATAROOTDIR/kservicetypes5)
              [SERVICETYPES_INSTALL_DIR]

       KXMLGUI5DIR
              knotify description files (DATAROOTDIR/kxmlgui5) [KXMLGUI_INSTALL_DIR]

       KTEMPLATESDIR
              Kapptemplate and Kdevelop templates (kdevappwizard/templates)

       KNOTIFY5RCDIR
              knotify description files (DATAROOTDIR/knotifications5) [KNOTIFYRC_INSTALL_DIR]

       ICONDIR
              icons (DATAROOTDIR/icons) [ICON_INSTALL_DIR]

       LOCALEDIR
              knotify description files (DATAROOTDIR/locale) [LOCALE_INSTALL_DIR]

       SOUNDDIR
              sound files (DATAROOTDIR/sounds) [SOUND_INSTALL_DIR]

       TEMPLATEDIR
              templates (DATAROOTDIR/templates) [TEMPLATES_INSTALL_DIR]

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

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

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

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

       METAINFODIR
              AppStream component metadata files (DATAROOTDIR/metainfo)

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

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

       MANDIR man documentation (DATAROOTDIR/man) [MAN_INSTALL_DIR]

       INFODIR
              info documentation (DATAROOTDIR/info)

       DBUSDIR
              D-Bus (DATAROOTDIR/dbus-1)

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

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

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

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

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

       AUTOSTARTDIR
              autostart files (CONFDIR/autostart) [AUTOSTART_INSTALL_DIR]

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

   KDETemplateGenerator
       Packages KApptemplate/KDevelop compatible application templates

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

       This module provides the following function:

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

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

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

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

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

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

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

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

       %{CPP_TEMPLATE}
              license header for cpp file

       %{H_TEMPLATE}
              license header for h file

       %{AUTHOR}
              author name ex: George Ignacious

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

       %{VERSION}
              project version ex: 0.1

       Deprecated:

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

       Multiple templates can be passed at once.

       Since 5.18

SEE ALSO

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

COPYRIGHT

       KDE Developers