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              [IMAGE_DIRS <idir> [<idir2> [...]]]
133              [EXAMPLE_DIRS <edir> [<edir2> [...]]]
134              [ORG_DOMAIN <domain>]
135              [NAMESPACE <namespace>]
136              [LINK_QCHS <qch> [<qch2> [...]]]
137              [PREDEFINED_MACROS <macro[=content]> [<macro2[=content]> [...]]]
138              [BLANK_MACROS <macro> [<macro2> [...]]]
139              [CONFIG_TEMPLATE <configtemplate_file>]
140              [VERBOSE]
141          )
142
143       This macro adds a target called <target_name> for the  creation  of  an
144       API  documentation manual in the QCH format from the given sources.  It
145       currently uses doxygen, future versions  might  optionally  also  allow
146       other  tools.   Next  to the QCH file the target will generate a corre‐
147       sponding doxygen tag file, which enables creating links from other doc‐
148       umentation into the generated QCH file.
149
150       It  is recommended to make the use of this macro optional, by depending
151       the call to ecm_add_qch on a CMake option being set, with a  name  like
152       BUILD_QCH  and being TRUE by default. This will allow the developers to
153       saves resources on normal source development build  cycles  by  setting
154       this option to FALSE.
155
156       The  macro  will  set the target properties DOXYGEN_TAGFILE, QHP_NAMES‐
157       PACE, QHP_NAMESPACE_VERSIONED, QHP_VIRTUALFOLDER and LINK_QCHS  to  the
158       respective  values,  to allow other code access to them, e.g. the macro
159       ecm_install_qch_export.  To enable the use of the target  <target_name>
160       as  item  for  LINK_QCHS  in  further  ecm_add_qch calls in the current
161       build, additionally a target  property  DOXYGEN_TAGFILE_BUILD  is  set,
162       with  the  path  of  the created doxygen tag file in the build dir.  If
163       existing, ecm_add_qch will use this property instead of DOXYGEN_TAGFILE
164       for access to the tags file.
165
166       NAME specifies the name for the generated documentation.
167
168       VERSION  specifies  the version of the library for which the documenta‐
169       tion is created.
170
171       BASE_NAME specifies the base name for the generated files.  The default
172       basename is <name>.
173
174       SOURCE_DIRS  specifies  the  dirs (incl. subdirs) with the source files
175       for which the API documentation should be generated.  Dirs can be rela‐
176       tive  to  the current source dir. Dependencies to the files in the dirs
177       are not tracked currently, other than with the SOURCES argument. So  do
178       not  use for sources generated during the build.  Needs to be used when
179       SOURCES or CONFIG_TEMPLATE are not used.
180
181       SOURCES specifies the source files  for  which  the  API  documentation
182       should  be generated.  Needs to be used when SOURCE_DIRS or CONFIG_TEM‐
183       PLATE are not used.
184
185       MD_MAINPAGE specifies a file in Markdown format that should be used  as
186       main  page.  This  page  will  overrule  any  \mainpage  command in the
187       included sources.
188
189       IMAGE_DIRS specifies the dirs which contain images that are included in
190       the documentation. Dirs can be relative to the current source dir.
191
192       EXAMPLE_DIRS  specifies  the  dirs  which  contain  examples  that  are
193       included in the documentation. Dirs can  be  relative  to  the  current
194       source dir.
195
196       QCH_INSTALL_DESTINATION  specifies where the generated QCH file will be
197       installed.
198
199       TAGFILE_INSTALL_DESTINATION specifies where the generated tag file will
200       be installed.
201
202       COMPONENT  specifies  the  installation  component  name with which the
203       install rules for the generated QCH file and tag file are associated.
204
205       NAMESPACE can be used to set a custom namespace <namespace> of the gen‐
206       erated QCH file. The namepspace is used as the unique id by QHelpEngine
207       (cmp.     https://doc.qt.io/qt-5/qthelpproject.html#namespace).     The
208       default namespace is <domain>.<name>.  Needs to be used when ORG_DOMAIN
209       is not used.
210
211       ORG_DOMAIN can be used to define the organization domain prefix for the
212       default  namespace  of  the  generated QCH file.  Needs to be used when
213       NAMESPACE is not used.
214
215       LINK_QCHS specifies a list of other QCH targets which  should  be  used
216       for  creating  references  to  API  documentation  of  code in external
217       libraries.  For each target <qch> in the list these  target  properties
218       are expected to be defined: DOXYGEN_TAGFILE, QHP_NAMESPACE and QHP_VIR‐
219       TUALFOLDER.  If any of these is not existing, <qch>  will  be  ignored.
220       Use  the macro ecm_install_qch_export for exporting a target with these
221       properties with the CMake config of a library.  Any  target  <qch>  can
222       also  be  one created before in the same buildsystem by another call of
223       ecm_add_qch.
224
225       PREDEFINED_MACROS specifies a list of C/C++ macros which should be han‐
226       dled as given by the API dox generation tool.  Examples are macros only
227       defined in generated files, so whose definition might be not  available
228       to the tool.
229
230       BLANK_MACROS  specifies  a  list  of  C/C++ macro names which should be
231       ignored by the API dox generation tool and handled as if  they  resolve
232       to empty strings.  Examples are export macros only defined in generated
233       files, so whose definition might be not available to the tool.
234
235       CONFIG_TEMPLATE specifies a custom cmake template file for  the  config
236       file that is created to control the execution of the API dox generation
237       tool.  The following CMake variables need  to  be  used:  ECM_QCH_DOXY‐
238       GEN_QHELPGENERATOR_EXECUTABLE,  ECM_QCH_DOXYGEN_FILEPATH, ECM_QCH_DOXY‐
239       GEN_TAGFILE.  The following CMake variables can be used:  ECM_QCH_DOXY‐
240       GEN_PROJECTNAME, ECM_QCH_DOXYGEN_PROJECTVERSION, ECM_QCH_DOXYGEN_VIRTU‐
241       ALFOLDER,   ECM_QCH_DOXYGEN_FULLNAMESPACE,    ECM_QCH_DOXYGEN_TAGFILES,
242       ECM_QCH_DOXYGEN_WARN_LOGFILE, ECM_QCH_DOXYGEN_QUIET.  There is no guar‐
243       antue that the other CMake variables currently used in the default con‐
244       fig  file  template  will  also  be  present with the same semantics in
245       future versions of this macro.
246
247       VERBOSE tells the API dox generation tool to be more verbose about  its
248       activity.
249
250       Example usage:
251
252          ecm_add_qch(
253              MyLib_QCH
254              NAME MyLib
255              VERSION "0.42.0"
256              ORG_DOMAIN org.myorg
257              SOURCE_DIRS
258                  src
259              LINK_QCHS
260                  Qt5Core_QCH
261                  Qt5Xml_QCH
262                  Qt5Gui_QCH
263                  Qt5Widgets_QCH
264              BLANK_MACROS
265                  MyLib_EXPORT
266                  MyLib_DEPRECATED
267              TAGFILE_INSTALL_DESTINATION ${CMAKE_INSTALL_PREFIX}/share/docs/tags
268              QCH_INSTALL_DESTINATION ${CMAKE_INSTALL_PREFIX}/share/docs/qch
269              COMPONENT Devel
270          )
271
272       Example usage (with two QCH files, second linking first):
273
274          ecm_add_qch(
275              MyLib_QCH
276              NAME MyLib
277              VERSION ${MyLib_VERSION}
278              ORG_DOMAIN org.myorg
279              SOURCES ${MyLib_PUBLIC_HEADERS}
280              MD_MAINPAGE src/mylib/README.md
281              LINK_QCHS Qt5Core_QCH
282              TAGFILE_INSTALL_DESTINATION ${CMAKE_INSTALL_PREFIX}/share/docs/tags
283              QCH_INSTALL_DESTINATION ${CMAKE_INSTALL_PREFIX}/share/docs/qch
284              COMPONENT Devel
285          )
286          ecm_add_qch(
287              MyOtherLib_QCH
288              NAME MyOtherLib
289              VERSION ${MyOtherLib_VERSION}
290              ORG_DOMAIN org.myorg
291              SOURCES ${MyOtherLib_PUBLIC_HEADERS}
292              MD_MAINPAGE src/myotherlib/README.md
293              LINK_QCHS Qt5Core_QCH MyLib_QCH
294              TAGFILE_INSTALL_DESTINATION ${CMAKE_INSTALL_PREFIX}/share/docs/tags
295              QCH_INSTALL_DESTINATION ${CMAKE_INSTALL_PREFIX}/share/docs/qch
296              COMPONENT Devel
297          )
298
299          ecm_install_qch_export(
300              TARGETS [<name> [<name2> [...]]]
301              FILE <file>
302              DESTINATION <dest>
303              [COMPONENT <component>]
304          )
305
306       This  macro  creates and installs a CMake file <file> which exports the
307       given QCH targets <name> etc., so they can be picked up by  CMake-based
308       builds   of   other  software  that  also  generate  QCH  files  (using
309       ecm_add_qch) and which should include links to the QCH files created by
310       the  given  targets.  The installed CMake file <file> is expected to be
311       included by the CMake config file created for the software the  related
312       QCH files are documenting.
313
314       TARGETS specifies the QCH targets which should be exported. If a target
315       does not exist or does not have all needed properties, a  warning  will
316       be  generated  and  the target skipped.  This behaviour might change in
317       future versions to result in a fail instead.
318
319       FILE specifies the name of the created CMake  file,  typically  with  a
320       .cmake extension.
321
322       DESTINATION  specifies  the directory on disk to which the file will be
323       installed. It usually is the same as the one  where  the  CMake  config
324       files for this software are installed.
325
326       COMPONENT  specifies  the  installation  component  name with which the
327       install rule is associated.
328
329       Example usage:
330
331          ecm_install_qch_export(
332              TARGETS MyLib_QCH
333              FILE MyLibQCHTargets.cmake
334              DESTINATION "${CMAKE_INSTALL_PREFIX}/lib/cmake/MyLib"
335              COMPONENT Devel
336          )
337
338       Since 5.36.0.
339
340   ECMAddTests
341       Convenience functions for adding tests.
342
343          ecm_add_tests(<sources> LINK_LIBRARIES <library> [<library> [...]]
344                                  [NAME_PREFIX <prefix>]
345                                  [GUI]
346                                  [TARGET_NAMES_VAR <target_names_var>]
347                                  [TEST_NAMES_VAR <test_names_var>])
348
349       A convenience function for adding multiple tests, each consisting of  a
350       single  source  file.  For each file in <sources>, an executable target
351       will be created (the name of which will be the basename of  the  source
352       file).   This   will   be  linked  against  the  libraries  given  with
353       LINK_LIBRARIES. Each executable will be added as a test with  the  same
354       name.
355
356       If  NAME_PREFIX  is  given,  this  prefix will be prepended to the test
357       names, but not the target names. As  a  result,  it  will  not  prevent
358       clashes  between  tests  with  the  same name in different parts of the
359       project, but it can be used to give an indication of where to look  for
360       a failing test.
361
362       If  the  flag  GUI is passed the test binaries will be GUI executables,
363       otherwise the resulting binaries will be console applications  (regard‐
364       less of the value of CMAKE_WIN32_EXECUTABLE or CMAKE_MACOSX_BUNDLE). Be
365       aware that this changes the executable entry point on Windows (although
366       some frameworks, such as Qt, abstract this difference away).
367
368       The  TARGET_NAMES_VAR  and  TEST_NAMES_VAR  arguments, if given, should
369       specify a variable name to receive the list  of  generated  target  and
370       test  names, respectively. This makes it convenient to apply properties
371       to them as a  whole,  for  example,  using  set_target_properties()  or
372       set_tests_properties().
373
374       The   generated   target   executables   will   have   the  effects  of
375       ecm_mark_as_test() (from the ECMMarkAsTest module) applied to it.
376
377          ecm_add_test(<sources> LINK_LIBRARIES <library> [<library> [...]]
378                                 [TEST_NAME <name>]
379                                 [NAME_PREFIX <prefix>]
380                                 [GUI])
381
382       This is a single-test form of ecm_add_tests that allows multiple source
383       files  to  be  used  for a single test. If using multiple source files,
384       TEST_NAME must be given; this will be used for both the target and test
385       names  (and,  as with ecm_add_tests(), the NAME_PREFIX argument will be
386       prepended to the test name).
387
388       Since pre-1.0.0.
389
390   ECMCoverageOption
391       Allow users to easily enable GCov code coverage support.
392
393       Code coverage allows you to check how much of your codebase is  covered
394       by  your  tests.  This  module  makes it easy to build with support for
395       GCov.
396
397       When this module is included, a BUILD_COVERAGE option is added (default
398       OFF).  Turning  this  option on enables GCC’s coverage instrumentation,
399       and links against libgcov.
400
401       Note that this will probably break the build if you are not using GCC.
402
403       Since 1.3.0.
404
405   ECMCreateQmFromPoFiles
406       WARNING:
407          This module is deprecated and will be removed by ECM 1.0. Use ECMPo‐
408          QmTools instead.
409
410       Generate QTranslator (.qm) catalogs from Gettext (.po) catalogs.
411
412          ecm_create_qm_from_po_files(PO_FILES <file1>... <fileN>
413                                      [CATALOG_NAME <catalog_name>]
414                                      [INSTALL_DESTINATION <install_destination>])
415
416       Creates  the  necessary  rules to compile .po files into .qm files, and
417       install them.
418
419       The .qm files  are  installed  in  <install_destination>/<lang>/LC_MES‐
420       SAGES,  where <install_destination> is the INSTALL_DESTINATION argument
421       and <lang> is extracted from the “Language” field inside the .po file.
422
423       INSTALL_DESTINATION defaults to ${LOCALE_INSTALL_DIR} if defined,  oth‐
424       erwise it uses ${CMAKE_INSTALL_LOCALEDIR} if that is defined, otherwise
425       it uses share/locale.
426
427       CATALOG_NAME defines the name of the installed .qm files. If  set,  .qm
428       files will be installed as <catalog_name>.qm. If not set .qm files will
429       be named after the name of their source .po file.
430
431       Setting the catalog name is useful when all .po files for a target  are
432       kept  in  a  single source directory. For example, the “mylib” probject
433       might keep all its translations in a “po” directory, like this:
434
435          po/
436              es.po
437              fr.po
438
439       Without setting CATALOG_NAME, those .po will be  turned  into  .qm  and
440       installed as:
441
442          share/locale/fr/LC_MESSAGES/fr.qm
443          share/locale/es/LC_MESSAGES/es.qm
444
445       If CATALOG_NAME is set to “mylib”, they will be installed as:
446
447          share/locale/fr/LC_MESSAGES/mylib.qm
448          share/locale/es/LC_MESSAGES/mylib.qm
449
450       Which is what the loader created by ecm_create_qm_loader() expects.
451
452       ecm_create_qm_from_po_files() creates a “translation” target. This tar‐
453       get builds all .po files into .qm files.
454
455          ecm_create_qm_loader(<source_files_var> <catalog_name>)
456
457       ecm_create_qm_loader() generates a C++ file which ensures  translations
458       are  automatically  loaded  at  startup.  The  path of the .cpp file is
459       appended to <source_files_var>.  Typical usage is like:
460
461          set(mylib_SRCS foo.cpp bar.cpp)
462          ecm_create_qm_loader(mylib_SRCS mylib)
463          add_library(mylib ${mylib_SRCS})
464
465       This generates a C++ file which loads “mylib.qm” at  startup,  assuming
466       it has been installed by ecm_create_qm_from_po_files(), and compiles it
467       into mylib.
468
469       Since pre-1.0.0.
470
471   ECMEnableSanitizers
472       Enable compiler sanitizer flags.
473
474       The following sanitizers are supported:
475
476       · Address Sanitizer
477
478       · Memory Sanitizer
479
480       · Thread Sanitizer
481
482       · Leak Sanitizer
483
484       · Undefined Behaviour Sanitizer
485
486       All of them are implemented in Clang, depending on  your  version,  and
487       there  is  an work in progress in GCC, where some of them are currently
488       implemented.
489
490       This module will check your current compiler version to see if it  sup‐
491       ports the sanitizers that you want to enable
492
493   Usage
494       Simply add:
495
496          include(ECMEnableSanitizers)
497
498       to your CMakeLists.txt. Note that this module is included in KDECompil‐
499       erSettings, so projects using that module do not need to  also  include
500       this one.
501
502       The  sanitizers  are  not  enabled  by  default.  Instead, you must set
503       ECM_ENABLE_SANITIZERS (either in your CMakeLists.txt or on the  command
504       line)  to  a semicolon-separated list of sanitizers you wish to enable.
505       The options are:
506
507       · address
508
509       · memory
510
511       · thread
512
513       · leak
514
515       · undefined
516
517       · fuzzer
518
519       The sanitizers “address”, “memory” and “thread” are mutually exclusive.
520       You cannot enable two of them in the same build.
521
522       “leak” requires the  “address” sanitizer.
523
524       NOTE:
525          To  reduce  the overhead induced by the instrumentation of the sani‐
526          tizers, it is advised  to  enable  compiler  optimizations  (-O1  or
527          higher).
528
529   Example
530       This is an example of usage:
531
532          mkdir build
533          cd build
534          cmake -DECM_ENABLE_SANITIZERS='address;leak;undefined' ..
535
536       NOTE:
537          Most of the sanitizers will require Clang. To enable it, use:
538
539              -DCMAKE_CXX_COMPILER=clang++
540
541       Since 1.3.0.
542
543   ECMFindModuleHelpers
544       Helper   macros  for  find  modules:  ecm_find_package_version_check(),
545       ecm_find_package_parse_components()      and      ecm_find_package_han‐
546       dle_library_components().
547
548          ecm_find_package_version_check(<name>)
549
550       Prints  warnings  if  the CMake version or the project’s required CMake
551       version is older than that required by extra-cmake-modules.
552
553          ecm_find_package_parse_components(<name>
554              RESULT_VAR <variable>
555              KNOWN_COMPONENTS <component1> [<component2> [...]]
556              [SKIP_DEPENDENCY_HANDLING])
557
558       This macro will populate <variable> with a list of components found  in
559       <name>_FIND_COMPONENTS, after checking that all those components are in
560       the list of KNOWN_COMPONENTS; if there are any unknown  components,  it
561       will   print   an   error   or  warning  (depending  on  the  value  of
562       <name>_FIND_REQUIRED) and call return().
563
564       The order of components in <variable> is guaranteed to match the  order
565       they are listed in the KNOWN_COMPONENTS argument.
566
567       If SKIP_DEPENDENCY_HANDLING is not set, for each component the variable
568       <name>_<component>_component_deps will be checked for dependent  compo‐
569       nents.   If  <component>  is listed in <name>_FIND_COMPONENTS, then all
570       its (transitive) dependencies will also be added to <variable>.
571
572          ecm_find_package_handle_library_components(<name>
573              COMPONENTS <component> [<component> [...]]
574              [SKIP_DEPENDENCY_HANDLING])
575              [SKIP_PKG_CONFIG])
576
577       Creates an imported library target for each component.   The  operation
578       of this macro depends on the presence of a number of CMake variables.
579
580       The  <name>_<component>_lib  variable  should  contain the name of this
581       library, and <name>_<component>_header variable should contain the name
582       of a header file associated with it (whatever relative path is normally
583       passed to ‘#include’). <name>_<component>_header_subdir variable can be
584       used to specify which subdirectory of the include path the headers will
585       be found in.  ecm_find_package_components() will then  search  for  the
586       library  and  include  directory (creating appropriate cache variables)
587       and create an imported library target named <name>::<component>.
588
589       Additional variables can be used to provide additional information:
590
591       If SKIP_PKG_CONFIG, the <name>_<component>_pkg_config variable is  set,
592       and  pkg-config is found, the pkg-config module given by <name>_<compo‐
593       nent>_pkg_config will be searched for  and  used  to  help  locate  the
594       library  and  header  file.  It will also be used to set <name>_<compo‐
595       nent>_VERSION.
596
597       Note that if version information is found via pkg-config,  <name>_<com‐
598       ponent>_FIND_VERSION  can  be  set  to require a particular version for
599       each component.
600
601       If SKIP_DEPENDENCY_HANDLING is not  set,  the  INTERFACE_LINK_LIBRARIES
602       property  of the imported target for <component> will be set to contain
603       the imported  targets  for  the  components  listed  in  <name>_<compo‐
604       nent>_component_deps.   <component>_FOUND  will also be set to false if
605       any of the  compoments  in  <name>_<component>_component_deps  are  not
606       found.   This  requires  the  components  in  <name>_<component>_compo‐
607       nent_deps to be listed before <component> in the COMPONENTS argument.
608
609       The following variables will be set:
610
611       <name>_TARGETS
612              the imported targets
613
614       <name>_LIBRARIES
615              the found libraries
616
617       <name>_INCLUDE_DIRS
618              the combined required include directories for the components
619
620       <name>_DEFINITIONS
621              the “other” CFLAGS provided by pkg-config, if any
622
623       <name>_VERSION
624              the value of <name>_<component>_VERSION for the first  component
625              that  has  this  variable set (note that components are searched
626              for in the order they are passed to the macro), although  if  it
627              is already set, it will not be altered
628
629       Note  that  these  variables  are  never  cleared, so if ecm_find_pack‐
630       age_handle_library_components() is called multiple times with different
631       components  (typically  because  of multiple find_package() calls) then
632       <name>_TARGETS, for example, will contain all the targets found in  any
633       call (although no duplicates).
634
635       Since pre-1.0.0.
636
637   ECMGenerateHeaders
638       Generate C/C++ CamelCase forwarding headers.
639
640          ecm_generate_headers(<camelcase_forwarding_headers_var>
641              HEADER_NAMES <CamelCaseName> [<CamelCaseName> [...]]
642              [ORIGINAL <CAMELCASE|LOWERCASE>]
643              [HEADER_EXTENSION <header_extension>]
644              [OUTPUT_DIR <output_dir>]
645              [PREFIX <prefix>]
646              [REQUIRED_HEADERS <variable>]
647              [COMMON_HEADER <HeaderName>]
648              [RELATIVE <relative_path>])
649
650       For  each  CamelCase header name passed to HEADER_NAMES, a file of that
651       name will be generated that will include a version with .h or, if  set,
652       .<header_extension> appended.  For example, the generated header ClassA
653       will include classa.h (or ClassA.h, see ORIGINAL).  If a  CamelCaseName
654       consists of multiple comma-separated files, e.g.  ClassA,ClassB,ClassC,
655       then multiple camelcase header files will be generated which are  redi‐
656       rects  to the first header file.  The file locations of these generated
657       headers will be stored in <camelcase_forwarding_headers_var>.
658
659       ORIGINAL specifies how the name of the original header is written: low‐
660       ercased or also camelcased.  The default is LOWERCASE. Since 1.8.0.
661
662       HEADER_EXTENSION  specifies  what  file  name extension is used for the
663       header files.  The default is “h”. Since 5.48.0.
664
665       PREFIX places the generated headers in subdirectories.  This should  be
666       a CamelCase name like KParts, which will cause the CamelCase forwarding
667       headers to be placed in the KParts directory  (e.g.  KParts/Part).   It
668       will also, for the convenience of code in the source distribution, gen‐
669       erate  forwarding  headers  based   on   the   original   names   (e.g.
670       kparts/part.h).   This  allows includes like "#include <kparts/part.h>"
671       to be used before installation, as long as the include_directories  are
672       set appropriately.
673
674       OUTPUT_DIR  specifies where the files will be generated; this should be
675       within the build  directory.  By  default,  ${CMAKE_CURRENT_BINARY_DIR}
676       will be used.  This option can be used to avoid file conflicts.
677
678       REQUIRED_HEADERS  specifies  an  output  variable  name  where  all the
679       required headers will  be  appended  so  that  they  can  be  installed
680       together  with the generated ones.  This is mostly intended as a conve‐
681       nience so that adding a new header to a project only requires  specify‐
682       ing  the  CamelCase  variant  in  the CMakeLists.txt file; the original
683       variant will then be added to this variable.
684
685       COMMON_HEADER generates an additional convenience header which includes
686       all other header files.
687
688       The RELATIVE argument indicates where the original headers can be found
689       relative to CMAKE_CURRENT_SOURCE_DIR.  It does not affect the generated
690       CamelCase  forwarding  files,  but  ecm_generate_headers() uses it when
691       checking that the original header exists, and  to  generate  originally
692       named forwarding headers when PREFIX is set.
693
694       To  allow other parts of the source distribution (eg: tests) to use the
695       generated headers before installation, it may be desirable to  set  the
696       INCLUDE_DIRECTORIES property for the library target to output_dir.  For
697       example, if OUTPUT_DIR is CMAKE_CURRENT_BINARY_DIR (the  default),  you
698       could do
699
700          target_include_directories(MyLib PUBLIC "$<BUILD_INTERFACE:${CMAKE_CURRENT_BINARY_DIR}>")
701
702       Example usage (without PREFIX):
703
704          ecm_generate_headers(
705              MyLib_FORWARDING_HEADERS
706              HEADERS
707                  MLFoo
708                  MLBar
709                  # etc
710              REQUIRED_HEADERS MyLib_HEADERS
711              COMMON_HEADER MLGeneral
712          )
713          install(FILES ${MyLib_FORWARDING_HEADERS} ${MyLib_HEADERS}
714                  DESTINATION ${CMAKE_INSTALL_PREFIX}/include
715                  COMPONENT Devel)
716
717       Example usage (with PREFIX):
718
719          ecm_generate_headers(
720              MyLib_FORWARDING_HEADERS
721              HEADERS
722                  Foo
723                  # several classes are contained in bar.h, so generate
724                  # additional files
725                  Bar,BarList
726                  # etc
727              PREFIX MyLib
728              REQUIRED_HEADERS MyLib_HEADERS
729          )
730          install(FILES ${MyLib_FORWARDING_HEADERS}
731                  DESTINATION ${CMAKE_INSTALL_PREFIX}/include/MyLib
732                  COMPONENT Devel)
733          install(FILES ${MyLib_HEADERS}
734                  DESTINATION ${CMAKE_INSTALL_PREFIX}/include/mylib
735                  COMPONENT Devel)
736
737       Since pre-1.0.0.
738
739   ECMGeneratePkgConfigFile
740       Generate a pkg-config file for the benefit of autotools-based projects.
741
742          ecm_generate_pkgconfig_file(BASE_NAME <baseName>
743                                [LIB_NAME <libName>]
744                                [DEPS "<dep> [<dep> [...]]"]
745                                [FILENAME_VAR <filename_variable>]
746                                [INCLUDE_INSTALL_DIR <dir>]
747                                [LIB_INSTALL_DIR <dir>]
748                                [DEFINES -D<variable=value>...]
749                                [DESCRIPTION <library description>] # since 5.41.0
750                                [INSTALL])
751
752       BASE_NAME is the name of the module. It’s the name projects will use to
753       find the module.
754
755       LIB_NAME is the name of the library that is being  exported.  If  unde‐
756       fined,  it  will default to the BASE_NAME. That means the LIB_NAME will
757       be set as the name field as well as the library to link to.
758
759       FILENAME_VAR is specified with a  variable  name.  This  variable  will
760       receive  the  location  of  the  generated file will be set, within the
761       build directory. This way it can be used in  case  some  processing  is
762       required. See also INSTALL.
763
764       INCLUDE_INSTALL_DIR  specifies where the includes will be installed. If
765       it’s  not   specified,   it   will   default   to   INSTALL_INCLUDEDIR,
766       CMAKE_INSTALL_INCLUDEDIR or just “include/” in case they are specified,
767       with the BASE_NAME postfixed.
768
769       LIB_INSTALL_DIR specifies where the library is being installed. If it’s
770       not specified, it will default to LIB_INSTALL_DIR, CMAKE_INSTALL_LIBDIR
771       or just “lib/” in case they are specified.
772
773       DEFINES is a list of preprocessor defines that it is recommended  users
774       of the library pass to the compiler when using it.
775
776       DESCRIPTION  describes  what  this  library  is. If it’s not specified,
777       CMake will first try to get the description from the metainfo.yaml file
778       or will create one based on LIB_NAME. Since 5.41.0.
779
780       INSTALL  will  cause the module to be installed to the pkgconfig subdi‐
781       rectory of LIB_INSTALL_DIR, unless the ECM_PKGCONFIG_INSTALL_DIR  cache
782       variable  is  set  to  something different. Note that the first call to
783       ecm_generate_pkgconfig_file  with  the  INSTALL  argument  will   cause
784       ECM_PKGCONFIG_INSTALL_DIR  to  be set to the cache, and will be used in
785       any subsequent calls.
786
787       To properly use this macro a version needs to be set. To  retrieve  it,
788       ECM_PKGCONFIG_INSTALL_DIR  uses  PROJECT_VERSION.  To  set  it, use the
789       project() command (only available since  CMake  3.0)  or  the  ecm_set‐
790       up_version() macro.
791
792       Example usage:
793
794          ecm_generate_pkgconfig_file(
795              BASE_NAME KF5Archive
796              DEPS Qt5Core
797              FILENAME_VAR pkgconfig_filename
798              INSTALL
799          )
800
801       Since 1.3.0.
802
803   ECMGeneratePriFile
804       Generate a .pri file for the benefit of qmake-based projects.
805
806       As  well  as the function below, this module creates the cache variable
807       ECM_MKSPECS_INSTALL_DIR and sets the default value to  mkspecs/modules.
808       This  assumes Qt and the current project are both installed to the same
809       non-system prefix.  Packagers who use -DCMAKE_INSTALL_PREFIX=/usr  will
810       certainly   want  to  set  ECM_MKSPECS_INSTALL_DIR  to  something  like
811       share/qt5/mkspecs/modules.
812
813       The main thing is that this  should  be  the  modules  subdirectory  of
814       either  the default qmake mkspecs directory or of a directory that will
815       be in the $QMAKEPATH environment variable when qmake is run.
816
817          ecm_generate_pri_file(BASE_NAME <baseName>
818                                LIB_NAME <libName>
819                                [DEPS "<dep> [<dep> [...]]"]
820                                [FILENAME_VAR <filename_variable>]
821                                [INCLUDE_INSTALL_DIR <dir>]
822                                [LIB_INSTALL_DIR <dir>])
823
824       If your CMake project produces a Qt-based library, you may expect there
825       to  be  applications  that  wish to use it that use a qmake-based build
826       system, rather than a CMake-based one.  Creating a .pri file will  make
827       use  of  your  library  convenient  for them, in much the same way that
828       CMake config files make things convenient for CMake-based applications.
829
830       ecm_generate_pri_file() generates just such a file.   It  requires  the
831       PROJECT_VERSION_STRING  variable  to  be set.  This is typically set by
832       ECMSetupVersion, although the project()  command  in  CMake  3.0.0  and
833       later can also set this.
834
835       BASE_NAME  specifies  the name qmake project (.pro) files should use to
836       refer to the library (eg: KArchive).   LIB_NAME  is  the  name  of  the
837       actual  library  to  link to (ie: the first argument to add_library()).
838       DEPS is a space-separated list of the base  names  of  other  libraries
839       (for Qt libraries, use the same names you use with the QT variable in a
840       qmake project file, such as “core” for QtCore).  FILENAME_VAR specifies
841       the name of a variable to store the path to the generated file in.
842
843       INCLUDE_INSTALL_DIR is the path (relative to CMAKE_INSTALL_PREFIX) that
844       include   files   will   be    installed    to.    It    defaults    to
845       ${INCLUDE_INSTALL_DIR}/<baseName>  if  the INCLUDE_INSTALL_DIR variable
846       is set. If that variable is not set, the CMAKE_INSTALL_INCLUDEDIR vari‐
847       able  is  used  instead,  and  if  neither  are  set  include  is used.
848       LIB_INSTALL_DIR operates similarly for the  installation  location  for
849       libraries;  it  defaults to ${LIB_INSTALL_DIR}, ${CMAKE_INSTALL_LIBDIR}
850       or lib, in that order.
851
852       Example usage:
853
854          ecm_generate_pri_file(
855              BASE_NAME KArchive
856              LIB_NAME KF5KArchive
857              DEPS "core"
858              FILENAME_VAR pri_filename
859          )
860          install(FILES ${pri_filename} DESTINATION ${ECM_MKSPECS_INSTALL_DIR})
861
862       A qmake-based project that wished to use this would then do:
863
864          QT += KArchive
865
866       in their .pro file.
867
868       Since pre-1.0.0.
869
870   ECMGenerateQmlTypes
871       Generates plugins.qmltypes files for QML plugins.
872
873          ecm_generate_qmltypes(<org.kde.pluginname> 1.3
874                                DESTINATION <${KDE_INSTALL_QMLDIR}/org/kde/pluginname>)
875
876       Makes it possible to generate plugins.qmltypes files for the QML  plug‐
877       ins  that  our project offers. These files offer introspection upon our
878       plugin and are useful for integrating with IDE language support of  our
879       plugin.  It  offers information about the objects its methods and their
880       argument types.
881
882       The developer will be in charge of making sure that these files are  up
883       to  date.   The  plugin.qmltypes file will sit in the source directory.
884       This function will include the code that installs the file in the right
885       place  and  a  small  unit  test named qmltypes-pluginname-version that
886       makes sure that it doesn’t need updating.
887
888       Since 5.33.0
889
890   ECMInstallIcons
891       Installs icons, sorting them into the correct directories according  to
892       the FreeDesktop.org icon naming specification.
893
894          ecm_install_icons(ICONS <icon> [<icon> [...]]
895                            DESTINATION <icon_install_dir>
896                            [LANG <l10n_code>]
897                            [THEME <theme>])
898
899       The given icons, whose names must match the pattern:
900
901          <size>-<group>-<name>.<ext>
902
903       will  be  installed  to  the  appropriate  subdirectory  of DESTINATION
904       according to the FreeDesktop.org icon naming scheme. By  default,  they
905       are installed to the “hicolor” theme, but this can be changed using the
906       THEME argument.  If the icons are localized, the LANG argument  can  be
907       used to install them in a locale-specific directory.
908
909       <size>  is  a  numeric pixel size (typically 16, 22, 32, 48, 64, 128 or
910       256) or sc for scalable (SVG) files, <group> is  one  of  the  standard
911       FreeDesktop.org  icon  groups  (actions,  animations, apps, categories,
912       devices, emblems, emotes, intl, mimetypes, places, status) and <ext> is
913       one of .png, .mng or .svgz.
914
915       The typical installation directory is share/icons.
916
917          ecm_install_icons(ICONS 22-actions-menu_new.png
918                            DESTINATION share/icons)
919
920       The  above  code  will  install  the  file  22-actions-menu_new.png  as
921       ${CMAKE_INSTALL_PREFIX}/share/icons/<theme>/22x22/actions/menu_new.png
922
923       Users   of   the   KDEInstallDirs    module    would    normally    use
924       ${KDE_INSTALL_ICONDIR}  as  the  DESTINATION, while users of the GNUIn‐
925       stallDirs module should use ${CMAKE_INSTALL_DATAROOTDIR}/icons.
926
927       An old form of arguments will also be accepted:
928
929          ecm_install_icons(<icon_install_dir> [<l10n_code>])
930
931       This matches files named like:
932
933          <theme><size>-<group>-<name>.<ext>
934
935       where <theme> is one of * hi for hicolor * lo for locolor * cr for  the
936       Crystal  icon  theme * ox for the Oxygen icon theme * br for the Breeze
937       icon theme
938
939       With this syntax, the file hi22-actions-menu_new.png would be installed
940       into <icon_install_dir>/hicolor/22x22/actions/menu_new.png
941
942       Since pre-1.0.0.
943
944   ECMMarkAsTest
945       Marks a target as only being required for tests.
946
947          ecm_mark_as_test(<target1> [<target2> [...]])
948
949       This  will  cause  the  specified targets to not be built unless either
950       BUILD_TESTING is set to ON or the user invokes the buildtests target.
951
952       BUILD_TESTING is created as a cache variable by the CTest module and by
953       the KDECMakeSettings module.
954
955       Since pre-1.0.0.
956
957   ECMMarkNonGuiExecutable
958       Marks an executable target as not being a GUI application.
959
960          ecm_mark_nongui_executable(<target1> [<target2> [...]])
961
962       This  will  indicate  to CMake that the specified targets should not be
963       included in a MACOSX_BUNDLE and should not  be  WIN32_EXECUTABLEs.   On
964       platforms other than MacOS X or Windows, this will have no effect.
965
966       Since pre-1.0.0.
967
968   ECMOptionalAddSubdirectory
969       Make subdirectories optional.
970
971          ecm_optional_add_subdirectory(<dir>)
972
973       This  behaves like add_subdirectory(), except that it does not complain
974       if the directory does not exist.  Additionally, if the  directory  does
975       exist,  it  creates  an option to allow the user to skip it. The option
976       will be named BUILD_<dir>.
977
978       This is useful for “meta-projects” that combine several mostly-indepen‐
979       dent sub-projects.
980
981       If  the  CMake  variable  DISABLE_ALL_OPTIONAL_SUBDIRECTORIES is set to
982       TRUE for the first CMake run on the project, all  optional  subdirecto‐
983       ries  will be disabled by default (but can of course be enabled via the
984       respective options).  For  example,  the  following  will  disable  all
985       optional subdirectories except the one named “foo”:
986
987          cmake -DDISABLE_ALL_OPTIONAL_SUBDIRECTORIES=TRUE -DBUILD_foo=TRUE myproject
988
989       Since pre-1.0.0.
990
991   ECMPackageConfigHelpers
992       Helper macros for generating CMake package config files.
993
994       write_basic_package_version_file()  is  the same as the one provided by
995       the CMakePackageConfigHelpers module in CMake; see that module’s  docu‐
996       mentation for more information.
997
998          ecm_configure_package_config_file(<input> <output>
999              INSTALL_DESTINATION <path>
1000              [PATH_VARS <var1> [<var2> [...]]
1001              [NO_SET_AND_CHECK_MACRO]
1002              [NO_CHECK_REQUIRED_COMPONENTS_MACRO])
1003
1004       This  behaves  in  the same way as configure_package_config_file() from
1005       CMake 2.8.12, except that it adds an extra  helper  macro:  find_depen‐
1006       dency().  It  is highly recommended that you read the documentation for
1007       CMakePackageConfigHelpers  for  more  information,  particularly   with
1008       regard to the PATH_VARS argument.
1009
1010       Note  that there is no argument that will disable the find_dependency()
1011       macro; if you do not require this macro, you should use configure_pack‐
1012       age_config_file from the CMakePackageConfigHelpers module.
1013
1014       CMake  3.0 includes a CMakeFindDependencyMacro module that provides the
1015       find_dependency() macro (which you can include() in your package config
1016       file), so this file is only useful for projects wishing to provide con‐
1017       fig files that will work with CMake 2.8.12.
1018
1019   Additional Config File Macros
1020          find_dependency(<dep> [<version> [EXACT]])
1021
1022       find_dependency() should be used  instead  of  find_package()  to  find
1023       package  dependencies.   It  forwards the correct parameters for EXACT,
1024       QUIET and REQUIRED which were passed  to  the  original  find_package()
1025       call.  It also sets an informative diagnostic message if the dependency
1026       could not be found.
1027
1028       Since pre-1.0.0.
1029
1030   ECMPoQmTools
1031       This    module    provides    the    ecm_process_po_files_as_qm     and
1032       ecm_install_po_files_as_qm  functions  for generating QTranslator (.qm)
1033       catalogs from Gettext  (.po)  catalogs,  and  the  ecm_create_qm_loader
1034       function  for generating the necessary code to load them in a Qt appli‐
1035       cation or library.
1036
1037          ecm_process_po_files_as_qm(<lang> [ALL]
1038                                     [INSTALL_DESTINATION <install_destination>]
1039                                     PO_FILES <pofile> [<pofile> [...]])
1040
1041       Compile .po files into .qm files for the given language.
1042
1043       If INSTALL_DESTINATION  is  given,  the  .qm  files  are  installed  in
1044       <install_destination>/<lang>/LC_MESSAGES.  Typically, <install_destina‐
1045       tion> is set to share/locale.
1046
1047       ecm_process_po_files_as_qm creates a “translations” target. This target
1048       builds  all .po files into .qm files.  If ALL is specified, these rules
1049       are added to the “all” target (and so the .qm files will  be  built  by
1050       default).
1051
1052          ecm_create_qm_loader(<source_files_var> <catalog_name>)
1053
1054       Generates  C++ code which ensures translations are automatically loaded
1055       at startup. The generated files are appended to <source_files_var>.
1056
1057       It assumes that the .qm file for the language code <lang> is  installed
1058       as     <sharedir>/locale/<lang>/LC_MESSAGES/<catalog_name>.qm,    where
1059       <sharedir> is one of the directories given by  the  GenericDataLocation
1060       of QStandardPaths.
1061
1062       Typical usage is like:
1063
1064          set(mylib_SRCS foo.cpp bar.cpp)
1065          ecm_create_qm_loader(mylib_SRCS mylib)
1066          add_library(mylib ${mylib_SRCS})
1067
1068          ecm_install_po_files_as_qm(<podir>)
1069
1070       Searches for .po files and installs them to the standard location.
1071
1072       This is a convenience function which relies on all .po files being kept
1073       in <podir>/<lang>/, where <lang> is the  language  the  .po  files  are
1074       written in.
1075
1076       For example, given the following directory structure:
1077
1078          po/
1079            fr/
1080              mylib.po
1081
1082       ecm_install_po_files_as_qm(po)  compiles  mylib.po  into  mylib.qm  and
1083       installs it in <install_destination>/fr/LC_MESSAGES.  <install_destina‐
1084       tion>  defaults  to ${LOCALE_INSTALL_DIR} if defined, otherwise it uses
1085       ${CMAKE_INSTALL_LOCALEDIR}  if  that  is  defined,  otherwise  it  uses
1086       share/locale.
1087
1088       Since pre-1.0.0.
1089
1090   ECMQMLModules
1091       Find  QML  import modules through a find_qmlmodule() call.  It uses the
1092       qmlplugindump application to find the plugins and sets them up as  run‐
1093       time dependencies.
1094
1095       This  is useful so that when we configure a project we are noified when
1096       some QML imports are not present in the system, thus having the  appli‐
1097       cation compilable but fail at runtime.
1098
1099          ecm_find_qmlmodule(<module_name> <version>...)
1100
1101       Any  further  arguments  passed will be forwarded into a find_package()
1102       call. See find_package() documentation for more information.
1103
1104       Usage example:
1105
1106          ecm_find_qmlmodule(org.kde.kirigami 2.1)
1107
1108       Since 5.38.0.
1109
1110   ECMQtDeclareLoggingCategory
1111       Generate declarations for logging categories in Qt5.
1112
1113          ecm_qt_declare_logging_category(<sources_var>
1114                                          HEADER <filename>
1115                                          IDENTIFIER <identifier>
1116                                          CATEGORY_NAME <category_name>
1117                                          [DEFAULT_SEVERITY
1118                                               <Debug|Info|Warning|
1119                                                Critical|Fatal>])
1120
1121       A header file, <filename>, will be generated along with a corresponding
1122       source file, which will be added to <sources_var>. These will provide a
1123       QLoggingCategory category that can be referred to from C++  code  using
1124       <identifier>, and from the logging configuration using <category_name>.
1125
1126       If <filename> is not absolute, it will be taken relative to the current
1127       binary directory.
1128
1129       If the code is compiled against Qt 5.4 or later,  by  default  it  will
1130       only   log   output   that  is  at  least  the  severity  specified  by
1131       DEFAULT_SEVERITY, or “Info” level if  DEFAULT_SEVERITY  is  not  given.
1132       Note that, due to a bug in Qt 5.5, “Info” may be treated as more severe
1133       than “Fatal”.
1134
1135       <identifier> may include namespaces (eg: foo::bar::IDENT).
1136
1137       Since 5.14.0.
1138
1139   ECMSetupQtPluginMacroNames
1140       Instruct CMake’s automoc about C++ preprocessor macros used  to  define
1141       Qt-style plugins.
1142
1143          ecm_setup_qtplugin_macro_names(
1144              [JSON_NONE <macro_name> [<macro_name> [...]]]
1145              [JSON_ARG1 <macro_name> [<macro_name> [...]]]
1146              [JSON_ARG2 <macro_name> [<macro_name> [...]]]
1147              [JSON_ARG3 <macro_name> [<macro_name> [...]]]
1148              [CONFIG_CODE_VARIABLE <variable_name>] )
1149
1150       CMake’s  automoc  needs  some  support when parsing C++ source files to
1151       detect whether moc should be run on those files and if there  are  also
1152       dependencies on other files, like those with Qt plugin metadata in JSON
1153       format. Because automoc just greps overs the  raw  plain  text  of  the
1154       sources  without  any C++ preprocessor-like processing.  CMake in newer
1155       versions provides the variables CMAKE_AUTOMOC_DEPEND_FILTERS (CMake  >=
1156       3.9.0)  and  CMAKE_AUTOMOC_MACRO_NAMES  (CMake  >=  3.10)  to allow the
1157       developer to assist automoc.
1158
1159       This macro cares for the explicit setup needed for those variables  for
1160       common cases of C++ preprocessor macros used for Qt-style plugins.
1161
1162       JSON_NONE lists the names of C++ preprocessor macros for Qt-style plug‐
1163       ins which do not refer to external files with the plugin metadata.
1164
1165       JSON_ARG1 lists the names of C++ preprocessor macros for Qt-style plug‐
1166       ins  where  the first argument to the macro is the name of the external
1167       file with the plugin metadata.
1168
1169       JSON_ARG2 is the same as JSON_ARG1 but with the  file  name  being  the
1170       second argument.
1171
1172       JSON_ARG3  is  the  same  as JSON_ARG1 but with the file name being the
1173       third argument.
1174
1175       CONFIG_CODE_VARIABLE specifies the name of the variable which will  get
1176       set  as value some generated CMake code for instructing automoc for the
1177       given macro names, as useful in an installed  CMake  config  file.  The
1178       variable  can  then  be  used  as usual in the template file for such a
1179       CMake config file, by @<variable_name>@.
1180
1181       Example usage:
1182
1183       Given some plugin-oriented Qt-based software which defines a custom C++
1184       preprocessor  macro  EXPORT_MYPLUGIN  for  declaring the central plugin
1185       object:
1186
1187          #define EXPORT_MYPLUGIN_WITH_JSON(classname, jsonFile) \
1188          class classname : public QObject \
1189          { \
1190              Q_OBJECT \
1191              Q_PLUGIN_METADATA(IID "myplugin" FILE jsonFile) \
1192              explicit classname() {} \
1193          };
1194
1195       In the CMake buildsystem of the library one calls
1196
1197          ecm_setup_qtplugin_macro_names(
1198              JSON_ARG2
1199                 EXPORT_MYPLUGIN_WITH_JSON
1200          )
1201
1202       to instruct automoc about the usage of that macro in the sources of the
1203       library itself.
1204
1205       Given  the  software  installs  a library including the header with the
1206       macro definition and a CMake config file, so 3rd-party can create addi‐
1207       tional  plugins by linking against the library, one passes additionally
1208       the name of a variable which shall be  set  as  value  the  CMake  code
1209       needed to instruct automoc about the usage of that macro.
1210
1211          ecm_setup_qtplugin_macro_names(
1212              JSON_ARG2
1213                 EXPORT_MYPLUGIN_WITH_JSON
1214              CONFIG_CODE_VARIABLE
1215                 PACKAGE_SETUP_AUTOMOC_VARIABLES
1216          )
1217
1218       This  variable  then  is used in the template file (e.g.  MyProjectCon‐
1219       fig.cmake.in) for the libary’s installed CMake config file and that way
1220       will  ensure  that  in  the  3rd-party  plugin’s buildsystem automoc is
1221       instructed as well as needed:
1222
1223          @PACKAGE_SETUP_AUTOMOC_VARIABLES@
1224
1225       Since 5.45.0.
1226
1227   ECMSetupVersion
1228       Handle library version information.
1229
1230          ecm_setup_version(<version>
1231                            VARIABLE_PREFIX <prefix>
1232                            [SOVERSION <soversion>]
1233                            [VERSION_HEADER <filename>]
1234                            [PACKAGE_VERSION_FILE <filename> [COMPATIBILITY <compat>]] )
1235
1236       This parses a version string and sets up  a  standard  set  of  version
1237       variables.  It can optionally also create a C version header file and a
1238       CMake package version file to install along with the library.
1239
1240       If the <version> argument is of the  form  <major>.<minor>.<patch>  (or
1241       <major>.<minor>.<patch>.<tweak>),  The  following  CMake  variables are
1242       set:
1243
1244          <prefix>_VERSION_MAJOR  - <major>
1245          <prefix>_VERSION_MINOR  - <minor>
1246          <prefix>_VERSION_PATCH  - <patch>
1247          <prefix>_VERSION        - <version>
1248          <prefix>_VERSION_STRING - <version> (for compatibility: use <prefix>_VERSION instead)
1249          <prefix>_SOVERSION      - <soversion>, or <major> if SOVERSION was not given
1250
1251       If CMake policy CMP0048 is not NEW, the following CMake variables  will
1252       also be set:
1253          PROJECT_VERSION_MAJOR    - <major> PROJECT_VERSION_MINOR   - <minor>
1254          PROJECT_VERSION_PATCH   - <patch>  PROJECT_VERSION          -  <ver‐
1255          sion>  PROJECT_VERSION_STRING   -  <version> (for compatibility: use
1256          PROJECT_VERSION instead)
1257
1258       If the VERSION_HEADER option is used, a simple C  header  is  generated
1259       with  the  given filename. If filename is a relative path, it is inter‐
1260       preted as relative to CMAKE_CURRENT_BINARY_DIR.  The  generated  header
1261       contains the following macros:
1262
1263          <prefix>_VERSION_MAJOR  - <major> as an integer
1264          <prefix>_VERSION_MINOR  - <minor> as an integer
1265          <prefix>_VERSION_PATCH  - <patch> as an integer
1266          <prefix>_VERSION_STRING - <version> as a C string
1267          <prefix>_VERSION        - the version as an integer
1268
1269       <prefix>_VERSION  has <patch> in the bottom 8 bits, <minor> in the next
1270       8 bits and <major> in  the  remaining  bits.   Note  that  <patch>  and
1271       <minor> must be less than 256.
1272
1273       If the PACKAGE_VERSION_FILE option is used, a simple CMake package ver‐
1274       sion file is created using the write_basic_package_version_file() macro
1275       provided  by  CMake. It should be installed in the same location as the
1276       Config.cmake file of the library so that it can be found by  find_pack‐
1277       age().   If the filename is a relative path, it is interpreted as rela‐
1278       tive to CMAKE_CURRENT_BINARY_DIR. The optional COMPATIBILITY option  is
1279       forwarded   to   write_basic_package_version_file(),  and  defaults  to
1280       AnyNewerVersion.
1281
1282       If CMake policy CMP0048 is NEW, an alternative form of the  command  is
1283       available:
1284
1285          ecm_setup_version(PROJECT
1286                            [VARIABLE_PREFIX <prefix>]
1287                            [SOVERSION <soversion>]
1288                            [VERSION_HEADER <filename>]
1289                            [PACKAGE_VERSION_FILE <filename>] )
1290
1291       This  will  use  the  version information set by the project() command.
1292       VARIABLE_PREFIX defaults to the project name.  Note that  PROJECT  must
1293       be  the  first  argument.   In  all other respects, it behaves like the
1294       other form of the command.
1295
1296       Since pre-1.0.0.
1297
1298       COMPATIBILITY option available since 1.6.0.
1299
1300   ECMUninstallTarget
1301       Add an uninstall target.
1302
1303       By including this module, an uninstall target will  be  added  to  your
1304       CMake  project.  This will remove all files installed (or updated) by a
1305       previous invocation of the install target. It  will  not  remove  files
1306       created or modified by an install(SCRIPT) or install(CODE) command; you
1307       should  create  a  custom  uninstallation  target  for  these  and  use
1308       add_dependency to make the uninstall target depend on it:
1309
1310          include(ECMUninstallTarget)
1311          install(SCRIPT install-foo.cmake)
1312          add_custom_target(uninstall_foo COMMAND ${CMAKE_COMMAND} -P uninstall-foo.cmake)
1313          add_dependency(uninstall uninstall_foo)
1314
1315       The  target will fail if the install target has not yet been run (so it
1316       is not possible to run CMake on the project and  then  immediately  run
1317       the uninstall target).
1318
1319       WARNING:
1320          CMake  deliberately  does not provide an uninstall target by default
1321          on the basis that such a target has the potential to  remove  impor‐
1322          tant files from a user’s computer. Use with caution.
1323
1324       Since 1.7.0.
1325
1326   ECMUseFindModules
1327       Selectively  use  some of the find modules provided by extra-cmake-mod‐
1328       ules.
1329
1330       This module is automatically  available  once  extra-cmake-modules  has
1331       been  found,  so  it  is  not  necessary  to include(ECMUseFindModules)
1332       explicitly.
1333
1334          ecm_use_find_modules(DIR <dir>
1335                               MODULES module1.cmake [module2.cmake [...]]
1336                               [NO_OVERRIDE])
1337
1338       This allows selective use of the find modules provided by ECM,  includ‐
1339       ing  deferring  to  CMake’s  versions  of those modules if it has them.
1340       Rather than adding ${ECM_FIND_MODULE_DIR} to CMAKE_MODULE_PATH, you use
1341       ecm_use_find_modules()  to copy the modules you want to a local (build)
1342       directory, and add that to CMAKE_MODULE_PATH.
1343
1344       The find modules given to MODULES will be copied to the directory given
1345       by  DIR  (which  should  be located in ${CMAKE_BINARY_DIR} and added to
1346       CMAKE_MODULE_PATH).  If NO_OVERRIDE is given,  only  modules  not  also
1347       provided by CMake will be copied.
1348
1349       Example:
1350
1351          find_package(ECM REQUIRED)
1352          ecm_use_find_modules(
1353              DIR ${CMAKE_BINARY_DIR}/cmake
1354              MODULES FindEGL.cmake
1355              NO_OVERRIDE
1356          )
1357          set(CMAKE_MODULE_PATH ${CMAKE_BINARY_DIR}/cmake)
1358
1359       This  example  will  make  FindEGL.cmake available in your project, but
1360       only as long as it is not yet part of CMake. Calls to find_package(EGL)
1361       will  then  make  use  of this copied module (or the CMake module if it
1362       exists).
1363
1364       Another possible use for this macro is to take copies of  find  modules
1365       that can be installed along with config files if they are required as a
1366       dependency (for example, if targets provided by the find module are  in
1367       the link interface of a library).
1368
1369       Since pre-1.0.0.
1370
1371   ECMWinResolveSymlinks
1372       Resolve pseudo-symlinks created by git when cloning on Windows.
1373
1374          ecm_win_resolve_symlinks(<dir>)
1375
1376       When git checks out a repository with UNIX symlinks on Windows machine,
1377       it creates a text file for each symlink, containing a relative path  to
1378       the  real  file.   This  function would recursively walk over specified
1379       directory and replace pseudo-symlinks with  corresponding  real  file’s
1380       contents.  It would then run git update-index –assume-unchanged on them
1381       to trick git.
1382
1383       This is useful for projects like “breeze-icons” that contain many iden‐
1384       tical icons implemented as symlinks.
1385
1386       Since 5.28
1387

SEE ALSO

1389       ecm(7), ecm-find-modules(7), ecm-kde-modules(7)
1390
1392       KDE Developers
1393
1394
1395
1396
13975.58                             May 14, 2019                   ECM-MODULES(7)
Impressum