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

NAME

6       ecm-modules - ECM Modules Reference
7

INTRODUCTION

9       Extra  CMake Modules (ECM) provides various modules that provide useful
10       functions for CMake scripts. ECM actually provides three types of  mod‐
11       ules  that  can be used from CMake scripts: those that extend the func‐
12       tionality of the find_package command are documented  in  ecm-find-mod‐
13       ules(7);  those that provide standard settings for software produced by
14       the KDE community are documented in ecm-kde-modules(7).  The rest  pro‐
15       vide macros and functions for general use by CMake scripts and are doc‐
16       umented here.
17
18       To use these modules, you need to tell CMake to find the  ECM  package,
19       and  then  add  either  ${ECM_MODULE_PATH}  or ${ECM_MODULE_DIR} to the
20       CMAKE_MODULE_PATH variable:
21
22          find_package(ECM REQUIRED NO_MODULE)
23          set(CMAKE_MODULE_PATH ${ECM_MODULE_DIR})
24
25       Using ${ECM_MODULE_PATH} will also make the find modules and  KDE  mod‐
26       ules available.
27
28       Note   that   there   are   also   toolchain   modules,  documented  in
29       ecm-toolchains(7), but these are used by users  building  the  software
30       rather than developers writing CMake scripts.
31

ALL MODULES

