1ECM-KDE-MODULES(7) Extra CMake Modules ECM-KDE-MODULES(7)
2
3
4
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
16 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
20 find_package(ECM REQUIRED NO_MODULE)
21 set(CMAKE_MODULE_PATH ${ECM_MODULE_DIR})
22
23 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
31 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
34 It is split into three parts, which can be independently disabled if
35 desired.
36
37 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
43 Note that LIB_INSTALL_DIR or alternatively KDE_INSTALL_LIBDIR needs to
44 be set before including this module. Typically, this is done by in‐
45 cluding the KDEInstallDirs module.
46
47 This section can be disabled by setting KDE_SKIP_RPATH_SETTINGS to TRUE
48 before including this module.
49
50 Testing
51 Testing is enabled by default, and an option (BUILD_TESTING) is pro‐
52 vided for users to control this. See the CTest module documentation in
53 the CMake manual for more details.
54
55 This section can be disabled by setting KDE_SKIP_TEST_SETTINGS to TRUE
56 before including this module.
57
58 Build Settings
59 Various CMake build defaults are altered, such as searching source and
60 build directories for includes first, enabling automoc by default.
61
62 When find_package(ECM 5.38) or higher is called, this also selects a
63 layout for the build dir that helps running executables without in‐
64 stalling: all executables are built into a toplevel “bin” dir, making
65 it possible to find helper binaries, and to find uninstalled plugins
66 (provided that you use kcoreaddons_add_plugin or set LIBRARY_OUTPUT_DI‐
67 RECTORY as documented on
68 https://community.kde.org/Guidelines_and_HOWTOs/Making_apps_run_uninstalled).
69
70 This section can be disabled by setting KDE_SKIP_BUILD_SETTINGS to TRUE
71 before including this module.
72
73 This section also provides an “uninstall” target that can be individu‐
74 ally disabled by setting KDE_SKIP_UNINSTALL_TARGET to TRUE before in‐
75 cluding this module.
76
77 By default on OS X, X11 and XCB related detections are disabled. How‐
78 ever if the need would arise to use these technologies, the detection
79 can be enabled by setting APPLE_FORCE_X11 to ON.
80
81 A warning is printed for the developer to know that the detection is
82 disabled on OS X. This message can be turned off by setting APPLE_SUP‐
83 PRESS_X11_WARNING to ON.
84
85 Since pre-1.0.0.
86
87 ENABLE_CLAZY option is added (OFF by default) when clang is being used.
88 Turning this option on will force clang to load the clazy plugins for
89 richer warnings on Qt-related code.
90
91 If clang is not being used, this won’t have an effect. See
92 https://commits.kde.org/clazy?path=README.md
93
94 Since 5.17.0
95
96 • Uninstall target functionality since 1.7.0.
97
98 • APPLE_FORCE_X11 option since 5.14.0 (detecting X11 was previously the
99 default behavior)
100
101 • APPLE_SUPPRESS_X11_WARNING option since 5.14.0
102
103 • CMAKE_AUTORCC enabled by default when supported by cmake (>= 3.0)
104 since 5.62.0
105
106 Translations
107 A fetch-translations target will be set up that will download transla‐
108 tions for projects using l10n.kde.org.
109
110 KDE_L10N_BRANCH will be responsible for choosing which l10n branch to
111 use for the translations.
112
113 KDE_L10N_AUTO_TRANSLATIONS (OFF by default) will indicate whether
114 translations should be downloaded when building the project.
115
116 Since 5.34.0
117
118 KDE_L10N_SYNC_TRANSLATIONS (OFF by default) will download the transla‐
119 tions at configuration time instead of build time.
120
121 Since 5.50.0
122
123 KDEClangFormat
124 This module provides a functionality to format the source code of your
125 repository according to a predefined KDE clang-format file.
126
127 This module provides the following function:
128
129 kde_clang_format(<files>)
130
131 Using this function will create a clang-format target that will format
132 all <files> passed to the function with the predefined KDE clang-format
133 style. To format the files you have to invoke the target with make
134 clang-format or ninja clang-format. Once the project is formatted it
135 is recommended to enforce the formatting using a pre-commit hook, this
136 can be done using KDEGitCommitHooks.
137
138 The .clang-format file from ECM will be copied to the source directory.
139 This file should not be added to version control. It is recommended to
140 add it to the .gitignore file: /.clang-format.
141
142 Since 5.79: If the source folder already contains a .clang-format file
143 it is not overwritten. Since version 5.80 this function is called by
144 default in KDEFrameworkCompilerSettings. If directories should be ex‐
145 cluded from the formatting a .clang-format file with “DisableFormat:
146 true” and “SortIncludes: false” should be created.
147
148 Example usage:
149
150 include(KDEClangFormat)
151 file(GLOB_RECURSE ALL_CLANG_FORMAT_SOURCE_FILES *.cpp *.h)
152 kde_clang_format(${ALL_CLANG_FORMAT_SOURCE_FILES})
153
154 To exclude directories from the formatting add a .clang-format file in
155 the directory with the following contents:
156
157 DisableFormat: true
158 SortIncludes: false
159
160 Since 5.64
161
162 KDECompilerSettings
163 Set useful compile and link flags for C++ (and C) code.
164
165 Enables many more warnings than the default, and sets stricter modes
166 for some compiler features. By default, exceptions are disabled;
167 kde_target_enable_exceptions() can be used to re-enable them for a spe‐
168 cific target.
169
170 NB: it is recommended to include this module with the NO_POLICY_SCOPE
171 flag, otherwise you may get spurious warnings with some versions of
172 CMake.
173
174 This module provides the following functions:
175
176 kde_source_files_enable_exceptions([file1 [file2 [...]]])
177
178 Enables exceptions for specific source files. This should not be used
179 on source files in a language other than C++.
180
181 kde_target_enable_exceptions(target <INTERFACE|PUBLIC|PRIVATE>)
182
183 Enables exceptions for a specific target. This should not be used on a
184 target that has source files in a language other than C++.
185
186 kde_enable_exceptions()
187
188 Enables exceptions for C++ source files compiled for the CMakeLists.txt
189 file in the current directory and all subdirectories.
190
191 Since pre-1.0.0.
192
193 KDEFrameworkCompilerSettings
194 Set stricter compile and link flags for KDE Frameworks modules.
195
196 The KDECompilerSettings module is included and, in addition, various
197 defines that affect the Qt libraries are set to enforce certain conven‐
198 tions.
199
200 For example, constructions like QString(“foo”) are prohibited, instead
201 forcing the use of QLatin1String or QStringLiteral, and some Qt-defined
202 keywords like signals and slots will not be defined.
203
204 NB: it is recommended to include this module with the NO_POLICY_SCOPE
205 flag, otherwise you may get spurious warnings with some versions of
206 CMake.
207
208 Since pre-1.0.0.
209
210 KDEGitCommitHooks
211 This module provides a functionality to enforce formatting or in the
212 future other QS checks.
213
214 This module provides the following function:
215
216 kde_configure_pre_commit_hook(
217 CHECKS <check1> [<check2> [...]]
218 )
219
220 This function will create a pre-commit hook which contains all the
221 given checks.
222
223 Checks:
224
225 • CLANG_FORMAT With this check enabled the git clang-format tool will
226 be used to make sure that the changed parts are properly formatted.
227 In case the changes are not properly formatted an error message with
228 the command to preview the formatting changes and to format the files
229 in place will be displayed. This tool will reuse the exsting
230 .clang-format file, in case you want to use the one provided by ECM
231 you can include include(KDEClangFormat) which will copy the file to
232 the source dir. It is also recommended to reformat the entire project
233 before enforcing the formatting using this commit hook.
234
235 Example usage:
236
237 include(KDEGitCommitHooks)
238 kde_configure_git_pre_commit_hook(CHECKS CLANG_FORMAT)
239
240 Since 5.79
241
242 KDEInstallDirs
243 Define KDE standard installation directories.
244
245 Note that none of the variables defined by this module provide any in‐
246 formation about the location of already-installed KDE software.
247
248 Also sets CMAKE_INSTALL_PREFIX to the installation prefix of ECM, un‐
249 less that variable has been already explicitly set by something else
250 (since 5.61 and with CMake >= 3.7).
251
252 Inclusion of this module defines the following variables:
253
254 KDE_INSTALL_<dir>
255 destination for files of a given type
256
257 KDE_INSTALL_FULL_<dir>
258 corresponding absolute path
259
260 where <dir> is one of (default values in parentheses and alternative,
261 deprecated variable name in square brackets):
262
263 BUNDLEDIR
264 application bundles (/Applications/KDE) [BUNDLE_INSTALL_DIR]
265
266 EXECROOTDIR
267 executables and libraries (<empty>) [EXEC_INSTALL_PREFIX]
268
269 BINDIR user executables (EXECROOTDIR/bin) [BIN_INSTALL_DIR]
270
271 SBINDIR
272 system admin executables (EXECROOTDIR/sbin) [SBIN_INSTALL_DIR]
273
274 LIBDIR object code libraries (EXECROOTDIR/lib, EXECROOTDIR/lib64 or EX‐
275 ECROOTDIR/lib/<multiarch-tuple on Debian) [LIB_INSTALL_DIR]
276
277 LIBEXECDIR
278 executables for internal use by programs and libraries (BINDIR
279 on Windows, LIBDIR/libexec otherwise) [LIBEXEC_INSTALL_DIR]
280
281 CMAKEPACKAGEDIR
282 CMake packages, including config files (LIBDIR/cmake) [CMAKECON‐
283 FIG_INSTALL_PREFIX]
284
285 QTPLUGINDIR
286 Qt plugins (LIBDIR/plugins or qmake-qt5’s QT_INSTALL_PLUGINS)
287 [QT_PLUGIN_INSTALL_DIR]
288
289 PLUGINDIR
290 Plugins (QTPLUGINDIR) [PLUGIN_INSTALL_DIR]
291
292 QTQUICKIMPORTSDIR
293 QtQuick1 imports (QTPLUGINDIR/imports or qmake-qt5’s QT_IN‐
294 STALL_IMPORTS) [IMPORTS_INSTALL_DIR]
295
296 QMLDIR QtQuick2 imports (LIBDIR/qml or qmake-qt5’s QT_INSTALL_QML)
297 [QML_INSTALL_DIR]
298
299 INCLUDEDIR
300 C and C++ header files (include) [INCLUDE_INSTALL_DIR]
301
302 LOCALSTATEDIR
303 modifiable single-machine data (var)
304
305 SHAREDSTATEDIR
306 modifiable architecture-independent data (com)
307
308 DATAROOTDIR
309 read-only architecture-independent data root (share) [SHARE_IN‐
310 STALL_PREFIX]
311
312 DATADIR
313 read-only architecture-independent data (DATAROOTDIR) [DATA_IN‐
314 STALL_DIR]
315
316 DOCBUNDLEDIR
317 documentation bundles generated using kdoctools (DATAROOT‐
318 DIR/doc/HTML) [HTML_INSTALL_DIR]
319
320 KCFGDIR
321 kconfig description files (DATAROOTDIR/config.kcfg) [KCFG_IN‐
322 STALL_DIR]
323
324 KCONFUPDATEDIR
325 kconf_update scripts (DATAROOTDIR/kconf_update) [KCONF_UP‐
326 DATE_INSTALL_DIR]
327
328 KSERVICES5DIR
329 services for KDE Frameworks 5 (DATAROOTDIR/kservices5) [SER‐
330 VICES_INSTALL_DIR]
331
332 KSERVICETYPES5DIR
333 service types for KDE Frameworks 5 (DATAROOTDIR/kservicetypes5)
334 [SERVICETYPES_INSTALL_DIR]
335
336 KXMLGUI5DIR
337 knotify description files (DATAROOTDIR/kxmlgui5) [KXMLGUI_IN‐
338 STALL_DIR]
339
340 KTEMPLATESDIR
341 Kapptemplate and Kdevelop templates (kdevappwizard/templates)
342
343 KNOTIFY5RCDIR
344 knotify description files (DATAROOTDIR/knotifications5) [KNOTI‐
345 FYRC_INSTALL_DIR]
346
347 ICONDIR
348 icons (DATAROOTDIR/icons) [ICON_INSTALL_DIR]
349
350 LOCALEDIR
351 knotify description files (DATAROOTDIR/locale) [LOCALE_IN‐
352 STALL_DIR]
353
354 SOUNDDIR
355 sound files (DATAROOTDIR/sounds) [SOUND_INSTALL_DIR]
356
357 TEMPLATEDIR
358 templates (DATAROOTDIR/templates) [TEMPLATES_INSTALL_DIR]
359
360 WALLPAPERDIR
361 desktop wallpaper images (DATAROOTDIR/wallpapers) [WALLPAPER_IN‐
362 STALL_DIR]
363
364 APPDIR application desktop files (DATAROOTDIR/applications) Since
365 1.1.0. [XDG_APPS_INSTALL_DIR]
366
367 DESKTOPDIR
368 desktop directories (DATAROOTDIR/desktop-directories) [XDG_DI‐
369 RECTORY_INSTALL_DIR]
370
371 MIMEDIR
372 mime description files (DATAROOTDIR/mime/packages) [XDG_MIME_IN‐
373 STALL_DIR]
374
375 METAINFODIR
376 AppStream component metadata files (DATAROOTDIR/metainfo)
377
378 QTQCHDIR
379 documentation bundles in QCH format for Qt-extending libraries
380 (DATAROOTDIR/doc/qch or qmake-qt5’s QT_INSTALL_DOCS) Since
381 5.36.0.
382
383 QCHDIR documentation bundles in QCH format (DATAROOTDIR/doc/qch) Since
384 5.36.0.
385
386 MANDIR man documentation (DATAROOTDIR/man) [MAN_INSTALL_DIR]
387
388 INFODIR
389 info documentation (DATAROOTDIR/info)
390
391 DBUSDIR
392 D-Bus (DATAROOTDIR/dbus-1)
393
394 DBUSINTERFACEDIR
395 D-Bus interfaces (DBUSDIR/interfaces) [DBUS_INTERFACES_IN‐
396 STALL_DIR]
397
398 DBUSSERVICEDIR
399 D-Bus session services (DBUSDIR/services) [DBUS_SERVICES_IN‐
400 STALL_DIR]
401
402 DBUSSYSTEMSERVICEDIR
403 D-Bus system services (DBUSDIR/system-services) [DBUS_SYS‐
404 TEM_SERVICES_INSTALL_DIR]
405
406 SYSCONFDIR
407 read-only single-machine data (etc, or /etc if CMAKE_IN‐
408 STALL_PREFIX is /usr) [SYSCONF_INSTALL_DIR]
409
410 CONFDIR
411 application configuration files (SYSCONFDIR/xdg) [CONFIG_IN‐
412 STALL_DIR]
413
414 AUTOSTARTDIR
415 autostart files (CONFDIR/autostart) [AUTOSTART_INSTALL_DIR]
416
417 LOGGINGCATEGORIESDIR
418 Qt logging categories files directory (DATAROOTDIR/qlogging-cat‐
419 egories5) Since 5.59.0
420
421 JARDIR Java AAR/JAR files for Android. Since 5.62.0
422
423 SYSTEMDUNITDIR
424 Systemd Units (lib/systemd) [SYSTEMD_UNIT_INSTALL_DIR]. Since
425 5.65
426
427 SYSTEMDUSERUNITDIR
428 Systemd User Units (lib/systemd/user) [SYSTEMD_USER_UNIT_IN‐
429 STALL_DIR]. Since 5.65
430
431 If KDE_INSTALL_USE_QT_SYS_PATHS is set to TRUE before including this
432 module, the default values for some variables are instead queried from
433 Qt5’s qmake (where mentioned in the parentheses above). If not set, it
434 will default to TRUE if Qt5’s qmake is found and it’s QT_INSTALL_PREFIX
435 is the same as CMAKE_INSTALL_PREFIX, otherwise default to FALSE. This
436 variable should NOT be set from within CMakeLists.txt files, instead is
437 intended to be set manually when configuring a project which uses KDE‐
438 InstallDirs (e.g. by packagers).
439
440 If KDE_INSTALL_DIRS_NO_DEPRECATED is set to TRUE before including this
441 module, the deprecated variables (listed in the square brackets above)
442 are not defined.
443
444 In addition, for each KDE_INSTALL_* variable, an equivalent CMAKE_IN‐
445 STALL_* variable is defined. If KDE_INSTALL_DIRS_NO_DEPRECATED is set
446 to TRUE, only those variables defined by the GNUInstallDirs module
447 (shipped with CMake) are defined. If KDE_INSTALL_DIRS_NO_CMAKE_VARI‐
448 ABLES is set to TRUE, no variables with a CMAKE_ prefix will be defined
449 by this module (other than CMAKE_INSTALL_DEFAULT_COMPONENT_NAME - see
450 below).
451
452 The KDE_INSTALL_<dir> variables (or their CMAKE_INSTALL_<dir> or depre‐
453 cated counterparts) may be passed to the DESTINATION options of in‐
454 stall() commands for the corresponding file type. They are set in the
455 CMake cache, and so the defaults above can be overridden by users.
456
457 Note that the KDE_INSTALL_<dir>, CMAKE_INSTALL_<dir> or deprecated form
458 of the variable can be changed using CMake command line variable defi‐
459 nitions; in either case, all forms of the variable will be affected.
460 The effect of passing multiple forms of the same variable on the com‐
461 mand line (such as KDE_INSTALL_BINDIR and CMAKE_INSTALL_BINDIR is unde‐
462 fined.
463
464 The variable KDE_INSTALL_TARGETS_DEFAULT_ARGS is also defined (along
465 with the deprecated form INSTALL_TARGETS_DEFAULT_ARGS). This should be
466 used when libraries or user-executable applications are installed, in
467 the following manner:
468
469 install(TARGETS mylib myapp ${KDE_INSTALL_TARGETS_DEFAULT_ARGS})
470
471 It MUST NOT be used for installing plugins, system admin executables or
472 executables only intended for use internally by other code. Those
473 should use KDE_INSTALL_PLUGINDIR, KDE_INSTALL_SBINDIR or KDE_IN‐
474 STALL_LIBEXECDIR respectively.
475
476 Additionally, CMAKE_INSTALL_DEFAULT_COMPONENT_NAME will be set to
477 ${PROJECT_NAME} to provide a sensible default for this CMake option.
478
479 Note that mixing absolute and relative paths, particularly for BINDIR,
480 LIBDIR and INCLUDEDIR, can cause issues with exported targets. Given
481 that the default values for these are relative paths, relative paths
482 should be used on the command line when possible (eg: use -DKDE_IN‐
483 STALL_LIBDIR=lib64 instead of -DKDE_INSTALL_LIBDIR=/usr/lib/lib64 to
484 override the library directory).
485
486 Since pre-1.0.0.
487
488 NB: The variables starting KDE_INSTALL_ are available since 1.6.0, un‐
489 less otherwise noted with the variable.
490
491 The KDE_INSTALL_PREFIX_SCRIPT option will install a ${CMAKE_IN‐
492 STALL_PREFIX}/prefix.sh file that allows to easily incorporate the nec‐
493 essary environment variables for the prefix into a process.
494
495 KDETemplateGenerator
496 Packages KApptemplate/KDevelop compatible application templates
497
498 This module provides a functionality to package in a tarball and in‐
499 stall project templates compatible with the format used by KApptemplate
500 and KDevelop. Useful for providing minimal examples for the usage of
501 the KDE Frameworks.
502
503 This module provides the following function:
504
505 kde_package_app_templates(TEMPLATES <template> [<template> [...]]
506 INSTALL_DIR <directory>)
507
508 INSTALL_DIR is the directory to install the template package to. In
509 most cases you will want to use the variable KDE_INSTALL_KTEMPLATESDIR
510 from KDEInstallDirs.
511
512 TEMPLATES lists subdirectories containing template files; each <tem‐
513 plate> directory will be packaged into a file named <template>.tar.bz2
514 and installed to the appropriate location.
515
516 The template is a minimal source tree of an application as if it was an
517 application project by itself, with names (file names or text inside)
518 the text files replaced by the following placeholders when needed:
519
520 %{PROJECTDIRNAME}
521 name of generated project base folder ex: %{APPNAMELC} for
522 KAppTemplate
523
524 %{APPNAME}
525 project name as entered by user ex: MyKApp
526
527 %{APPNAMELC}
528 project name in lower case ex: mykapp
529
530 %{APPNAMEUC}
531 project name in upper case ex: MYKAPP
532
533 %{CPP_TEMPLATE}
534 license header for cpp file
535
536 %{H_TEMPLATE}
537 license header for h file
538
539 %{AUTHOR}
540 author name ex: George Ignacious
541
542 %{EMAIL}
543 author email ex: foo@bar.org
544
545 %{VERSION}
546 project version ex: 0.1
547
548 Deprecated:
549
550 %{dest}
551 path of generated project base folder, used in .kdevtemplate
552 with the ShowFilesAfterGeneration entry KDevelop >= 5.1.1 sup‐
553 ports relative paths with that entry, making this placeholder
554 obsolete
555
556 Multiple templates can be passed at once.
557
558 Since 5.18
559
561 ecm(7), ecm-modules(7), ecm-find-modules(7)
562
564 KDE Developers
565
566
567
568
5695.82 May 03, 2021 ECM-KDE-MODULES(7)