KDECMakeSettings

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

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

This section can be disabled by setting KDE_SKIP_TEST_SETTINGS to TRUE before including this module.

Build Settings

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

Translations

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

KDEClangFormat

This module provides the following function:

kde_clang_format(<files>)

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

The .clang-format file from ECM will be copied to the source directory. This file should not be added to version control. It is recommended to add it to the .gitignore file: /.clang-format.

Since 5.79: If the source folder already contains a .clang-format file it is not overwritten. Since version 5.80 this function is called by default in KDEFrameworkCompilerSettings. If directories should be excluded from the formatting a .clang-format file with “DisableFormat: true” and “SortIncludes: false” should be created.

Example usage:

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

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.

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

Modern code

For KDE_COMPILERSETTINGS_LEVEL >= 5.85:

Otherwise:

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:

Otherwise:

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:

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

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

WARNING:

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.

KDEGitCommitHooks

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:

Example usage:

include(KDEGitCommitHooks)
kde_configure_git_pre_commit_hook(CHECKS CLANG_FORMAT)

Since 5.79

KDEInstallDirs

Since 5.82.0, prior to that equivalent to KDEInstallDirs5.

KDEInstallDirs5

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

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

Inclusion of this module defines the following variables:

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

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

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

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

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

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

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

install(TARGETS mylib myapp ${KDE_INSTALL_TARGETS_DEFAULT_ARGS})

It MUST NOT be used for installing plugins, system admin executables or executables only intended for use internally by other code. Those should use KDE_INSTALL_PLUGINDIR, KDE_INSTALL_SBINDIR or KDE_INSTALL_LIBEXECDIR respectively.

Additionally, CMAKE_INSTALL_DEFAULT_COMPONENT_NAME will be set to ${PROJECT_NAME} to provide a sensible default for this CMake option.

Note that mixing absolute and relative paths, particularly for BINDIR, LIBDIR and INCLUDEDIR, can cause issues with exported targets. Given that the default values for these are relative paths, relative paths should be used on the command line when possible (eg: use -DKDE_INSTALL_LIBDIR=lib64 instead of -DKDE_INSTALL_LIBDIR=/usr/lib/lib64 to override the library directory).

Since 5.82.0, prior to that available as KDEInstallDirs.

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

The KDE_INSTALL_PREFIX_SCRIPT option will install a ${CMAKE_INSTALL_PREFIX}/prefix.sh file that allows to easily incorporate the necessary environment variables for the prefix into a process.

KDEInstallDirs6

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

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

Also sets CMAKE_INSTALL_PREFIX to the installation prefix of ECM, unless that variable has been already explicitly set by something else.

Inclusion of this module defines the following variables:

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

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

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

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

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

The variable KDE_INSTALL_TARGETS_DEFAULT_ARGS is also defined. This should be used when libraries or user-executable applications are installed, in the following manner:

install(TARGETS mylib myapp ${KDE_INSTALL_TARGETS_DEFAULT_ARGS})

It MUST NOT be used for installing plugins, system admin executables or executables only intended for use internally by other code. Those should use KDE_INSTALL_PLUGINDIR, KDE_INSTALL_SBINDIR or KDE_INSTALL_LIBEXECDIR respectively.

Additionally, CMAKE_INSTALL_DEFAULT_COMPONENT_NAME will be set to ${PROJECT_NAME} to provide a sensible default for this CMake option.

Note that mixing absolute and relative paths, particularly for BINDIR, LIBDIR and INCLUDEDIR, can cause issues with exported targets. Given that the default values for these are relative paths, relative paths should be used on the command line when possible (eg: use -DKDE_INSTALL_LIBDIR=lib64 instead of -DKDE_INSTALL_LIBDIR=/usr/lib/lib64 to override the library directory).

The KDE_INSTALL_PREFIX_SCRIPT option will install a ${CMAKE_INSTALL_PREFIX}/prefix.sh file that allows to easily incorporate the necessary environment variables for the prefix into a process.

KDETemplateGenerator

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:

Deprecated:

Multiple templates can be passed at once.

Since 5.18