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 Translations
104 A fetch-translations target will be set up that will download transla‐
105 tions for projects using l10n.kde.org.
106 KDE_L10N_BRANCH will be responsible for choosing which l10n branch to
108 use for the translations.
109 KDE_L10N_AUTO_TRANSLATIONS (OFF by default) will indicate whether
111 translations should be downloaded when building the project.
112 Since 5.34.0
114 KDE_L10N_SYNC_TRANSLATIONS (OFF by default) will download the transla‐
116 tions at configuration time instead of build time.
117 Since 5.50.0
119 KDECompilerSettings
121 Set useful compile and link flags for C++ (and C) code.
122 Enables many more warnings than the default, and sets stricter modes
124 for some compiler features. By default, exceptions are disabled;
125 kde_target_enable_exceptions() can be used to re-enable them for a spe‐
126 cific target.
127 NB: it is recommended to include this module with the NO_POLICY_SCOPE
129 flag, otherwise you may get spurious warnings with some versions of
130 CMake.
131 This module provides the following functions:
133 kde_source_files_enable_exceptions([file1 [file2 [...]]])
135 Enables exceptions for specific source files. This should not be used
137 on source files in a language other than C++.
138 kde_target_enable_exceptions(target <INTERFACE|PUBLIC|PRIVATE>)
140 Enables exceptions for a specific target. This should not be used on a
142 target that has source files in a language other than C++.
143 kde_enable_exceptions()
145 Enables exceptions for C++ source files compiled for the CMakeLists.txt
147 file in the current directory and all subdirectories.
148 Since pre-1.0.0.
150 KDEFrameworkCompilerSettings
152 Set stricter compile and link flags for KDE Frameworks modules.
153 The KDECompilerSettings module is included and, in addition, various
155 defines that affect the Qt libraries are set to enforce certain conven‐
156 tions.
157 For example, constructions like QString(“foo”) are prohibited, instead
159 forcing the use of QLatin1String or QStringLiteral, and some Qt-defined
160 keywords like signals and slots will not be defined.
161 NB: it is recommended to include this module with the NO_POLICY_SCOPE
163 flag, otherwise you may get spurious warnings with some versions of
164 CMake.
165 Since pre-1.0.0.
167 KDEInstallDirs
169 Define KDE standard installation directories.
170 Note that none of the variables defined by this module provide any
172 information about the location of already-installed KDE software.
173 Inclusion of this module defines the following variables:
175 KDE_INSTALL_<dir>
177 destination for files of a given type
178 KDE_INSTALL_FULL_<dir>
180 corresponding absolute path
181 where <dir> is one of (default values in parentheses and alternative,
183 deprecated variable name in square brackets):
184 BUNDLEDIR
186 application bundles (/Applications/KDE) [BUNDLE_INSTALL_DIR]
187 EXECROOTDIR
189 executables and libraries (<empty>) [EXEC_INSTALL_PREFIX]
190 BINDIR user executables (EXECROOTDIR/bin) [BIN_INSTALL_DIR]
192 SBINDIR
194 system admin executables (EXECROOTDIR/sbin) [SBIN_INSTALL_DIR]
195 LIBDIR object code libraries (EXECROOTDIR/lib, EXECROOTDIR/lib64 or
197 EXECROOTDIR/lib/<multiarch-tuple on Debian) [LIB_INSTALL_DIR]
198 LIBEXECDIR
200 executables for internal use by programs and libraries (BINDIR
201 on Windows, LIBDIR/libexec otherwise) [LIBEXEC_INSTALL_DIR]
202 CMAKEPACKAGEDIR
204 CMake packages, including config files (LIBDIR/cmake) [CMAKECON‐
205 FIG_INSTALL_PREFIX]
206 QTPLUGINDIR
208 Qt plugins (LIBDIR/plugins or qmake-qt5’s QT_INSTALL_PLUGINS)
209 [QT_PLUGIN_INSTALL_DIR]
210 PLUGINDIR
212 Plugins (QTPLUGINDIR) [PLUGIN_INSTALL_DIR]
213 QTQUICKIMPORTSDIR
215 QtQuick1 imports (QTPLUGINDIR/imports or qmake-qt5’s
216 QT_INSTALL_IMPORTS) [IMPORTS_INSTALL_DIR]
217 QMLDIR QtQuick2 imports (LIBDIR/qml or qmake-qt5’s QT_INSTALL_QML)
219 [QML_INSTALL_DIR]
220 INCLUDEDIR
222 C and C++ header files (include) [INCLUDE_INSTALL_DIR]
223 LOCALSTATEDIR
225 modifiable single-machine data (var)
226 SHAREDSTATEDIR
228 modifiable architecture-independent data (com)
229 DATAROOTDIR
231 read-only architecture-independent data root (share)
232 [SHARE_INSTALL_PREFIX]
233 DATADIR
235 read-only architecture-independent data (DATAROOTDIR)
236 [DATA_INSTALL_DIR]
237 DOCBUNDLEDIR
239 documentation bundles generated using kdoctools (DATAROOT‐
240 DIR/doc/HTML) [HTML_INSTALL_DIR]
241 KCFGDIR
243 kconfig description files (DATAROOTDIR/config.kcfg)
244 [KCFG_INSTALL_DIR]
245 KCONFUPDATEDIR
247 kconf_update scripts (DATAROOTDIR/kconf_update)
248 [KCONF_UPDATE_INSTALL_DIR]
249 KSERVICES5DIR
251 services for KDE Frameworks 5 (DATAROOTDIR/kservices5) [SER‐
252 VICES_INSTALL_DIR]
253 KSERVICETYPES5DIR
255 service types for KDE Frameworks 5 (DATAROOTDIR/kservicetypes5)
256 [SERVICETYPES_INSTALL_DIR]
257 KXMLGUI5DIR
259 knotify description files (DATAROOTDIR/kxmlgui5) [KXML‐
260 GUI_INSTALL_DIR]
261 KTEMPLATESDIR
263 Kapptemplate and Kdevelop templates (kdevappwizard/templates)
264 KNOTIFY5RCDIR
266 knotify description files (DATAROOTDIR/knotifications5) [KNOTI‐
267 FYRC_INSTALL_DIR]
268 ICONDIR
270 icons (DATAROOTDIR/icons) [ICON_INSTALL_DIR]
271 LOCALEDIR
273 knotify description files (DATAROOTDIR/locale)
274 [LOCALE_INSTALL_DIR]
275 SOUNDDIR
277 sound files (DATAROOTDIR/sounds) [SOUND_INSTALL_DIR]
278 TEMPLATEDIR
280 templates (DATAROOTDIR/templates) [TEMPLATES_INSTALL_DIR]
281 WALLPAPERDIR
283 desktop wallpaper images (DATAROOTDIR/wallpapers) [WALLPA‐
284 PER_INSTALL_DIR]
285 APPDIR application desktop files (DATAROOTDIR/applications) Since
287 1.1.0. [XDG_APPS_INSTALL_DIR]
288 DESKTOPDIR
290 desktop directories (DATAROOTDIR/desktop-directories)
291 [XDG_DIRECTORY_INSTALL_DIR]
292 MIMEDIR
294 mime description files (DATAROOTDIR/mime/packages)
295 [XDG_MIME_INSTALL_DIR]
296 METAINFODIR
298 AppStream component metadata files (DATAROOTDIR/metainfo)
299 QTQCHDIR
301 documentation bundles in QCH format for Qt-extending libraries
302 (DATAROOTDIR/doc/qch or qmake-qt5’s QT_INSTALL_DOCS) Since
303 5.36.0.
304 QCHDIR documentation bundles in QCH format (DATAROOTDIR/doc/qch) Since
306 5.36.0.
307 MANDIR man documentation (DATAROOTDIR/man) [MAN_INSTALL_DIR]
309 INFODIR
311 info documentation (DATAROOTDIR/info)
312 DBUSDIR
314 D-Bus (DATAROOTDIR/dbus-1)
315 DBUSINTERFACEDIR
317 D-Bus interfaces (DBUSDIR/interfaces) [DBUS_INTER‐
318 FACES_INSTALL_DIR]
319 DBUSSERVICEDIR
321 D-Bus session services (DBUSDIR/services) [DBUS_SER‐
322 VICES_INSTALL_DIR]
323 DBUSSYSTEMSERVICEDIR
325 D-Bus system services (DBUSDIR/system-services) [DBUS_SYS‐
326 TEM_SERVICES_INSTALL_DIR]
327 SYSCONFDIR
329 read-only single-machine data (etc, or /etc if
330 CMAKE_INSTALL_PREFIX is /usr) [SYSCONF_INSTALL_DIR]
331 CONFDIR
333 application configuration files (SYSCONFDIR/xdg) [CON‐
334 FIG_INSTALL_DIR]
335 AUTOSTARTDIR
337 autostart files (CONFDIR/autostart) [AUTOSTART_INSTALL_DIR]
338 If KDE_INSTALL_USE_QT_SYS_PATHS is set to TRUE before including this
340 module, the default values for some variables are instead queried from
341 Qt5’s qmake (where mentioned in the parentheses above). If not set, it
342 will default to TRUE if Qt5’s qmake is found and it’s QT_INSTALL_PREFIX
343 is the same as CMAKE_INSTALL_PREFIX, otherwise default to FALSE. This
344 variable should NOT be set from within CMakeLists.txt files, instead is
345 intended to be set manually when configuring a project which uses KDE‐
346 InstallDirs (e.g. by packagers).
347 If KDE_INSTALL_DIRS_NO_DEPRECATED is set to TRUE before including this
349 module, the deprecated variables (listed in the square brackets above)
350 are not defined.
351 In addition, for each KDE_INSTALL_* variable, an equivalent
353 CMAKE_INSTALL_* variable is defined. If KDE_INSTALL_DIRS_NO_DEPRECATED
354 is set to TRUE, only those variables defined by the GNUInstallDirs mod‐
355 ule (shipped with CMake) are defined. If
356 KDE_INSTALL_DIRS_NO_CMAKE_VARIABLES is set to TRUE, no variables with a
357 CMAKE_ prefix will be defined by this module (other than
358 CMAKE_INSTALL_DEFAULT_COMPONENT_NAME - see below).
359 The KDE_INSTALL_<dir> variables (or their CMAKE_INSTALL_<dir> or depre‐
361 cated counterparts) may be passed to the DESTINATION options of
362 install() commands for the corresponding file type. They are set in
363 the CMake cache, and so the defaults above can be overridden by users.
364 Note that the KDE_INSTALL_<dir>, CMAKE_INSTALL_<dir> or deprecated form
366 of the variable can be changed using CMake command line variable defi‐
367 nitions; in either case, all forms of the variable will be affected.
368 The effect of passing multiple forms of the same variable on the com‐
369 mand line (such as KDE_INSTALL_BINDIR and CMAKE_INSTALL_BINDIR is unde‐
370 fined.
371 The variable KDE_INSTALL_TARGETS_DEFAULT_ARGS is also defined (along
373 with the deprecated form INSTALL_TARGETS_DEFAULT_ARGS). This should be
374 used when libraries or user-executable applications are installed, in
375 the following manner:
376 install(TARGETS mylib myapp ${KDE_INSTALL_TARGETS_DEFAULT_ARGS})
378 It MUST NOT be used for installing plugins, system admin executables or
380 executables only intended for use internally by other code. Those
381 should use KDE_INSTALL_PLUGINDIR, KDE_INSTALL_SBINDIR or
382 KDE_INSTALL_LIBEXECDIR respectively.
383 Additionally, CMAKE_INSTALL_DEFAULT_COMPONENT_NAME will be set to
385 ${PROJECT_NAME} to provide a sensible default for this CMake option.
386 Note that mixing absolute and relative paths, particularly for BINDIR,
388 LIBDIR and INCLUDEDIR, can cause issues with exported targets. Given
389 that the default values for these are relative paths, relative paths
390 should be used on the command line when possible (eg: use
391 -DKDE_INSTALL_LIBDIR=lib64 instead of -DKDE_INSTALL_LIB‐
392 DIR=/usr/lib/lib64 to override the library directory).
393 Since pre-1.0.0.
395 NB: The variables starting KDE_INSTALL_ are available since 1.6.0,
397 unless otherwise noted with the variable.
398 The KDE_INSTALL_PREFIX_SCRIPT option will install a
400 ${CMAKE_INSTALL_PREFIX}/prefix.sh file that allows to easily incorpo‐
401 rate the necessary environment variables for the prefix into a process.
402 KDETemplateGenerator
404 Packages KApptemplate/KDevelop compatible application templates
405 This module provides a functionality to package in a tarball and
407 install project templates compatible with the format used by KApptem‐
408 plate and KDevelop. Useful for providing minimal examples for the usage
409 of the KDE Frameworks.
410 This module provides the following function:
412 kde_package_app_templates(TEMPLATES <template> [<template> [...]]
414 INSTALL_DIR <directory>)
415 INSTALL_DIR is the directory to install the template package to. In
417 most cases you will want to use the variable KDE_INSTALL_KTEMPLATESDIR
418 from KDEInstallDirs.
419 TEMPLATES lists subdirectories containing template files; each <tem‐
421 plate> directory will be packaged into a file named <template>.tar.bz2
422 and installed to the appropriate location.
423 The template is a minimal source tree of an application as if it was an
425 application project by itself, with names (file names or text inside)
426 the text files replaced by the following placeholders when needed:
427 %{PROJECTDIRNAME}
429 name of generated project base folder ex: %{APPNAMELC} for
430 KAppTemplate
431 %{APPNAME}
433 project name as entered by user ex: MyKApp
434 %{APPNAMELC}
436 project name in lower case ex: mykapp
437 %{APPNAMEUC}
439 project name in upper case ex: MYKAPP
440 %{CPP_TEMPLATE}
442 license header for cpp file
443 %{H_TEMPLATE}
445 license header for h file
446 %{AUTHOR}
448 author name ex: George Ignacious
449 %{EMAIL}
451 author email ex: foo@bar.org
452 %{VERSION}
454 project version ex: 0.1
455 Deprecated:
457 %{dest}
459 path of generated project base folder, used in .kdevtemplate
460 with the ShowFilesAfterGeneration entry KDevelop >= 5.1.1 sup‐
461 ports relative paths with that entry, making this placeholder
462 obsolete
463 Multiple templates can be passed at once.
465 Since 5.18
467
469 ecm(7), ecm-modules(7), ecm-find-modules(7)
470
472 KDE Developers
4735.58 May 14, 2019 ECM-KDE-MODULES(7)