ECM-KDE-MODULES(7)

📦
version 6.31.0 · 11 versions
, in arch rolling

🌸 NAME 🌸

ecm-kde-modules(7) — ECM KDE Modules Reference 💖 from Extra CMake Modules. Yes bestie, you found the manual page, and it’s giving “KDE CMake defaults but make it understandable.” 🎀

🌟 INTRODUCTION 🌟

Extra CMake Modules (ECM) provides several modules that give you default settings (like installation directories, compiler flags and other CMake options) aimed at software produced by the KDE modules; these are documented right 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). So there’s a whole little ecosystem, iykyk. 🦋

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. Lowkey iconic of them. 👑

It is recommended to include this module with the NO_POLICY_SCOPE flag, otherwise you may get spurious warnings with some versions of CMake. Not me warning you about warnings, but here we are. 😭

It is split into three parts, which can be independently disabled if desired. Choose your own adventure, bestie. 🎀

🌀 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. Path stuff: handled. 🛣️

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. Set it first, bestie, fr fr.

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. Tests are slaying by default. ✅

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. Very “we fixed the vibes before you got here.” ✨

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). Run uninstalled apps without the chaos? Obsessed. 🫶

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. Clazy said “let me cook,” and honestly? Let her. 🔥

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

Since 6.25.0: disable CMAKE_CXX_SCAN_FOR_MODULES by default. 🧚

🌍 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

Deprecated alert: all KDE_L10N_* options have been deprecated since 5.102.0, as translations are meanwhile present inside the source code repositories. So this whole section is giving “retired but still in the group chat.” 💀

🎀 KDEClangFormat

This module provides a functionality to format the source code of your repository according to a predefined KDE clang-format file. Formatting? We love a clean little codebase. 🧼

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. Slay, but make it automated. 💅

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. Compiler settings, but make it KDE-approved. 👑

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. Choose your exception adventure wisely. 🎢

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. Set it before, bestie, or it picks for you. 🎀

🧬 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. Your call, your rules. 💅

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

For KDE_COMPILERSETTINGS_LEVEL >= 6.13:

  • CMAKE_CXX_STANDARD: 20
  • CMAKE_CXX_STANDARD_REQUIRED: TRUE
  • CMAKE_CXX_EXTENSIONS: OFF

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_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. Not the Windows link error jumping out 😭

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++. C++ only, bestie. 🚫

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. Exceptions: enabled, but responsibly. ✨

  • ENABLE_BSYMBOLICFUNCTIONS — tells you whether we're out here using -Bsymbolic-functions when linking. It makes libraries bind global function references locally instead of waiting till runtime to figure it out. Heads up: this one only does anything on ELF-based systems. 💅 It's disabled by default, except when you're using KDEFrameworkCompilerSettings (yes, the one right below 👀) where it's enabled. Wanna turn it on? Just call set(ENABLE_BSYMBOLICFUNCTIONS ON) or pass -DENABLE BSYMBOLICFUNCTIONS=ON when you configure the build directory. Since 5.85 ✨
  • ECM_FORCE_ASSERTS — enables Q_ASSERT no matter what your CMAKE_BUILD_TYPE is. Off by default, bestie. Since 6.24 🫶

Example usages, served fresh:

# 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 🎀

Okay so this one sets stricter compile and link flags, specifically for KDE Frameworks modules. It's giving strict-parent energy and honestly? Slay.

⚠️ Warning: do not use this module for software that isn't part of KDE-Frameworks. No cap, there is no guarantee of backward-compatibility in newer versions. It will not hesitate, it will not warn you first. 💀

It pulls in the KDECompilerSettings module and, on top of that, sets a bunch of defines that affect the Qt libraries so certain conventions get enforced.

Like, for example: constructions such as QString("foo") are prohibited — instead you're forced to use QLatin1String or QStringLiteral. And some Qt-defined keywords like signals and slots simply won't be defined at all. Periodt. 🔥

💡 Note: it's recommended (read: pls do this) to include this module with the NO_POLICY_SCOPE flag, otherwise you might get spurious warnings with some versions of CMake. Nobody wants that.

Since pre-1.0.0. ⭐

💅 KDEGitCommitHooks 💅

