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.
134 Example usage:
136 include(KDEClangFormat)
138 file(GLOB_RECURSE ALL_CLANG_FORMAT_SOURCE_FILES src/*.cpp src/*.h)
139 kde_clang_format(${ALL_CLANG_FORMAT_SOURCE_FILES})
140 Since 5.64
142 KDECompilerSettings
144 Set useful compile and link flags for C++ (and C) code.
145 Enables many more warnings than the default, and sets stricter modes
147 for some compiler features. By default, exceptions are disabled;
148 kde_target_enable_exceptions() can be used to re-enable them for a spe‐
149 cific target.
150 NB: it is recommended to include this module with the NO_POLICY_SCOPE
152 flag, otherwise you may get spurious warnings with some versions of
153 CMake.
154 This module provides the following functions:
156 kde_source_files_enable_exceptions([file1 [file2 [...]]])
158 Enables exceptions for specific source files. This should not be used
160 on source files in a language other than C++.
161 kde_target_enable_exceptions(target <INTERFACE|PUBLIC|PRIVATE>)
163 Enables exceptions for a specific target. This should not be used on a
165 target that has source files in a language other than C++.
166 kde_enable_exceptions()
168 Enables exceptions for C++ source files compiled for the CMakeLists.txt
170 file in the current directory and all subdirectories.
171 Since pre-1.0.0.
173 KDEFrameworkCompilerSettings
175 Set stricter compile and link flags for KDE Frameworks modules.
176 The KDECompilerSettings module is included and, in addition, various
178 defines that affect the Qt libraries are set to enforce certain conven‐
179 tions.
180 For example, constructions like QString(“foo”) are prohibited, instead
182 forcing the use of QLatin1String or QStringLiteral, and some Qt-defined
183 keywords like signals and slots will not be defined.
184 NB: it is recommended to include this module with the NO_POLICY_SCOPE
186 flag, otherwise you may get spurious warnings with some versions of
187 CMake.
188 Since pre-1.0.0.
190 KDEInstallDirs
192 Define KDE standard installation directories.
193 Note that none of the variables defined by this module provide any
195 information about the location of already-installed KDE software.
196 Inclusion of this module defines the following variables:
198 KDE_INSTALL_<dir>
200 destination for files of a given type
201 KDE_INSTALL_FULL_<dir>
203 corresponding absolute path
204 where <dir> is one of (default values in parentheses and alternative,
206 deprecated variable name in square brackets):
207 BUNDLEDIR
209 application bundles (/Applications/KDE) [BUNDLE_INSTALL_DIR]
210 EXECROOTDIR
212 executables and libraries (<empty>) [EXEC_INSTALL_PREFIX]
213 BINDIR user executables (EXECROOTDIR/bin) [BIN_INSTALL_DIR]
215 SBINDIR
217 system admin executables (EXECROOTDIR/sbin) [SBIN_INSTALL_DIR]
218 LIBDIR object code libraries (EXECROOTDIR/lib, EXECROOTDIR/lib64 or
220 EXECROOTDIR/lib/<multiarch-tuple on Debian) [LIB_INSTALL_DIR]
221 LIBEXECDIR
223 executables for internal use by programs and libraries (BINDIR
224 on Windows, LIBDIR/libexec otherwise) [LIBEXEC_INSTALL_DIR]
225 CMAKEPACKAGEDIR
227 CMake packages, including config files (LIBDIR/cmake) [CMAKECON‐
228 FIG_INSTALL_PREFIX]
229 QTPLUGINDIR
231 Qt plugins (LIBDIR/plugins or qmake-qt5’s QT_INSTALL_PLUGINS)
232 [QT_PLUGIN_INSTALL_DIR]
233 PLUGINDIR
235 Plugins (QTPLUGINDIR) [PLUGIN_INSTALL_DIR]
236 QTQUICKIMPORTSDIR
238 QtQuick1 imports (QTPLUGINDIR/imports or qmake-qt5’s
239 QT_INSTALL_IMPORTS) [IMPORTS_INSTALL_DIR]
240 QMLDIR QtQuick2 imports (LIBDIR/qml or qmake-qt5’s QT_INSTALL_QML)
242 [QML_INSTALL_DIR]
243 INCLUDEDIR
245 C and C++ header files (include) [INCLUDE_INSTALL_DIR]
246 LOCALSTATEDIR
248 modifiable single-machine data (var)
249 SHAREDSTATEDIR
251 modifiable architecture-independent data (com)
252 DATAROOTDIR
254 read-only architecture-independent data root (share)
255 [SHARE_INSTALL_PREFIX]
256 DATADIR
258 read-only architecture-independent data (DATAROOTDIR)
259 [DATA_INSTALL_DIR]
260 DOCBUNDLEDIR
262 documentation bundles generated using kdoctools (DATAROOT‐
263 DIR/doc/HTML) [HTML_INSTALL_DIR]
264 KCFGDIR
266 kconfig description files (DATAROOTDIR/config.kcfg)
267 [KCFG_INSTALL_DIR]
268 KCONFUPDATEDIR
270 kconf_update scripts (DATAROOTDIR/kconf_update)
271 [KCONF_UPDATE_INSTALL_DIR]
272 KSERVICES5DIR
274 services for KDE Frameworks 5 (DATAROOTDIR/kservices5) [SER‐
275 VICES_INSTALL_DIR]
276 KSERVICETYPES5DIR
278 service types for KDE Frameworks 5 (DATAROOTDIR/kservicetypes5)
279 [SERVICETYPES_INSTALL_DIR]
280 KXMLGUI5DIR
282 knotify description files (DATAROOTDIR/kxmlgui5) [KXML‐
283 GUI_INSTALL_DIR]
284 KTEMPLATESDIR
286 Kapptemplate and Kdevelop templates (kdevappwizard/templates)
287 KNOTIFY5RCDIR
289 knotify description files (DATAROOTDIR/knotifications5) [KNOTI‐
290 FYRC_INSTALL_DIR]
291 ICONDIR
293 icons (DATAROOTDIR/icons) [ICON_INSTALL_DIR]
294 LOCALEDIR
296 knotify description files (DATAROOTDIR/locale)
297 [LOCALE_INSTALL_DIR]
298 SOUNDDIR
300 sound files (DATAROOTDIR/sounds) [SOUND_INSTALL_DIR]
301 TEMPLATEDIR
303 templates (DATAROOTDIR/templates) [TEMPLATES_INSTALL_DIR]
304 WALLPAPERDIR
306 desktop wallpaper images (DATAROOTDIR/wallpapers) [WALLPA‐
307 PER_INSTALL_DIR]
308 APPDIR application desktop files (DATAROOTDIR/applications) Since
310 1.1.0. [XDG_APPS_INSTALL_DIR]
311 DESKTOPDIR
313 desktop directories (DATAROOTDIR/desktop-directories)
314 [XDG_DIRECTORY_INSTALL_DIR]
315 MIMEDIR
317 mime description files (DATAROOTDIR/mime/packages)
318 [XDG_MIME_INSTALL_DIR]
319 METAINFODIR
321 AppStream component metadata files (DATAROOTDIR/metainfo)
322 QTQCHDIR
324 documentation bundles in QCH format for Qt-extending libraries
325 (DATAROOTDIR/doc/qch or qmake-qt5’s QT_INSTALL_DOCS) Since
326 5.36.0.
327 QCHDIR documentation bundles in QCH format (DATAROOTDIR/doc/qch) Since
329 5.36.0.
330 MANDIR man documentation (DATAROOTDIR/man) [MAN_INSTALL_DIR]
332 INFODIR
334 info documentation (DATAROOTDIR/info)
335 DBUSDIR
337 D-Bus (DATAROOTDIR/dbus-1)
338 DBUSINTERFACEDIR
340 D-Bus interfaces (DBUSDIR/interfaces) [DBUS_INTER‐
341 FACES_INSTALL_DIR]
342 DBUSSERVICEDIR
344 D-Bus session services (DBUSDIR/services) [DBUS_SER‐
345 VICES_INSTALL_DIR]
346 DBUSSYSTEMSERVICEDIR
348 D-Bus system services (DBUSDIR/system-services) [DBUS_SYS‐
349 TEM_SERVICES_INSTALL_DIR]
350 SYSCONFDIR
352 read-only single-machine data (etc, or /etc if
353 CMAKE_INSTALL_PREFIX is /usr) [SYSCONF_INSTALL_DIR]
354 CONFDIR
356 application configuration files (SYSCONFDIR/xdg) [CON‐
357 FIG_INSTALL_DIR]
358 AUTOSTARTDIR
360 autostart files (CONFDIR/autostart) [AUTOSTART_INSTALL_DIR]
361 LOGGINGCATEGORIESDIR
363 Qt logging categories files directory (DATAROOTDIR/qlogging-cat‐
364 egories5) Since 5.59.0
365 JARDIR Java AAR/JAR files for Android. Since 5.62.0
367 SYSTEMDUNITDIR
369 Systemd Units (lib/systemd) [SYSTEMD_UNIT_INSTALL_DIR]. Since
370 5.65
371 SYSTEMDUSERUNITDIR
373 Systemd User Units (lib/systemd/user) [SYS‐
374 TEMD_USER_UNIT_INSTALL_DIR]. Since 5.65
375 If KDE_INSTALL_USE_QT_SYS_PATHS is set to TRUE before including this
377 module, the default values for some variables are instead queried from
378 Qt5’s qmake (where mentioned in the parentheses above). If not set, it
379 will default to TRUE if Qt5’s qmake is found and it’s QT_INSTALL_PREFIX
380 is the same as CMAKE_INSTALL_PREFIX, otherwise default to FALSE. This
381 variable should NOT be set from within CMakeLists.txt files, instead is
382 intended to be set manually when configuring a project which uses KDE‐
383 InstallDirs (e.g. by packagers).
384 If KDE_INSTALL_DIRS_NO_DEPRECATED is set to TRUE before including this
386 module, the deprecated variables (listed in the square brackets above)
387 are not defined.
388 In addition, for each KDE_INSTALL_* variable, an equivalent
390 CMAKE_INSTALL_* variable is defined. If KDE_INSTALL_DIRS_NO_DEPRECATED
391 is set to TRUE, only those variables defined by the GNUInstallDirs mod‐
392 ule (shipped with CMake) are defined. If
393 KDE_INSTALL_DIRS_NO_CMAKE_VARIABLES is set to TRUE, no variables with a
394 CMAKE_ prefix will be defined by this module (other than
395 CMAKE_INSTALL_DEFAULT_COMPONENT_NAME - see below).
396 The KDE_INSTALL_<dir> variables (or their CMAKE_INSTALL_<dir> or depre‐
398 cated counterparts) may be passed to the DESTINATION options of
399 install() commands for the corresponding file type. They are set in
400 the CMake cache, and so the defaults above can be overridden by users.
401 Note that the KDE_INSTALL_<dir>, CMAKE_INSTALL_<dir> or deprecated form
403 of the variable can be changed using CMake command line variable defi‐
404 nitions; in either case, all forms of the variable will be affected.
405 The effect of passing multiple forms of the same variable on the com‐
406 mand line (such as KDE_INSTALL_BINDIR and CMAKE_INSTALL_BINDIR is unde‐
407 fined.
408 The variable KDE_INSTALL_TARGETS_DEFAULT_ARGS is also defined (along
410 with the deprecated form INSTALL_TARGETS_DEFAULT_ARGS). This should be
411 used when libraries or user-executable applications are installed, in
412 the following manner:
413 install(TARGETS mylib myapp ${KDE_INSTALL_TARGETS_DEFAULT_ARGS})
415 It MUST NOT be used for installing plugins, system admin executables or
417 executables only intended for use internally by other code. Those
418 should use KDE_INSTALL_PLUGINDIR, KDE_INSTALL_SBINDIR or
419 KDE_INSTALL_LIBEXECDIR respectively.
420 Additionally, CMAKE_INSTALL_DEFAULT_COMPONENT_NAME will be set to
422 ${PROJECT_NAME} to provide a sensible default for this CMake option.
423 Note that mixing absolute and relative paths, particularly for BINDIR,
425 LIBDIR and INCLUDEDIR, can cause issues with exported targets. Given
426 that the default values for these are relative paths, relative paths
427 should be used on the command line when possible (eg: use
428 -DKDE_INSTALL_LIBDIR=lib64 instead of -DKDE_INSTALL_LIB‐
429 DIR=/usr/lib/lib64 to override the library directory).
430 Since pre-1.0.0.
432 NB: The variables starting KDE_INSTALL_ are available since 1.6.0,
434 unless otherwise noted with the variable.
435 The KDE_INSTALL_PREFIX_SCRIPT option will install a
437 ${CMAKE_INSTALL_PREFIX}/prefix.sh file that allows to easily incorpo‐
438 rate the necessary environment variables for the prefix into a process.
439 KDETemplateGenerator
441 Packages KApptemplate/KDevelop compatible application templates
442 This module provides a functionality to package in a tarball and
444 install project templates compatible with the format used by KApptem‐
445 plate and KDevelop. Useful for providing minimal examples for the usage
446 of the KDE Frameworks.
447 This module provides the following function:
449 kde_package_app_templates(TEMPLATES <template> [<template> [...]]
451 INSTALL_DIR <directory>)
452 INSTALL_DIR is the directory to install the template package to. In
454 most cases you will want to use the variable KDE_INSTALL_KTEMPLATESDIR
455 from KDEInstallDirs.
456 TEMPLATES lists subdirectories containing template files; each <tem‐
458 plate> directory will be packaged into a file named <template>.tar.bz2
459 and installed to the appropriate location.
460 The template is a minimal source tree of an application as if it was an
462 application project by itself, with names (file names or text inside)
463 the text files replaced by the following placeholders when needed:
464 %{PROJECTDIRNAME}
466 name of generated project base folder ex: %{APPNAMELC} for
467 KAppTemplate
468 %{APPNAME}
470 project name as entered by user ex: MyKApp
471 %{APPNAMELC}
473 project name in lower case ex: mykapp
474 %{APPNAMEUC}
476 project name in upper case ex: MYKAPP
477 %{CPP_TEMPLATE}
479 license header for cpp file
480 %{H_TEMPLATE}
482 license header for h file
483 %{AUTHOR}
485 author name ex: George Ignacious
486 %{EMAIL}
488 author email ex: foo@bar.org
489 %{VERSION}
491 project version ex: 0.1
492 Deprecated:
494 %{dest}
496 path of generated project base folder, used in .kdevtemplate
497 with the ShowFilesAfterGeneration entry KDevelop >= 5.1.1 sup‐
498 ports relative paths with that entry, making this placeholder
499 obsolete
500 Multiple templates can be passed at once.
502 Since 5.18
504
506 ecm(7), ecm-modules(7), ecm-find-modules(7)
507
509 KDE Developers
5105.68 Mar 19, 2020 ECM-KDE-MODULES(7)