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