33   ECMAddAppIcon
34       Add icons to executable files and packages.
35
36          ecm_add_app_icon(<sources_var>
37                           ICONS <icon> [<icon> [...]]
38                           [SIDEBAR_ICONS <icon> [<icon> [...]] # Since 5.49
39                           [OUTFILE_BASENAME <name>]) # Since 5.49
40                           )
41
42       The given icons, whose names must match the pattern:
43
44          <size>-<other_text>.png
45
46       will  be  added to the executable target whose sources are specified by
47       <sources_var> on platforms that support it  (Windows  and  Mac  OS  X).
48       Other  icon files are ignored but on Mac SVG files can be supported and
49       it is thus possible to mix those with png files in a single macro call.
50
51       <size> is a numeric pixel size (typically 16, 32, 48, 64, 128 or  256).
52       <other_text>  can  be  any other text. See the platform notes below for
53       any recommendations about icon sizes.
54
55       SIDEBAR_ICONS can be used to add Mac OS X sidebar icons to  the  gener‐
56       ated  iconset. They are used when a folder monitored by the application
57       is dragged into Finder’s sidebar. Since 5.49.
58
59       OUTFILE_BASENAME will be used as the basename for the icon file. If you
60       specify it, the icon file will be called <OUTFILE_BASENAME>.icns on Mac
61       OS X and <OUTFILE_BASENAME>.ico on Windows. If you don’t specify it, it
62       defaults to <sources_var>.<ext>. Since 5.49.
63
64       Windows notes
65
66              · Icons are compiled into the executable using a resource file.
67
68              · Icons  may  not  show up in Windows Explorer if the executable
69                target does not have the WIN32_EXECUTABLE property set.
70
71              · One of the tools png2ico (See  FindPng2Ico)  or  icotool  (see
72                FindIcoTool) is required.
73
74              · Supported sizes: 16, 24, 32, 48, 64, 128, 256, 512 and 1024.
75
76       Mac OS X notes
77
78              · The  executable  target  must  have the MACOSX_BUNDLE property
79                set.
80
81              · Icons are added to the bundle.
82
83              · If the ksvg2icns tool from KIconThemes is available, .svg  and
84                .svgz files are accepted; the first that is converted success‐
85                fully to .icns will provide the application  icon.  SVG  files
86                are ignored otherwise.
87
88              · The  tool  iconutil (provided by Apple) is required for bitmap
89                icons.
90
91              · Supported sizes: 16, 32, 64, 128, 256 (and 512, 1024 after  OS
92                X 10.9).
93
94              · At least a 128x128px (or an SVG) icon is required.
95
96              · Larger  sizes are automatically used to substitute for smaller
97                sizes on “Retina” (high-resolution) displays. For  example,  a
98                32px  icon,  if provided, will be used as a 32px icon on stan‐
99                dard-resolution displays, and as a 16px-equivalent icon  (with
100                an  “@2x”  tag)  on  high-resolution displays. That is why you
101                should provide 64px and 1024px icons  although  they  are  not
102                supported  anymore  directly.  Instead  they  will  be used as
103                32px@2x and 512px@2x. ksvg2icns handles this internally.
104
105              · This function sets the MACOSX_BUNDLE_ICON_FILE variable to the
106                name  of  the  generated icns file, so that it will be used as
107                the MACOSX_BUNDLE_ICON_FILE  target  property  when  you  call
108                add_executable.
109
110              · Sidebar icons should typically provided in 16, 32, 64, 128 and
111                256px.
112
113       Since 1.7.0.
114
115   ECMAddQch
116       This module provides the ecm_add_qch function for generating API  docu‐
117       mentation files in the QCH format, and the ecm_install_qch_export func‐
118       tion for generating and installing exported CMake targets for such gen‐
119       erated  QCH files to enable builds of other software with generation of
120       QCH files to create links into the given QCH files.
121
122          ecm_add_qch(<target_name>
123              NAME <name>
124              VERSION <version>
125              QCH_INSTALL_DESTINATION <qchfile_install_path>
126              TAGFILE_INSTALL_DESTINATION <tagsfile_install_path>
127              [COMPONENT <component>]
128              [BASE_NAME <basename>]
129              [SOURCE_DIRS <dir> [<dir2> [...]]]
130              [SOURCES <file> [<file2> [...]]]
131              |MD_MAINPAGE <md_file>]
132              [INCLUDE_DIRS <incdir> [<incdir2> [...]]]
133              [IMAGE_DIRS <idir> [<idir2> [...]]]
134              [EXAMPLE_DIRS <edir> [<edir2> [...]]]
135              [ORG_DOMAIN <domain>]
136              [NAMESPACE <namespace>]
137              [LINK_QCHS <qch> [<qch2> [...]]]
138              [PREDEFINED_MACROS <macro[=content]> [<macro2[=content]> [...]]]
139              [BLANK_MACROS <macro> [<macro2> [...]]]
140              [CONFIG_TEMPLATE <configtemplate_file>]
141              [VERBOSE]
142          )
143
144       This macro adds a target called <target_name> for the  creation  of  an
145       API  documentation manual in the QCH format from the given sources.  It
146       currently uses doxygen, future versions  might  optionally  also  allow
147       other  tools.   Next  to the QCH file the target will generate a corre‐
148       sponding doxygen tag file, which enables creating links from other doc‐
149       umentation into the generated QCH file.
150
151       It  is recommended to make the use of this macro optional, by depending
152       the call to ecm_add_qch on a CMake option being set, with a  name  like
153       BUILD_QCH  and being TRUE by default. This will allow the developers to
154       saves resources on normal source development build  cycles  by  setting
155       this option to FALSE.
156
157       The  macro  will  set the target properties DOXYGEN_TAGFILE, QHP_NAMES‐
158       PACE, QHP_NAMESPACE_VERSIONED, QHP_VIRTUALFOLDER and LINK_QCHS  to  the
159       respective  values,  to allow other code access to them, e.g. the macro
160       ecm_install_qch_export.  To enable the use of the target  <target_name>
161       as  item  for  LINK_QCHS  in  further  ecm_add_qch calls in the current
162       build, additionally a target  property  DOXYGEN_TAGFILE_BUILD  is  set,
163       with  the  path  of  the created doxygen tag file in the build dir.  If
164       existing, ecm_add_qch will use this property instead of DOXYGEN_TAGFILE
165       for access to the tags file.
166
167       NAME specifies the name for the generated documentation.
168
169       VERSION  specifies  the version of the library for which the documenta‐
170       tion is created.
171
172       BASE_NAME specifies the base name for the generated files.  The default
173       basename is <name>.
174
175       SOURCE_DIRS  specifies  the  dirs (incl. subdirs) with the source files
176       for which the API documentation should be generated.  Dirs can be rela‐
177       tive  to  the current source dir. Dependencies to the files in the dirs
178       are not tracked currently, other than with the SOURCES argument. So  do
179       not  use for sources generated during the build.  Needs to be used when
180       SOURCES or CONFIG_TEMPLATE are not used.
181
182       SOURCES specifies the source files  for  which  the  API  documentation
183       should  be generated.  Needs to be used when SOURCE_DIRS or CONFIG_TEM‐
184       PLATE are not used.
185
186       MD_MAINPAGE specifies a file in Markdown format that should be used  as
187       main  page.  This  page  will  overrule  any  \mainpage  command in the
188       included sources.
189
190       INCLUDE_DIRS specifies the dirs which should be searched  for  included
191       headers. Dirs can be relative to the current source dir. Since 5.63.
192
193       IMAGE_DIRS specifies the dirs which contain images that are included in
194       the documentation. Dirs can be relative to the current source dir.
195
196       EXAMPLE_DIRS  specifies  the  dirs  which  contain  examples  that  are
197       included  in  the  documentation.  Dirs  can be relative to the current
198       source dir.
199
200       QCH_INSTALL_DESTINATION specifies where the generated QCH file will  be
201       installed.
202
203       TAGFILE_INSTALL_DESTINATION specifies where the generated tag file will
204       be installed.
205
206       COMPONENT specifies the installation  component  name  with  which  the
207       install rules for the generated QCH file and tag file are associated.
208
209       NAMESPACE can be used to set a custom namespace <namespace> of the gen‐
210       erated QCH file. The namepspace is used as the unique id by QHelpEngine
211       (cmp.     https://doc.qt.io/qt-5/qthelpproject.html#namespace).     The
212       default namespace is <domain>.<name>.  Needs to be used when ORG_DOMAIN
213       is not used.
214
215       ORG_DOMAIN can be used to define the organization domain prefix for the
216       default namespace of the generated QCH file.  Needs  to  be  used  when
217       NAMESPACE is not used.
218
219       LINK_QCHS  specifies  a  list of other QCH targets which should be used
220       for creating references  to  API  documentation  of  code  in  external
221       libraries.   For  each target <qch> in the list these target properties
222       are expected to be defined: DOXYGEN_TAGFILE, QHP_NAMESPACE and QHP_VIR‐
223       TUALFOLDER.   If  any  of these is not existing, <qch> will be ignored.
224       Use the macro ecm_install_qch_export for exporting a target with  these
225       properties  with  the  CMake config of a library.  Any target <qch> can
226       also be one created before in the same buildsystem by another  call  of
227       ecm_add_qch.
228
229       PREDEFINED_MACROS specifies a list of C/C++ macros which should be han‐
230       dled as given by the API dox generation tool.  Examples are macros only
231       defined  in generated files, so whose definition might be not available
232       to the tool.
233
234       BLANK_MACROS specifies a list of C/C++  macro  names  which  should  be
235       ignored  by  the API dox generation tool and handled as if they resolve
236       to empty strings.  Examples are export macros only defined in generated
237       files, so whose definition might be not available to the tool.
238
239       CONFIG_TEMPLATE  specifies  a custom cmake template file for the config
240       file that is created to control the execution of the API dox generation
241       tool.   The  following  CMake  variables need to be used: ECM_QCH_DOXY‐
242       GEN_QHELPGENERATOR_EXECUTABLE, ECM_QCH_DOXYGEN_FILEPATH,  ECM_QCH_DOXY‐
243       GEN_TAGFILE.   The following CMake variables can be used: ECM_QCH_DOXY‐
244       GEN_PROJECTNAME, ECM_QCH_DOXYGEN_PROJECTVERSION, ECM_QCH_DOXYGEN_VIRTU‐
245       ALFOLDER,    ECM_QCH_DOXYGEN_FULLNAMESPACE,   ECM_QCH_DOXYGEN_TAGFILES,
246       ECM_QCH_DOXYGEN_WARN_LOGFILE, ECM_QCH_DOXYGEN_QUIET.  There is no guar‐
247       antue that the other CMake variables currently used in the default con‐
248       fig file template will also be  present  with  the  same  semantics  in
249       future versions of this macro.
250
251       VERBOSE  tells the API dox generation tool to be more verbose about its
252       activity.
253
254       Example usage:
255
256          ecm_add_qch(
257              MyLib_QCH
258              NAME MyLib
259              VERSION "0.42.0"
260              ORG_DOMAIN org.myorg
261              SOURCE_DIRS
262                  src
263              LINK_QCHS
264                  Qt5Core_QCH
265                  Qt5Xml_QCH
266                  Qt5Gui_QCH
267                  Qt5Widgets_QCH
268              BLANK_MACROS
269                  MyLib_EXPORT
270                  MyLib_DEPRECATED
271              TAGFILE_INSTALL_DESTINATION ${CMAKE_INSTALL_PREFIX}/share/docs/tags
272              QCH_INSTALL_DESTINATION ${CMAKE_INSTALL_PREFIX}/share/docs/qch
273              COMPONENT Devel
274          )
275
276       Example usage (with two QCH files, second linking first):
277
278          ecm_add_qch(
279              MyLib_QCH
280              NAME MyLib
281              VERSION ${MyLib_VERSION}
282              ORG_DOMAIN org.myorg
283              SOURCES ${MyLib_PUBLIC_HEADERS}
284              MD_MAINPAGE src/mylib/README.md
285              LINK_QCHS Qt5Core_QCH
286              TAGFILE_INSTALL_DESTINATION ${CMAKE_INSTALL_PREFIX}/share/docs/tags
287              QCH_INSTALL_DESTINATION ${CMAKE_INSTALL_PREFIX}/share/docs/qch
288              COMPONENT Devel
289          )
290          ecm_add_qch(
291              MyOtherLib_QCH
292              NAME MyOtherLib
293              VERSION ${MyOtherLib_VERSION}
294              ORG_DOMAIN org.myorg
295              SOURCES ${MyOtherLib_PUBLIC_HEADERS}
296              MD_MAINPAGE src/myotherlib/README.md
297              LINK_QCHS Qt5Core_QCH MyLib_QCH
298              TAGFILE_INSTALL_DESTINATION ${CMAKE_INSTALL_PREFIX}/share/docs/tags
299              QCH_INSTALL_DESTINATION ${CMAKE_INSTALL_PREFIX}/share/docs/qch
300              COMPONENT Devel
301          )
302
303          ecm_install_qch_export(
304              TARGETS [<name> [<name2> [...]]]
305              FILE <file>
306              DESTINATION <dest>
307              [COMPONENT <component>]
308          )
309
310       This macro creates and installs a CMake file <file> which  exports  the
311       given  QCH targets <name> etc., so they can be picked up by CMake-based
312       builds  of  other  software  that  also  generate  QCH   files   (using
313       ecm_add_qch) and which should include links to the QCH files created by
314       the given targets.  The installed CMake file <file> is expected  to  be
315       included  by the CMake config file created for the software the related
316       QCH files are documenting.
317
318       TARGETS specifies the QCH targets which should be exported. If a target
319       does  not  exist or does not have all needed properties, a warning will
320       be generated and the target skipped.  This behaviour  might  change  in
321       future versions to result in a fail instead.
322
323       FILE  specifies  the  name  of the created CMake file, typically with a
324       .cmake extension.
325
326       DESTINATION specifies the directory on disk to which the file  will  be
327       installed.  It  usually  is  the same as the one where the CMake config
328       files for this software are installed.
329
330       COMPONENT specifies the installation  component  name  with  which  the
331       install rule is associated.
332
333       Example usage:
334
335          ecm_install_qch_export(
336              TARGETS MyLib_QCH
337              FILE MyLibQCHTargets.cmake
338              DESTINATION "${CMAKE_INSTALL_PREFIX}/lib/cmake/MyLib"
339              COMPONENT Devel
340          )
341
342       Since 5.36.0.
343
344   ECMAddQtDesignerPlugin
345       This module provides the ecm_add_qtdesignerplugin function for generat‐
346       ing Qt Designer plugins for custom widgets. Each of  those  widgets  is
347       described using a second function ecm_qtdesignerplugin_widget.
348
349          ecm_add_qtdesignerplugin(<target_name>
350              NAME <name>
351              WIDGETS <widgetid> [<widgetid2> [...]]
352              LINK_LIBRARIES <lib> [<lib2> [...]]
353              INSTALL_DESTINATION <install_path>
354              [OUTPUT_NAME <output_name>]
355              [DEFAULT_GROUP <group>]
356              [DEFAULT_HEADER_CASE <SAME_CASE|LOWER_CASE|UPPER_CASE>]
357              [DEFAULT_HEADER_EXTENSION <header_extension>]
358              [DEFAULT_ICON_DIR <icon_dir>]
359              [INCLUDE_FILES <include_file> [<include_file2> [...]]]
360              [SOURCES <src> [<src2> [...]]]
361              [COMPONENT <component>]
362          )
363
364       NAME  specifies  the  base  name  to use in the generated sources.  The
365       default is <target_name>.
366
367       WIDGETS specifies the widgets the plugin should  support.  Each  widget
368       has  to be defined before by a call of ecm_qtdesignerplugin_widget with
369       the respective <widgetid>, in a scope including the current call.
370
371       LINK_LIBRARIES specifies the libraries to link against. This will be at
372       least the library providing the widget class(es).
373
374       INSTALL_DESTINATION specifies where the generated plugin binary will be
375       installed.
376
377       OUTPUT_NAME specifies the name of the plugin  binary.  The  default  is
378       “<target_name>”.
379
380       DEFAULT_GROUP specifies the default group in Qt Designer where the wid‐
381       gets will be placed. The default is “Custom”.
382
383       DEFAULT_HEADER_CASE specifies how the name of  the  header  is  derived
384       from the widget class name.  The default is “LOWER_CASE”.
385
386       DEFAULT_HEADER_EXTENSION specifies what file name extension is used for
387       the header file derived from the class name.  The default is “h”.
388
389       DEFAULT_ICON_DIR specifies what file name extension  is  used  for  the
390       header file derived from the class name.  The default is “pics”.
391
392       INCLUDE_FILES  specifies  additional  include files to include with the
393       generated source file. This can be needed for custom code used in  ini‐
394       tializing or creating widgets.
395
396       SOURCES  specifies  additional  source  files to build the plugin from.
397       This can be needed to support custom code used in initializing or  cre‐
398       ating widgets.
399
400       COMPONENT  specifies  the  installation  component  name with which the
401       install rules for the generated plugin are associated.
402
403          ecm_qtdesignerplugin_widget(<widgetid>
404              [CLASS_NAME <class_name>]
405              [INCLUDE_FILE <include_file>]
406              [CONTAINER]
407              [ICON <iconfile>]
408              [TOOLTIP <tooltip>]
409              [WHATSTHIS <whatsthis>]
410              [GROUP <group>]
411              [CREATE_WIDGET_CODE_FROM_VARIABLE <create_widget_code_variable>]
412              [INITIALIZE_CODE_FROM_VARIABLE <initialize_code_variable]
413              [DOM_XML_FROM_VARIABLE <dom_xml_variable>]
414              [IMPL_CLASS_NAME <impl_class_name>]
415              [CONSTRUCTOR_ARGS_CODE <constructor_args_code>]
416              [CONSTRUCTOR_ARGS_CODE_FROM_VARIABLE <constructor_args_code_variable>]
417          )
418
419       CLASS_NAME specifies the name of the  widget  class,  including  names‐
420       paces.  The default is “<widgetid>”.
421
422       INCLUDE_FILE  specifies  the  include file to use for the class of this
423       widget. The default is derived from <class_name> as configured  by  the
424       DEFAULT_HEADER_*  options  of  ecm_add_qtdesignerplugin, also replacing
425       any namespace separators with “/”.
426
427       CONTAINER specifies, if set, that this widget is a container for  other
428       widgets.
429
430       ICON  specifies  the  icon  file to use as symbol for this widget.  The
431       default is “{lowercased <class_name>}.png” in the default icons dir  as
432       configured  by the DEFAULT_ICON_DIR option of ecm_add_qtdesignerplugin,
433       if such a file exists.
434
435       TOOLTIP specifies the tooltip text to use for this widget.  Default  is
436       “<class_name> Widget”.
437
438       WHATSTHIS  specifies  the  What’s-This  text  to  use  for this widget.
439       Defaults to the tooltip.
440
441       GROUP specifies the group in Qt  Designer  where  the  widget  will  be
442       placed.   The  default is set as configured by the DEFAULT_GROUP option
443       of ecm_add_qtdesignerplugin.
444
445       CREATE_WIDGET_CODE_FROM_VARIABLE specifies the variable to get from the
446       C++  code  to  use as factory code to create an instance of the widget,
447       for the override of  QDesignerCustomWidgetInterface::createWidget(QWid‐
448       get*  parent).   The default is “return new <impl_class_name><construc‐
449       tor_args_code>;”.
450
451       INITIALIZE_CODE_FROM_VARIABLE specifies the variable to  get  from  the
452       C++  code  to  use  with  the  override  of QDesignerCustomWidgetInter‐
453       face::initialize(QDesignerFormEditorInterface* core).  The code has  to
454       use  the  present  class  member  m_initialized to track and update the
455       state. The default code simply sets m_initialized to true,  if  it  was
456       not before.
457
458       DOM_XML_FROM_VARIABLE  specifies the variable to get from the string to
459       use  with  the   optional   override   of   QDesignerCustomWidgetInter‐
460       face::domXml().  Default does not override.
461
462       IMPL_CLASS_NAME  specifies  the name of the widget class to use for the
463       widget instance with Qt Designer. The default is “<class_name>”.
464
465       CONSTRUCTOR_ARGS_CODE specifies the C++ code to use for the constructor
466       arguments  with  the  default of CREATE_WIDGET_CODE_FROM_VARIABLE. Note
467       that the parentheses are required. The default is “(parent)”.
468
469       CONSTRUCTOR_ARGS_CODE_FROM_VARIABLE specifies the variable to get  from
470       the  C++ code instead of passing it directly via CONSTRUCTOR_ARGS_CODE.
471       This can be needed if the code is more complex and  e.g.  includes  “;”
472       chars.
473
474       Example usage:
475
476          ecm_qtdesignerplugin_widget(FooWidget
477              TOOLTIP "Enables to browse foo."
478              GROUP "Views (Foo)"
479          )
480
481          set(BarWidget_CREATE_WIDGET_CODE
482          "
483              auto* widget = new BarWidget(parent);
484              widget->setBar("Example bar");
485              return widget;
486          ")
487
488          ecm_qtdesignerplugin_widget(BarWidget
489              TOOLTIP "Displays bars."
490              GROUP "Display (Foo)"
491              CREATE_WIDGET_CODE_FROM_VARIABLE BarWidget_CREATE_WIDGET_CODE
492          )
493
494          ecm_add_qtdesignerplugin(foowidgets
495              NAME FooWidgets
496              OUTPUT_NAME foo2widgets
497              WIDGETS
498                  FooWidget
499                  BarWidget
500              LINK_LIBRARIES
501                  Foo::Widgets
502              INSTALL_DESTINATION "${KDE_INSTALL_QTPLUGINDIR}/designer"
503              COMPONENT Devel
504          )
505
506       Since 5.62.0.
507
508   ECMAddTests
509       Convenience functions for adding tests.
510
511          ecm_add_tests(<sources> LINK_LIBRARIES <library> [<library> [...]]
512                                  [NAME_PREFIX <prefix>]
513                                  [GUI]
514                                  [TARGET_NAMES_VAR <target_names_var>]
515                                  [TEST_NAMES_VAR <test_names_var>])
516
517       A  convenience function for adding multiple tests, each consisting of a
518       single source file. For each file in <sources>,  an  executable  target
519       will  be  created (the name of which will be the basename of the source
520       file).  This  will  be  linked  against  the   libraries   given   with
521       LINK_LIBRARIES.  Each  executable will be added as a test with the same
522       name.
523
524       If NAME_PREFIX is given, this prefix will  be  prepended  to  the  test
525       names,  but  not  the  target  names.  As a result, it will not prevent
526       clashes between tests with the same name  in  different  parts  of  the
527       project,  but it can be used to give an indication of where to look for
528       a failing test.
529
530       If the flag GUI is passed the test binaries will  be  GUI  executables,
531       otherwise  the resulting binaries will be console applications (regard‐
532       less of the value of CMAKE_WIN32_EXECUTABLE or CMAKE_MACOSX_BUNDLE). Be
533       aware that this changes the executable entry point on Windows (although
534       some frameworks, such as Qt, abstract this difference away).
535
536       The TARGET_NAMES_VAR and TEST_NAMES_VAR  arguments,  if  given,  should
537       specify  a  variable  name  to receive the list of generated target and
538       test names, respectively. This makes it convenient to apply  properties
539       to  them  as  a  whole,  for  example, using set_target_properties() or
540       set_tests_properties().
541
542       The  generated  target   executables   will   have   the   effects   of
543       ecm_mark_as_test() (from the ECMMarkAsTest module) applied to it.
544
545          ecm_add_test(<sources> LINK_LIBRARIES <library> [<library> [...]]
546                                 [TEST_NAME <name>]
547                                 [NAME_PREFIX <prefix>]
548                                 [GUI])
549
550       This is a single-test form of ecm_add_tests that allows multiple source
551       files to be used for a single test. If  using  multiple  source  files,
552       TEST_NAME must be given; this will be used for both the target and test
553       names (and, as with ecm_add_tests(), the NAME_PREFIX argument  will  be
554       prepended to the test name).
555
556       Since pre-1.0.0.
557
558   ECMCoverageOption
559       Allow users to easily enable GCov code coverage support.
560
561       Code  coverage allows you to check how much of your codebase is covered
562       by your tests. This module makes it easy  to  build  with  support  for
563       GCov.
564
565       When this module is included, a BUILD_COVERAGE option is added (default
566       OFF). Turning this option on enables  GCC’s  coverage  instrumentation,
567       and links against libgcov.
568
569       Note that this will probably break the build if you are not using GCC.
570
571       Since 1.3.0.
572
573   ECMCreateQmFromPoFiles
574       WARNING:
575          This module is deprecated and will be removed by ECM 1.0. Use ECMPo‐
576          QmTools instead.
577
578       Generate QTranslator (.qm) catalogs from Gettext (.po) catalogs.
579
580          ecm_create_qm_from_po_files(PO_FILES <file1>... <fileN>
581                                      [CATALOG_NAME <catalog_name>]
582                                      [INSTALL_DESTINATION <install_destination>])
583
584       Creates the necessary rules to compile .po files into  .qm  files,  and
585       install them.
586
587       The  .qm  files  are  installed in <install_destination>/<lang>/LC_MES‐
588       SAGES, where <install_destination> is the INSTALL_DESTINATION  argument
589       and <lang> is extracted from the “Language” field inside the .po file.
590
591       INSTALL_DESTINATION  defaults to ${LOCALE_INSTALL_DIR} if defined, oth‐
592       erwise it uses ${CMAKE_INSTALL_LOCALEDIR} if that is defined, otherwise
593       it uses share/locale.
594
595       CATALOG_NAME  defines  the name of the installed .qm files. If set, .qm
596       files will be installed as <catalog_name>.qm. If not set .qm files will
597       be named after the name of their source .po file.
598
599       Setting  the catalog name is useful when all .po files for a target are
600       kept in a single source directory. For example,  the  “mylib”  probject
601       might keep all its translations in a “po” directory, like this:
602
603          po/
604              es.po
605              fr.po
606
607       Without  setting  CATALOG_NAME,  those  .po will be turned into .qm and
608       installed as:
609
610          share/locale/fr/LC_MESSAGES/fr.qm
611          share/locale/es/LC_MESSAGES/es.qm
612
613       If CATALOG_NAME is set to “mylib”, they will be installed as:
614
615          share/locale/fr/LC_MESSAGES/mylib.qm
616          share/locale/es/LC_MESSAGES/mylib.qm
617
618       Which is what the loader created by ecm_create_qm_loader() expects.
619
620       ecm_create_qm_from_po_files() creates a “translation” target. This tar‐
621       get builds all .po files into .qm files.
622
623          ecm_create_qm_loader(<source_files_var> <catalog_name>)
624
625       ecm_create_qm_loader()  generates a C++ file which ensures translations
626       are automatically loaded at startup. The  path  of  the  .cpp  file  is
627       appended to <source_files_var>.  Typical usage is like:
628
629          set(mylib_SRCS foo.cpp bar.cpp)
630          ecm_create_qm_loader(mylib_SRCS mylib)
631          add_library(mylib ${mylib_SRCS})
632
633       This  generates  a C++ file which loads “mylib.qm” at startup, assuming
634       it has been installed by ecm_create_qm_from_po_files(), and compiles it
635       into mylib.
636
637       Since pre-1.0.0.
638
639   ECMEnableSanitizers
640       Enable compiler sanitizer flags.
641
642       The following sanitizers are supported:
643
644       · Address Sanitizer
645
646       · Memory Sanitizer
647
648       · Thread Sanitizer
649
650       · Leak Sanitizer
651
652       · Undefined Behaviour Sanitizer
653
654       All  of  them  are implemented in Clang, depending on your version, and
655       there is an work in progress in GCC, where some of them  are  currently
656       implemented.
657
658       This  module will check your current compiler version to see if it sup‐
659       ports the sanitizers that you want to enable
660
661   Usage
662       Simply add:
663
664          include(ECMEnableSanitizers)
665
666       to your CMakeLists.txt. Note that this module is included in KDECompil‐
667       erSettings,  so  projects using that module do not need to also include
668       this one.
669
670       The sanitizers are not  enabled  by  default.  Instead,  you  must  set
671       ECM_ENABLE_SANITIZERS  (either in your CMakeLists.txt or on the command
672       line) to a semicolon-separated list of sanitizers you wish  to  enable.
673       The options are:
674
675       · address
676
677       · memory
678
679       · thread
680
681       · leak
682
683       · undefined
684
685       · fuzzer
686
687       The sanitizers “address”, “memory” and “thread” are mutually exclusive.
688       You cannot enable two of them in the same build.
689
690       “leak” requires the  “address” sanitizer.
691
692       NOTE:
693          To reduce the overhead induced by the instrumentation of  the  sani‐
694          tizers,  it  is  advised  to  enable  compiler optimizations (-O1 or
695          higher).
696
697   Example
698       This is an example of usage:
699
700          mkdir build
701          cd build
702          cmake -DECM_ENABLE_SANITIZERS='address;leak;undefined' ..
703
704       NOTE:
705          Most of the sanitizers will require Clang. To enable it, use:
706
707              -DCMAKE_CXX_COMPILER=clang++
708
709       Since 1.3.0.
710
711   ECMFindModuleHelpers
712       Helper  macros  for  find  modules:   ecm_find_package_version_check(),
713       ecm_find_package_parse_components()      and      ecm_find_package_han‐
714       dle_library_components().
715
716          ecm_find_package_version_check(<name>)
717
718       Prints warnings if the CMake version or the  project’s  required  CMake
719       version is older than that required by extra-cmake-modules.
720
721          ecm_find_package_parse_components(<name>
722              RESULT_VAR <variable>
723              KNOWN_COMPONENTS <component1> [<component2> [...]]
724              [SKIP_DEPENDENCY_HANDLING])
725
726       This  macro will populate <variable> with a list of components found in
727       <name>_FIND_COMPONENTS, after checking that all those components are in
728       the  list  of KNOWN_COMPONENTS; if there are any unknown components, it
729       will  print  an  error  or  warning  (depending   on   the   value   of
730       <name>_FIND_REQUIRED) and call return().
731
732       The  order of components in <variable> is guaranteed to match the order
733       they are listed in the KNOWN_COMPONENTS argument.
734
735       If SKIP_DEPENDENCY_HANDLING is not set, for each component the variable
736       <name>_<component>_component_deps  will be checked for dependent compo‐
737       nents.  If <component> is listed in  <name>_FIND_COMPONENTS,  then  all
738       its (transitive) dependencies will also be added to <variable>.
739
740          ecm_find_package_handle_library_components(<name>
741              COMPONENTS <component> [<component> [...]]
742              [SKIP_DEPENDENCY_HANDLING])
743              [SKIP_PKG_CONFIG])
744
745       Creates  an  imported library target for each component.  The operation
746       of this macro depends on the presence of a number of CMake variables.
747
748       The <name>_<component>_lib variable should contain  the  name  of  this
749       library, and <name>_<component>_header variable should contain the name
750       of a header file associated with it (whatever relative path is normally
751       passed to ‘#include’). <name>_<component>_header_subdir variable can be
752       used to specify which subdirectory of the include path the headers will
753       be  found  in.   ecm_find_package_components() will then search for the
754       library and include directory (creating  appropriate  cache  variables)
755       and create an imported library target named <name>::<component>.
756
757       Additional variables can be used to provide additional information:
758
759       If  SKIP_PKG_CONFIG, the <name>_<component>_pkg_config variable is set,
760       and pkg-config is found, the pkg-config module given by  <name>_<compo‐
761       nent>_pkg_config  will  be  searched  for  and  used to help locate the
762       library and header file.  It will also be used  to  set  <name>_<compo‐
763       nent>_VERSION.
764
765       Note  that if version information is found via pkg-config, <name>_<com‐
766       ponent>_FIND_VERSION can be set to require  a  particular  version  for
767       each component.
768
769       If  SKIP_DEPENDENCY_HANDLING  is  not set, the INTERFACE_LINK_LIBRARIES
770       property of the imported target for <component> will be set to  contain
771       the  imported  targets  for  the  components  listed  in <name>_<compo‐
772       nent>_component_deps.  <component>_FOUND will also be set to  false  if
773       any  of  the  compoments  in  <name>_<component>_component_deps are not
774       found.   This  requires  the  components  in  <name>_<component>_compo‐
775       nent_deps to be listed before <component> in the COMPONENTS argument.
776
777       The following variables will be set:
778
779       <name>_TARGETS
780              the imported targets
781
782       <name>_LIBRARIES
783              the found libraries
784
785       <name>_INCLUDE_DIRS
786              the combined required include directories for the components
787
788       <name>_DEFINITIONS
789              the “other” CFLAGS provided by pkg-config, if any
790
791       <name>_VERSION
792              the  value of <name>_<component>_VERSION for the first component
793              that has this variable set (note that  components  are  searched
794              for  in  the order they are passed to the macro), although if it
795              is already set, it will not be altered
796
797       Note that these variables  are  never  cleared,  so  if  ecm_find_pack‐
798       age_handle_library_components() is called multiple times with different
799       components (typically because of multiple  find_package()  calls)  then
800       <name>_TARGETS,  for example, will contain all the targets found in any
801       call (although no duplicates).
802
803       Since pre-1.0.0.
804
805   ECMGenerateExportHeader
806       This module provides the ecm_generate_export_header function for gener‐
807       ating export macros for libraries with version-based control over visi‐
808       bility of and compiler warnings for  deprecated  API  for  the  library
809       user, as well as over excluding deprecated API and their implementation
810       when building the library itself.
811
812       For preparing some values useful in the  context  it  also  provides  a
813       function ecm_export_header_format_version.
814
815          ecm_generate_export_header(<library_target_name>
816              VERSION <version>
817              [BASE_NAME <base_name>]
818              [GROUP_BASE_NAME <group_base_name>]
819              [EXPORT_MACRO_NAME <export_macro_name>]
820              [EXPORT_FILE_NAME <export_file_name>]
821              [DEPRECATED_MACRO_NAME <deprecated_macro_name>]
822              [NO_EXPORT_MACRO_NAME <no_export_macro_name>]
823              [INCLUDE_GUARD_NAME <include_guard_name>]
824              [STATIC_DEFINE <static_define>]
825              [PREFIX_NAME <prefix_name>]
826              [DEPRECATED_BASE_VERSION <deprecated_base_version>]
827              [DEPRECATION_VERSIONS <deprecation_version> [<deprecation_version2> [...]]]
828              [EXCLUDE_DEPRECATED_BEFORE_AND_AT <exclude_deprecated_before_and_at_version>]
829              [NO_DEFINITION_EXPORT_TO_BUILD_INTERFACE]
830              [CUSTOM_CONTENT_FROM_VARIABLE <variable>]
831          )
832
833       VERSION  specifies  the  version  of  the  library, given in the format
834       “<major>.<minor>.<patchlevel>”.
835
836       GROUP_BASE_NAME specifies the name  to  use  for  the  macros  defining
837       library  group default values. If set, this will generate code support‐
838       ing  <group_base_name>_NO_DEPRECATED_WARNINGS,   <group_base_name>_DIS‐
839       ABLE_DEPRECATED_BEFORE_AND_AT,       <group_base_name>_DEPRECATED_WARN‐
840       INGS_SINCE  and <group_base_name>_NO_DEPRECATED (see  below).   If  not
841       set, the generated code will ignore any such macros.
842
843       DEPRECATED_BASE_VERSION  specifies  the  default  version before and at
844       which  deprecated  API  is  disabled.  The  default  is  the  value  of
845       “<exclude_deprecated_before_and_at_version>”  if set, or “<major>.0.0”,
846       with <major> taken from <version>.
847
848       DEPRECATION_VERSIONS specifies versions in “<major>.<minor>” format  in
849       which  API was declared deprecated. Any version used with the generated
850       macro <prefix_name><base_name>_DEPRECATED_VERSION(major,  minor,  text)
851       needs to be listed here, otherwise the macro will fail to work.
852
853       EXCLUDE_DEPRECATED_BEFORE_AND_AT  specifies  the  version for which all
854       API deprecated before and at should be excluded  from  the  build  com‐
855       pletely.   Possible values are “0” (default), “CURRENT” (which resolves
856       to   <version>)    and    a    version    string    in    the    format
857       “<major>.<minor>.<patchlevel>”.
858
859       NO_DEFINITION_EXPORT_TO_BUILD_INTERFACE  specifies  that the definition
860       <prefix_name><uppercase_base_name>_DISABLE_DEPRECATED_BEFORE_AND_AT
861       will  not  be set in the public interface of the library inside its own
862       build.  The default is that it is set,  to  the  version  specified  by
863       EXCLUDE_DEPRECATED_BEFORE_AND_AT, so e.g. test and examples part of the
864       project automatically build against the full API included in the build.
865
866       The function ecm_generate_export_header defines C++ preprocessor macros
867       in  the  generated  export  header,  some for use in the sources of the
868       library the header is generated for, other for use by projects  linking
869       agsinst the library.
870
871       The  macros for use in the library C++ sources are these, next to those
872       also defined by GenerateExportHeader:
873
874       <prefix_name><uppercase_base_name>_DEPRECATED_VERSION(major,     minor,
875       text)
876              to    use    to   conditionally   set   a   <prefix_name><upper‐
877              case_base_name>_DEPRECATED macro for a class, struct or function
878              (other  elements  to be supported in future versions), depending
879              on the visibility macro flags set (see below)
880
881       <prefix_name><uppercase_base_name>_ENABLE_DEPRECATED_SINCE(major,
882       minor)
883              evaluates  to  TRUE  or  FALSE depending on the visibility macro
884              flags set (see below). To be used mainly with #if/#endif to mark
885              sections of code which should be included depending on the visi‐
886              bility requested.
887
888       <prefix_name><uppercase_base_name>_BUILD_DEPRECATED_SINCE(major, minor)
889              evaluates  to  TRUE  or  FALSE  depending  on   the   value   of
890              EXCLUDE_DEPRECATED_BEFORE_AND_AT.   To   be   used  mainly  with
891              #if/#endif to mark sections of two types of code: implementation
892              code  for  deprecated API and declaration code of deprecated API
893              which only may be disabled at build time of the library  for  BC
894              reasons (e.g. virtual methods, see notes below).
895
896       <prefix_name><uppercase_base_name>_EXCLUDE_DEPRECATED_BEFORE_AND_AT
897              holds  the  version used to exclude deprecated API at build time
898              of the library.
899
900       The macros used to control visibility when building against the library
901       are:
902
903       <prefix_name><uppercase_base_name>_DISABLE_DEPRECATED_BEFORE_AND_AT
904              definition  to set to a value in single hex number version nota‐
905              tion (0x<major><minor><patchlevel>).
906
907       <prefix_name><uppercase_base_name>_NO_DEPRECATED
908              flag to define to disable all deprecated API, being  a  shortcut
909              for  settings  <prefix_name><uppercase_base_name>_DISABLE_DEPRE‐
910              CATED_BEFORE_AND_AT to the current version.  If  both  are  set,
911              this flag overrules.
912
913       <prefix_name><uppercase_base_name>_DEPRECATED_WARNINGS_SINCE
914              definition  to set to a value in single hex number version nota‐
915              tion (0x<major><minor><patchlevel>). Warnings will be only acti‐
916              vated  for  API  deprecated  up to and including the version. If
917              <prefix_name><uppercase_base_name>_DISABLE_DEPRE‐
918              CATED_BEFORE_AND_AT  is set (directly or via the group default),
919              it will default to that version, resulting in no warnings.  Oth‐
920              erwise the default is the current version, resulting in warnings
921              for all deprecated API.
922
923       <prefix_name><uppercase_base_name>_NO_DEPRECATED_WARNINGS
924              flag to define to disable  all  deprecation  warnings,  being  a
925              shortcut  for  setting <prefix_name><uppercase_base_name>_DEPRE‐
926              CATED_WARNINGS_SINCE to “0”. If both are set,  this  flag  over‐
927              rules.
928
929       When  the  GROUP_BASE_NAME  has been used, the same macros but with the
930       given <group_base_name> prefix are available to define the defaults  of
931       these macros, if not explicitely set.
932
933       Note: The tricks applied here for hiding deprecated API to the compiler
934       when building against a library do not work for all deprecated API:
935
936       · virtual methods need to stay visible to the compiler to build  proper
937         virtual method tables for subclasses
938
939       · enumerators from enums cannot be simply removed, as this changes auto
940         values of following enumerators, also can poke  holes  in  enumerator
941         series used as index into tables
942
943       In  such  cases  the  API  can  be  only  “hidden” at build time of the
944       library, itself, by generated hard coded macro  settings,  using  <pre‐
945       fix_name><uppercase_base_name>_BUILD_DEPRECATED_SINCE(major, minor).
946
947       Examples:
948
949       Preparing  a  library “Foo” created by target “foo”, which is part of a
950       group of libraries “Bar”, where some API of  “Foo”  got  deprecated  at
951       versions 5.0 & 5.12:
952
953          ecm_generate_export_header(foo
954              GROUP_BASE_NAME BAR
955              VERSION ${FOO_VERSION}
956              DEPRECATION_VERSIONS 5.0 5.12
957          )
958
959       In  the  library “Foo” sources in the headers the API would be prepared
960       like this, using the generated macros  FOO_ENABLE_DEPRECATED_SINCE  and
961       FOO_DEPRECATED_VERSION:
962
963          #include <foo_export.h>
964
965          #if FOO_ENABLE_DEPRECATED_SINCE(5, 0)
966          /**
967            * @deprecated Since 5.0
968            */
969          FOO_DEPRECATED_VERSION(5, 0, "Use doFoo2()")
970          FOO_EXPORT void doFoo();
971          #endif
972
973          #if FOO_ENABLE_DEPRECATED_SINCE(5, 12)
974          /**
975            * @deprecated Since 5.12
976            */
977          FOO_DEPRECATED_VERSION(5, 12, "Use doBar2()")
978          FOO_EXPORT void doBar();
979          #endif
980
981       Projects  linking  against  the “Foo” library can control which part of
982       its deprecated API should be hidden to the compiler by adding a defini‐
983       tion  using the FOO_DISABLE_DEPRECATED_BEFORE_AND_AT macro variable set
984       to the desired value (in version hex number notation):
985
986          add_definitions(-DFOO_DISABLE_DEPRECATED_BEFORE_AND_AT=0x050000)
987
988       Or using the macro variable of the group:
989
990          add_definitions(-DBAR_DISABLE_DEPRECATED_BEFORE_AND_AT=0x050000)
991
992       If both are specified, FOO_DISABLE_DEPRECATED_BEFORE_AND_AT  will  take
993       precedence.
994
995       To  build  a  variant  of a library with some deprecated API completely
996       left out from the build, not only optionally  invisible  to  consumers,
997       one  uses  the EXCLUDE_DEPRECATED_BEFORE_AND_AT parameter. This is best
998       combined with a cached CMake variable.
999
1000          set(EXCLUDE_DEPRECATED_BEFORE_AND_AT 0 CACHE STRING "Control the range of deprecated API excluded from the build [default=0].")
1001
1002          ecm_generate_export_header(foo
1003              VERSION ${FOO_VERSION}
1004              EXCLUDE_DEPRECATED_BEFORE_AND_AT ${EXCLUDE_DEPRECATED_BEFORE_AND_AT}
1005              DEPRECATION_VERSIONS 5.0 5.12
1006          )
1007
1008       The macros used in the headers for library  consumers  are  reused  for
1009       disabling  the  API excluded in the build of the library. For disabling
1010       the implementation of that API as well as for disabling deprecated  API
1011       which only can be disabled at build time of the library for BC reasons,
1012       one uses the generated macro FOO_BUILD_DEPRECATED_SINCE, like this:
1013
1014          #include <foo_export.h>
1015
1016          enum Bars {
1017              One,
1018          #if FOO_BUILD_DEPRECATED_SINCE(5, 0)
1019              Two,
1020          #endif
1021              Three,
1022          };
1023
1024          #if FOO_ENABLE_DEPRECATED_SINCE(5, 0)
1025          /**
1026            * @deprecated Since 5.0
1027            */
1028          FOO_DEPRECATED_VERSION(5, 0, "Use doFoo2()")
1029          FOO_EXPORT void doFoo();
1030          #endif
1031
1032          #if FOO_ENABLE_DEPRECATED_SINCE(5, 12)
1033          /**
1034            * @deprecated Since 5.12
1035            */
1036          FOO_DEPRECATED_VERSION(5, 12, "Use doBar2()")
1037          FOO_EXPORT void doBar();
1038          #endif
1039
1040          class FOO_EXPORT Foo {
1041          public:
1042          #if FOO_BUILD_DEPRECATED_SINCE(5, 0)
1043              /**
1044                * @deprecated Since 5.0
1045                */
1046              FOO_DEPRECATED_VERSION(5, 0, "Feature removed")
1047              virtual void doWhat();
1048          #endif
1049          };
1050
1051          #if FOO_BUILD_DEPRECATED_SINCE(5, 0)
1052          void doFoo()
1053          {
1054              // [...]
1055          }
1056          #endif
1057
1058          #if FOO_BUILD_DEPRECATED_SINCE(5, 12)
1059          void doBar()
1060          {
1061              // [...]
1062          }
1063          #endif
1064
1065          #if FOO_BUILD_DEPRECATED_SINCE(5, 0)
1066          void Foo::doWhat()
1067          {
1068              // [...]
1069          }
1070          #endif
1071
1072       So e.g. if EXCLUDE_DEPRECATED_BEFORE_AND_AT is set to “5.0.0”, the enu‐
1073       merator  Two as well as the methods ::doFoo() and Foo::doWhat() will be
1074       not available to library consumers. The methods will not have been com‐
1075       piled  into  the library binary, and the declarations will be hidden to
1076       the compiler, FOO_DISABLE_DEPRECATED_BEFORE_AND_AT also cannot be  used
1077       to reactivate them.
1078
1079       When  using the NO_DEFINITION_EXPORT_TO_BUILD_INTERFACE and the project
1080       for the “Foo” library includes also tests and examples linking  against
1081       the library and using deprecated API (like tests covering it), one bet‐
1082       ter explicitely  sets  FOO_DISABLE_DEPRECATED_BEFORE_AND_AT  for  those
1083       targets  to the version before and at which all deprecated API has been
1084       excluded from  the  build.   Even  more  when  building  against  other
1085       libraries  from  the same group “Bar” and disabling some deprecated API
1086       of  those  libraries   using   the   group   macro   BAR_DISABLE_DEPRE‐
1087       CATED_BEFORE_AND_AT, which also works as default for FOO_DISABLE_DEPRE‐
1088       CATED_BEFORE_AND_AT.
1089
1090       To   get   the   hex   number   style   value    the    helper    macro
1091       ecm_export_header_format_version() will be used:
1092
1093          set(EXCLUDE_DEPRECATED_BEFORE_AND_AT 0 CACHE STRING "Control what part of deprecated API is excluded from build [default=0].")
1094
1095          ecm_generate_export_header(foo
1096              VERSION ${FOO_VERSION}
1097              GROUP_BASE_NAME BAR
1098              EXCLUDE_DEPRECATED_BEFORE_AND_AT ${EXCLUDE_DEPRECATED_BEFORE_AND_AT}
1099              NO_DEFINITION_EXPORT_TO_BUILD_INTERFACE
1100              DEPRECATION_VERSIONS 5.0 5.12
1101          )
1102
1103          ecm_export_header_format_version(${EXCLUDE_DEPRECATED_BEFORE_AND_AT}
1104              CURRENT_VERSION ${FOO_VERSION}
1105              HEXNUMBER_VAR foo_no_deprecated_before_and_at
1106          )
1107
1108          # disable all deprecated API up to 5.9.0 from all other libs of group "BAR" that we use ourselves
1109          add_definitions(-DBAR_DISABLE_DEPRECATED_BEFORE_AND_AT=0x050900)
1110
1111          add_executable(app app.cpp)
1112          target_link_libraries(app foo)
1113          target_compile_definitions(app
1114               PRIVATE "FOO_DISABLE_DEPRECATED_BEFORE_AND_AT=${foo_no_deprecated_before_and_at}")
1115
1116       Since 5.64.0.
1117
1118   ECMGenerateHeaders
1119       Generate C/C++ CamelCase forwarding headers.
1120
1121          ecm_generate_headers(<camelcase_forwarding_headers_var>
1122              HEADER_NAMES <CamelCaseName> [<CamelCaseName> [...]]
1123              [ORIGINAL <CAMELCASE|LOWERCASE>]
1124              [HEADER_EXTENSION <header_extension>]
1125              [OUTPUT_DIR <output_dir>]
1126              [PREFIX <prefix>]
1127              [REQUIRED_HEADERS <variable>]
1128              [COMMON_HEADER <HeaderName>]
1129              [RELATIVE <relative_path>])
1130
1131       For  each  CamelCase header name passed to HEADER_NAMES, a file of that
1132       name will be generated that will include a version with .h or, if  set,
1133       .<header_extension> appended.  For example, the generated header ClassA
1134       will include classa.h (or ClassA.h, see ORIGINAL).  If a  CamelCaseName
1135       consists of multiple comma-separated files, e.g.  ClassA,ClassB,ClassC,
1136       then multiple camelcase header files will be generated which are  redi‐
1137       rects  to the first header file.  The file locations of these generated
1138       headers will be stored in <camelcase_forwarding_headers_var>.
1139
1140       ORIGINAL specifies how the name of the original header is written: low‐
1141       ercased or also camelcased.  The default is LOWERCASE. Since 1.8.0.
1142
1143       HEADER_EXTENSION  specifies  what  file  name extension is used for the
1144       header files.  The default is “h”. Since 5.48.0.
1145
1146       PREFIX places the generated headers in subdirectories.  This should  be
1147       a CamelCase name like KParts, which will cause the CamelCase forwarding
1148       headers to be placed in the KParts directory  (e.g.  KParts/Part).   It
1149       will also, for the convenience of code in the source distribution, gen‐
1150       erate  forwarding  headers  based   on   the   original   names   (e.g.
1151       kparts/part.h).   This  allows includes like "#include <kparts/part.h>"
1152       to be used before installation, as long as the include_directories  are
1153       set appropriately.
1154
1155       OUTPUT_DIR  specifies where the files will be generated; this should be
1156       within the build  directory.  By  default,  ${CMAKE_CURRENT_BINARY_DIR}
1157       will be used.  This option can be used to avoid file conflicts.
1158
1159       REQUIRED_HEADERS  specifies  an  output  variable  name  where  all the
1160       required headers will  be  appended  so  that  they  can  be  installed
1161       together  with the generated ones.  This is mostly intended as a conve‐
1162       nience so that adding a new header to a project only requires  specify‐
1163       ing  the  CamelCase  variant  in  the CMakeLists.txt file; the original
1164       variant will then be added to this variable.
1165
1166       COMMON_HEADER generates an additional convenience header which includes
1167       all other header files.
1168
1169       The RELATIVE argument indicates where the original headers can be found
1170       relative to CMAKE_CURRENT_SOURCE_DIR.  It does not affect the generated
1171       CamelCase  forwarding  files,  but  ecm_generate_headers() uses it when
1172       checking that the original header exists, and  to  generate  originally
1173       named forwarding headers when PREFIX is set.
1174
1175       To  allow other parts of the source distribution (eg: tests) to use the
1176       generated headers before installation, it may be desirable to  set  the
1177       INCLUDE_DIRECTORIES property for the library target to output_dir.  For
1178       example, if OUTPUT_DIR is CMAKE_CURRENT_BINARY_DIR (the  default),  you
1179       could do
1180
1181          target_include_directories(MyLib PUBLIC "$<BUILD_INTERFACE:${CMAKE_CURRENT_BINARY_DIR}>")
1182
1183       Example usage (without PREFIX):
1184
1185          ecm_generate_headers(
1186              MyLib_FORWARDING_HEADERS
1187              HEADERS
1188                  MLFoo
1189                  MLBar
1190                  # etc
1191              REQUIRED_HEADERS MyLib_HEADERS
1192              COMMON_HEADER MLGeneral
1193          )
1194          install(FILES ${MyLib_FORWARDING_HEADERS} ${MyLib_HEADERS}
1195                  DESTINATION ${CMAKE_INSTALL_PREFIX}/include
1196                  COMPONENT Devel)
1197
1198       Example usage (with PREFIX):
1199
1200          ecm_generate_headers(
1201              MyLib_FORWARDING_HEADERS
1202              HEADERS
1203                  Foo
1204                  # several classes are contained in bar.h, so generate
1205                  # additional files
1206                  Bar,BarList
1207                  # etc
1208              PREFIX MyLib
1209              REQUIRED_HEADERS MyLib_HEADERS
1210          )
1211          install(FILES ${MyLib_FORWARDING_HEADERS}
1212                  DESTINATION ${CMAKE_INSTALL_PREFIX}/include/MyLib
1213                  COMPONENT Devel)
1214          install(FILES ${MyLib_HEADERS}
1215                  DESTINATION ${CMAKE_INSTALL_PREFIX}/include/mylib
1216                  COMPONENT Devel)
1217
1218       Since pre-1.0.0.
1219
1220   ECMGeneratePkgConfigFile
1221       Generate a pkg-config file for the benefit of autotools-based projects.
1222
1223          ecm_generate_pkgconfig_file(BASE_NAME <baseName>
1224                                [LIB_NAME <libName>]
1225                                [DEPS "<dep> [<dep> [...]]"]
1226                                [FILENAME_VAR <filename_variable>]
1227                                [INCLUDE_INSTALL_DIR <dir>]
1228                                [LIB_INSTALL_DIR <dir>]
1229                                [DEFINES -D<variable=value>...]
1230                                [DESCRIPTION <library description>] # since 5.41.0
1231                                [INSTALL])
1232
1233       BASE_NAME is the name of the module. It’s the name projects will use to
1234       find the module.
1235
1236       LIB_NAME is the name of the library that is being  exported.  If  unde‐
1237       fined,  it  will default to the BASE_NAME. That means the LIB_NAME will
1238       be set as the name field as well as the library to link to.
1239
1240       FILENAME_VAR is specified with a  variable  name.  This  variable  will
1241       receive  the  location  of  the  generated file will be set, within the
1242       build directory. This way it can be used in  case  some  processing  is
1243       required. See also INSTALL.
1244
1245       INCLUDE_INSTALL_DIR  specifies where the includes will be installed. If
1246       it’s  not   specified,   it   will   default   to   INSTALL_INCLUDEDIR,
1247       CMAKE_INSTALL_INCLUDEDIR or just “include/” in case they are specified,
1248       with the BASE_NAME postfixed.
1249
1250       LIB_INSTALL_DIR specifies where the library is being installed. If it’s
1251       not specified, it will default to LIB_INSTALL_DIR, CMAKE_INSTALL_LIBDIR
1252       or just “lib/” in case they are specified.
1253
1254       DEFINES is a list of preprocessor defines that it is recommended  users
1255       of the library pass to the compiler when using it.
1256
1257       DESCRIPTION  describes  what  this  library  is. If it’s not specified,
1258       CMake will first try to get the description from the metainfo.yaml file
1259       or will create one based on LIB_NAME. Since 5.41.0.
1260
1261       INSTALL  will  cause the module to be installed to the pkgconfig subdi‐
1262       rectory of LIB_INSTALL_DIR, unless the ECM_PKGCONFIG_INSTALL_DIR  cache
1263       variable  is  set  to  something different. Note that the first call to
1264       ecm_generate_pkgconfig_file  with  the  INSTALL  argument  will   cause
1265       ECM_PKGCONFIG_INSTALL_DIR  to  be set to the cache, and will be used in
1266       any subsequent calls.
1267
1268       To properly use this macro a version needs to be set. To  retrieve  it,
1269       ECM_PKGCONFIG_INSTALL_DIR  uses  PROJECT_VERSION.  To  set  it, use the
1270       project() command (only available since  CMake  3.0)  or  the  ecm_set‐
1271       up_version() macro.
1272
1273       Example usage:
1274
1275          ecm_generate_pkgconfig_file(
1276              BASE_NAME KF5Archive
1277              DEPS Qt5Core
1278              FILENAME_VAR pkgconfig_filename
1279              INSTALL
1280          )
1281
1282       Since 1.3.0.
1283
1284   ECMGeneratePriFile
1285       Generate a .pri file for the benefit of qmake-based projects.
1286
1287       As  well  as the function below, this module creates the cache variable
1288       ECM_MKSPECS_INSTALL_DIR and sets the default value to  mkspecs/modules.
1289       This  assumes Qt and the current project are both installed to the same
1290       non-system prefix.  Packagers who use -DCMAKE_INSTALL_PREFIX=/usr  will
1291       certainly   want  to  set  ECM_MKSPECS_INSTALL_DIR  to  something  like
1292       share/qt5/mkspecs/modules.
1293
1294       The main thing is that this  should  be  the  modules  subdirectory  of
1295       either  the default qmake mkspecs directory or of a directory that will
1296       be in the $QMAKEPATH environment variable when qmake is run.
1297
1298          ecm_generate_pri_file(BASE_NAME <baseName>
1299                                LIB_NAME <libName>
1300                                [DEPS "<dep> [<dep> [...]]"]
1301                                [FILENAME_VAR <filename_variable>]
1302                                [INCLUDE_INSTALL_DIR <dir>]
1303                                [LIB_INSTALL_DIR <dir>])
1304
1305       If your CMake project produces a Qt-based library, you may expect there
1306       to  be  applications  that  wish to use it that use a qmake-based build
1307       system, rather than a CMake-based one.  Creating a .pri file will  make
1308       use  of  your  library  convenient  for them, in much the same way that
1309       CMake config files make things convenient for CMake-based applications.
1310
1311       ecm_generate_pri_file() generates just such a file.   It  requires  the
1312       PROJECT_VERSION_STRING  variable  to  be set.  This is typically set by
1313       ECMSetupVersion, although the project()  command  in  CMake  3.0.0  and
1314       later can also set this.
1315
1316       BASE_NAME  specifies  the name qmake project (.pro) files should use to
1317       refer to the library (eg: KArchive).   LIB_NAME  is  the  name  of  the
1318       actual  library  to  link to (ie: the first argument to add_library()).
1319       DEPS is a space-separated list of the base  names  of  other  libraries
1320       (for Qt libraries, use the same names you use with the QT variable in a
1321       qmake project file, such as “core” for QtCore).  FILENAME_VAR specifies
1322       the name of a variable to store the path to the generated file in.
1323
1324       INCLUDE_INSTALL_DIR is the path (relative to CMAKE_INSTALL_PREFIX) that
1325       include   files   will   be    installed    to.    It    defaults    to
1326       ${INCLUDE_INSTALL_DIR}/<baseName>  if  the INCLUDE_INSTALL_DIR variable
1327       is set. If that variable is not set, the CMAKE_INSTALL_INCLUDEDIR vari‐
1328       able  is  used  instead,  and  if  neither  are  set  include  is used.
1329       LIB_INSTALL_DIR operates similarly for the  installation  location  for
1330       libraries;  it  defaults to ${LIB_INSTALL_DIR}, ${CMAKE_INSTALL_LIBDIR}
1331       or lib, in that order.
1332
1333       Example usage:
1334
1335          ecm_generate_pri_file(
1336              BASE_NAME KArchive
1337              LIB_NAME KF5KArchive
1338              DEPS "core"
1339              FILENAME_VAR pri_filename
1340          )
1341          install(FILES ${pri_filename} DESTINATION ${ECM_MKSPECS_INSTALL_DIR})
1342
1343       A qmake-based project that wished to use this would then do:
1344
1345          QT += KArchive
1346
1347       in their .pro file.
1348
1349       Since pre-1.0.0.
1350
1351   ECMGenerateQmlTypes
1352       Generates plugins.qmltypes files for QML plugins.
1353
1354          ecm_generate_qmltypes(<org.kde.pluginname> 1.3
1355                                DESTINATION <${KDE_INSTALL_QMLDIR}/org/kde/pluginname>)
1356
1357       Makes it possible to generate plugins.qmltypes files for the QML  plug‐
1358       ins  that  our project offers. These files offer introspection upon our
1359       plugin and are useful for integrating with IDE language support of  our
1360       plugin.  It  offers information about the objects its methods and their
1361       argument types.
1362
1363       The developer will be in charge of making sure that these files are  up
1364       to  date.   The  plugin.qmltypes file will sit in the source directory.
1365       This function will include the code that installs the file in the right
1366       place  and  a  small  unit  test named qmltypes-pluginname-version that
1367       makes sure that it doesn’t need updating.
1368
1369       Since 5.33.0
1370
1371   ECMInstallIcons
1372       Installs icons, sorting them into the correct directories according  to
1373       the FreeDesktop.org icon naming specification.
1374
1375          ecm_install_icons(ICONS <icon> [<icon> [...]]
1376                            DESTINATION <icon_install_dir>
1377                            [LANG <l10n_code>]
1378                            [THEME <theme>])
1379
1380       The given icons, whose names must match the pattern:
1381
1382          <size>-<group>-<name>.<ext>
1383
1384       will  be  installed  to  the  appropriate  subdirectory  of DESTINATION
1385       according to the FreeDesktop.org icon naming scheme. By  default,  they
1386       are installed to the “hicolor” theme, but this can be changed using the
1387       THEME argument.  If the icons are localized, the LANG argument  can  be
1388       used to install them in a locale-specific directory.
1389
1390       <size>  is  a  numeric pixel size (typically 16, 22, 32, 48, 64, 128 or
1391       256) or sc for scalable (SVG) files, <group> is  one  of  the  standard
1392       FreeDesktop.org  icon  groups  (actions,  animations, apps, categories,
1393       devices, emblems, emotes, intl, mimetypes, places, status) and <ext> is
1394       one of .png, .mng or .svgz.
1395
1396       The typical installation directory is share/icons.
1397
1398          ecm_install_icons(ICONS 22-actions-menu_new.png
1399                            DESTINATION share/icons)
1400
1401       The  above  code  will  install  the  file  22-actions-menu_new.png  as
1402       ${CMAKE_INSTALL_PREFIX}/share/icons/<theme>/22x22/actions/menu_new.png
1403
1404       Users   of   the   KDEInstallDirs    module    would    normally    use
1405       ${KDE_INSTALL_ICONDIR}  as  the  DESTINATION, while users of the GNUIn‐
1406       stallDirs module should use ${CMAKE_INSTALL_DATAROOTDIR}/icons.
1407
1408       An old form of arguments will also be accepted:
1409
1410          ecm_install_icons(<icon_install_dir> [<l10n_code>])
1411
1412       This matches files named like:
1413
1414          <theme><size>-<group>-<name>.<ext>
1415
1416       where <theme> is one of * hi for hicolor * lo for locolor * cr for  the
1417       Crystal  icon  theme * ox for the Oxygen icon theme * br for the Breeze
1418       icon theme
1419
1420       With this syntax, the file hi22-actions-menu_new.png would be installed
1421       into <icon_install_dir>/hicolor/22x22/actions/menu_new.png
1422
1423       Since pre-1.0.0.
1424
1425   ECMMarkAsTest
1426       Marks a target as only being required for tests.
1427
1428          ecm_mark_as_test(<target1> [<target2> [...]])
1429
1430       This  will  cause  the  specified targets to not be built unless either
1431       BUILD_TESTING is set to ON or the user invokes the buildtests target.
1432
1433       BUILD_TESTING is created as a cache variable by the CTest module and by
1434       the KDECMakeSettings module.
1435
1436       Since pre-1.0.0.
1437
1438   ECMMarkNonGuiExecutable
1439       Marks an executable target as not being a GUI application.
1440
1441          ecm_mark_nongui_executable(<target1> [<target2> [...]])
1442
1443       This  will  indicate  to CMake that the specified targets should not be
1444       included in a MACOSX_BUNDLE and should not  be  WIN32_EXECUTABLEs.   On
1445       platforms other than MacOS X or Windows, this will have no effect.
1446
1447       Since pre-1.0.0.
1448
1449   ECMOptionalAddSubdirectory
1450       Make subdirectories optional.
1451
1452          ecm_optional_add_subdirectory(<dir>)
1453
1454       This  behaves like add_subdirectory(), except that it does not complain
1455       if the directory does not exist.  Additionally, if the  directory  does
1456       exist,  it  creates  an option to allow the user to skip it. The option
1457       will be named BUILD_<dir>.
1458
1459       This is useful for “meta-projects” that combine several mostly-indepen‐
1460       dent sub-projects.
1461
1462       If  the  CMake  variable  DISABLE_ALL_OPTIONAL_SUBDIRECTORIES is set to
1463       TRUE for the first CMake run on the project, all  optional  subdirecto‐
1464       ries  will be disabled by default (but can of course be enabled via the
1465       respective options).  For  example,  the  following  will  disable  all
1466       optional subdirectories except the one named “foo”:
1467
1468          cmake -DDISABLE_ALL_OPTIONAL_SUBDIRECTORIES=TRUE -DBUILD_foo=TRUE myproject
1469
1470       Since pre-1.0.0.
1471
1472   ECMPackageConfigHelpers
1473       Helper macros for generating CMake package config files.
1474
1475       write_basic_package_version_file()  is  the same as the one provided by
1476       the CMakePackageConfigHelpers module in CMake; see that module’s  docu‐
1477       mentation for more information.
1478
1479          ecm_configure_package_config_file(<input> <output>
1480              INSTALL_DESTINATION <path>
1481              [PATH_VARS <var1> [<var2> [...]]
1482              [NO_SET_AND_CHECK_MACRO]
1483              [NO_CHECK_REQUIRED_COMPONENTS_MACRO])
1484
1485       This  behaves  in  the same way as configure_package_config_file() from
1486       CMake 2.8.12, except that it adds an extra  helper  macro:  find_depen‐
1487       dency().  It  is highly recommended that you read the documentation for
1488       CMakePackageConfigHelpers  for  more  information,  particularly   with
1489       regard to the PATH_VARS argument.
1490
1491       Note  that there is no argument that will disable the find_dependency()
1492       macro; if you do not require this macro, you should use configure_pack‐
1493       age_config_file from the CMakePackageConfigHelpers module.
1494
1495       CMake  3.0 includes a CMakeFindDependencyMacro module that provides the
1496       find_dependency() macro (which you can include() in your package config
1497       file), so this file is only useful for projects wishing to provide con‐
1498       fig files that will work with CMake 2.8.12.
1499
1500   Additional Config File Macros
1501          find_dependency(<dep> [<version> [EXACT]])
1502
1503       find_dependency() should be used  instead  of  find_package()  to  find
1504       package  dependencies.   It  forwards the correct parameters for EXACT,
1505       QUIET and REQUIRED which were passed  to  the  original  find_package()
1506       call.  It also sets an informative diagnostic message if the dependency
1507       could not be found.
1508
1509       Since pre-1.0.0.
1510
1511   ECMPoQmTools
1512       This    module    provides    the    ecm_process_po_files_as_qm     and
1513       ecm_install_po_files_as_qm  functions  for generating QTranslator (.qm)
1514       catalogs from Gettext  (.po)  catalogs,  and  the  ecm_create_qm_loader
1515       function  for generating the necessary code to load them in a Qt appli‐
1516       cation or library.
1517
1518          ecm_process_po_files_as_qm(<lang> [ALL]
1519                                     [INSTALL_DESTINATION <install_destination>]
1520                                     PO_FILES <pofile> [<pofile> [...]])
1521
1522       Compile .po files into .qm files for the given language.
1523
1524       If INSTALL_DESTINATION  is  given,  the  .qm  files  are  installed  in
1525       <install_destination>/<lang>/LC_MESSAGES.  Typically, <install_destina‐
1526       tion> is set to share/locale.
1527
1528       ecm_process_po_files_as_qm creates a “translations” target. This target
1529       builds  all .po files into .qm files.  If ALL is specified, these rules
1530       are added to the “all” target (and so the .qm files will  be  built  by
1531       default).
1532
1533          ecm_create_qm_loader(<source_files_var> <catalog_name>)
1534
1535       Generates  C++ code which ensures translations are automatically loaded
1536       at startup. The generated files are appended to <source_files_var>.
1537
1538       It assumes that the .qm file for the language code <lang> is  installed
1539       as     <sharedir>/locale/<lang>/LC_MESSAGES/<catalog_name>.qm,    where
1540       <sharedir> is one of the directories given by  the  GenericDataLocation
1541       of QStandardPaths.
1542
1543       Typical usage is like:
1544
1545          set(mylib_SRCS foo.cpp bar.cpp)
1546          ecm_create_qm_loader(mylib_SRCS mylib)
1547          add_library(mylib ${mylib_SRCS})
1548
1549          ecm_install_po_files_as_qm(<podir>)
1550
1551       Searches for .po files and installs them to the standard location.
1552
1553       This is a convenience function which relies on all .po files being kept
1554       in <podir>/<lang>/, where <lang> is the  language  the  .po  files  are
1555       written in.
1556
1557       For example, given the following directory structure:
1558
1559          po/
1560            fr/
1561              mylib.po
1562
1563       ecm_install_po_files_as_qm(po)  compiles  mylib.po  into  mylib.qm  and
1564       installs it in <install_destination>/fr/LC_MESSAGES.  <install_destina‐
1565       tion>  defaults  to ${LOCALE_INSTALL_DIR} if defined, otherwise it uses
1566       ${CMAKE_INSTALL_LOCALEDIR}  if  that  is  defined,  otherwise  it  uses
1567       share/locale.
1568
1569       Since pre-1.0.0.
1570
1571   ECMQMLModules
1572       Find  QML  import modules through a find_qmlmodule() call.  It uses the
1573       qmlplugindump application to find the plugins and sets them up as  run‐
1574       time dependencies.
1575
1576       This  is useful so that when we configure a project we are noified when
1577       some QML imports are not present in the system, thus having the  appli‐
1578       cation compilable but fail at runtime.
1579
1580          ecm_find_qmlmodule(<module_name> <version>...)
1581
1582       Any  further  arguments  passed will be forwarded into a find_package()
1583       call. See find_package() documentation for more information.
1584
1585       Usage example:
1586
1587          ecm_find_qmlmodule(org.kde.kirigami 2.1)
1588
1589       Since 5.38.0.
1590
1591   ECMQtDeclareLoggingCategory
1592       Generate declarations for logging categories in Qt5.
1593
1594          ecm_qt_declare_logging_category(<sources_var>
1595                                          HEADER <filename>
1596                                          IDENTIFIER <identifier>
1597                                          CATEGORY_NAME <category_name>
1598                                          [DEFAULT_SEVERITY
1599                                               <Debug|Info|Warning|
1600                                                Critical|Fatal>])
1601
1602       A header file, <filename>, will be generated along with a corresponding
1603       source file, which will be added to <sources_var>. These will provide a
1604       QLoggingCategory category that can be referred to from C++  code  using
1605       <identifier>, and from the logging configuration using <category_name>.
1606
1607       If <filename> is not absolute, it will be taken relative to the current
1608       binary directory.
1609
1610       If the code is compiled against Qt 5.4 or later,  by  default  it  will
1611       only   log   output   that  is  at  least  the  severity  specified  by
1612       DEFAULT_SEVERITY, or “Info” level if  DEFAULT_SEVERITY  is  not  given.
1613       Note that, due to a bug in Qt 5.5, “Info” may be treated as more severe
1614       than “Fatal”.
1615
1616       <identifier> may include namespaces (eg: foo::bar::IDENT).
1617
1618       Since 5.14.0.
1619
1620   ECMSetupQtPluginMacroNames
1621       Instruct CMake’s automoc about C++ preprocessor macros used  to  define
1622       Qt-style plugins.
1623
1624          ecm_setup_qtplugin_macro_names(
1625              [JSON_NONE <macro_name> [<macro_name> [...]]]
1626              [JSON_ARG1 <macro_name> [<macro_name> [...]]]
1627              [JSON_ARG2 <macro_name> [<macro_name> [...]]]
1628              [JSON_ARG3 <macro_name> [<macro_name> [...]]]
1629              [CONFIG_CODE_VARIABLE <variable_name>] )
1630
1631       CMake’s  automoc  needs  some  support when parsing C++ source files to
1632       detect whether moc should be run on those files and if there  are  also
1633       dependencies on other files, like those with Qt plugin metadata in JSON
1634       format. Because automoc just greps overs the  raw  plain  text  of  the
1635       sources  without  any C++ preprocessor-like processing.  CMake in newer
1636       versions provides the variables CMAKE_AUTOMOC_DEPEND_FILTERS (CMake  >=
1637       3.9.0)  and  CMAKE_AUTOMOC_MACRO_NAMES  (CMake  >=  3.10)  to allow the
1638       developer to assist automoc.
1639
1640       This macro cares for the explicit setup needed for those variables  for
1641       common cases of C++ preprocessor macros used for Qt-style plugins.
1642
1643       JSON_NONE lists the names of C++ preprocessor macros for Qt-style plug‐
1644       ins which do not refer to external files with the plugin metadata.
1645
1646       JSON_ARG1 lists the names of C++ preprocessor macros for Qt-style plug‐
1647       ins  where  the first argument to the macro is the name of the external
1648       file with the plugin metadata.
1649
1650       JSON_ARG2 is the same as JSON_ARG1 but with the  file  name  being  the
1651       second argument.
1652
1653       JSON_ARG3  is  the  same  as JSON_ARG1 but with the file name being the
1654       third argument.
1655
1656       CONFIG_CODE_VARIABLE specifies the name of the variable which will  get
1657       set  as value some generated CMake code for instructing automoc for the
1658       given macro names, as useful in an installed  CMake  config  file.  The
1659       variable  can  then  be  used  as usual in the template file for such a
1660       CMake config file, by @<variable_name>@.
1661
1662       Example usage:
1663
1664       Given some plugin-oriented Qt-based software which defines a custom C++
1665       preprocessor  macro  EXPORT_MYPLUGIN  for  declaring the central plugin
1666       object:
1667
1668          #define EXPORT_MYPLUGIN_WITH_JSON(classname, jsonFile) \
1669          class classname : public QObject \
1670          { \
1671              Q_OBJECT \
1672              Q_PLUGIN_METADATA(IID "myplugin" FILE jsonFile) \
1673              explicit classname() {} \
1674          };
1675
1676       In the CMake buildsystem of the library one calls
1677
1678          ecm_setup_qtplugin_macro_names(
1679              JSON_ARG2
1680                 EXPORT_MYPLUGIN_WITH_JSON
1681          )
1682
1683       to instruct automoc about the usage of that macro in the sources of the
1684       library itself.
1685
1686       Given  the  software  installs  a library including the header with the
1687       macro definition and a CMake config file, so 3rd-party can create addi‐
1688       tional  plugins by linking against the library, one passes additionally
1689       the name of a variable which shall be  set  as  value  the  CMake  code
1690       needed to instruct automoc about the usage of that macro.
1691
1692          ecm_setup_qtplugin_macro_names(
1693              JSON_ARG2
1694                 EXPORT_MYPLUGIN_WITH_JSON
1695              CONFIG_CODE_VARIABLE
1696                 PACKAGE_SETUP_AUTOMOC_VARIABLES
1697          )
1698
1699       This  variable  then  is used in the template file (e.g.  MyProjectCon‐
1700       fig.cmake.in) for the libary’s installed CMake config file and that way
1701       will  ensure  that  in  the  3rd-party  plugin’s buildsystem automoc is
1702       instructed as well as needed:
1703
1704          @PACKAGE_SETUP_AUTOMOC_VARIABLES@
1705
1706       Since 5.45.0.
1707
1708   ECMSetupVersion
1709       Handle library version information.
1710
1711          ecm_setup_version(<version>
1712                            VARIABLE_PREFIX <prefix>
1713                            [SOVERSION <soversion>]
1714                            [VERSION_HEADER <filename>]
1715                            [PACKAGE_VERSION_FILE <filename> [COMPATIBILITY <compat>]] )
1716
1717       This parses a version string and sets up  a  standard  set  of  version
1718       variables.  It can optionally also create a C version header file and a
1719       CMake package version file to install along with the library.
1720
1721       If the <version> argument is of the  form  <major>.<minor>.<patch>  (or
1722       <major>.<minor>.<patch>.<tweak>),  The  following  CMake  variables are
1723       set:
1724
1725          <prefix>_VERSION_MAJOR  - <major>
1726          <prefix>_VERSION_MINOR  - <minor>
1727          <prefix>_VERSION_PATCH  - <patch>
1728          <prefix>_VERSION        - <version>
1729          <prefix>_VERSION_STRING - <version> (for compatibility: use <prefix>_VERSION instead)
1730          <prefix>_SOVERSION      - <soversion>, or <major> if SOVERSION was not given
1731
1732       If CMake policy CMP0048 is not NEW, the following CMake variables  will
1733       also be set:
1734
1735          PROJECT_VERSION_MAJOR   - <major>
1736          PROJECT_VERSION_MINOR   - <minor>
1737          PROJECT_VERSION_PATCH   - <patch>
1738          PROJECT_VERSION         - <version>
1739          PROJECT_VERSION_STRING  - <version> (for compatibility: use PROJECT_VERSION instead)
1740
1741       If  the  VERSION_HEADER  option is used, a simple C header is generated
1742       with the given filename. If filename is a relative path, it  is  inter‐
1743       preted  as  relative to CMAKE_CURRENT_BINARY_DIR.  The generated header
1744       contains the following macros:
1745
1746          <prefix>_VERSION_MAJOR  - <major> as an integer
1747          <prefix>_VERSION_MINOR  - <minor> as an integer
1748          <prefix>_VERSION_PATCH  - <patch> as an integer
1749          <prefix>_VERSION_STRING - <version> as a C string
1750          <prefix>_VERSION        - the version as an integer
1751
1752       <prefix>_VERSION has <patch> in the bottom 8 bits, <minor> in the  next
1753       8  bits  and  <major>  in  the  remaining  bits.  Note that <patch> and
1754       <minor> must be less than 256.
1755
1756       If the PACKAGE_VERSION_FILE option is used, a simple CMake package ver‐
1757       sion file is created using the write_basic_package_version_file() macro
1758       provided by CMake. It should be installed in the same location  as  the
1759       Config.cmake  file of the library so that it can be found by find_pack‐
1760       age().  If the filename is a relative path, it is interpreted as  rela‐
1761       tive  to CMAKE_CURRENT_BINARY_DIR. The optional COMPATIBILITY option is
1762       forwarded  to  write_basic_package_version_file(),  and   defaults   to
1763       AnyNewerVersion.
1764
1765       If  CMake  policy CMP0048 is NEW, an alternative form of the command is
1766       available:
1767
1768          ecm_setup_version(PROJECT
1769                            [VARIABLE_PREFIX <prefix>]
1770                            [SOVERSION <soversion>]
1771                            [VERSION_HEADER <filename>]
1772                            [PACKAGE_VERSION_FILE <filename>] )
1773
1774       This will use the version information set  by  the  project()  command.
1775       VARIABLE_PREFIX  defaults  to the project name.  Note that PROJECT must
1776       be the first argument.  In all other  respects,  it  behaves  like  the
1777       other form of the command.
1778
1779       Since pre-1.0.0.
1780
1781       COMPATIBILITY option available since 1.6.0.
1782
1783   ECMSourceVersionControl
1784       Tries  to  determine  whether  the source is under version control (git
1785       clone, svn checkout, etc).
1786
1787       ECM_SOURCE_UNDER_VERSION_CONTROL is set when indication is  found  that
1788       CMAKE_SOURCE_DIR is under version control.
1789
1790       Since 5.63
1791
1792   ECMUninstallTarget
1793       Add an uninstall target.
1794
1795       By  including  this  module,  an uninstall target will be added to your
1796       CMake project. This will remove all files installed (or updated)  by  a
1797       previous  invocation  of  the  install target. It will not remove files
1798       created or modified by an install(SCRIPT) or install(CODE) command; you
1799       should  create  a  custom  uninstallation  target  for  these  and  use
1800       add_dependency to make the uninstall target depend on it:
1801
1802          include(ECMUninstallTarget)
1803          install(SCRIPT install-foo.cmake)
1804          add_custom_target(uninstall_foo COMMAND ${CMAKE_COMMAND} -P uninstall-foo.cmake)
1805          add_dependency(uninstall uninstall_foo)
1806
1807       The target will fail if the install target has not yet been run (so  it
1808       is  not  possible  to run CMake on the project and then immediately run
1809       the uninstall target).
1810
1811       WARNING:
1812          CMake deliberately does not provide an uninstall target  by  default
1813          on  the  basis that such a target has the potential to remove impor‐
1814          tant files from a user’s computer. Use with caution.
1815
1816       Since 1.7.0.
1817
1818   ECMUseFindModules
1819       Selectively use some of the find modules provided  by  extra-cmake-mod‐
1820       ules.
1821
1822       This  module  is  automatically  available once extra-cmake-modules has
1823       been found,  so  it  is  not  necessary  to  include(ECMUseFindModules)
1824       explicitly.
1825
1826          ecm_use_find_modules(DIR <dir>
1827                               MODULES module1.cmake [module2.cmake [...]]
1828                               [NO_OVERRIDE])
1829
1830       This  allows selective use of the find modules provided by ECM, includ‐
1831       ing deferring to CMake’s versions of those  modules  if  it  has  them.
1832       Rather than adding ${ECM_FIND_MODULE_DIR} to CMAKE_MODULE_PATH, you use
1833       ecm_use_find_modules() to copy the modules you want to a local  (build)
1834       directory, and add that to CMAKE_MODULE_PATH.
1835
1836       The find modules given to MODULES will be copied to the directory given
1837       by DIR (which should be located in  ${CMAKE_BINARY_DIR}  and  added  to
1838       CMAKE_MODULE_PATH).   If  NO_OVERRIDE  is  given, only modules not also
1839       provided by CMake will be copied.
1840
1841       Example:
1842
1843          find_package(ECM REQUIRED)
1844          ecm_use_find_modules(
1845              DIR ${CMAKE_BINARY_DIR}/cmake
1846              MODULES FindEGL.cmake
1847              NO_OVERRIDE
1848          )
1849          set(CMAKE_MODULE_PATH ${CMAKE_BINARY_DIR}/cmake)
1850
1851       This example will make FindEGL.cmake available  in  your  project,  but
1852       only as long as it is not yet part of CMake. Calls to find_package(EGL)
1853       will then make use of this copied module (or the  CMake  module  if  it
1854       exists).
1855
1856       Another  possible  use for this macro is to take copies of find modules
1857       that can be installed along with config files if they are required as a
1858       dependency  (for example, if targets provided by the find module are in
1859       the link interface of a library).
1860
1861       Since pre-1.0.0.
1862
1863   ECMWinResolveSymlinks
1864       Resolve pseudo-symlinks created by git when cloning on Windows.
1865
1866          ecm_win_resolve_symlinks(<dir>)
1867
1868       When git checks out a repository with UNIX symlinks on Windows machine,
1869       it  creates a text file for each symlink, containing a relative path to
1870       the real file.  This function would  recursively  walk  over  specified
1871       directory  and  replace  pseudo-symlinks with corresponding real file’s
1872       contents. It would then run git update-index –assume-unchanged on  them
1873       to trick git.
1874
1875       This is useful for projects like “breeze-icons” that contain many iden‐
1876       tical icons implemented as symlinks.
1877
1878       Since 5.28
1879

SEE ALSO

1881       ecm(7), ecm-find-modules(7), ecm-kde-modules(7)
1882
1884       KDE Developers
1885
1886
1887
1888
18895.64                             Nov 08, 2019                   ECM-MODULES(7)
Impressum