1ECM-KDE-MODULES(7) Extra CMake Modules ECM-KDE-MODULES(7)
2
6 ecm-kde-modules - ECM KDE Modules Reference
7
9 Extra CMake Modules (ECM) provides several modules that provide default
10 settings (like installation directories, compiler flags and other CMake
11 options) aimed at software produced by the KDE modules; these are docu‐
12 mented here. ECM also provides modules with more general functionality,
13 documented in ecm-modules(7), and ones that extend the functionality of
14 the find_package command, documented in ecm-find-modules(7).
15 To use these modules, you need to tell CMake to find the ECM package,
17 and then add either ${ECM_MODULE_PATH} or ${ECM_KDE_MODULE_DIR} to the
18 CMAKE_MODULE_PATH variable:
19 find_package(ECM REQUIRED NO_MODULE)
21 set(CMAKE_MODULE_PATH ${ECM_MODULE_DIR})
22 Using ${ECM_MODULE_PATH} will also make the other types of modules
24 available.
25
27 KDECMakeSettings
28 Changes various CMake settings to what the KDE community views as more
29 sensible defaults.
30 It is recommended to include this module with the NO_POLICY_SCOPE flag,
32 otherwise you may get spurious warnings with some versions of CMake.
33 It is split into three parts, which can be independently disabled if
35 desired.
36 Runtime Paths
38 The default runtime path (used on Unix systems to search for dynami‐
39 cally-linked libraries) is set to include the location that libraries
40 will be installed to (as set in LIB_INSTALL_DIR or, if the former is
41 not set, KDE_INSTALL_LIBDIR), and also the linker search path.
42 NOTE:
44 LIB_INSTALL_DIR or alternatively KDE_INSTALL_LIBDIR needs to be set
45 before including this module. Typically, this is done by including
46 the KDEInstallDirs module.
47 This section can be disabled by setting KDE_SKIP_RPATH_SETTINGS to TRUE
49 before including this module.
50 Testing
52 Testing is enabled by default, and an option BUILD_TESTING is provided
53 for users to control this. See the CTest module documentation in the
54 CMake manual for more details.
55 This section can be disabled by setting KDE_SKIP_TEST_SETTINGS to TRUE
57 before including this module.
58 Build Settings
60 Various CMake build defaults are altered, such as searching source and
61 build directories for includes first, enabling automoc by default.
62 When find_package(ECM 5.38) or higher is called, this also selects a
64 layout for the build dir that helps running executables without in‐
65 stalling: all executables are built into a toplevel “bin” dir, making
66 it possible to find helper binaries, and to find uninstalled plugins
67 (provided that you use kcoreaddons_add_plugin() or set LIBRARY_OUT‐
68 PUT_DIRECTORY as documented on
69 https://community.kde.org/Guidelines_and_HOWTOs/Making_apps_run_uninstalled).
70 This section can be disabled by setting KDE_SKIP_BUILD_SETTINGS to TRUE
72 before including this module.
73 This section also provides an uninstall target that can be individually
75 disabled by setting KDE_SKIP_UNINSTALL_TARGET to TRUE before including
76 this module.
77 By default on OS X, X11 and XCB related detections are disabled. How‐
79 ever if the need would arise to use these technologies, the detection
80 can be enabled by setting APPLE_FORCE_X11 to ON.
81 A warning is printed for the developer to know that the detection is
83 disabled on OS X. This message can be turned off by setting APPLE_SUP‐
84 PRESS_X11_WARNING to ON.
85 Since pre-1.0.0.
87 ENABLE_CLAZY option is added (OFF by default) when clang is being used.
89 Turning this option on will force clang to load the clazy plugins for
90 richer warnings on Qt-related code.
91 If clang is not being used, this won’t have an effect. See
93 https://commits.kde.org/clazy?path=README.md
94 Since 5.17.0
96 • uninstall target functionality since 1.7.0
98 • APPLE_FORCE_X11 option since 5.14.0 (detecting X11 was previously the
100 default behavior)
101 • APPLE_SUPPRESS_X11_WARNING option since 5.14.0
103 • CMAKE_AUTORCC enabled by default when supported by CMake (>= 3.0)
105 since 5.62.0
106 Translations
108 A fetch-translations target will be set up that will download transla‐
109 tions for projects using l10n.kde.org.
110 KDE_L10N_BRANCH will be responsible for choosing which l10n branch to
112 use for the translations.
113 KDE_L10N_AUTO_TRANSLATIONS (OFF by default) will indicate whether
115 translations should be downloaded when building the project.
116 Since 5.34.0
118 KDE_L10N_SYNC_TRANSLATIONS (OFF by default) will download the transla‐
120 tions at configuration time instead of build time.
121 Since 5.50.0
123 KDEClangFormat
125 This module provides a functionality to format the source code of your
126 repository according to a predefined KDE clang-format file.
127 This module provides the following function:
129 kde_clang_format(<files>)
131 Using this function will create a clang-format target that will format
133 all <files> passed to the function with the predefined KDE clang-format
134 style. To format the files you have to invoke the target with make
135 clang-format or ninja clang-format. Once the project is formatted it
136 is recommended to enforce the formatting using a pre-commit hook, this
137 can be done using KDEGitCommitHooks.
138 The .clang-format file from ECM will be copied to the source directory.
140 This file should not be added to version control. It is recommended to
141 add it to the .gitignore file: /.clang-format.
142 Since 5.79: If the source folder already contains a .clang-format file
144 it is not overwritten. Since version 5.80 this function is called by
145 default in KDEFrameworkCompilerSettings. If directories should be ex‐
146 cluded from the formatting a .clang-format file with DisableFormat:
147 true and SortIncludes: false should be created.
148 Example usage:
150 include(KDEClangFormat)
152 file(GLOB_RECURSE ALL_CLANG_FORMAT_SOURCE_FILES *.cpp *.h *.hpp *.c)
153 kde_clang_format(${ALL_CLANG_FORMAT_SOURCE_FILES})
154 To exclude directories from the formatting add a .clang-format file in
156 the directory with the following contents:
157 DisableFormat: true
159 SortIncludes: false
160 Since 5.64
162 KDECompilerSettings
164 Set useful compile and link flags for C++ (and C) code.
165 Enables many more warnings than the default, and sets stricter modes
167 for some compiler features. By default, exceptions are disabled;
168 kde_target_enable_exceptions() can be used to re-enable them for a spe‐
169 cific target.
170 NOTE:
172 It is recommended to include this module with the NO_POLICY_SCOPE
173 flag, otherwise you may get spurious warnings with some versions of
174 CMake.
175 Since 5.85 newer settings are controlled by a variable KDE_COMPILERSET‐
177 TINGS_LEVEL, taking an ECM version as value. That version can not be
178 greater than the minimum required ECM version. The settings which are
179 default at that version will then be used, but can be overridden by
180 more fine-grained controls (see respective settings). This variable
181 needs to be set before including this module, otherwise defaults to the
182 minimum required ECM version.
183 Modern code
185 The following CMake C standard default variables are set:
186 For KDE_COMPILERSETTINGS_LEVEL >= 5.85:
188 • CMAKE_C_STANDARD: 99
190 • CMAKE_C_STANDARD_REQUIRED: TRUE
192 • CMAKE_C_EXTENSIONS: OFF
194 Otherwise:
196 • CMAKE_C_STANDARD: 90
198 • CMAKE_C_STANDARD_REQUIRED: not modified
200 • CMAKE_C_EXTENSIONS: not modified
202 If the variable CMAKE_C_STANDARD is already set when including this
204 module, none of the above variables will be modified.
205 The following CMake C++ standard default variables are set:
207 For KDE_COMPILERSETTINGS_LEVEL >= 5.85:
209 • CMAKE_CXX_STANDARD: 17
211 • CMAKE_CXX_STANDARD_REQUIRED: TRUE
213 • CMAKE_CXX_EXTENSIONS: OFF
215 Otherwise:
217 • CMAKE_CXX_STANDARD: 11
219 • CMAKE_CXX_STANDARD_REQUIRED: TRUE
221 • CMAKE_CXX_EXTENSIONS: not modified.
223 If the variable CMAKE_CXX_STANDARD is already set when including this
225 module, none of the above variables will be modified.
226 The following C++ compiler flags are set:
228 • -pedantic (GNU and Clang compilers, since 5.85)
230 Can be disabled by setting KDE_SKIP_PEDANTIC_WARNINGS_SETTINGS to
232 TRUE before including this module (default is FALSE for KDE_COMPILER‐
233 SETTINGS_LEVEL >= 5.85, TRUE otherwise).
234 • -Wmissing-include-dirs (GNU compilers, since 5.85)
236 Can be disabled by setting KDE_SKIP_MISSING_INCLUDE_DIRS_WARN‐
238 INGS_SETTINGS to TRUE before including this module (default is FALSE
239 for KDE_COMPILERSETTINGS_LEVEL >= 5.85, TRUE otherwise).
240 • -Wzero-as-null-pointer-constant (GNU and Clang compilers, since 5.85)
242 Can be disabled by setting KDE_SKIP_NULLPTR_WARNINGS_SETTINGS to TRUE
244 before including this module (default is FALSE for KDE_COMPILERSET‐
245 TINGS_LEVEL >= 5.85, TRUE otherwise).
246 • -Werror=undef (GNU and Clang compilers, since 5.96.0)
248 • Qt related preprocessor definitions (since 5.85.0):
250 • -DQT_NO_CAST_TO_ASCII
252 • -DQT_NO_CAST_FROM_ASCII
254 • -DQT_NO_URL_CAST_FROM_STRING
256 • -DQT_NO_CAST_FROM_BYTEARRAY
258 • -DQT_USE_QSTRINGBUILDER
260 • -DQT_NO_NARROWING_CONVERSIONS_IN_CONNECT
262 • -DQT_NO_KEYWORDS
264 • -DQT_NO_FOREACH
266 • -DQT_STRICT_ITERATORS
268 Strict iterators are not enabled on Windows, because they lead to a
270 link error when application code iterates over a QVector<QPoint>
271 for instance, unless Qt itself was also built with strict itera‐
272 tors. See example at https://bugreports.qt.io/browse/AUTOSUITE-946
273 Can be controlled by setting KDE_QT_MODERNCODE_DEFINITIONS_LEVEL to
275 the version of ECM where the wanted set of definitions has been added
276 before including this module (default is KDE_COMPILERSETTINGS_LEVEL).
277 To disable individual definitions instead use remove_definitions()
278 directly after including this module.
279 Functions
281 This module provides the following functions:
282 kde_source_files_enable_exceptions([file1 [file2 [...]]])
284 Enables exceptions for specific source files. This should not be used
286 on source files in a language other than C++.
287 kde_target_enable_exceptions(target <INTERFACE|PUBLIC|PRIVATE>)
289 Enables exceptions for a specific target. This should not be used on a
291 target that has source files in a language other than C++.
292 kde_enable_exceptions()
294 Enables exceptions for C++ source files compiled for the CMakeLists.txt
296 file in the current directory and all subdirectories.
297 Variables
299 Inclusion of this module defines the following variables:
300 ENABLE_BSYMBOLICFUNCTIONS
302 indicates whether we make use of -Bsymbolic-functions for link‐
303 ing. It ensures libraries bind global function references lo‐
304 cally rather than at runtime. This option only has an effect on
305 ELF-based systems.
306 The option is disabled by default except when using KDEFrame‐
308 workCompilerSettings where it’s enabled. Projects can enable it
309 by calling set(ENABLE_BSYMBOLICFUNCTIONS ON) or passing -DENABLE
310 BSYMBOLICFUNCTIONS=ON when configuring the build directory.
311 Since 5.85
313 Example usages:
315 # needing some macro/feature only available with ECM 5.80.0
317 find_package(ECM 5.80.0 NO_MODULE)
318 # requiring ECM 5.80.0 above will default KDE_COMPILERSETTINGS_LEVEL also to 5.80.0,
320 # thus not activate any newer settings
321 include(KDECompilerSettings NO_POLICY_SCOPE)
322 # needing some macro/feature only available with ECM 5.87.0
324 find_package(ECM 5.87.0 NO_MODULE)
325 # project uses settings default as of KDECompilerSettings in ECM 5.85.0
327 set(KDE_COMPILERSETTINGS_LEVEL 5.85.0)
328 include(KDECompilerSettings NO_POLICY_SCOPE)
329 # needing some macro/feature only available with ECM 5.87.0
331 find_package(ECM 5.87.0 NO_MODULE)
332 # project mainly uses settings default as of KDECompilerSettings in ECM 5.85.0
334 # with some small twisting
335 set(KDE_COMPILERSETTINGS_LEVEL 5.85.0)
336 # not ready yet for pedantic compilers
337 set(KDE_SKIP_PEDANTIC_WARNINGS_SETTINGS TRUE)
338 # avoid any Qt definitions
339 set(KDE_QT_MODERNCODE_DEFINITIONS_LEVEL 5.84.0)
340 include(KDECompilerSettings NO_POLICY_SCOPE)
341 # needing some macro/feature only available with ECM 5.85.0
343 find_package(ECM 5.85.0 NO_MODULE)
344 # requiring ECM 5.85.0 above will default KDE_COMPILERSETTINGS_LEVEL also to 5.85.0,
346 # which again defaults KDE_QT_MODERNCODE_DEFINITIONS_LEVEL also to 5.85.0
347 include(KDECompilerSettings NO_POLICY_SCOPE)
348 # project is fine with almost all added Qt definitions as of 5.85.0, but not these ones:
349 remove_definitions(
350 -DQT_NO_KEYWORDS
351 -DQT_NO_FOREACH
352 )
353 Since pre-1.0.0.
355 KDEFrameworkCompilerSettings
357 Set stricter compile and link flags for KDE Frameworks modules.
358 WARNING:
360 Do not use this module for software which is not part of KDE-Frame‐
361 works. There is no guarantee for backward-compatibility in newer
362 versions.
363 The KDECompilerSettings module is included and, in addition, various
365 defines that affect the Qt libraries are set to enforce certain conven‐
366 tions.
367 For example, constructions like QString("foo") are prohibited, instead
369 forcing the use of QLatin1String or QStringLiteral, and some Qt-defined
370 keywords like signals and slots will not be defined.
371 NOTE:
373 It is recommended to include this module with the NO_POLICY_SCOPE
374 flag, otherwise you may get spurious warnings with some versions of
375 CMake.
376 Since pre-1.0.0.
378 KDEGitCommitHooks
380 This module provides a functionality to enforce formatting or in the
381 future other QS checks.
382 This module provides the following function:
384 kde_configure_pre_commit_hook(
386 CHECKS <check1> [<check2> [...]]
387 )
388 This function will create a pre-commit hook which contains all the
390 given checks.
391 Checks:
393 • CLANG_FORMAT With this check enabled the git clang-format tool will
395 be used to make sure that the changed parts are properly formatted.
396 In case the changes are not properly formatted an error message with
397 the command to preview the formatting changes and to format the files
398 in place will be displayed. This tool will reuse the exsting
399 .clang-format file, in case you want to use the one provided by ECM
400 you can include include(KDEClangFormat) which will copy the file to
401 the source dir. It is also recommended to reformat the entire project
402 before enforcing the formatting using this commit hook.
403 Example usage:
405 include(KDEGitCommitHooks)
407 kde_configure_git_pre_commit_hook(CHECKS CLANG_FORMAT)
408 Since 5.79
410 KDEInstallDirs
412 Compatibility wrapper around KDEInstallDirs5.
413 Since 5.82.0, prior to that equivalent to KDEInstallDirs5.
415 KDEInstallDirs5
417 Define KDE standard installation directories for Qt5/KF5 based soft‐
418 ware.
419 Note that none of the variables defined by this module provide any in‐
421 formation about the location of already-installed KDE software.
422 Also sets CMAKE_INSTALL_PREFIX to the installation prefix of ECM, un‐
424 less that variable has been already explicitly set by something else
425 (since 5.61 and with CMake >= 3.7).
426 Inclusion of this module defines the following variables:
428 KDE_INSTALL_<dir>
430 destination for files of a given type
431 KDE_INSTALL_FULL_<dir>
433 corresponding absolute path
434 where <dir> is one of (default values in parentheses and alternative,
436 deprecated variable name in square brackets):
437 BUNDLEDIR
439 application bundles (/Applications/KDE) [BUNDLE_INSTALL_DIR]
440 EXECROOTDIR
442 executables and libraries (<empty>) [EXEC_INSTALL_PREFIX]
443 BINDIR user executables (EXECROOTDIR/bin) [BIN_INSTALL_DIR]
445 SBINDIR
447 system admin executables (EXECROOTDIR/sbin) [SBIN_INSTALL_DIR]
448 LIBDIR object code libraries (EXECROOTDIR/lib, EXECROOTDIR/lib64 or EX‐
450 ECROOTDIR/lib/<multiarch-tuple on Debian) [LIB_INSTALL_DIR]
451 LIBEXECDIR
453 executables for internal use by programs and libraries (BINDIR
454 on Windows, LIBDIR/libexec otherwise) [LIBEXEC_INSTALL_DIR]
455 CMAKEPACKAGEDIR
457 CMake packages, including config files (LIBDIR/cmake) [CMAKECON‐
458 FIG_INSTALL_PREFIX]
459 QTPLUGINDIR
461 Qt plugins (LIBDIR/plugins or qmake-qt5’s QT_INSTALL_PLUGINS)
462 [QT_PLUGIN_INSTALL_DIR]
463 PLUGINDIR
465 Plugins (QTPLUGINDIR) [PLUGIN_INSTALL_DIR]
466 QTQUICKIMPORTSDIR
468 QtQuick1 imports (QTPLUGINDIR/imports or qmake-qt5’s QT_IN‐
469 STALL_IMPORTS) [IMPORTS_INSTALL_DIR]
470 QMLDIR QtQuick2 imports (LIBDIR/qml or qmake-qt5’s QT_INSTALL_QML)
472 [QML_INSTALL_DIR]
473 INCLUDEDIR
475 C and C++ header files (include) [INCLUDE_INSTALL_DIR]
476 LOCALSTATEDIR
478 modifiable single-machine data (var)
479 SHAREDSTATEDIR
481 modifiable architecture-independent data (com)
482 DATAROOTDIR
484 read-only architecture-independent data root (share) [SHARE_IN‐
485 STALL_PREFIX]
486 DATADIR
488 read-only architecture-independent data (DATAROOTDIR) [DATA_IN‐
489 STALL_DIR]
490 DOCBUNDLEDIR
492 documentation bundles generated using kdoctools (DATAROOT‐
493 DIR/doc/HTML) [HTML_INSTALL_DIR]
494 KCFGDIR
496 kconfig description files (DATAROOTDIR/config.kcfg) [KCFG_IN‐
497 STALL_DIR]
498 KCONFUPDATEDIR
500 kconf_update scripts (DATAROOTDIR/kconf_update) [KCONF_UP‐
501 DATE_INSTALL_DIR]
502 KSERVICES5DIR or (since 5.89) KSERVICESDIR
504 services for KDE Frameworks 5 (DATAROOTDIR/kservices5) [SER‐
505 VICES_INSTALL_DIR]
506 KSERVICETYPES5DIR or (since 5.89) KSERVICETYPESDIR
508 service types for KDE Frameworks 5 (DATAROOTDIR/kservicetypes5)
509 [SERVICETYPES_INSTALL_DIR]
510 KXMLGUI5DIR or (since 5.89) KXMLGUIDIR
512 knotify description files (DATAROOTDIR/kxmlgui5) [KXMLGUI_IN‐
513 STALL_DIR]
514 KTEMPLATESDIR
516 Kapptemplate and Kdevelop templates (kdevappwizard/templates)
517 KNOTIFY5RCDIR or (since 5.89) KNOTIFYRCDIR
519 knotify description files (DATAROOTDIR/knotifications5) [KNOTI‐
520 FYRC_INSTALL_DIR]
521 ICONDIR
523 icons (DATAROOTDIR/icons) [ICON_INSTALL_DIR]
524 LOCALEDIR
526 knotify description files (DATAROOTDIR/locale) [LOCALE_IN‐
527 STALL_DIR]
528 SOUNDDIR
530 sound files (DATAROOTDIR/sounds) [SOUND_INSTALL_DIR]
531 TEMPLATEDIR
533 templates (DATAROOTDIR/templates) [TEMPLATES_INSTALL_DIR]
534 WALLPAPERDIR
536 desktop wallpaper images (DATAROOTDIR/wallpapers) [WALLPAPER_IN‐
537 STALL_DIR]
538 APPDIR application desktop files (DATAROOTDIR/applications) Since
540 1.1.0. [XDG_APPS_INSTALL_DIR]
541 DESKTOPDIR
543 desktop directories (DATAROOTDIR/desktop-directories) [XDG_DI‐
544 RECTORY_INSTALL_DIR]
545 MIMEDIR
547 mime description files (DATAROOTDIR/mime/packages) [XDG_MIME_IN‐
548 STALL_DIR]
549 METAINFODIR
551 AppStream component metadata files (DATAROOTDIR/metainfo)
552 QTQCHDIR
554 documentation bundles in QCH format for Qt-extending libraries
555 (DATAROOTDIR/doc/qch or qmake-qt5’s QT_INSTALL_DOCS) Since
556 5.36.0.
557 QCHDIR documentation bundles in QCH format (DATAROOTDIR/doc/qch) Since
559 5.36.0.
560 MANDIR man documentation (DATAROOTDIR/man) [MAN_INSTALL_DIR]
562 INFODIR
564 info documentation (DATAROOTDIR/info)
565 DBUSDIR
567 D-Bus (DATAROOTDIR/dbus-1)
568 DBUSINTERFACEDIR
570 D-Bus interfaces (DBUSDIR/interfaces) [DBUS_INTERFACES_IN‐
571 STALL_DIR]
572 DBUSSERVICEDIR
574 D-Bus session services (DBUSDIR/services) [DBUS_SERVICES_IN‐
575 STALL_DIR]
576 DBUSSYSTEMSERVICEDIR
578 D-Bus system services (DBUSDIR/system-services) [DBUS_SYS‐
579 TEM_SERVICES_INSTALL_DIR]
580 SYSCONFDIR
582 read-only single-machine data (etc, or /etc if CMAKE_IN‐
583 STALL_PREFIX is /usr) [SYSCONF_INSTALL_DIR]
584 CONFDIR
586 application configuration files (SYSCONFDIR/xdg) [CONFIG_IN‐
587 STALL_DIR]
588 AUTOSTARTDIR
590 autostart files (CONFDIR/autostart) [AUTOSTART_INSTALL_DIR]
591 LOGGINGCATEGORIESDIR
593 Qt logging categories files directory (DATAROOTDIR/qlogging-cat‐
594 egories5) Since 5.59.0
595 JARDIR Java AAR/JAR files for Android. Since 5.62.0
597 SYSTEMDUNITDIR
599 Systemd Units (lib/systemd) [SYSTEMD_UNIT_INSTALL_DIR]. Since
600 5.65
601 SYSTEMDUSERUNITDIR
603 Systemd User Units (lib/systemd/user) [SYSTEMD_USER_UNIT_IN‐
604 STALL_DIR]. Since 5.65
605 If KDE_INSTALL_USE_QT_SYS_PATHS is set to TRUE before including this
607 module, the default values for some variables are instead queried from
608 Qt5’s qmake (where mentioned in the parentheses above). If not set, it
609 will default to TRUE if Qt5’s qmake is found and it’s QT_INSTALL_PREFIX
610 is the same as CMAKE_INSTALL_PREFIX, otherwise default to FALSE. This
611 variable should NOT be set from within CMakeLists.txt files, instead is
612 intended to be set manually when configuring a project which uses KDE‐
613 InstallDirs (e.g. by packagers).
614 If KDE_INSTALL_DIRS_NO_DEPRECATED is set to TRUE before including this
616 module, the deprecated variables (listed in the square brackets above)
617 are not defined.
618 In addition, for each KDE_INSTALL_* variable, an equivalent CMAKE_IN‐
620 STALL_* variable is defined. If KDE_INSTALL_DIRS_NO_DEPRECATED is set
621 to TRUE, only those variables defined by the GNUInstallDirs module
622 (shipped with CMake) are defined. If KDE_INSTALL_DIRS_NO_CMAKE_VARI‐
623 ABLES is set to TRUE, no variables with a CMAKE_ prefix will be defined
624 by this module (other than CMAKE_INSTALL_DEFAULT_COMPONENT_NAME - see
625 below).
626 The KDE_INSTALL_<dir> variables (or their CMAKE_INSTALL_<dir> or depre‐
628 cated counterparts) may be passed to the DESTINATION options of in‐
629 stall() commands for the corresponding file type. They are set in the
630 CMake cache, and so the defaults above can be overridden by users.
631 Note that the KDE_INSTALL_<dir>, CMAKE_INSTALL_<dir> or deprecated form
633 of the variable can be changed using CMake command line variable defi‐
634 nitions; in either case, all forms of the variable will be affected.
635 The effect of passing multiple forms of the same variable on the com‐
636 mand line (such as KDE_INSTALL_BINDIR and CMAKE_INSTALL_BINDIR is unde‐
637 fined.
638 The variable KDE_INSTALL_TARGETS_DEFAULT_ARGS is also defined (along
640 with the deprecated form INSTALL_TARGETS_DEFAULT_ARGS). This should be
641 used when libraries or user-executable applications are installed, in
642 the following manner:
643 install(TARGETS mylib myapp ${KDE_INSTALL_TARGETS_DEFAULT_ARGS})
645 It MUST NOT be used for installing plugins, system admin executables or
647 executables only intended for use internally by other code. Those
648 should use KDE_INSTALL_PLUGINDIR, KDE_INSTALL_SBINDIR or KDE_IN‐
649 STALL_LIBEXECDIR respectively.
650 Additionally, CMAKE_INSTALL_DEFAULT_COMPONENT_NAME will be set to
652 ${PROJECT_NAME} to provide a sensible default for this CMake option.
653 Note that mixing absolute and relative paths, particularly for BINDIR,
655 LIBDIR and INCLUDEDIR, can cause issues with exported targets. Given
656 that the default values for these are relative paths, relative paths
657 should be used on the command line when possible (eg: use -DKDE_IN‐
658 STALL_LIBDIR=lib64 instead of -DKDE_INSTALL_LIBDIR=/usr/lib/lib64 to
659 override the library directory).
660 Since 5.82.0, prior to that available as KDEInstallDirs.
662 NB: The variables starting KDE_INSTALL_ are available since 1.6.0, un‐
664 less otherwise noted with the variable.
665 The KDE_INSTALL_PREFIX_SCRIPT option will install a ${CMAKE_IN‐
667 STALL_PREFIX}/prefix.sh file that allows to easily incorporate the nec‐
668 essary environment variables for the prefix into a process.
669 KDEInstallDirs6
671 THIS IS CURRENTLY ONLY AN ALPHA VERSION, FOR FRAMEWORKS USAGE ONLY, AND
672 TO BE MODIFIED INCREMENTALLY. PLEASE DO NOT USE IN APPLICATIONS YET.
673 Define KDE standard installation directories for Qt6/KF6 based soft‐
675 ware.
676 Note that none of the variables defined by this module provide any in‐
678 formation about the location of already-installed KDE software.
679 Also sets CMAKE_INSTALL_PREFIX to the installation prefix of ECM, un‐
681 less that variable has been already explicitly set by something else.
682 Inclusion of this module defines the following variables:
684 KDE_INSTALL_<dir>
686 destination for files of a given type
687 KDE_INSTALL_FULL_<dir>
689 corresponding absolute path
690 where <dir> is one of (default values in parentheses):
692 BUNDLEDIR
694 application bundles (/Applications/KDE)
695 EXECROOTDIR
697 executables and libraries (<empty>)
698 BINDIR user executables (EXECROOTDIR/bin)
700 SBINDIR
702 system admin executables (EXECROOTDIR/sbin)
703 LIBDIR object code libraries (EXECROOTDIR/lib, EXECROOTDIR/lib64 or EX‐
705 ECROOTDIR/lib/<multiarch-tuple on Debian)
706 LIBEXECDIR
708 executables for internal use by programs and libraries (BINDIR
709 on Windows, LIBDIR/libexec otherwise)
710 CMAKEPACKAGEDIR
712 CMake packages, including config files (LIBDIR/cmake)
713 QTPLUGINDIR
715 Qt plugins (LIBDIR/plugins or qmake-qt5’s QT_INSTALL_PLUGINS)
716 PLUGINDIR
718 Plugins (QTPLUGINDIR) [PLUGIN_INSTALL_DIR]
719 QMLDIR QtQuick2 imports (LIBDIR/qml or qmake-qt5’s QT_INSTALL_QML)
721 INCLUDEDIR
723 C and C++ header files (include)
724 LOCALSTATEDIR
726 modifiable single-machine data (var)
727 SHAREDSTATEDIR
729 modifiable architecture-independent data (com)
730 DATAROOTDIR
732 read-only architecture-independent data root (share)
733 DATADIR
735 read-only architecture-independent data (DATAROOTDIR)
736 DOCBUNDLEDIR
738 documentation bundles generated using kdoctools (DATAROOT‐
739 DIR/doc/HTML)
740 KCFGDIR
742 kconfig description files (DATAROOTDIR/config.kcfg)
743 KCONFUPDATEDIR
745 kconf_update scripts (DATAROOTDIR/kconf_update)
746 KSERVICESDIR
748 services for KDE Frameworks 6 (DATAROOTDIR/kservices6)
749 KSERVICETYPESDIR
751 service types for KDE Frameworks 6 (DATAROOTDIR/kservicetypes6)
752 KXMLGUIDIR
754 knotify description files (DATAROOTDIR/kxmlgui6)
755 KTEMPLATESDIR
757 Kapptemplate and Kdevelop templates (kdevappwizard/templates)
758 KNOTIFYRCDIR
760 knotify description files (DATAROOTDIR/knotifications6)
761 ICONDIR
763 icons (DATAROOTDIR/icons)
764 LOCALEDIR
766 knotify description files (DATAROOTDIR/locale)
767 SOUNDDIR
769 sound files (DATAROOTDIR/sounds)
770 TEMPLATEDIR
772 templates (DATAROOTDIR/templates)
773 WALLPAPERDIR
775 desktop wallpaper images (DATAROOTDIR/wallpapers)
776 APPDIR application desktop files (DATAROOTDIR/applications)
778 DESKTOPDIR
780 desktop directories (DATAROOTDIR/desktop-directories)
781 MIMEDIR
783 mime description files (DATAROOTDIR/mime/packages)
784 METAINFODIR
786 AppStream component metadata files (DATAROOTDIR/metainfo)
787 QTQCHDIR
789 documentation bundles in QCH format for Qt-extending libraries
790 (DATAROOTDIR/doc/qch or qmake-qt5’s QT_INSTALL_DOCS)
791 QCHDIR documentation bundles in QCH format (DATAROOTDIR/doc/qch)
793 MANDIR man documentation (DATAROOTDIR/man)
795 INFODIR
797 info documentation (DATAROOTDIR/info)
798 DBUSDIR
800 D-Bus (DATAROOTDIR/dbus-1)
801 DBUSINTERFACEDIR
803 D-Bus interfaces (DBUSDIR/interfaces)
804 DBUSSERVICEDIR
806 D-Bus session services (DBUSDIR/services)
807 DBUSSYSTEMSERVICEDIR
809 D-Bus system services (DBUSDIR/system-services)
810 SYSCONFDIR
812 read-only single-machine data (etc, or /etc if CMAKE_IN‐
813 STALL_PREFIX is /usr)
814 CONFDIR
816 application configuration files (SYSCONFDIR/xdg)
817 AUTOSTARTDIR
819 autostart files (CONFDIR/autostart)
820 LOGGINGCATEGORIESDIR
822 Qt logging categories files directory (DATAROOTDIR/qlogging-cat‐
823 egories6)
824 JARDIR Java AAR/JAR files for Android.
826 SYSTEMDUNITDIR
828 Systemd Units (lib/systemd)
829 SYSTEMDUSERUNITDIR
831 Systemd User Units (lib/systemd/user)
832 If KDE_INSTALL_USE_QT_SYS_PATHS is set to TRUE before including this
834 module, the default values for some variables are instead queried from
835 Qt6’s qmake (where mentioned in the parentheses above). If not set, it
836 will default to TRUE if Qt6’s qmake is found and it’s QT_INSTALL_PREFIX
837 is the same as CMAKE_INSTALL_PREFIX, otherwise default to FALSE. This
838 variable should NOT be set from within CMakeLists.txt files, instead is
839 intended to be set manually when configuring a project which uses KDE‐
840 InstallDirs (e.g. by packagers).
841 In addition, for each KDE_INSTALL_* variable, an equivalent CMAKE_IN‐
843 STALL_* variable is defined, if such a variable is also defined by the
844 GNUInstallDirs module (shipped with CMake). If KDE_IN‐
845 STALL_DIRS_NO_CMAKE_VARIABLES is set to TRUE, no variables with a
846 CMAKE_ prefix will be defined by this module (other than CMAKE_IN‐
847 STALL_DEFAULT_COMPONENT_NAME - see below).
848 The KDE_INSTALL_<dir> variables may be passed to the DESTINATION op‐
850 tions of install() commands for the corresponding file type. They are
851 set in the CMake cache, and so the defaults above can be overridden by
852 users.
853 Note that the KDE_INSTALL_<dir> or CMAKE_INSTALL_<dir> variables can be
855 changed using CMake command line variable definitions; in either case,
856 both forms of the variable will be affected. The effect of passing mul‐
857 tiple forms of the same variable on the command line (such as KDE_IN‐
858 STALL_BINDIR and CMAKE_INSTALL_BINDIR is undefined.
859 The variable KDE_INSTALL_TARGETS_DEFAULT_ARGS is also defined. This
861 should be used when libraries or user-executable applications are in‐
862 stalled, in the following manner:
863 install(TARGETS mylib myapp ${KDE_INSTALL_TARGETS_DEFAULT_ARGS})
865 It MUST NOT be used for installing plugins, system admin executables or
867 executables only intended for use internally by other code. Those
868 should use KDE_INSTALL_PLUGINDIR, KDE_INSTALL_SBINDIR or KDE_IN‐
869 STALL_LIBEXECDIR respectively.
870 Additionally, CMAKE_INSTALL_DEFAULT_COMPONENT_NAME will be set to
872 ${PROJECT_NAME} to provide a sensible default for this CMake option.
873 Note that mixing absolute and relative paths, particularly for BINDIR,
875 LIBDIR and INCLUDEDIR, can cause issues with exported targets. Given
876 that the default values for these are relative paths, relative paths
877 should be used on the command line when possible (eg: use -DKDE_IN‐
878 STALL_LIBDIR=lib64 instead of -DKDE_INSTALL_LIBDIR=/usr/lib/lib64 to
879 override the library directory).
880 The KDE_INSTALL_PREFIX_SCRIPT option will install a ${CMAKE_IN‐
882 STALL_PREFIX}/prefix.sh file that allows to easily incorporate the nec‐
883 essary environment variables for the prefix into a process.
884 KDEMetaInfoPlatformCheck
886 By including this module there will be an automatic check between the
887 supported platforms listed in the metainfo.yaml file and the current
888 platform that is the target of the build
889 If the current platform that is the target of the build is not sup‐
891 ported a CMake FATAL_ERROR will be issued
892 The check can be ignored by setting KF_IGNORE_PLATFORM_CHECK to ON.
894 Since 5.93
896 KDETemplateGenerator
898 Packages KApptemplate/KDevelop compatible application templates
899 This module provides a functionality to package in a tarball and in‐
901 stall project templates compatible with the format used by KApptemplate
902 and KDevelop. Useful for providing minimal examples for the usage of
903 the KDE Frameworks.
904 This module provides the following function:
906 kde_package_app_templates(TEMPLATES <template> [<template> [...]]
908 INSTALL_DIR <directory>)
909 INSTALL_DIR is the directory to install the template package to. In
911 most cases you will want to use the variable KDE_INSTALL_KTEMPLATESDIR
912 from KDEInstallDirs.
913 TEMPLATES lists subdirectories containing template files; each <tem‐
915 plate> directory will be packaged into a file named <template>.tar.bz2
916 and installed to the appropriate location.
917 The template is a minimal source tree of an application as if it was an
919 application project by itself, with names (file names or text inside)
920 the text files replaced by the following placeholders when needed:
921 %{PROJECTDIRNAME}
923 name of generated project base folder ex: %{APPNAMELC} for
924 KAppTemplate
925 %{APPNAME}
927 project name as entered by user ex: MyKApp
928 %{APPNAMELC}
930 project name in lower case ex: mykapp
931 %{APPNAMEUC}
933 project name in upper case ex: MYKAPP
934 %{CPP_TEMPLATE}
936 license header for cpp file
937 %{H_TEMPLATE}
939 license header for h file
940 %{AUTHOR}
942 author name ex: George Ignacious
943 %{EMAIL}
945 author email ex: foo@bar.org
946 %{VERSION}
948 project version ex: 0.1
949 Deprecated:
951 %{dest}
953 path of generated project base folder, used in .kdevtemplate
954 with the ShowFilesAfterGeneration entry KDevelop >= 5.1.1 sup‐
955 ports relative paths with that entry, making this placeholder
956 obsolete
957 Multiple templates can be passed at once.
959 Since 5.18
961
963 ecm(7), ecm-modules(7), ecm-find-modules(7)
964
966 KDE Developers
9675.96 Jul 03, 2022 ECM-KDE-MODULES(7)