FreeBSD Manual Pages
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 op- tions) 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_pack- age 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 avail- able. ALL KDE MODULES KDECMakeSettings Changes various CMake settings to what the KDE community views as more sen- sible 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 de- sired. 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 be- fore 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 be- fore 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 man- ual for more details. This section can be disabled by setting KDE_SKIP_TEST_SETTINGS to TRUE be- fore 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 abina 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_unin- stalled). This section can be disabled by setting KDE_SKIP_BUILD_SETTINGS to TRUE be- fore 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 en- abled by setting APPLE_FORCE_X11 to ON. A warning is printed for the developer to know that the detection is dis- abled 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 wonat 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 de- fault 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 transla- tions 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 All KDE_L10N_* options have been deprecated since 5.102.0, as translations 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 en- force 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 *.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_tar- get_enable_exceptions() can be used to re-enable them for a specific tar- get. 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 de- fault 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 re- quired 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 >= 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 mod- ule, 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_COMPILERSET- TINGS_LEVEL >= 5.85, TRUE otherwise). * -Wmissing-include-dirs (GNU compilers, since 5.85) Can be disabled by setting KDE_SKIP_MISSING_INCLUDE_DIRS_WARNINGS_SET- TINGS to TRUE before including this module (default is FALSE for KDE_COM- PILERSETTINGS_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 be- fore 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 iterators. 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 dis- able individual definitions instead use remove_definitions() directly af- ter 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 linking. It ensures libraries bind global function references locally rather than at runtime. This option only has an effect on ELF-based sys- tems. The option is disabled by default except when using KDEFrameworkCompilerSettings where itas enabled. Projects can enable it by calling set(ENABLE_BSYMBOLICFUNCTIONS ON) or passing -DENABLE BSYMBOLICFUNCTIONS=ON when configuring the build directory. Since 5.85 ECM_FORCE_ASSERTS Enable Q_ASSERT regardless of CMAKE_BUILD_TYPE. Off by default. Since 6.24 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-Frameworks. There is no guarantee for backward-compatibility in newer versions. The KDECompilerSettings module is included and, in addition, various de- fines 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. 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_git_pre_commit_hook( CHECKS <check1> [<check2> [...] [CUSTOM_SCRIPTS [<script paths> [<script paths> ...]]] # since 5.109 ) This function will create a pre-commit hook which contains all the given checks. In addition to that, you can pass in paths to custom scripts that will be run as the pre-commit hook. If a custom hooks directory is set via core.hooksPath, a warning is issued. The created pre-commit script will also execute any custom user-provided scripts located in .git/hooks/pre-commit.d directory. 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 existing .clang-format file, in case you want to use the one provided by ECM you can include include(KDE- ClangFormat) which will copy the file to the source dir. It is also rec- ommended to reformat the entire project before enforcing the formatting using this commit hook. * JSON_SCHEMA Since 5.110, uses the check-jsonschema CLI tool to ensure that all files are valid JSON and match the KPluginMetaData spec. This only applied if the JSON file has a aKPlugina object in its root. To ig- nore invalid files, for example for testing error handling, given files can be excluded in the .kde-ci.yml file Define Options.json-validate-ig- nore with an array of the files you want to ignore Example usage: include(KDEGitCommitHooks) kde_configure_git_pre_commit_hook(CHECKS JSON_SCHEMA 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 software. Note that none of the variables defined by this module provide any informa- tion 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: 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, dep- recated 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 EXEC- ROOTDIR/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-qt5as QT_INSTALL_PLUGINS) [QT_PLUGIN_INSTALL_DIR] PLUGINDIR Plugins (QTPLUGINDIR) [PLUGIN_INSTALL_DIR] QTQUICKIMPORTSDIR QtQuick1 imports (QTPLUGINDIR/imports or qmake-qt5as QT_INSTALL_IM- PORTS) [IMPORTS_INSTALL_DIR] QMLDIR QtQuick2 imports (LIBDIR/qml or qmake-qt5as QT_INSTALL_QML) [QML_IN- STALL_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 Win- dows, share otherwise) [SHARE_INSTALL_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_UPDATE_IN- STALL_DIR] KSERVICES5DIR or (since 5.89) KSERVICESDIR services for KDE Frameworks 5 (DATAROOTDIR/kservices5) [SERVICES_IN- STALL_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/tem- plates) [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) [KNOTI- FYRC_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_IN- STALL_DIR] APPDIR application desktop files (DATAROOTDIR/applications) Since 1.1.0. [XDG_APPS_INSTALL_DIR] DESKTOPDIR desktop directories (DATAROOTDIR/desktop-directories) [XDG_DIREC- TORY_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-qt5as 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_IN- STALL_DIR] DBUSSYSTEMSERVICEDIR D-Bus system services (DBUSDIR/system-services) [DBUS_SYSTEM_SER- VICES_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_IN- STALL_DIR] AUTOSTARTDIR autostart files (CONFDIR/autostart) [AUTOSTART_INSTALL_DIR] LOGGINGCATEGORIESDIR Qt logging categories files directory (DATAROOTDIR/qlogging-cate- gories5) 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-functions) Since 5.101 If KDE_INSTALL_USE_QT_SYS_PATHS is set to TRUE before including this mod- ule, the default values for some variables are instead queried from Qt5as qmake (where mentioned in the parentheses above). If not set, it will de- fault to TRUE if Qt5as qmake is found and itas 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 mod- ule, 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() com- mands for the corresponding file type. They are set in the CMake cache, and so the defaults above can be overridden by users. Note that if the KDE_INSTALL_<dir>, CMAKE_INSTALL_<dir> or deprecated form of the variable are set before include(KDEInstallDirs), they wonat be over- written by KDEInstallDirs. This is useful if you eg. want to use CMake com- mand line variable definitions to set custom values. There are however some other implications you need to be aware of: GNUInstallDirs defines CMAKE_INSTALL_<dir> variables, before hence KDEInstallDirs will not over- write them if it is included later. In most cases this is unintended and if you need to include GNUInstallDirs you should always do that after after you included KDEInstallDirs. If you set custom values to KDE_INSTALL_<dir> or CMAKE_INSTALL_<dir> as de- scribed above always both forms of the variable will be affected. The ef- fect of passing multiple forms of the same variable eg. on the command line (such as KDE_INSTALL_BINDIR and CMAKE_INSTALL_BINDIR) is undefined and should be avoided. 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 fol- lowing manner: install(TARGETS mylib myapp ${KDE_INSTALL_TARGETS_DEFAULT_ARGS}) It MUST NOT be used for installing plugins, system admin executables or ex- ecutables only intended for use internally by other code. Those should use KDE_INSTALL_PLUGINDIR, KDE_INSTALL_SBINDIR or KDE_INSTALL_LIBEXECDIR re- spectively. 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, LIB- DIR 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 in- stead of -DKDE_INSTALL_LIBDIR=/usr/lib/lib64 to override the library direc- tory). 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_PRE- FIX}/prefix.sh file that allows to easily incorporate the necessary envi- ronment 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 informa- tion 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: 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 EXEC- ROOTDIR/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 qtpathsas QT_INSTALL_PLUGINS) PLUGINDIR Plugins (QTPLUGINDIR) [PLUGIN_INSTALL_DIR] QMLDIR QtQuick2 imports (LIBDIR/qml or qtpathsas 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 Win- dows, share otherwise) 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) KXMLGUIDIR kxmlgui .rc files (DATAROOTDIR/kxmlgui5) KAPPTEMPLATESDIR KAppTemplate and KDevelop templates (DATAROOTDIR/kdevappwizard/tem- plates) 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 qtpathsas QT_INSTALL_DOCS) QCHDIR documentation bundles in QCH format (DATAROOTDIR/doc/qch) QTMETATYPESDIR Qt metatypes files (metatypes or qtpathsas QT_INSTALL_ARCH- DATA/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-cate- gories6) 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 mod- ule, the default values for some variables are instead queried from Qt6as qmake (where mentioned in the parentheses above). If not set, it will de- fault to TRUE if Qt6as qmake is found and itas 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 GNUIn- stallDirs module (shipped with CMake). 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 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 if the KDE_INSTALL_<dir> or CMAKE_INSTALL_<dir> variables are set before include(KDEInstallDirs), they wonat be overwritten by KDEIn- stallDirs. This is useful if you eg. want to use CMake command line vari- able definitions to set custom values. There are however some other impli- cations you need to be aware of: GNUInstallDirs defines CMAKE_INSTALL_<dir> variables, before hence KDEInstallDirs will not overwrite them if it is in- cluded later. In most cases this is unintended and if you need to include GNUInstallDirs you should always do that after after you included KDEIn- stallDirs. Be aware that Qt uses GNUInstallDirs since Qt6 and hence find_package(Qt6 ...) is equivalent to include(GNUInstallDirs) in this case. If you set custom values to KDE_INSTALL_<dir> or CMAKE_INSTALL_<dir> as de- scribed above always both forms of the variable will be affected. The ef- fect of passing multiple forms of the same variable eg. on the command line (such as KDE_INSTALL_BINDIR and CMAKE_INSTALL_BINDIR) is undefined and should be avoided. 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 ex- ecutables only intended for use internally by other code. Those should use KDE_INSTALL_PLUGINDIR, KDE_INSTALL_SBINDIR or KDE_INSTALL_LIBEXECDIR re- spectively. 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, LIB- DIR 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 in- stead of -DKDE_INSTALL_LIBDIR=/usr/lib/lib64 to override the library direc- tory). The KDE_INSTALL_PREFIX_SCRIPT option will install a ${CMAKE_INSTALL_PRE- FIX}/prefix.sh file that allows to easily incorporate the necessary envi- ronment variables for the prefix into a process. KDEMetaInfoPlatformCheck By including this module there will be an automatic check between the sup- ported 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 supported 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 install project templates compatible with the format used by KApptemplate and KDe- velop. 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_KAPPTEMPLATESDIR from KDEInstallDirs. TEMPLATES lists subdirectories containing template files; each <template> directory will be packaged into a file named <template>.tar.bz2 and in- stalled to the appropriate location. The template is a minimal source tree of an application as if it was an ap- plication 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 KAppTem- plate %{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 rela- tive paths with that entry, making this placeholder obsolete Multiple templates can be passed at once. Unless setting KDE_INSTALL_APP_TEMPLATES, this function is skipped when cross-compiling. Since 5.18 SEE ALSO ecm(7), ecm-modules(7), ecm-find-modules(7) COPYRIGHT KDE Developers 6.28 Jul 31, 2026 ECM-KDE-MODULES(7)
NAME | INTRODUCTION | ALL KDE MODULES | SEE ALSO | COPYRIGHT
Want to link to this manual page? Use this URL:
<https://man.freebsd.org/cgi/man.cgi?query=ecm-kde-modules&sektion=7&manpath=FreeBSD+Ports+15.1.quarterly>