This module gives you functionality to enforce formatting — or, in the future, other QS checks. Main character energy for your git hooks, honestly.

It provides this function:

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

What it does: creates a pre-commit hook containing all the checks you give it. And on top of that, you can pass in paths to custom scripts that'll get run as the pre-commit hook. One thing though — if a custom hooks directory is set via core.hooksPath, a warning gets issued. Just so you know. 🙈

The created pre-commit script will also execute any custom user-provided scripts living in the .git/hooks/pre-commit.d directory. Cute, right?

✨ Checks ✨

  • CLANG_FORMAT — with this check enabled, the git clang-format tool gets used to make sure the changed parts are properly formatted. If they're not, you get an error message with the command to preview the formatting changes and the command to format the files in place. Super helpful. This tool reuses your existing .clang-format file — but if you'd rather use the one ECM provides, you can include(KDEClangFormat) and it'll copy the file to the source dir. Also, big recommendation: reformat the entire project before enforcing formatting with this commit hook. Trust. 🫶
  • JSON_SCHEMA — since 5.110, uses the check-jsonschema CLI tool to make sure all files are valid JSON and match the KPluginMetaData spec. Important detail: this only applies if the JSON file has a "KPlugin" object in its root. Wanna ignore invalid files (like, say, for testing error handling)? You can exclude given files in the .kde-ci.yml file — just define Options.json-validate-ignore with an array of the files you want to ignore. 🌸

Example usage so you can copy-paste and go:

include(KDEGitCommitHooks)
kde_configure_git_pre_commit_hook(CHECKS JSON_SCHEMA CLANG_FORMAT)

Since 5.79 💜

🦋 KDEInstallDirs 🦋

A compatibility wrapper around KDEInstallDirs5. That's literally it, she's a lil bridge. 🌈

Since 5.82.0 — before that, it was equivalent to KDEInstallDirs5.

🌸 KDEInstallDirs5 🌸

Defines the KDE standard installation directories for Qt5/KF5 based software. Iconic behaviour.

Quick note before we go off: none of the variables defined by this module tell you anything about where already-installed KDE software lives. That's just not what she does, bestie. 💅

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

Including this module defines these variables:

  • KDE_INSTALL_<dir> — destination for files of a given type
  • KDE_INSTALL_FULL_<dir> — the corresponding absolute path

