1ECM-KDE-MODULES(7)            Extra CMake Modules           ECM-KDE-MODULES(7)
2
3
4

NAME

6       ecm-kde-modules - ECM KDE Modules Reference
7

INTRODUCTION

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

ALL KDE MODULES

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

SEE ALSO

473       ecm(7), ecm-modules(7), ecm-find-modules(7)
474
476       KDE Developers
477
478
479
480
4815.59                             Jun 12, 2019               ECM-KDE-MODULES(7)
Impressum