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 (deprecated)
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 All KDE_L10N_* options have been deprecated since 5.102.0, as transla‐
125 tions are meanwhile present inside the source code repositories.
126 KDEClangFormat
128 This module provides a functionality to format the source code of your
129 repository according to a predefined KDE clang-format file.
130 This module provides the following function:
132 kde_clang_format(<files>)
134 Using this function will create a clang-format target that will format
136 all <files> passed to the function with the predefined KDE clang-format
137 style. To format the files you have to invoke the target with make
138 clang-format or ninja clang-format. Once the project is formatted it
139 is recommended to enforce the formatting using a pre-commit hook, this
140 can be done using KDEGitCommitHooks.
141 The .clang-format file from ECM will be copied to the source directory.
143 This file should not be added to version control. It is recommended to
144 add it to the .gitignore file: /.clang-format.
145 Since 5.79: If the source folder already contains a .clang-format file
147 it is not overwritten. Since version 5.80 this function is called by
148 default in KDEFrameworkCompilerSettings. If directories should be ex‐
149 cluded from the formatting a .clang-format file with DisableFormat:
150 true and SortIncludes: false should be created.
151 Example usage:
153 include(KDEClangFormat)
155 file(GLOB_RECURSE ALL_CLANG_FORMAT_SOURCE_FILES *.cpp *.h *.hpp *.c)
156 kde_clang_format(${ALL_CLANG_FORMAT_SOURCE_FILES})
157 To exclude directories from the formatting add a .clang-format file in
159 the directory with the following contents:
160 DisableFormat: true
162 SortIncludes: false
163 Since 5.64
165 KDECompilerSettings
167 Set useful compile and link flags for C++ (and C) code.
168 Enables many more warnings than the default, and sets stricter modes
170 for some compiler features. By default, exceptions are disabled;
171 kde_target_enable_exceptions() can be used to re-enable them for a spe‐
172 cific target.
173 NOTE:
175 It is recommended to include this module with the NO_POLICY_SCOPE
176 flag, otherwise you may get spurious warnings with some versions of
177 CMake.
178 Since 5.85 newer settings are controlled by a variable KDE_COMPILERSET‐
180 TINGS_LEVEL, taking an ECM version as value. That version can not be
181 greater than the minimum required ECM version. The settings which are
182 default at that version will then be used, but can be overridden by
183 more fine-grained controls (see respective settings). This variable
184 needs to be set before including this module, otherwise defaults to the
185 minimum required ECM version.
186 Modern code
188 The following CMake C standard default variables are set:
189 For KDE_COMPILERSETTINGS_LEVEL >= 5.85:
191 • CMAKE_C_STANDARD: 99
193 • CMAKE_C_STANDARD_REQUIRED: TRUE
195 • CMAKE_C_EXTENSIONS: OFF
197 Otherwise:
199 • CMAKE_C_STANDARD: 90
201 • CMAKE_C_STANDARD_REQUIRED: not modified
203 • CMAKE_C_EXTENSIONS: not modified
205 If the variable CMAKE_C_STANDARD is already set when including this
207 module, none of the above variables will be modified.
208 The following CMake C++ standard default variables are set:
210 For KDE_COMPILERSETTINGS_LEVEL >= 5.85:
212 • CMAKE_CXX_STANDARD: 17
214 • CMAKE_CXX_STANDARD_REQUIRED: TRUE
216 • CMAKE_CXX_EXTENSIONS: OFF
218 Otherwise:
220 • CMAKE_CXX_STANDARD: 11
222 • CMAKE_CXX_STANDARD_REQUIRED: TRUE
224 • CMAKE_CXX_EXTENSIONS: not modified.
226 If the variable CMAKE_CXX_STANDARD is already set when including this
228 module, none of the above variables will be modified.
229 The following C++ compiler flags are set:
231 • -pedantic (GNU and Clang compilers, since 5.85)
233 Can be disabled by setting KDE_SKIP_PEDANTIC_WARNINGS_SETTINGS to
235 TRUE before including this module (default is FALSE for KDE_COMPILER‐
236 SETTINGS_LEVEL >= 5.85, TRUE otherwise).
237 • -Wmissing-include-dirs (GNU compilers, since 5.85)
239 Can be disabled by setting KDE_SKIP_MISSING_INCLUDE_DIRS_WARN‐
241 INGS_SETTINGS to TRUE before including this module (default is FALSE
242 for KDE_COMPILERSETTINGS_LEVEL >= 5.85, TRUE otherwise).
243 • -Wzero-as-null-pointer-constant (GNU and Clang compilers, since 5.85)
245 Can be disabled by setting KDE_SKIP_NULLPTR_WARNINGS_SETTINGS to TRUE
247 before including this module (default is FALSE for KDE_COMPILERSET‐
248 TINGS_LEVEL >= 5.85, TRUE otherwise).
249 • -Werror=undef (GNU and Clang compilers, since 5.96.0)
251 • Qt related preprocessor definitions (since 5.85.0):
253 • -DQT_NO_CAST_TO_ASCII
255 • -DQT_NO_CAST_FROM_ASCII
257 • -DQT_NO_URL_CAST_FROM_STRING
259 • -DQT_NO_CAST_FROM_BYTEARRAY
261 • -DQT_USE_QSTRINGBUILDER
263 • -DQT_NO_NARROWING_CONVERSIONS_IN_CONNECT
265 • -DQT_NO_KEYWORDS
267 • -DQT_NO_FOREACH
269 • -DQT_STRICT_ITERATORS
271 Strict iterators are not enabled on Windows, because they lead to a
273 link error when application code iterates over a QVector<QPoint>
274 for instance, unless Qt itself was also built with strict itera‐
275 tors. See example at https://bugreports.qt.io/browse/AUTOSUITE-946
276 Can be controlled by setting KDE_QT_MODERNCODE_DEFINITIONS_LEVEL to
278 the version of ECM where the wanted set of definitions has been added
279 before including this module (default is KDE_COMPILERSETTINGS_LEVEL).
280 To disable individual definitions instead use remove_definitions()
281 directly after including this module.
282 Functions
284 This module provides the following functions:
285 kde_source_files_enable_exceptions([file1 [file2 [...]]])
287 Enables exceptions for specific source files. This should not be used
289 on source files in a language other than C++.
290 kde_target_enable_exceptions(target <INTERFACE|PUBLIC|PRIVATE>)
292 Enables exceptions for a specific target. This should not be used on a
294 target that has source files in a language other than C++.
295 kde_enable_exceptions()
297 Enables exceptions for C++ source files compiled for the CMakeLists.txt
299 file in the current directory and all subdirectories.
300 Variables
302 Inclusion of this module defines the following variables:
303 ENABLE_BSYMBOLICFUNCTIONS
305 indicates whether we make use of -Bsymbolic-functions for link‐
306 ing. It ensures libraries bind global function references lo‐
307 cally rather than at runtime. This option only has an effect on
308 ELF-based systems.
309 The option is disabled by default except when using
311 KDEFrameworkCompilerSettings where it’s enabled. Projects can
312 enable it by calling set(ENABLE_BSYMBOLICFUNCTIONS ON) or pass‐
313 ing -DENABLE BSYMBOLICFUNCTIONS=ON when configuring the build
314 directory.
315 Since 5.85
317 Example usages:
319 # needing some macro/feature only available with ECM 5.80.0
321 find_package(ECM 5.80.0 NO_MODULE)
322 # requiring ECM 5.80.0 above will default KDE_COMPILERSETTINGS_LEVEL also to 5.80.0,
324 # thus not activate any newer settings
325 include(KDECompilerSettings NO_POLICY_SCOPE)
326 # needing some macro/feature only available with ECM 5.87.0
328 find_package(ECM 5.87.0 NO_MODULE)
329 # project uses settings default as of KDECompilerSettings in ECM 5.85.0
331 set(KDE_COMPILERSETTINGS_LEVEL 5.85.0)
332 include(KDECompilerSettings NO_POLICY_SCOPE)
333 # needing some macro/feature only available with ECM 5.87.0
335 find_package(ECM 5.87.0 NO_MODULE)
336 # project mainly uses settings default as of KDECompilerSettings in ECM 5.85.0
338 # with some small twisting
339 set(KDE_COMPILERSETTINGS_LEVEL 5.85.0)
340 # not ready yet for pedantic compilers
341 set(KDE_SKIP_PEDANTIC_WARNINGS_SETTINGS TRUE)
342 # avoid any Qt definitions
343 set(KDE_QT_MODERNCODE_DEFINITIONS_LEVEL 5.84.0)
344 include(KDECompilerSettings NO_POLICY_SCOPE)
345 # needing some macro/feature only available with ECM 5.85.0
347 find_package(ECM 5.85.0 NO_MODULE)
348 # requiring ECM 5.85.0 above will default KDE_COMPILERSETTINGS_LEVEL also to 5.85.0,
350 # which again defaults KDE_QT_MODERNCODE_DEFINITIONS_LEVEL also to 5.85.0
351 include(KDECompilerSettings NO_POLICY_SCOPE)
352 # project is fine with almost all added Qt definitions as of 5.85.0, but not these ones:
353 remove_definitions(
354 -DQT_NO_KEYWORDS
355 -DQT_NO_FOREACH
356 )
357 Since pre-1.0.0.
359 KDEFrameworkCompilerSettings
361 Set stricter compile and link flags for KDE Frameworks modules.
362 WARNING:
364 Do not use this module for software which is not part of KDE-Frame‐
365 works. There is no guarantee for backward-compatibility in newer
366 versions.
367 The KDECompilerSettings module is included and, in addition, various
369 defines that affect the Qt libraries are set to enforce certain conven‐
370 tions.
371 For example, constructions like QString("foo") are prohibited, instead
373 forcing the use of QLatin1String or QStringLiteral, and some Qt-defined
374 keywords like signals and slots will not be defined.
375 NOTE:
377 It is recommended to include this module with the NO_POLICY_SCOPE
378 flag, otherwise you may get spurious warnings with some versions of
379 CMake.
380 Since pre-1.0.0.
382 KDEGitCommitHooks
384 This module provides a functionality to enforce formatting or in the
385 future other QS checks.
386 This module provides the following function:
388 kde_configure_pre_commit_hook(
390 CHECKS <check1> [<check2> [...]]
391 )
392 This function will create a pre-commit hook which contains all the
394 given checks.
395 Checks:
397 • CLANG_FORMAT With this check enabled the git clang-format tool will
399 be used to make sure that the changed parts are properly formatted.
400 In case the changes are not properly formatted an error message with
401 the command to preview the formatting changes and to format the files
402 in place will be displayed. This tool will reuse the exsting
403 .clang-format file, in case you want to use the one provided by ECM
404 you can include include(KDEClangFormat) which will copy the file to
405 the source dir. It is also recommended to reformat the entire project
406 before enforcing the formatting using this commit hook.
407 Example usage:
409 include(KDEGitCommitHooks)
411 kde_configure_git_pre_commit_hook(CHECKS CLANG_FORMAT)
412 Since 5.79
414 KDEInstallDirs
416 Compatibility wrapper around KDEInstallDirs5.
417 Since 5.82.0, prior to that equivalent to KDEInstallDirs5.
419 KDEInstallDirs5
421 Define KDE standard installation directories for Qt5/KF5 based soft‐
422 ware.
423 Note that none of the variables defined by this module provide any in‐
425 formation about the location of already-installed KDE software.
426 Also sets CMAKE_INSTALL_PREFIX to the installation prefix of ECM, un‐
428 less that variable has been already explicitly set by something else
429 (since 5.61 and with CMake >= 3.7).
430 Inclusion of this module defines the following variables:
432 KDE_INSTALL_<dir>
434 destination for files of a given type
435 KDE_INSTALL_FULL_<dir>
437 corresponding absolute path
438 where <dir> is one of (default values in parentheses and alternative,
440 deprecated variable name in square brackets):
441 BUNDLEDIR
443 application bundles (/Applications/KDE) [BUNDLE_INSTALL_DIR]
444 EXECROOTDIR
446 executables and libraries (<empty>) [EXEC_INSTALL_PREFIX]
447 BINDIR user executables (EXECROOTDIR/bin) [BIN_INSTALL_DIR]
449 SBINDIR
451 system admin executables (EXECROOTDIR/sbin) [SBIN_INSTALL_DIR]
452 LIBDIR object code libraries (EXECROOTDIR/lib, EXECROOTDIR/lib64 or EX‐
454 ECROOTDIR/lib/<multiarch-tuple on Debian) [LIB_INSTALL_DIR]
455 LIBEXECDIR
457 executables for internal use by programs and libraries (BINDIR
458 on Windows, LIBDIR/libexec otherwise) [LIBEXEC_INSTALL_DIR]
459 CMAKEPACKAGEDIR
461 CMake packages, including config files (LIBDIR/cmake) [CMAKECON‐
462 FIG_INSTALL_PREFIX]
463 QTPLUGINDIR
465 Qt plugins (LIBDIR/plugins or qmake-qt5’s QT_INSTALL_PLUGINS)
466 [QT_PLUGIN_INSTALL_DIR]
467 PLUGINDIR
469 Plugins (QTPLUGINDIR) [PLUGIN_INSTALL_DIR]
470 QTQUICKIMPORTSDIR
472 QtQuick1 imports (QTPLUGINDIR/imports or qmake-qt5’s QT_IN‐
473 STALL_IMPORTS) [IMPORTS_INSTALL_DIR]
474 QMLDIR QtQuick2 imports (LIBDIR/qml or qmake-qt5’s QT_INSTALL_QML)
476 [QML_INSTALL_DIR]
477 INCLUDEDIR
479 C and C++ header files (include) [INCLUDE_INSTALL_DIR]
480 LOCALSTATEDIR
482 modifiable single-machine data (var)
483 SHAREDSTATEDIR
485 modifiable architecture-independent data (com)
486 DATAROOTDIR
488 read-only architecture-independent data root (share) [SHARE_IN‐
489 STALL_PREFIX]
490 DATADIR
492 read-only architecture-independent data (DATAROOTDIR) [DATA_IN‐
493 STALL_DIR]
494 DOCBUNDLEDIR
496 documentation bundles generated using kdoctools (DATAROOT‐
497 DIR/doc/HTML) [HTML_INSTALL_DIR]
498 KCFGDIR
500 kconfig description files (DATAROOTDIR/config.kcfg) [KCFG_IN‐
501 STALL_DIR]
502 KCONFUPDATEDIR
504 kconf_update scripts (DATAROOTDIR/kconf_update) [KCONF_UP‐
505 DATE_INSTALL_DIR]
506 KSERVICES5DIR or (since 5.89) KSERVICESDIR
508 services for KDE Frameworks 5 (DATAROOTDIR/kservices5) [SER‐
509 VICES_INSTALL_DIR]
510 KSERVICETYPES5DIR or (since 5.89) KSERVICETYPESDIR
512 service types for KDE Frameworks 5 (DATAROOTDIR/kservicetypes5)
513 [SERVICETYPES_INSTALL_DIR]
514 KXMLGUI5DIR or (since 5.89) KXMLGUIDIR
516 knotify description files (DATAROOTDIR/kxmlgui5) [KXMLGUI_IN‐
517 STALL_DIR]
518 KAPPTEMPLATESDIR
520 KAppTemplate and KDevelop templates (DATAROOTDIR/kdevappwiz‐
521 ard/templates) [KDE_INSTALL_KTEMPLATESDIR] Since 5.77.
522 KFILETEMPLATESDIR
524 KDevelop file templates (DATAROOTDIR/kdevfiletemplates/tem‐
525 plates) Since 5.77.
526 KNOTIFY5RCDIR or (since 5.89) KNOTIFYRCDIR
528 knotify description files (DATAROOTDIR/knotifications5) [KNOTI‐
529 FYRC_INSTALL_DIR]
530 ICONDIR
532 icons (DATAROOTDIR/icons) [ICON_INSTALL_DIR]
533 LOCALEDIR
535 knotify description files (DATAROOTDIR/locale) [LOCALE_IN‐
536 STALL_DIR]
537 SOUNDDIR
539 sound files (DATAROOTDIR/sounds) [SOUND_INSTALL_DIR]
540 TEMPLATEDIR
542 templates (DATAROOTDIR/templates) [TEMPLATES_INSTALL_DIR]
543 WALLPAPERDIR
545 desktop wallpaper images (DATAROOTDIR/wallpapers) [WALLPAPER_IN‐
546 STALL_DIR]
547 APPDIR application desktop files (DATAROOTDIR/applications) Since
549 1.1.0. [XDG_APPS_INSTALL_DIR]
550 DESKTOPDIR
552 desktop directories (DATAROOTDIR/desktop-directories) [XDG_DI‐
553 RECTORY_INSTALL_DIR]
554 MIMEDIR
556 mime description files (DATAROOTDIR/mime/packages) [XDG_MIME_IN‐
557 STALL_DIR]
558 METAINFODIR
560 AppStream component metadata files (DATAROOTDIR/metainfo)
561 QTQCHDIR
563 documentation bundles in QCH format for Qt-extending libraries
564 (DATAROOTDIR/doc/qch or qmake-qt5’s QT_INSTALL_DOCS) Since
565 5.36.0.
566 QCHDIR documentation bundles in QCH format (DATAROOTDIR/doc/qch) Since
568 5.36.0.
569 MANDIR man documentation (DATAROOTDIR/man) [MAN_INSTALL_DIR]
571 INFODIR
573 info documentation (DATAROOTDIR/info)
574 DBUSDIR
576 D-Bus (DATAROOTDIR/dbus-1)
577 DBUSINTERFACEDIR
579 D-Bus interfaces (DBUSDIR/interfaces) [DBUS_INTERFACES_IN‐
580 STALL_DIR]
581 DBUSSERVICEDIR
583 D-Bus session services (DBUSDIR/services) [DBUS_SERVICES_IN‐
584 STALL_DIR]
585 DBUSSYSTEMSERVICEDIR
587 D-Bus system services (DBUSDIR/system-services) [DBUS_SYS‐
588 TEM_SERVICES_INSTALL_DIR]
589 SYSCONFDIR
591 read-only single-machine data (etc, or /etc if CMAKE_IN‐
592 STALL_PREFIX is /usr) [SYSCONF_INSTALL_DIR]
593 CONFDIR
595 application configuration files (SYSCONFDIR/xdg) [CONFIG_IN‐
596 STALL_DIR]
597 AUTOSTARTDIR
599 autostart files (CONFDIR/autostart) [AUTOSTART_INSTALL_DIR]
600 LOGGINGCATEGORIESDIR
602 Qt logging categories files directory (DATAROOTDIR/qlogging-cat‐
603 egories5) Since 5.59.0
604 JARDIR Java AAR/JAR files for Android. Since 5.62.0
606 SYSTEMDUNITDIR
608 Systemd Units (lib/systemd) [SYSTEMD_UNIT_INSTALL_DIR]. Since
609 5.65
610 SYSTEMDUSERUNITDIR
612 Systemd User Units (lib/systemd/user) [SYSTEMD_USER_UNIT_IN‐
613 STALL_DIR]. Since 5.65
614 ZSHAUTOCOMPLETEDIR
616 Zsh functions and autocompletion definitions (zsh/site-func‐
617 tions) Since 5.101
618 If KDE_INSTALL_USE_QT_SYS_PATHS is set to TRUE before including this
620 module, the default values for some variables are instead queried from
621 Qt5’s qmake (where mentioned in the parentheses above). If not set, it
622 will default to TRUE if Qt5’s qmake is found and it’s QT_INSTALL_PREFIX
623 is the same as CMAKE_INSTALL_PREFIX, otherwise default to FALSE. This
624 variable should NOT be set from within CMakeLists.txt files, instead is
625 intended to be set manually when configuring a project which uses KDE‐
626 InstallDirs (e.g. by packagers).
627 If KDE_INSTALL_DIRS_NO_DEPRECATED is set to TRUE before including this
629 module, the deprecated variables (listed in the square brackets above)
630 are not defined.
631 In addition, for each KDE_INSTALL_* variable, an equivalent CMAKE_IN‐
633 STALL_* variable is defined. If KDE_INSTALL_DIRS_NO_DEPRECATED is set
634 to TRUE, only those variables defined by the GNUInstallDirs module
635 (shipped with CMake) are defined. If KDE_INSTALL_DIRS_NO_CMAKE_VARI‐
636 ABLES is set to TRUE, no variables with a CMAKE_ prefix will be defined
637 by this module (other than CMAKE_INSTALL_DEFAULT_COMPONENT_NAME - see
638 below).
639 The KDE_INSTALL_<dir> variables (or their CMAKE_INSTALL_<dir> or depre‐
641 cated counterparts) may be passed to the DESTINATION options of in‐
642 stall() commands for the corresponding file type. They are set in the
643 CMake cache, and so the defaults above can be overridden by users.
644 Note that the KDE_INSTALL_<dir>, CMAKE_INSTALL_<dir> or deprecated form
646 of the variable can be changed using CMake command line variable defi‐
647 nitions; in either case, all forms of the variable will be affected.
648 The effect of passing multiple forms of the same variable on the com‐
649 mand line (such as KDE_INSTALL_BINDIR and CMAKE_INSTALL_BINDIR is unde‐
650 fined.
651 The variable KDE_INSTALL_TARGETS_DEFAULT_ARGS is also defined (along
653 with the deprecated form INSTALL_TARGETS_DEFAULT_ARGS). This should be
654 used when libraries or user-executable applications are installed, in
655 the following manner:
656 install(TARGETS mylib myapp ${KDE_INSTALL_TARGETS_DEFAULT_ARGS})
658 It MUST NOT be used for installing plugins, system admin executables or
660 executables only intended for use internally by other code. Those
661 should use KDE_INSTALL_PLUGINDIR, KDE_INSTALL_SBINDIR or KDE_IN‐
662 STALL_LIBEXECDIR respectively.
663 Additionally, CMAKE_INSTALL_DEFAULT_COMPONENT_NAME will be set to
665 ${PROJECT_NAME} to provide a sensible default for this CMake option.
666 Note that mixing absolute and relative paths, particularly for BINDIR,
668 LIBDIR and INCLUDEDIR, can cause issues with exported targets. Given
669 that the default values for these are relative paths, relative paths
670 should be used on the command line when possible (eg: use -DKDE_IN‐
671 STALL_LIBDIR=lib64 instead of -DKDE_INSTALL_LIBDIR=/usr/lib/lib64 to
672 override the library directory).
673 Since 5.82.0, prior to that available as KDEInstallDirs.
675 NB: The variables starting KDE_INSTALL_ are available since 1.6.0, un‐
677 less otherwise noted with the variable.
678 The KDE_INSTALL_PREFIX_SCRIPT option will install a ${CMAKE_IN‐
680 STALL_PREFIX}/prefix.sh file that allows to easily incorporate the nec‐
681 essary environment variables for the prefix into a process.
682 KDEInstallDirs6
684 THIS IS CURRENTLY ONLY AN ALPHA VERSION, FOR FRAMEWORKS USAGE ONLY, AND
685 TO BE MODIFIED INCREMENTALLY. PLEASE DO NOT USE IN APPLICATIONS YET.
686 Define KDE standard installation directories for Qt6/KF6 based soft‐
688 ware.
689 Note that none of the variables defined by this module provide any in‐
691 formation about the location of already-installed KDE software.
692 Also sets CMAKE_INSTALL_PREFIX to the installation prefix of ECM, un‐
694 less that variable has been already explicitly set by something else.
695 Inclusion of this module defines the following variables:
697 KDE_INSTALL_<dir>
699 destination for files of a given type
700 KDE_INSTALL_FULL_<dir>
702 corresponding absolute path
703 where <dir> is one of (default values in parentheses):
705 BUNDLEDIR
707 application bundles (/Applications/KDE)
708 EXECROOTDIR
710 executables and libraries (<empty>)
711 BINDIR user executables (EXECROOTDIR/bin)
713 SBINDIR
715 system admin executables (EXECROOTDIR/sbin)
716 LIBDIR object code libraries (EXECROOTDIR/lib, EXECROOTDIR/lib64 or EX‐
718 ECROOTDIR/lib/<multiarch-tuple on Debian)
719 LIBEXECDIR
721 executables for internal use by programs and libraries (BINDIR
722 on Windows, LIBDIR/libexec otherwise)
723 CMAKEPACKAGEDIR
725 CMake packages, including config files (LIBDIR/cmake)
726 QTPLUGINDIR
728 Qt plugins (LIBDIR/plugins or qmake-qt5’s QT_INSTALL_PLUGINS)
729 PLUGINDIR
731 Plugins (QTPLUGINDIR) [PLUGIN_INSTALL_DIR]
732 QMLDIR QtQuick2 imports (LIBDIR/qml or qmake-qt5’s QT_INSTALL_QML)
734 INCLUDEDIR
736 C and C++ header files (include)
737 LOCALSTATEDIR
739 modifiable single-machine data (var)
740 SHAREDSTATEDIR
742 modifiable architecture-independent data (com)
743 DATAROOTDIR
745 read-only architecture-independent data root (share)
746 DATADIR
748 read-only architecture-independent data (DATAROOTDIR)
749 DOCBUNDLEDIR
751 documentation bundles generated using kdoctools (DATAROOT‐
752 DIR/doc/HTML)
753 KCFGDIR
755 kconfig description files (DATAROOTDIR/config.kcfg)
756 KCONFUPDATEDIR
758 kconf_update scripts (DATAROOTDIR/kconf_update)
759 KSERVICESDIR
761 services for KDE Frameworks 6 (DATAROOTDIR/kservices6)
762 KSERVICETYPESDIR
764 service types for KDE Frameworks 6 (DATAROOTDIR/kservicetypes6)
765 KXMLGUIDIR
767 knotify description files (DATAROOTDIR/kxmlgui6)
768 KAPPTEMPLATESDIR
770 KAppTemplate and KDevelop templates (DATAROOTDIR/kdevappwiz‐
771 ard/templates)
772 KFILETEMPLATESDIR
774 KDevelop file templates (DATAROOTDIR/kdevfiletemplates/tem‐
775 plates)
776 KNOTIFYRCDIR
778 knotify description files (DATAROOTDIR/knotifications6)
779 ICONDIR
781 icons (DATAROOTDIR/icons)
782 LOCALEDIR
784 knotify description files (DATAROOTDIR/locale)
785 SOUNDDIR
787 sound files (DATAROOTDIR/sounds)
788 TEMPLATEDIR
790 templates (DATAROOTDIR/templates)
791 WALLPAPERDIR
793 desktop wallpaper images (DATAROOTDIR/wallpapers)
794 APPDIR application desktop files (DATAROOTDIR/applications)
796 DESKTOPDIR
798 desktop directories (DATAROOTDIR/desktop-directories)
799 MIMEDIR
801 mime description files (DATAROOTDIR/mime/packages)
802 METAINFODIR
804 AppStream component metadata files (DATAROOTDIR/metainfo)
805 QTQCHDIR
807 documentation bundles in QCH format for Qt-extending libraries
808 (DATAROOTDIR/doc/qch or qmake-qt5’s QT_INSTALL_DOCS)
809 QCHDIR documentation bundles in QCH format (DATAROOTDIR/doc/qch)
811 MANDIR man documentation (DATAROOTDIR/man)
813 INFODIR
815 info documentation (DATAROOTDIR/info)
816 DBUSDIR
818 D-Bus (DATAROOTDIR/dbus-1)
819 DBUSINTERFACEDIR
821 D-Bus interfaces (DBUSDIR/interfaces)
822 DBUSSERVICEDIR
824 D-Bus session services (DBUSDIR/services)
825 DBUSSYSTEMSERVICEDIR
827 D-Bus system services (DBUSDIR/system-services)
828 SYSCONFDIR
830 read-only single-machine data (etc, or /etc if CMAKE_IN‐
831 STALL_PREFIX is /usr)
832 CONFDIR
834 application configuration files (SYSCONFDIR/xdg)
835 AUTOSTARTDIR
837 autostart files (CONFDIR/autostart)
838 LOGGINGCATEGORIESDIR
840 Qt logging categories files directory (DATAROOTDIR/qlogging-cat‐
841 egories6)
842 JARDIR Java AAR/JAR files for Android.
844 SYSTEMDUNITDIR
846 Systemd Units (lib/systemd)
847 SYSTEMDUSERUNITDIR
849 Systemd User Units (lib/systemd/user)
850 If KDE_INSTALL_USE_QT_SYS_PATHS is set to TRUE before including this
852 module, the default values for some variables are instead queried from
853 Qt6’s qmake (where mentioned in the parentheses above). If not set, it
854 will default to TRUE if Qt6’s qmake is found and it’s QT_INSTALL_PREFIX
855 is the same as CMAKE_INSTALL_PREFIX, otherwise default to FALSE. This
856 variable should NOT be set from within CMakeLists.txt files, instead is
857 intended to be set manually when configuring a project which uses KDE‐
858 InstallDirs (e.g. by packagers).
859 In addition, for each KDE_INSTALL_* variable, an equivalent CMAKE_IN‐
861 STALL_* variable is defined, if such a variable is also defined by the
862 GNUInstallDirs module (shipped with CMake). If KDE_IN‐
863 STALL_DIRS_NO_CMAKE_VARIABLES is set to TRUE, no variables with a
864 CMAKE_ prefix will be defined by this module (other than CMAKE_IN‐
865 STALL_DEFAULT_COMPONENT_NAME - see below).
866 The KDE_INSTALL_<dir> variables may be passed to the DESTINATION op‐
868 tions of install() commands for the corresponding file type. They are
869 set in the CMake cache, and so the defaults above can be overridden by
870 users.
871 Note that the KDE_INSTALL_<dir> or CMAKE_INSTALL_<dir> variables can be
873 changed using CMake command line variable definitions; in either case,
874 both forms of the variable will be affected. The effect of passing mul‐
875 tiple forms of the same variable on the command line (such as KDE_IN‐
876 STALL_BINDIR and CMAKE_INSTALL_BINDIR is undefined.
877 The variable KDE_INSTALL_TARGETS_DEFAULT_ARGS is also defined. This
879 should be used when libraries or user-executable applications are in‐
880 stalled, in the following manner:
881 install(TARGETS mylib myapp ${KDE_INSTALL_TARGETS_DEFAULT_ARGS})
883 It MUST NOT be used for installing plugins, system admin executables or
885 executables only intended for use internally by other code. Those
886 should use KDE_INSTALL_PLUGINDIR, KDE_INSTALL_SBINDIR or KDE_IN‐
887 STALL_LIBEXECDIR respectively.
888 Additionally, CMAKE_INSTALL_DEFAULT_COMPONENT_NAME will be set to
890 ${PROJECT_NAME} to provide a sensible default for this CMake option.
891 Note that mixing absolute and relative paths, particularly for BINDIR,
893 LIBDIR and INCLUDEDIR, can cause issues with exported targets. Given
894 that the default values for these are relative paths, relative paths
895 should be used on the command line when possible (eg: use -DKDE_IN‐
896 STALL_LIBDIR=lib64 instead of -DKDE_INSTALL_LIBDIR=/usr/lib/lib64 to
897 override the library directory).
898 The KDE_INSTALL_PREFIX_SCRIPT option will install a ${CMAKE_IN‐
900 STALL_PREFIX}/prefix.sh file that allows to easily incorporate the nec‐
901 essary environment variables for the prefix into a process.
902 KDEMetaInfoPlatformCheck
904 By including this module there will be an automatic check between the
905 supported platforms listed in the metainfo.yaml file and the current
906 platform that is the target of the build
907 If the current platform that is the target of the build is not sup‐
909 ported a CMake FATAL_ERROR will be issued
910 The check can be ignored by setting KF_IGNORE_PLATFORM_CHECK to ON.
912 Since 5.93
914 KDETemplateGenerator
916 Packages KApptemplate/KDevelop compatible application templates
917 This module provides a functionality to package in a tarball and in‐
919 stall project templates compatible with the format used by KApptemplate
920 and KDevelop. Useful for providing minimal examples for the usage of
921 the KDE Frameworks.
922 This module provides the following function:
924 kde_package_app_templates(TEMPLATES <template> [<template> [...]]
926 INSTALL_DIR <directory>)
927 INSTALL_DIR is the directory to install the template package to. In
929 most cases you will want to use the variable KDE_INSTALL_KAPPTEMPLATES‐
930 DIR from KDEInstallDirs.
931 TEMPLATES lists subdirectories containing template files; each <tem‐
933 plate> directory will be packaged into a file named <template>.tar.bz2
934 and installed to the appropriate location.
935 The template is a minimal source tree of an application as if it was an
937 application project by itself, with names (file names or text inside)
938 the text files replaced by the following placeholders when needed:
939 %{PROJECTDIRNAME}
941 name of generated project base folder ex: %{APPNAMELC} for
942 KAppTemplate
943 %{APPNAME}
945 project name as entered by user ex: MyKApp
946 %{APPNAMELC}
948 project name in lower case ex: mykapp
949 %{APPNAMEUC}
951 project name in upper case ex: MYKAPP
952 %{CPP_TEMPLATE}
954 license header for cpp file
955 %{H_TEMPLATE}
957 license header for h file
958 %{AUTHOR}
960 author name ex: George Ignacious
961 %{EMAIL}
963 author email ex: foo@bar.org
964 %{VERSION}
966 project version ex: 0.1
967 Deprecated:
969 %{dest}
971 path of generated project base folder, used in .kdevtemplate
972 with the ShowFilesAfterGeneration entry KDevelop >= 5.1.1 sup‐
973 ports relative paths with that entry, making this placeholder
974 obsolete
975 Multiple templates can be passed at once.
977 Since 5.18
979
981 ecm(7), ecm-modules(7), ecm-find-modules(7)
982
984 KDE Developers
9855.102 Jan 14, 2023 ECM-KDE-MODULES(7)