where <dir> is one of these (default values in parentheses, and the 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 — the directory for Qt logging category files (DATAROOTDIR/qlogging-categories5). Since 5.59.0 ✨
  • JARDIR — Java AAR/JAR files for Android, bestie. 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 — yes she's new here, be nice 🎀

Ok so now the part where it gets a lil spicy 🔥 — the configuration rules. Buckle up.

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 (the ones where it says so in the parentheses up there ⬆️). If it's not set, it defaults to TRUE when Qt5's qmake is found and its QT_INSTALL_PREFIX matches CMAKE_INSTALL_PREFIX — otherwise it defaults to FALSE.

Big warning energy: this variable should NOT be set from inside CMakeLists.txt files. Like, literally don't. It's meant to be set by hand when you're configuring a project that uses KDEInstallDirs (packagers do this, iykyk).

If KDE_INSTALL_DIRS_NO_DEPRECATED is set to TRUE before including this module, the deprecated variables (the ones in square brackets above) simply don't get defined. Poof, gone 💨

On top of that, for each KDE_INSTALL_* variable there's an equivalent CMAKE_INSTALL_* variable that gets defined. And if KDE_INSTALL_DIRS_NO_DEPRECATED is TRUE, only the ones defined by the GNUInstallDirs module (that ships with CMake) are defined. If KDE_INSTALL_DIRS_NO_CMAKE_VARIABLES is TRUE, this module defines no variables with a CMAKE_ prefix at all — with the one exception of CMAKE_INSTALL_DEFAULT_COMPONENT_NAME, which you'll hear about below 👀

The KDE_INSTALL_<dir> variables (or their CMAKE_INSTALL_<dir> or deprecated counterparts) can be passed to the DESTINATION options of install() commands for the matching file type. They live in the CMake cache, so users can totally override the defaults above.

Now the plot twist 🌈: if the KDE_INSTALL_<dir>, CMAKE_INSTALL_<dir> or deprecated form of the variable is already set before include(KDEInstallDirs), it won't be overwritten by KDEInstallDirs. That's lowkey useful if you want to set custom values via CMake command line variable definitions. But there are implications, bestie, and you need to know them:

  • GNUInstallDirs defines CMAKE_INSTALL_<dir> variables, so because of that, KDEInstallDirs won't overwrite them if it gets included later. In most cases that's unintended, and if you need GNUInstallDirs you should always include it after you've included KDEInstallDirs.

If you set custom values to KDE_INSTALL_<dir> or CMAKE_INSTALL_<dir> the way we just described, both forms of the variable are affected. But passing multiple forms of the same variable (say, KDE_INSTALL_BINDIR and CMAKE_INSTALL_BINDIR together) is undefined behaviour 💀 — just don't, fr fr.

There's also KDE_INSTALL_TARGETS_DEFAULT_ARGS (plus its deprecated form INSTALL_TARGETS_DEFAULT_ARGS). Use it when you're installing libraries or user-executable applications, like this:

install(TARGETS mylib myapp ${KDE_INSTALL_TARGETS_DEFAULT_ARGS})
It MUST NOT be used for installing plugins, system admin executables, or executables that are only meant to be used internally by other code. Those go to KDE_INSTALL_PLUGINDIR, KDE_INSTALL_SBINDIR or KDE_INSTALL_LIBEXECDIR respectively. Respect the categories, periodt.

Also CMAKE_INSTALL_DEFAULT_COMPONENT_NAME gets set to ${PROJECT_NAME} so there's a sensible default for that CMake option. Cute of them 🫶

Mixing absolute and relative paths — especially for BINDIR, LIBDIR and INCLUDEDIR — can cause issues with exported targets. And since the defaults for those are relative paths, use relative paths on the command line whenever you can. So do:

-DKDE_INSTALL_LIBDIR=lib64

instead of:

-DKDE_INSTALL_LIBDIR=/usr/lib/lib64

when you're overriding the library directory. Slay 💅

Since 5.82.0 — before that it was available as KDEInstallDirs <#kde-module:KDEInstallDirs>.

NB: the variables starting with KDE_INSTALL_ are available since 1.6.0, unless the individual variable says otherwise.

And KDE_INSTALL_PREFIX_SCRIPT will install a ${CMAKE_INSTALL_PREFIX}/prefix.sh file, which lets you easily pull the necessary environment variables for the prefix into a process. Iconic convenience 💖

🦋 KDEInstallDirs6

Ok this is the Qt6/KF6 glow-up ✨ — it defines the KDE standard installation directories for Qt6/KF6 based software.

Real talk: none of the variables defined by this module tell you anything about where already-installed KDE software lives. It's not that kind of module.

It also sets CMAKE_INSTALL_PREFIX to ECM's installation prefix, unless something else already set that variable explicitly. First come, first served 🎀

Including this module defines these variables:

  • KDE_INSTALL_<dir> — destination for files of a given type
  • KDE_INSTALL_FULL_<dir> — the corresponding absolute path

where <dir> is one of these (default values in parentheses, keep up 🏃‍♀️):

  • 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)
  • QTMETATYPESDIR — Qt metatypes files (metatypes or qtpaths's QT_INSTALL_ARCHDATA/metatypes). Since 6.27.
  • 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 defaults for some variables get queried from Qt6's qmake instead (again, wherever it says so in the parentheses above). If it's not set, it defaults to TRUE when Qt6's qmake is found and its QT_INSTALL_PREFIX equals CMAKE_INSTALL_PREFIX — otherwise FALSE.

Do NOT set this from inside CMakeLists.txt files 🚫 It's meant to be set manually when configuring a project that uses KDEInstallDirs (packagers, this is your moment 👑).

Also, for each KDE_INSTALL_* variable there's an equivalent CMAKE_INSTALL_* variable defined — if that variable is also defined by the GNUInstallDirs module (the one shipped with CMake). If KDE_INSTALL_DIRS_NO_CMAKE_VARIABLES is TRUE, this module defines zero variables with a CMAKE_ prefix (other than CMAKE_INSTALL_DEFAULT_COMPONENT_NAME — see below, as always).

The KDE_INSTALL_<dir> variables can be passed to the DESTINATION options of install() commands for the matching file type. They're set in the CMake cache, so users can override the defaults above. Standard behaviour, no notes 💅

And if the KDE_INSTALL_<dir> or CMAKE_INSTALL_<dir> variables are set before include(KDEInstallDirs), KDEInstallDirs won't overwrite them. Handy if you want to set custom values with CMake command line variable definitions. But, again, implications:

  • GNUInstallDirs defines CMAKE_INSTALL_<dir> variables, so KDEInstallDirs won't overwrite them if it's included afterwards. Usually unintended! If you need GNUInstallDirs, always include it after KDEInstallDirs.
  • Extra heads up: Qt uses GNUInstallDirs since Qt6, which means find_package(Qt6 ...) is equivalent to include(GNUInstallDirs) in that case. Yeah. Plan accordingly 😭

If you set custom values to KDE_INSTALL_<dir> or CMAKE_INSTALL_<dir> like we talked about, both forms of the variable get affected. But passing multiple forms of the same variable (e.g. KDE_INSTALL_BINDIR and CMAKE_INSTALL_BINDIR on the command line) is undefined behaviour — avoid, avoid, avoid 💀

Okay bestie, so the variable KDE_INSTALL_TARGETS_DEFAULT_ARGS is also defined for you ✨. Use this one whenever you're installing libraries or user-executable applications, like this:

install(TARGETS mylib myapp ${KDE_INSTALL_TARGETS_DEFAULT_ARGS})
🫶 Hard rule, no cap: it MUST NOT be used for installing plugins, system admin executables, or executables that are only meant to be used internally by other code. Those get their own homes — use KDE_INSTALL_PLUGINDIR, KDE_INSTALL_SBINDIR or KDE_INSTALL_LIBEXECDIR respectively. Everybody in their own lane 💅

On top of that, CMAKE_INSTALL_DEFAULT_COMPONENT_NAME gets set to ${PROJECT_NAME} so that this CMake option has a sensible default out of the box. Iconic behaviour, honestly.

Also, heads up: mixing absolute and relative paths — especially for BINDIR, LIBDIR and INCLUDEDIR — can cause issues with exported targets 😭. And since the default values for those are relative paths, you should use relative paths on the command line whenever you can. So like, use -DKDE_INSTALL_LIBDIR=lib64 instead of -DKDE_INSTALL_LIBDIR=/usr/lib/lib64 to override the library directory. Learn from my mistakes, bestie.

The KDE_INSTALL_PREFIX_SCRIPT option will install a ${CMAKE_INSTALL_PREFIX}/prefix.sh file, which lets you easily incorporate the necessary environment variables for the prefix into a process. 🎀

🌸 KDEMetaInfoPlatformCheck

By including this module, you get an automatic check between the supported platforms listed in the metainfo.yaml file and the current platform that's the target of the build. Vibe check, but for platforms.

If the current platform that is the target of the build isn't supported, a CMake FATAL_ERROR will be issued 💀.

You can skip the check entirely by setting KF_IGNORE_PLATFORM_CHECK to ON.

Since 5.93 🦋

🎀 KDEPackageAppTemplates

Packages KApptemplate/KDevelop compatible application templates. This is the little module that could.

This module gives you the functionality to package project templates into a tarball and install them, compatible with the format used by KApptemplate and KDevelop. Super useful for providing minimal examples for the usage of the KDE Frameworks ✨.

It provides this 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'll 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, which makes this placeholder obsolete 🙈
Deprecated means deprecated, bestie — it's giving legacy energy.

Multiple templates can be passed at once 👑.

Unless you set KDE_INSTALL_APP_TEMPLATES, this function is skipped when cross-compiling.

Since 5.18 🍓

👀 SEE ALSO

KDE Developers 💜

And that's a wrap on the whole page, bestie!! 🌟 This is version 6.31, dated Oct 11, 2026, and it lives at ECM-KDE-MODULES(7) — go forth and install(TARGETS) responsibly ✨💅🫶

📦 where this page comes from