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 that LIB_INSTALL_DIR or alternatively KDE_INSTALL_LIBDIR needs to
44 be set before including this module. Typically, this is done by
45 including the KDEInstallDirs module.
46 This section can be disabled by setting KDE_SKIP_RPATH_SETTINGS to TRUE
48 before including this module.
49 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 This section can be disabled by setting KDE_SKIP_TEST_SETTINGS to TRUE
56 before including this module.
57 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 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
64 installing: 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_OUT‐
67 PUT_DIRECTORY as documented on
68 https://community.kde.org/Guidelines_and_HOWTOs/Making_apps_run_uninstalled).
69 This section can be disabled by setting KDE_SKIP_BUILD_SETTINGS to TRUE
71 before including this module.
72 This section also provides an “uninstall” target that can be individu‐
74 ally disabled by setting KDE_SKIP_UNINSTALL_TARGET to TRUE before
75 including this module.
76 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 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 Since pre-1.0.0.
86 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 If clang is not being used, this won’t have an effect. See
92 https://commits.kde.org/clazy?path=README.md
93 Since 5.17.0
95 · Uninstall target functionality since 1.7.0.
97 · APPLE_FORCE_X11 option since 5.14.0 (detecting X11 was previously the
99 default behavior)
100 · APPLE_SUPPRESS_X11_WARNING option since 5.14.0
102 · CMAKE_AUTORCC enabled by default when supported by cmake (>= 3.0)
104 since 5.62.0
105 Translations
107 A fetch-translations target will be set up that will download transla‐
108 tions for projects using l10n.kde.org.
109 KDE_L10N_BRANCH will be responsible for choosing which l10n branch to
111 use for the translations.
112 KDE_L10N_AUTO_TRANSLATIONS (OFF by default) will indicate whether
114 translations should be downloaded when building the project.
115 Since 5.34.0
117 KDE_L10N_SYNC_TRANSLATIONS (OFF by default) will download the transla‐
119 tions at configuration time instead of build time.
120 Since 5.50.0
122 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 This module provides the following function:
128 kde_clang_format(<files>)
130 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 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 Since 5.79: If the source folder already contains a .clang-format file
143 it is not overwritten.
144 Example usage:
146 include(KDEClangFormat)
148 file(GLOB_RECURSE ALL_CLANG_FORMAT_SOURCE_FILES *.cpp *.h)
149 kde_clang_format(${ALL_CLANG_FORMAT_SOURCE_FILES})
150 To exclude directories from the formatting add a .clang-format file in
152 the directory with the following contents:
153 DisableFormat: true
155 SortIncludes: false
156 Since 5.64
158 KDECompilerSettings
160 Set useful compile and link flags for C++ (and C) code.
161 Enables many more warnings than the default, and sets stricter modes
163 for some compiler features. By default, exceptions are disabled;
164 kde_target_enable_exceptions() can be used to re-enable them for a spe‐
165 cific target.
166 NB: it is recommended to include this module with the NO_POLICY_SCOPE
168 flag, otherwise you may get spurious warnings with some versions of
169 CMake.
170 This module provides the following functions:
172 kde_source_files_enable_exceptions([file1 [file2 [...]]])
174 Enables exceptions for specific source files. This should not be used
176 on source files in a language other than C++.
177 kde_target_enable_exceptions(target <INTERFACE|PUBLIC|PRIVATE>)
179 Enables exceptions for a specific target. This should not be used on a
181 target that has source files in a language other than C++.
182 kde_enable_exceptions()
184 Enables exceptions for C++ source files compiled for the CMakeLists.txt
186 file in the current directory and all subdirectories.
187 Since pre-1.0.0.
189 KDEFrameworkCompilerSettings
191 Set stricter compile and link flags for KDE Frameworks modules.
192 The KDECompilerSettings module is included and, in addition, various
194 defines that affect the Qt libraries are set to enforce certain conven‐
195 tions.
196 For example, constructions like QString(“foo”) are prohibited, instead
198 forcing the use of QLatin1String or QStringLiteral, and some Qt-defined
199 keywords like signals and slots will not be defined.
200 NB: it is recommended to include this module with the NO_POLICY_SCOPE
202 flag, otherwise you may get spurious warnings with some versions of
203 CMake.
204 Since pre-1.0.0.
206 KDEGitCommitHooks
208 This module provides a functionality to enforce formatting or in the
209 future other QS checks.
210 This module provides the following function:
212 kde_configure_pre_commit_hook(
214 CHECKS <check1> [<check2> [...]]
215 )
216 This function will create a pre-commit hook which contains all the
218 given checks.
219 Checks:
221 · CLANG_FORMAT With this check enabled the git clang-format tool will
223 be used to make sure that the changed parts are properly formatted.
224 In case the changes are not properly formatted an error message with
225 the command to preview the formatting changes and to format the files
226 in place will be displayed. This tool will reuse the exsting
227 .clang-format file, in case you want to use the one provided by ECM
228 you can include include(KDEClangFormat) which will copy the file to
229 the source dir. It is also recommended to reformat the entire project
230 before enforcing the formatting using this commit hook.
231 Example usage:
233 include(KDEGitCommitHooks)
235 kde_configure_git_pre_commit_hook(CHECKS CLANG_FORMAT)
236 Since 5.79
238 KDEInstallDirs
240 Define KDE standard installation directories.
241 Note that none of the variables defined by this module provide any
243 information about the location of already-installed KDE software.
244 Also sets CMAKE_INSTALL_PREFIX to the installation prefix of ECM,
246 unless that variable has been already explicitly set by something else
247 (since 5.61 and with CMake >= 3.7).
248 Inclusion of this module defines the following variables:
250 KDE_INSTALL_<dir>
252 destination for files of a given type
253 KDE_INSTALL_FULL_<dir>
255 corresponding absolute path
256 where <dir> is one of (default values in parentheses and alternative,
258 deprecated variable name in square brackets):
259 BUNDLEDIR
261 application bundles (/Applications/KDE) [BUNDLE_INSTALL_DIR]
262 EXECROOTDIR
264 executables and libraries (<empty>) [EXEC_INSTALL_PREFIX]
265 BINDIR user executables (EXECROOTDIR/bin) [BIN_INSTALL_DIR]
267 SBINDIR
269 system admin executables (EXECROOTDIR/sbin) [SBIN_INSTALL_DIR]
270 LIBDIR object code libraries (EXECROOTDIR/lib, EXECROOTDIR/lib64 or
272 EXECROOTDIR/lib/<multiarch-tuple on Debian) [LIB_INSTALL_DIR]
273 LIBEXECDIR
275 executables for internal use by programs and libraries (BINDIR
276 on Windows, LIBDIR/libexec otherwise) [LIBEXEC_INSTALL_DIR]
277 CMAKEPACKAGEDIR
279 CMake packages, including config files (LIBDIR/cmake) [CMAKECON‐
280 FIG_INSTALL_PREFIX]
281 QTPLUGINDIR
283 Qt plugins (LIBDIR/plugins or qmake-qt5’s QT_INSTALL_PLUGINS)
284 [QT_PLUGIN_INSTALL_DIR]
285 PLUGINDIR
287 Plugins (QTPLUGINDIR) [PLUGIN_INSTALL_DIR]
288 QTQUICKIMPORTSDIR
290 QtQuick1 imports (QTPLUGINDIR/imports or qmake-qt5’s
291 QT_INSTALL_IMPORTS) [IMPORTS_INSTALL_DIR]
292 QMLDIR QtQuick2 imports (LIBDIR/qml or qmake-qt5’s QT_INSTALL_QML)
294 [QML_INSTALL_DIR]
295 INCLUDEDIR
297 C and C++ header files (include) [INCLUDE_INSTALL_DIR]
298 LOCALSTATEDIR
300 modifiable single-machine data (var)
301 SHAREDSTATEDIR
303 modifiable architecture-independent data (com)
304 DATAROOTDIR
306 read-only architecture-independent data root (share)
307 [SHARE_INSTALL_PREFIX]
308 DATADIR
310 read-only architecture-independent data (DATAROOTDIR)
311 [DATA_INSTALL_DIR]
312 DOCBUNDLEDIR
314 documentation bundles generated using kdoctools (DATAROOT‐
315 DIR/doc/HTML) [HTML_INSTALL_DIR]
316 KCFGDIR
318 kconfig description files (DATAROOTDIR/config.kcfg)
319 [KCFG_INSTALL_DIR]
320 KCONFUPDATEDIR
322 kconf_update scripts (DATAROOTDIR/kconf_update)
323 [KCONF_UPDATE_INSTALL_DIR]
324 KSERVICES5DIR
326 services for KDE Frameworks 5 (DATAROOTDIR/kservices5) [SER‐
327 VICES_INSTALL_DIR]
328 KSERVICETYPES5DIR
330 service types for KDE Frameworks 5 (DATAROOTDIR/kservicetypes5)
331 [SERVICETYPES_INSTALL_DIR]
332 KXMLGUI5DIR
334 knotify description files (DATAROOTDIR/kxmlgui5) [KXML‐
335 GUI_INSTALL_DIR]
336 KTEMPLATESDIR
338 Kapptemplate and Kdevelop templates (kdevappwizard/templates)
339 KNOTIFY5RCDIR
341 knotify description files (DATAROOTDIR/knotifications5) [KNOTI‐
342 FYRC_INSTALL_DIR]
343 ICONDIR
345 icons (DATAROOTDIR/icons) [ICON_INSTALL_DIR]
346 LOCALEDIR
348 knotify description files (DATAROOTDIR/locale)
349 [LOCALE_INSTALL_DIR]
350 SOUNDDIR
352 sound files (DATAROOTDIR/sounds) [SOUND_INSTALL_DIR]
353 TEMPLATEDIR
355 templates (DATAROOTDIR/templates) [TEMPLATES_INSTALL_DIR]
356 WALLPAPERDIR
358 desktop wallpaper images (DATAROOTDIR/wallpapers) [WALLPA‐
359 PER_INSTALL_DIR]
360 APPDIR application desktop files (DATAROOTDIR/applications) Since
362 1.1.0. [XDG_APPS_INSTALL_DIR]
363 DESKTOPDIR
365 desktop directories (DATAROOTDIR/desktop-directories)
366 [XDG_DIRECTORY_INSTALL_DIR]
367 MIMEDIR
369 mime description files (DATAROOTDIR/mime/packages)
370 [XDG_MIME_INSTALL_DIR]
371 METAINFODIR
373 AppStream component metadata files (DATAROOTDIR/metainfo)
374 QTQCHDIR
376 documentation bundles in QCH format for Qt-extending libraries
377 (DATAROOTDIR/doc/qch or qmake-qt5’s QT_INSTALL_DOCS) Since
378 5.36.0.
379 QCHDIR documentation bundles in QCH format (DATAROOTDIR/doc/qch) Since
381 5.36.0.
382 MANDIR man documentation (DATAROOTDIR/man) [MAN_INSTALL_DIR]
384 INFODIR
386 info documentation (DATAROOTDIR/info)
387 DBUSDIR
389 D-Bus (DATAROOTDIR/dbus-1)
390 DBUSINTERFACEDIR
392 D-Bus interfaces (DBUSDIR/interfaces) [DBUS_INTER‐
393 FACES_INSTALL_DIR]
394 DBUSSERVICEDIR
396 D-Bus session services (DBUSDIR/services) [DBUS_SER‐
397 VICES_INSTALL_DIR]
398 DBUSSYSTEMSERVICEDIR
400 D-Bus system services (DBUSDIR/system-services) [DBUS_SYS‐
401 TEM_SERVICES_INSTALL_DIR]
402 SYSCONFDIR
404 read-only single-machine data (etc, or /etc if
405 CMAKE_INSTALL_PREFIX is /usr) [SYSCONF_INSTALL_DIR]
406 CONFDIR
408 application configuration files (SYSCONFDIR/xdg) [CON‐
409 FIG_INSTALL_DIR]
410 AUTOSTARTDIR
412 autostart files (CONFDIR/autostart) [AUTOSTART_INSTALL_DIR]
413 LOGGINGCATEGORIESDIR
415 Qt logging categories files directory (DATAROOTDIR/qlogging-cat‐
416 egories5) Since 5.59.0
417 JARDIR Java AAR/JAR files for Android. Since 5.62.0
419 SYSTEMDUNITDIR
421 Systemd Units (lib/systemd) [SYSTEMD_UNIT_INSTALL_DIR]. Since
422 5.65
423 SYSTEMDUSERUNITDIR
425 Systemd User Units (lib/systemd/user) [SYS‐
426 TEMD_USER_UNIT_INSTALL_DIR]. Since 5.65
427 If KDE_INSTALL_USE_QT_SYS_PATHS is set to TRUE before including this
429 module, the default values for some variables are instead queried from
430 Qt5’s qmake (where mentioned in the parentheses above). If not set, it
431 will default to TRUE if Qt5’s qmake is found and it’s QT_INSTALL_PREFIX
432 is the same as CMAKE_INSTALL_PREFIX, otherwise default to FALSE. This
433 variable should NOT be set from within CMakeLists.txt files, instead is
434 intended to be set manually when configuring a project which uses KDE‐
435 InstallDirs (e.g. by packagers).
436 If KDE_INSTALL_DIRS_NO_DEPRECATED is set to TRUE before including this
438 module, the deprecated variables (listed in the square brackets above)
439 are not defined.
440 In addition, for each KDE_INSTALL_* variable, an equivalent
442 CMAKE_INSTALL_* variable is defined. If KDE_INSTALL_DIRS_NO_DEPRECATED
443 is set to TRUE, only those variables defined by the GNUInstallDirs mod‐
444 ule (shipped with CMake) are defined. If
445 KDE_INSTALL_DIRS_NO_CMAKE_VARIABLES is set to TRUE, no variables with a
446 CMAKE_ prefix will be defined by this module (other than
447 CMAKE_INSTALL_DEFAULT_COMPONENT_NAME - see below).
448 The KDE_INSTALL_<dir> variables (or their CMAKE_INSTALL_<dir> or depre‐
450 cated counterparts) may be passed to the DESTINATION options of
451 install() commands for the corresponding file type. They are set in
452 the CMake cache, and so the defaults above can be overridden by users.
453 Note that the KDE_INSTALL_<dir>, CMAKE_INSTALL_<dir> or deprecated form
455 of the variable can be changed using CMake command line variable defi‐
456 nitions; in either case, all forms of the variable will be affected.
457 The effect of passing multiple forms of the same variable on the com‐
458 mand line (such as KDE_INSTALL_BINDIR and CMAKE_INSTALL_BINDIR is unde‐
459 fined.
460 The variable KDE_INSTALL_TARGETS_DEFAULT_ARGS is also defined (along
462 with the deprecated form INSTALL_TARGETS_DEFAULT_ARGS). This should be
463 used when libraries or user-executable applications are installed, in
464 the following manner:
465 install(TARGETS mylib myapp ${KDE_INSTALL_TARGETS_DEFAULT_ARGS})
467 It MUST NOT be used for installing plugins, system admin executables or
469 executables only intended for use internally by other code. Those
470 should use KDE_INSTALL_PLUGINDIR, KDE_INSTALL_SBINDIR or
471 KDE_INSTALL_LIBEXECDIR respectively.
472 Additionally, CMAKE_INSTALL_DEFAULT_COMPONENT_NAME will be set to
474 ${PROJECT_NAME} to provide a sensible default for this CMake option.
475 Note that mixing absolute and relative paths, particularly for BINDIR,
477 LIBDIR and INCLUDEDIR, can cause issues with exported targets. Given
478 that the default values for these are relative paths, relative paths
479 should be used on the command line when possible (eg: use
480 -DKDE_INSTALL_LIBDIR=lib64 instead of -DKDE_INSTALL_LIB‐
481 DIR=/usr/lib/lib64 to override the library directory).
482 Since pre-1.0.0.
484 NB: The variables starting KDE_INSTALL_ are available since 1.6.0,
486 unless otherwise noted with the variable.
487 The KDE_INSTALL_PREFIX_SCRIPT option will install a
489 ${CMAKE_INSTALL_PREFIX}/prefix.sh file that allows to easily incorpo‐
490 rate the necessary environment variables for the prefix into a process.
491 KDETemplateGenerator
493 Packages KApptemplate/KDevelop compatible application templates
494 This module provides a functionality to package in a tarball and
496 install project templates compatible with the format used by KApptem‐
497 plate and KDevelop. Useful for providing minimal examples for the usage
498 of the KDE Frameworks.
499 This module provides the following function:
501 kde_package_app_templates(TEMPLATES <template> [<template> [...]]
503 INSTALL_DIR <directory>)
504 INSTALL_DIR is the directory to install the template package to. In
506 most cases you will want to use the variable KDE_INSTALL_KTEMPLATESDIR
507 from KDEInstallDirs.
508 TEMPLATES lists subdirectories containing template files; each <tem‐
510 plate> directory will be packaged into a file named <template>.tar.bz2
511 and installed to the appropriate location.
512 The template is a minimal source tree of an application as if it was an
514 application project by itself, with names (file names or text inside)
515 the text files replaced by the following placeholders when needed:
516 %{PROJECTDIRNAME}
518 name of generated project base folder ex: %{APPNAMELC} for
519 KAppTemplate
520 %{APPNAME}
522 project name as entered by user ex: MyKApp
523 %{APPNAMELC}
525 project name in lower case ex: mykapp
526 %{APPNAMEUC}
528 project name in upper case ex: MYKAPP
529 %{CPP_TEMPLATE}
531 license header for cpp file
532 %{H_TEMPLATE}
534 license header for h file
535 %{AUTHOR}
537 author name ex: George Ignacious
538 %{EMAIL}
540 author email ex: foo@bar.org
541 %{VERSION}
543 project version ex: 0.1
544 Deprecated:
546 %{dest}
548 path of generated project base folder, used in .kdevtemplate
549 with the ShowFilesAfterGeneration entry KDevelop >= 5.1.1 sup‐
550 ports relative paths with that entry, making this placeholder
551 obsolete
552 Multiple templates can be passed at once.
554 Since 5.18
556
558 ecm(7), ecm-modules(7), ecm-find-modules(7)
559
561 KDE Developers
5625.79 Feb 06, 2021 ECM-KDE-MODULES(7)