ECM-KDE-MODULES(7) Extra CMake Modules ECM-KDE-MODULES(7)
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 docu-
mented 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 dynami-
cally-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 in-
stalling: 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_OUT-
PUT_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. How-
ever 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_SUP-
PRESS_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 transla-
tions 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 transla-
tions at configuration time instead of build time.
Since 5.50.0
All KDE_L10N_* options have been deprecated since 5.102.0, as transla-
tions 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 ex-
cluded 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 spe-
cific 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_COMPILERSET-
TINGS_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: 99
• CMAKE_C_STANDARD_REQUIRED: TRUE
• CMAKE_C_EXTENSIONS: OFF
Otherwise:
• CMAKE_C_STANDARD: 90
• CMAKE_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: 17
• CMAKE_CXX_STANDARD_REQUIRED: TRUE
• CMAKE_CXX_EXTENSIONS: OFF
Otherwise:
• CMAKE_CXX_STANDARD: 11
• CMAKE_CXX_STANDARD_REQUIRED: TRUE
• CMAKE_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_COMPILER-
SETTINGS_LEVEL >= 5.85, TRUE otherwise).
• -Wmissing-include-dirs (GNU compilers, since 5.85)
Can be disabled by setting KDE_SKIP_MISSING_INCLUDE_DIRS_WARN-
INGS_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_COMPILERSET-
TINGS_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 itera-
tors. 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 link-
ing. It ensures libraries bind global function references lo-
cally 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 pass-
ing -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-Frame-
works. 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 conven-
tions.
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_pre_commit_hook(
CHECKS <check1> [<check2> [...]]
)
This function will create a pre-commit hook which contains all the
given checks.
Checks:
• CLANG_FORMAT With this check enabled the git clang-format tool will
be used to make sure that the changed parts are properly formatted.
In case the changes are not properly formatted an error message with
the command to preview the formatting changes and to format the files
in place will be displayed. This tool will reuse the exsting
.clang-format file, in case you want to use the one provided by ECM
you can include include(KDEClangFormat) which will copy the file to
the source dir. It is also recommended to reformat the entire project
before enforcing the formatting using this commit hook.
Example usage:
include(KDEGitCommitHooks)
kde_configure_git_pre_commit_hook(CHECKS 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 soft-
ware.
Note that none of the variables defined by this module provide any in-
formation about the location of already-installed KDE software.
Also sets CMAKE_INSTALL_PREFIX to the installation prefix of ECM, un-
less 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 EX-
ECROOTDIR/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) [CMAKECON-
FIG_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_IN-
STALL_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_IN-
STALL_PREFIX]
DATADIR
read-only architecture-independent data (DATAROOTDIR) [DATA_IN-
STALL_DIR]
DOCBUNDLEDIR
documentation bundles generated using kdoctools (DATAROOT-
DIR/doc/HTML) [HTML_INSTALL_DIR]
KCFGDIR
kconfig description files (DATAROOTDIR/config.kcfg) [KCFG_IN-
STALL_DIR]
KCONFUPDATEDIR
kconf_update scripts (DATAROOTDIR/kconf_update) [KCONF_UP-
DATE_INSTALL_DIR]
KSERVICES5DIR or (since 5.89) KSERVICESDIR
services for KDE Frameworks 5 (DATAROOTDIR/kservices5) [SER-
VICES_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
knotify description files (DATAROOTDIR/kxmlgui5) [KXMLGUI_IN-
STALL_DIR]
KAPPTEMPLATESDIR
KAppTemplate and KDevelop templates (DATAROOTDIR/kdevappwiz-
ard/templates) [KDE_INSTALL_KTEMPLATESDIR] Since 5.77.
KFILETEMPLATESDIR
KDevelop file templates (DATAROOTDIR/kdevfiletemplates/tem-
plates) Since 5.77.
KNOTIFY5RCDIR or (since 5.89) KNOTIFYRCDIR
knotify description files (DATAROOTDIR/knotifications5) [KNOTI-
FYRC_INSTALL_DIR]
ICONDIR
icons (DATAROOTDIR/icons) [ICON_INSTALL_DIR]
LOCALEDIR
knotify description files (DATAROOTDIR/locale) [LOCALE_IN-
STALL_DIR]
SOUNDDIR
sound files (DATAROOTDIR/sounds) [SOUND_INSTALL_DIR]
TEMPLATEDIR
templates (DATAROOTDIR/templates) [TEMPLATES_INSTALL_DIR]
WALLPAPERDIR
desktop wallpaper images (DATAROOTDIR/wallpapers) [WALLPAPER_IN-
STALL_DIR]
APPDIR application desktop files (DATAROOTDIR/applications) Since
1.1.0. [XDG_APPS_INSTALL_DIR]
DESKTOPDIR
desktop directories (DATAROOTDIR/desktop-directories) [XDG_DI-
RECTORY_INSTALL_DIR]
MIMEDIR
mime description files (DATAROOTDIR/mime/packages) [XDG_MIME_IN-
STALL_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_IN-
STALL_DIR]
DBUSSERVICEDIR
D-Bus session services (DBUSDIR/services) [DBUS_SERVICES_IN-
STALL_DIR]
DBUSSYSTEMSERVICEDIR
D-Bus system services (DBUSDIR/system-services) [DBUS_SYS-
TEM_SERVICES_INSTALL_DIR]
SYSCONFDIR
read-only single-machine data (etc, or /etc if CMAKE_IN-
STALL_PREFIX is /usr) [SYSCONF_INSTALL_DIR]
CONFDIR
application configuration files (SYSCONFDIR/xdg) [CONFIG_IN-
STALL_DIR]
AUTOSTARTDIR
autostart files (CONFDIR/autostart) [AUTOSTART_INSTALL_DIR]
LOGGINGCATEGORIESDIR
Qt logging categories files directory (DATAROOTDIR/qlogging-cat-
egories5) 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_IN-
STALL_DIR]. Since 5.65
ZSHAUTOCOMPLETEDIR
Zsh functions and autocompletion definitions (zsh/site-func-
tions) 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 KDE-
InstallDirs (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_IN-
STALL_* 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_VARI-
ABLES 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 depre-
cated counterparts) may be passed to the DESTINATION options of in-
stall() 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 defi-
nitions; in either case, all forms of the variable will be affected.
The effect of passing multiple forms of the same variable on the com-
mand line (such as KDE_INSTALL_BINDIR and CMAKE_INSTALL_BINDIR is unde-
fined.
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_IN-
STALL_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_IN-
STALL_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, un-
less otherwise noted with the variable.
The KDE_INSTALL_PREFIX_SCRIPT option will install a ${CMAKE_IN-
STALL_PREFIX}/prefix.sh file that allows to easily incorporate the nec-
essary environment variables for the prefix into a process.
KDEInstallDirs6
THIS IS CURRENTLY ONLY AN ALPHA VERSION, FOR FRAMEWORKS USAGE ONLY, AND
TO BE MODIFIED INCREMENTALLY. PLEASE DO NOT USE IN APPLICATIONS YET.
Define KDE standard installation directories for Qt6/KF6 based soft-
ware.
Note that none of the variables defined by this module provide any in-
formation about the location of already-installed KDE software.
Also sets CMAKE_INSTALL_PREFIX to the installation prefix of ECM, un-
less 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 EX-
ECROOTDIR/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 qmake-qt5’s QT_INSTALL_PLUGINS)
PLUGINDIR
Plugins (QTPLUGINDIR) [PLUGIN_INSTALL_DIR]
QMLDIR QtQuick2 imports (LIBDIR/qml or qmake-qt5’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 (share)
DATADIR
read-only architecture-independent data (DATAROOTDIR)
DOCBUNDLEDIR
documentation bundles generated using kdoctools (DATAROOT-
DIR/doc/HTML)
KCFGDIR
kconfig description files (DATAROOTDIR/config.kcfg)
KCONFUPDATEDIR
kconf_update scripts (DATAROOTDIR/kconf_update)
KSERVICESDIR
services for KDE Frameworks 6 (DATAROOTDIR/kservices6)
KSERVICETYPESDIR
service types for KDE Frameworks 6 (DATAROOTDIR/kservicetypes6)
KXMLGUIDIR
knotify description files (DATAROOTDIR/kxmlgui6)
KAPPTEMPLATESDIR
KAppTemplate and KDevelop templates (DATAROOTDIR/kdevappwiz-
ard/templates)
KFILETEMPLATESDIR
KDevelop file templates (DATAROOTDIR/kdevfiletemplates/tem-
plates)
KNOTIFYRCDIR
knotify description files (DATAROOTDIR/knotifications6)
ICONDIR
icons (DATAROOTDIR/icons)
LOCALEDIR
knotify description files (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 qmake-qt5’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_IN-
STALL_PREFIX is /usr)
CONFDIR
application configuration files (SYSCONFDIR/xdg)
AUTOSTARTDIR
autostart files (CONFDIR/autostart)
LOGGINGCATEGORIESDIR
Qt logging categories files directory (DATAROOTDIR/qlogging-cat-
egories6)
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 KDE-
InstallDirs (e.g. by packagers).
In addition, for each KDE_INSTALL_* variable, an equivalent CMAKE_IN-
STALL_* variable is defined, if such a variable is also defined by the
GNUInstallDirs module (shipped with CMake). If KDE_IN-
STALL_DIRS_NO_CMAKE_VARIABLES is set to TRUE, no variables with a
CMAKE_ prefix will be defined by this module (other than CMAKE_IN-
STALL_DEFAULT_COMPONENT_NAME - see below).
The KDE_INSTALL_<dir> variables may be passed to the DESTINATION op-
tions 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 mul-
tiple forms of the same variable on the command line (such as KDE_IN-
STALL_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 in-
stalled, 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_IN-
STALL_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_IN-
STALL_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_IN-
STALL_PREFIX}/prefix.sh file that allows to easily incorporate the nec-
essary 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 sup-
ported 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 in-
stall 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_KAPPTEMPLATES-
DIR from KDEInstallDirs.
TEMPLATES lists subdirectories containing template files; each <tem-
plate> 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 sup-
ports 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
5.103 Feb 12, 2023 ECM-KDE-MODULES(7)
Generated by dwww version 1.15 on Sat Jun 29 02:13:07 CEST 2024.