1ECM-MODULES(7) Extra CMake Modules ECM-MODULES(7)
2
6 ecm-modules - ECM Modules Reference
7
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 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 find_package(ECM REQUIRED NO_MODULE)
23 set(CMAKE_MODULE_PATH ${ECM_MODULE_DIR})
24 Using ${ECM_MODULE_PATH} will also make the find modules and KDE mod‐
26 ules available.
27 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
33 ECMAddAppIcon
34 Add icons to executable files and packages.
35 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 The given icons, whose names must match the pattern:
43 <size>-<other_text>.png
45 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 <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 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 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 Windows notes
65 · Icons are compiled into the executable using a resource file.
67 · Icons may not show up in Windows Explorer if the executable
69 target does not have the WIN32_EXECUTABLE property set.
70 · One of the tools png2ico (See FindPng2Ico) or icotool (see
72 FindIcoTool) is required.
73 · Supported sizes: 16, 24, 32, 48, 64, 128, 256, 512 and 1024.
75 Mac OS X notes
77 · The executable target must have the MACOSX_BUNDLE property
79 set.
80 · Icons are added to the bundle.
82 · 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 · The tool iconutil (provided by Apple) is required for bitmap
89 icons.
90 · Supported sizes: 16, 32, 64, 128, 256 (and 512, 1024 after OS
92 X 10.9).
93 · At least a 128x128px (or an SVG) icon is required.
95 · 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 · 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 · Sidebar icons should typically provided in 16, 32, 64, 128 and
111 256px.
112 Since 1.7.0.
114 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 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 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 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 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 NAME specifies the name for the generated documentation.
168 VERSION specifies the version of the library for which the documenta‐
170 tion is created.
171 BASE_NAME specifies the base name for the generated files. The default
173 basename is <name>.
174 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 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 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 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 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 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 QCH_INSTALL_DESTINATION specifies where the generated QCH file will be
201 installed.
202 TAGFILE_INSTALL_DESTINATION specifies where the generated tag file will
204 be installed.
205 COMPONENT specifies the installation component name with which the
207 install rules for the generated QCH file and tag file are associated.
208 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 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 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 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 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 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 VERBOSE tells the API dox generation tool to be more verbose about its
252 activity.
253 The default config file for the API dox generation tool, so the one
255 when not using CONFIG_TEMPLATE, allows code to handle the case of being
256 processed by the tool by defining the C/C++ preprocessor macro K_DOXY‐
257 GEN when run (since v5.67.0). For backward-compatibility also the defi‐
258 nition DOXYGEN_SHOULD_SKIP_THIS is set, but its usage is deprecated.
259 Example usage:
261 ecm_add_qch(
263 MyLib_QCH
264 NAME MyLib
265 VERSION "0.42.0"
266 ORG_DOMAIN org.myorg
267 SOURCE_DIRS
268 src
269 LINK_QCHS
270 Qt5Core_QCH
271 Qt5Xml_QCH
272 Qt5Gui_QCH
273 Qt5Widgets_QCH
274 BLANK_MACROS
275 MyLib_EXPORT
276 MyLib_DEPRECATED
277 TAGFILE_INSTALL_DESTINATION ${CMAKE_INSTALL_PREFIX}/share/docs/tags
278 QCH_INSTALL_DESTINATION ${CMAKE_INSTALL_PREFIX}/share/docs/qch
279 COMPONENT Devel
280 )
281 Example usage (with two QCH files, second linking first):
283 ecm_add_qch(
285 MyLib_QCH
286 NAME MyLib
287 VERSION ${MyLib_VERSION}
288 ORG_DOMAIN org.myorg
289 SOURCES ${MyLib_PUBLIC_HEADERS}
290 MD_MAINPAGE src/mylib/README.md
291 LINK_QCHS Qt5Core_QCH
292 TAGFILE_INSTALL_DESTINATION ${CMAKE_INSTALL_PREFIX}/share/docs/tags
293 QCH_INSTALL_DESTINATION ${CMAKE_INSTALL_PREFIX}/share/docs/qch
294 COMPONENT Devel
295 )
296 ecm_add_qch(
297 MyOtherLib_QCH
298 NAME MyOtherLib
299 VERSION ${MyOtherLib_VERSION}
300 ORG_DOMAIN org.myorg
301 SOURCES ${MyOtherLib_PUBLIC_HEADERS}
302 MD_MAINPAGE src/myotherlib/README.md
303 LINK_QCHS Qt5Core_QCH MyLib_QCH
304 TAGFILE_INSTALL_DESTINATION ${CMAKE_INSTALL_PREFIX}/share/docs/tags
305 QCH_INSTALL_DESTINATION ${CMAKE_INSTALL_PREFIX}/share/docs/qch
306 COMPONENT Devel
307 )
308 ecm_install_qch_export(
310 TARGETS [<name> [<name2> [...]]]
311 FILE <file>
312 DESTINATION <dest>
313 [COMPONENT <component>]
314 )
315 This macro creates and installs a CMake file <file> which exports the
317 given QCH targets <name> etc., so they can be picked up by CMake-based
318 builds of other software that also generate QCH files (using
319 ecm_add_qch) and which should include links to the QCH files created by
320 the given targets. The installed CMake file <file> is expected to be
321 included by the CMake config file created for the software the related
322 QCH files are documenting.
323 TARGETS specifies the QCH targets which should be exported. If a target
325 does not exist or does not have all needed properties, a warning will
326 be generated and the target skipped. This behaviour might change in
327 future versions to result in a fail instead.
328 FILE specifies the name of the created CMake file, typically with a
330 .cmake extension.
331 DESTINATION specifies the directory on disk to which the file will be
333 installed. It usually is the same as the one where the CMake config
334 files for this software are installed.
335 COMPONENT specifies the installation component name with which the
337 install rule is associated.
338 Example usage:
340 ecm_install_qch_export(
342 TARGETS MyLib_QCH
343 FILE MyLibQCHTargets.cmake
344 DESTINATION "${CMAKE_INSTALL_PREFIX}/lib/cmake/MyLib"
345 COMPONENT Devel
346 )
347 Since 5.36.0.
349 ECMAddQtDesignerPlugin
351 This module provides the ecm_add_qtdesignerplugin function for generat‐
352 ing Qt Designer plugins for custom widgets. Each of those widgets is
353 described using a second function ecm_qtdesignerplugin_widget.
354 ecm_add_qtdesignerplugin(<target_name>
356 NAME <name>
357 WIDGETS <widgetid> [<widgetid2> [...]]
358 LINK_LIBRARIES <lib> [<lib2> [...]]
359 INSTALL_DESTINATION <install_path>
360 [OUTPUT_NAME <output_name>]
361 [DEFAULT_GROUP <group>]
362 [DEFAULT_HEADER_CASE <SAME_CASE|LOWER_CASE|UPPER_CASE>]
363 [DEFAULT_HEADER_EXTENSION <header_extension>]
364 [DEFAULT_ICON_DIR <icon_dir>]
365 [INCLUDE_FILES <include_file> [<include_file2> [...]]]
366 [SOURCES <src> [<src2> [...]]]
367 [COMPONENT <component>]
368 )
369 NAME specifies the base name to use in the generated sources. The
371 default is <target_name>.
372 WIDGETS specifies the widgets the plugin should support. Each widget
374 has to be defined before by a call of ecm_qtdesignerplugin_widget with
375 the respective <widgetid>, in a scope including the current call.
376 LINK_LIBRARIES specifies the libraries to link against. This will be at
378 least the library providing the widget class(es).
379 INSTALL_DESTINATION specifies where the generated plugin binary will be
381 installed.
382 OUTPUT_NAME specifies the name of the plugin binary. The default is
384 “<target_name>”.
385 DEFAULT_GROUP specifies the default group in Qt Designer where the wid‐
387 gets will be placed. The default is “Custom”.
388 DEFAULT_HEADER_CASE specifies how the name of the header is derived
390 from the widget class name. The default is “LOWER_CASE”.
391 DEFAULT_HEADER_EXTENSION specifies what file name extension is used for
393 the header file derived from the class name. The default is “h”.
394 DEFAULT_ICON_DIR specifies what file name extension is used for the
396 header file derived from the class name. The default is “pics”.
397 INCLUDE_FILES specifies additional include files to include with the
399 generated source file. This can be needed for custom code used in ini‐
400 tializing or creating widgets.
401 SOURCES specifies additional source files to build the plugin from.
403 This can be needed to support custom code used in initializing or cre‐
404 ating widgets.
405 COMPONENT specifies the installation component name with which the
407 install rules for the generated plugin are associated.
408 ecm_qtdesignerplugin_widget(<widgetid>
410 [CLASS_NAME <class_name>]
411 [INCLUDE_FILE <include_file>]
412 [CONTAINER]
413 [ICON <iconfile>]
414 [TOOLTIP <tooltip>]
415 [WHATSTHIS <whatsthis>]
416 [GROUP <group>]
417 [CREATE_WIDGET_CODE_FROM_VARIABLE <create_widget_code_variable>]
418 [INITIALIZE_CODE_FROM_VARIABLE <initialize_code_variable]
419 [DOM_XML_FROM_VARIABLE <dom_xml_variable>]
420 [IMPL_CLASS_NAME <impl_class_name>]
421 [CONSTRUCTOR_ARGS_CODE <constructor_args_code>]
422 [CONSTRUCTOR_ARGS_CODE_FROM_VARIABLE <constructor_args_code_variable>]
423 )
424 CLASS_NAME specifies the name of the widget class, including names‐
426 paces. The default is “<widgetid>”.
427 INCLUDE_FILE specifies the include file to use for the class of this
429 widget. The default is derived from <class_name> as configured by the
430 DEFAULT_HEADER_* options of ecm_add_qtdesignerplugin, also replacing
431 any namespace separators with “/”.
432 CONTAINER specifies, if set, that this widget is a container for other
434 widgets.
435 ICON specifies the icon file to use as symbol for this widget. The
437 default is “{lowercased <class_name>}.png” in the default icons dir as
438 configured by the DEFAULT_ICON_DIR option of ecm_add_qtdesignerplugin,
439 if such a file exists.
440 TOOLTIP specifies the tooltip text to use for this widget. Default is
442 “<class_name> Widget”.
443 WHATSTHIS specifies the What’s-This text to use for this widget.
445 Defaults to the tooltip.
446 GROUP specifies the group in Qt Designer where the widget will be
448 placed. The default is set as configured by the DEFAULT_GROUP option
449 of ecm_add_qtdesignerplugin.
450 CREATE_WIDGET_CODE_FROM_VARIABLE specifies the variable to get from the
452 C++ code to use as factory code to create an instance of the widget,
453 for the override of QDesignerCustomWidgetInterface::createWidget(QWid‐
454 get* parent). The default is “return new <impl_class_name><construc‐
455 tor_args_code>;”.
456 INITIALIZE_CODE_FROM_VARIABLE specifies the variable to get from the
458 C++ code to use with the override of QDesignerCustomWidgetInter‐
459 face::initialize(QDesignerFormEditorInterface* core). The code has to
460 use the present class member m_initialized to track and update the
461 state. The default code simply sets m_initialized to true, if it was
462 not before.
463 DOM_XML_FROM_VARIABLE specifies the variable to get from the string to
465 use with the optional override of QDesignerCustomWidgetInter‐
466 face::domXml(). Default does not override.
467 IMPL_CLASS_NAME specifies the name of the widget class to use for the
469 widget instance with Qt Designer. The default is “<class_name>”.
470 CONSTRUCTOR_ARGS_CODE specifies the C++ code to use for the constructor
472 arguments with the default of CREATE_WIDGET_CODE_FROM_VARIABLE. Note
473 that the parentheses are required. The default is “(parent)”.
474 CONSTRUCTOR_ARGS_CODE_FROM_VARIABLE specifies the variable to get from
476 the C++ code instead of passing it directly via CONSTRUCTOR_ARGS_CODE.
477 This can be needed if the code is more complex and e.g. includes “;”
478 chars.
479 Example usage:
481 ecm_qtdesignerplugin_widget(FooWidget
483 TOOLTIP "Enables to browse foo."
484 GROUP "Views (Foo)"
485 )
486 set(BarWidget_CREATE_WIDGET_CODE
488 "
489 auto* widget = new BarWidget(parent);
490 widget->setBar("Example bar");
491 return widget;
492 ")
493 ecm_qtdesignerplugin_widget(BarWidget
495 TOOLTIP "Displays bars."
496 GROUP "Display (Foo)"
497 CREATE_WIDGET_CODE_FROM_VARIABLE BarWidget_CREATE_WIDGET_CODE
498 )
499 ecm_add_qtdesignerplugin(foowidgets
501 NAME FooWidgets
502 OUTPUT_NAME foo2widgets
503 WIDGETS
504 FooWidget
505 BarWidget
506 LINK_LIBRARIES
507 Foo::Widgets
508 INSTALL_DESTINATION "${KDE_INSTALL_QTPLUGINDIR}/designer"
509 COMPONENT Devel
510 )
511 Since 5.62.0.
513 ECMAddTests
515 Convenience functions for adding tests.
516 ecm_add_tests(<sources> LINK_LIBRARIES <library> [<library> [...]]
518 [NAME_PREFIX <prefix>]
519 [GUI]
520 [TARGET_NAMES_VAR <target_names_var>]
521 [TEST_NAMES_VAR <test_names_var>])
522 A convenience function for adding multiple tests, each consisting of a
524 single source file. For each file in <sources>, an executable target
525 will be created (the name of which will be the basename of the source
526 file). This will be linked against the libraries given with
527 LINK_LIBRARIES. Each executable will be added as a test with the same
528 name.
529 If NAME_PREFIX is given, this prefix will be prepended to the test
531 names, but not the target names. As a result, it will not prevent
532 clashes between tests with the same name in different parts of the
533 project, but it can be used to give an indication of where to look for
534 a failing test.
535 If the flag GUI is passed the test binaries will be GUI executables,
537 otherwise the resulting binaries will be console applications (regard‐
538 less of the value of CMAKE_WIN32_EXECUTABLE or CMAKE_MACOSX_BUNDLE). Be
539 aware that this changes the executable entry point on Windows (although
540 some frameworks, such as Qt, abstract this difference away).
541 The TARGET_NAMES_VAR and TEST_NAMES_VAR arguments, if given, should
543 specify a variable name to receive the list of generated target and
544 test names, respectively. This makes it convenient to apply properties
545 to them as a whole, for example, using set_target_properties() or
546 set_tests_properties().
547 The generated target executables will have the effects of
549 ecm_mark_as_test() (from the ECMMarkAsTest module) applied to it.
550 ecm_add_test(<sources> LINK_LIBRARIES <library> [<library> [...]]
552 [TEST_NAME <name>]
553 [NAME_PREFIX <prefix>]
554 [GUI])
555 This is a single-test form of ecm_add_tests that allows multiple source
557 files to be used for a single test. If using multiple source files,
558 TEST_NAME must be given; this will be used for both the target and test
559 names (and, as with ecm_add_tests(), the NAME_PREFIX argument will be
560 prepended to the test name).
561 Since pre-1.0.0.
563 ECMCoverageOption
565 Allow users to easily enable GCov code coverage support.
566 Code coverage allows you to check how much of your codebase is covered
568 by your tests. This module makes it easy to build with support for
569 GCov.
570 When this module is included, a BUILD_COVERAGE option is added (default
572 OFF). Turning this option on enables GCC’s coverage instrumentation,
573 and links against libgcov.
574 Note that this will probably break the build if you are not using GCC.
576 Since 1.3.0.
578 ECMCreateQmFromPoFiles
580 WARNING:
581 This module is deprecated and will be removed by ECM 1.0. Use ECMPo‐
582 QmTools instead.
583 Generate QTranslator (.qm) catalogs from Gettext (.po) catalogs.
585 ecm_create_qm_from_po_files(PO_FILES <file1>... <fileN>
587 [CATALOG_NAME <catalog_name>]
588 [INSTALL_DESTINATION <install_destination>])
589 Creates the necessary rules to compile .po files into .qm files, and
591 install them.
592 The .qm files are installed in <install_destination>/<lang>/LC_MES‐
594 SAGES, where <install_destination> is the INSTALL_DESTINATION argument
595 and <lang> is extracted from the “Language” field inside the .po file.
596 INSTALL_DESTINATION defaults to ${LOCALE_INSTALL_DIR} if defined, oth‐
598 erwise it uses ${CMAKE_INSTALL_LOCALEDIR} if that is defined, otherwise
599 it uses share/locale.
600 CATALOG_NAME defines the name of the installed .qm files. If set, .qm
602 files will be installed as <catalog_name>.qm. If not set .qm files will
603 be named after the name of their source .po file.
604 Setting the catalog name is useful when all .po files for a target are
606 kept in a single source directory. For example, the “mylib” probject
607 might keep all its translations in a “po” directory, like this:
608 po/
610 es.po
611 fr.po
612 Without setting CATALOG_NAME, those .po will be turned into .qm and
614 installed as:
615 share/locale/fr/LC_MESSAGES/fr.qm
617 share/locale/es/LC_MESSAGES/es.qm
618 If CATALOG_NAME is set to “mylib”, they will be installed as:
620 share/locale/fr/LC_MESSAGES/mylib.qm
622 share/locale/es/LC_MESSAGES/mylib.qm
623 Which is what the loader created by ecm_create_qm_loader() expects.
625 ecm_create_qm_from_po_files() creates a “translation” target. This tar‐
627 get builds all .po files into .qm files.
628 ecm_create_qm_loader(<source_files_var> <catalog_name>)
630 ecm_create_qm_loader() generates a C++ file which ensures translations
632 are automatically loaded at startup. The path of the .cpp file is
633 appended to <source_files_var>. Typical usage is like:
634 set(mylib_SRCS foo.cpp bar.cpp)
636 ecm_create_qm_loader(mylib_SRCS mylib)
637 add_library(mylib ${mylib_SRCS})
638 This generates a C++ file which loads “mylib.qm” at startup, assuming
640 it has been installed by ecm_create_qm_from_po_files(), and compiles it
641 into mylib.
642 Since pre-1.0.0.
644 ECMEnableSanitizers
646 Enable compiler sanitizer flags.
647 The following sanitizers are supported:
649 · Address Sanitizer
651 · Memory Sanitizer
653 · Thread Sanitizer
655 · Leak Sanitizer
657 · Undefined Behaviour Sanitizer
659 All of them are implemented in Clang, depending on your version, and
661 there is an work in progress in GCC, where some of them are currently
662 implemented.
663 This module will check your current compiler version to see if it sup‐
665 ports the sanitizers that you want to enable
666 Usage
668 Simply add:
669 include(ECMEnableSanitizers)
671 to your CMakeLists.txt. Note that this module is included in KDECompil‐
673 erSettings, so projects using that module do not need to also include
674 this one.
675 The sanitizers are not enabled by default. Instead, you must set
677 ECM_ENABLE_SANITIZERS (either in your CMakeLists.txt or on the command
678 line) to a semicolon-separated list of sanitizers you wish to enable.
679 The options are:
680 · address
682 · memory
684 · thread
686 · leak
688 · undefined
690 · fuzzer
692 The sanitizers “address”, “memory” and “thread” are mutually exclusive.
694 You cannot enable two of them in the same build.
695 “leak” requires the “address” sanitizer.
697 NOTE:
699 To reduce the overhead induced by the instrumentation of the sani‐
700 tizers, it is advised to enable compiler optimizations (-O1 or
701 higher).
702 Example
704 This is an example of usage:
705 mkdir build
707 cd build
708 cmake -DECM_ENABLE_SANITIZERS='address;leak;undefined' ..
709 NOTE:
711 Most of the sanitizers will require Clang. To enable it, use:
712 -DCMAKE_CXX_COMPILER=clang++
714 Since 1.3.0.
716 ECMFindModuleHelpers
718 Helper macros for find modules: ecm_find_package_version_check(),
719 ecm_find_package_parse_components() and ecm_find_package_han‐
720 dle_library_components().
721 ecm_find_package_version_check(<name>)
723 Prints warnings if the CMake version or the project’s required CMake
725 version is older than that required by extra-cmake-modules.
726 ecm_find_package_parse_components(<name>
728 RESULT_VAR <variable>
729 KNOWN_COMPONENTS <component1> [<component2> [...]]
730 [SKIP_DEPENDENCY_HANDLING])
731 This macro will populate <variable> with a list of components found in
733 <name>_FIND_COMPONENTS, after checking that all those components are in
734 the list of KNOWN_COMPONENTS; if there are any unknown components, it
735 will print an error or warning (depending on the value of
736 <name>_FIND_REQUIRED) and call return().
737 The order of components in <variable> is guaranteed to match the order
739 they are listed in the KNOWN_COMPONENTS argument.
740 If SKIP_DEPENDENCY_HANDLING is not set, for each component the variable
742 <name>_<component>_component_deps will be checked for dependent compo‐
743 nents. If <component> is listed in <name>_FIND_COMPONENTS, then all
744 its (transitive) dependencies will also be added to <variable>.
745 ecm_find_package_handle_library_components(<name>
747 COMPONENTS <component> [<component> [...]]
748 [SKIP_DEPENDENCY_HANDLING])
749 [SKIP_PKG_CONFIG])
750 Creates an imported library target for each component. The operation
752 of this macro depends on the presence of a number of CMake variables.
753 The <name>_<component>_lib variable should contain the name of this
755 library, and <name>_<component>_header variable should contain the name
756 of a header file associated with it (whatever relative path is normally
757 passed to ‘#include’). <name>_<component>_header_subdir variable can be
758 used to specify which subdirectory of the include path the headers will
759 be found in. ecm_find_package_components() will then search for the
760 library and include directory (creating appropriate cache variables)
761 and create an imported library target named <name>::<component>.
762 Additional variables can be used to provide additional information:
764 If SKIP_PKG_CONFIG, the <name>_<component>_pkg_config variable is set,
766 and pkg-config is found, the pkg-config module given by <name>_<compo‐
767 nent>_pkg_config will be searched for and used to help locate the
768 library and header file. It will also be used to set <name>_<compo‐
769 nent>_VERSION.
770 Note that if version information is found via pkg-config, <name>_<com‐
772 ponent>_FIND_VERSION can be set to require a particular version for
773 each component.
774 If SKIP_DEPENDENCY_HANDLING is not set, the INTERFACE_LINK_LIBRARIES
776 property of the imported target for <component> will be set to contain
777 the imported targets for the components listed in <name>_<compo‐
778 nent>_component_deps. <component>_FOUND will also be set to false if
779 any of the compoments in <name>_<component>_component_deps are not
780 found. This requires the components in <name>_<component>_compo‐
781 nent_deps to be listed before <component> in the COMPONENTS argument.
782 The following variables will be set:
784 <name>_TARGETS
786 the imported targets
787 <name>_LIBRARIES
789 the found libraries
790 <name>_INCLUDE_DIRS
792 the combined required include directories for the components
793 <name>_DEFINITIONS
795 the “other” CFLAGS provided by pkg-config, if any
796 <name>_VERSION
798 the value of <name>_<component>_VERSION for the first component
799 that has this variable set (note that components are searched
800 for in the order they are passed to the macro), although if it
801 is already set, it will not be altered
802 Note that these variables are never cleared, so if ecm_find_pack‐
804 age_handle_library_components() is called multiple times with different
805 components (typically because of multiple find_package() calls) then
806 <name>_TARGETS, for example, will contain all the targets found in any
807 call (although no duplicates).
808 Since pre-1.0.0.
810 ECMGenerateExportHeader
812 This module provides the ecm_generate_export_header function for gener‐
813 ating export macros for libraries with version-based control over visi‐
814 bility of and compiler warnings for deprecated API for the library
815 user, as well as over excluding deprecated API and their implementation
816 when building the library itself.
817 For preparing some values useful in the context it also provides a
819 function ecm_export_header_format_version.
820 ecm_generate_export_header(<library_target_name>
822 VERSION <version>
823 [BASE_NAME <base_name>]
824 [GROUP_BASE_NAME <group_base_name>]
825 [EXPORT_MACRO_NAME <export_macro_name>]
826 [EXPORT_FILE_NAME <export_file_name>]
827 [DEPRECATED_MACRO_NAME <deprecated_macro_name>]
828 [NO_EXPORT_MACRO_NAME <no_export_macro_name>]
829 [INCLUDE_GUARD_NAME <include_guard_name>]
830 [STATIC_DEFINE <static_define>]
831 [PREFIX_NAME <prefix_name>]
832 [DEPRECATED_BASE_VERSION <deprecated_base_version>]
833 [DEPRECATION_VERSIONS <deprecation_version> [<deprecation_version2> [...]]]
834 [EXCLUDE_DEPRECATED_BEFORE_AND_AT <exclude_deprecated_before_and_at_version>]
835 [NO_BUILD_SET_DEPRECATED_WARNINGS_SINCE]
836 [NO_DEFINITION_EXPORT_TO_BUILD_INTERFACE]
837 [CUSTOM_CONTENT_FROM_VARIABLE <variable>]
838 )
839 VERSION specifies the version of the library, given in the format
841 “<major>.<minor>.<patchlevel>”.
842 GROUP_BASE_NAME specifies the name to use for the macros defining
844 library group default values. If set, this will generate code support‐
845 ing <group_base_name>_NO_DEPRECATED_WARNINGS, <group_base_name>_DIS‐
846 ABLE_DEPRECATED_BEFORE_AND_AT, <group_base_name>_DEPRECATED_WARN‐
847 INGS_SINCE and <group_base_name>_NO_DEPRECATED (see below). If not
848 set, the generated code will ignore any such macros.
849 DEPRECATED_BASE_VERSION specifies the default version before and at
851 which deprecated API is disabled. The default is the value of
852 “<exclude_deprecated_before_and_at_version>” if set, or “<major>.0.0”,
853 with <major> taken from <version>.
854 DEPRECATION_VERSIONS specifies versions in “<major>.<minor>” format in
856 which API was declared deprecated. Any version used with the generated
857 macro <prefix_name><base_name>_DEPRECATED_VERSION(major, minor, text)
858 needs to be listed here, otherwise the macro will fail to work.
859 EXCLUDE_DEPRECATED_BEFORE_AND_AT specifies the version for which all
861 API deprecated before and at should be excluded from the build com‐
862 pletely. Possible values are “0” (default), “CURRENT” (which resolves
863 to <version>) and a version string in the format
864 “<major>.<minor>.<patchlevel>”.
865 NO_BUILD_SET_DEPRECATED_WARNINGS_SINCE specifies that the definition
867 <prefix_name><uppercase_base_name>_DEPRECATED_WARNINGS_SINCE will not
868 be set for the library inside its own build, and thus will be defined
869 by either explicit definition in the build system configuration or by
870 the default value mechanism (see below). The default is that it is set
871 for the build, to the version specified by EXCLUDE_DEPRE‐
872 CATED_BEFORE_AND_AT, so no deprecation warnings are done for any own
873 deprecated API used in the library implementation itself.
874 NO_DEFINITION_EXPORT_TO_BUILD_INTERFACE specifies that the definition
876 <prefix_name><uppercase_base_name>_DISABLE_DEPRECATED_BEFORE_AND_AT
877 will not be set in the public interface of the library inside its own
878 build, and the same for the definition <prefix_name><upper‐
879 case_base_name>_DEPRECATED_WARNINGS_SINCE (if not disabled by
880 NO_BUILD_SET_DEPRECATED_WARNINGS_SINCE already). The default is that
881 they are set, to the version specified by EXCLUDE_DEPRE‐
882 CATED_BEFORE_AND_AT, so e.g. test and examples part of the project
883 automatically build against the full API included in the build and
884 without any deprecation warnings for it.
885 The function ecm_generate_export_header defines C++ preprocessor macros
887 in the generated export header, some for use in the sources of the
888 library the header is generated for, other for use by projects linking
889 agsinst the library.
890 The macros for use in the library C++ sources are these, next to those
892 also defined by GenerateExportHeader:
893 <prefix_name><uppercase_base_name>_DEPRECATED_VERSION(major, minor,
895 text)
896 to use to conditionally set a <prefix_name><upper‐
897 case_base_name>_DEPRECATED macro for a class, struct or function
898 (other elements to be supported in future versions), depending
899 on the visibility macro flags set (see below)
900 <prefix_name><uppercase_base_name>_ENABLE_DEPRECATED_SINCE(major,
902 minor)
903 evaluates to TRUE or FALSE depending on the visibility macro
904 flags set (see below). To be used mainly with #if/#endif to mark
905 sections of code which should be included depending on the visi‐
906 bility requested.
907 <prefix_name><uppercase_base_name>_BUILD_DEPRECATED_SINCE(major, minor)
909 evaluates to TRUE or FALSE depending on the value of
910 EXCLUDE_DEPRECATED_BEFORE_AND_AT. To be used mainly with
911 #if/#endif to mark sections of two types of code: implementation
912 code for deprecated API and declaration code of deprecated API
913 which only may be disabled at build time of the library for BC
914 reasons (e.g. virtual methods, see notes below).
915 <prefix_name><uppercase_base_name>_EXCLUDE_DEPRECATED_BEFORE_AND_AT
917 holds the version used to exclude deprecated API at build time
918 of the library.
919 The macros used to control visibility when building against the library
921 are:
922 <prefix_name><uppercase_base_name>_DISABLE_DEPRECATED_BEFORE_AND_AT
924 definition to set to a value in single hex number version nota‐
925 tion (0x<major><minor><patchlevel>).
926 <prefix_name><uppercase_base_name>_NO_DEPRECATED
928 flag to define to disable all deprecated API, being a shortcut
929 for settings <prefix_name><uppercase_base_name>_DISABLE_DEPRE‐
930 CATED_BEFORE_AND_AT to the current version. If both are set,
931 this flag overrules.
932 <prefix_name><uppercase_base_name>_DEPRECATED_WARNINGS_SINCE
934 definition to set to a value in single hex number version nota‐
935 tion (0x<major><minor><patchlevel>). Warnings will be only acti‐
936 vated for API deprecated up to and including the version. If
937 <prefix_name><uppercase_base_name>_DISABLE_DEPRE‐
938 CATED_BEFORE_AND_AT is set (directly or via the group default),
939 it will default to that version, resulting in no warnings. Oth‐
940 erwise the default is the current version, resulting in warnings
941 for all deprecated API.
942 <prefix_name><uppercase_base_name>_NO_DEPRECATED_WARNINGS
944 flag to define to disable all deprecation warnings, being a
945 shortcut for setting <prefix_name><uppercase_base_name>_DEPRE‐
946 CATED_WARNINGS_SINCE to “0”. If both are set, this flag over‐
947 rules.
948 When the GROUP_BASE_NAME has been used, the same macros but with the
950 given <group_base_name> prefix are available to define the defaults of
951 these macros, if not explicitly set.
952 Note: The tricks applied here for hiding deprecated API to the compiler
954 when building against a library do not work for all deprecated API:
955 · virtual methods need to stay visible to the compiler to build proper
957 virtual method tables for subclasses
958 · enumerators from enums cannot be simply removed, as this changes auto
960 values of following enumerators, also can poke holes in enumerator
961 series used as index into tables
962 In such cases the API can be only “hidden” at build time of the
964 library, itself, by generated hard coded macro settings, using <pre‐
965 fix_name><uppercase_base_name>_BUILD_DEPRECATED_SINCE(major, minor).
966 Examples:
968 Preparing a library “Foo” created by target “foo”, which is part of a
970 group of libraries “Bar”, where some API of “Foo” got deprecated at
971 versions 5.0 & 5.12:
972 ecm_generate_export_header(foo
974 GROUP_BASE_NAME BAR
975 VERSION ${FOO_VERSION}
976 DEPRECATION_VERSIONS 5.0 5.12
977 )
978 In the library “Foo” sources in the headers the API would be prepared
980 like this, using the generated macros FOO_ENABLE_DEPRECATED_SINCE and
981 FOO_DEPRECATED_VERSION:
982 #include <foo_export.h>
984 #if FOO_ENABLE_DEPRECATED_SINCE(5, 0)
986 /**
987 * @deprecated Since 5.0
988 */
989 FOO_DEPRECATED_VERSION(5, 0, "Use doFoo2()")
990 FOO_EXPORT void doFoo();
991 #endif
992 #if FOO_ENABLE_DEPRECATED_SINCE(5, 12)
994 /**
995 * @deprecated Since 5.12
996 */
997 FOO_DEPRECATED_VERSION(5, 12, "Use doBar2()")
998 FOO_EXPORT void doBar();
999 #endif
1000 Projects linking against the “Foo” library can control which part of
1002 its deprecated API should be hidden to the compiler by adding a defini‐
1003 tion using the FOO_DISABLE_DEPRECATED_BEFORE_AND_AT macro variable set
1004 to the desired value (in version hex number notation):
1005 add_definitions(-DFOO_DISABLE_DEPRECATED_BEFORE_AND_AT=0x050000)
1007 Or using the macro variable of the group:
1009 add_definitions(-DBAR_DISABLE_DEPRECATED_BEFORE_AND_AT=0x050000)
1011 If both are specified, FOO_DISABLE_DEPRECATED_BEFORE_AND_AT will take
1013 precedence.
1014 To build a variant of a library with some deprecated API completely
1016 left out from the build, not only optionally invisible to consumers,
1017 one uses the EXCLUDE_DEPRECATED_BEFORE_AND_AT parameter. This is best
1018 combined with a cached CMake variable.
1019 set(EXCLUDE_DEPRECATED_BEFORE_AND_AT 0 CACHE STRING "Control the range of deprecated API excluded from the build [default=0].")
1021 ecm_generate_export_header(foo
1023 VERSION ${FOO_VERSION}
1024 EXCLUDE_DEPRECATED_BEFORE_AND_AT ${EXCLUDE_DEPRECATED_BEFORE_AND_AT}
1025 DEPRECATION_VERSIONS 5.0 5.12
1026 )
1027 The macros used in the headers for library consumers are reused for
1029 disabling the API excluded in the build of the library. For disabling
1030 the implementation of that API as well as for disabling deprecated API
1031 which only can be disabled at build time of the library for BC reasons,
1032 one uses the generated macro FOO_BUILD_DEPRECATED_SINCE, like this:
1033 #include <foo_export.h>
1035 enum Bars {
1037 One,
1038 #if FOO_BUILD_DEPRECATED_SINCE(5, 0)
1039 Two,
1040 #endif
1041 Three,
1042 };
1043 #if FOO_ENABLE_DEPRECATED_SINCE(5, 0)
1045 /**
1046 * @deprecated Since 5.0
1047 */
1048 FOO_DEPRECATED_VERSION(5, 0, "Use doFoo2()")
1049 FOO_EXPORT void doFoo();
1050 #endif
1051 #if FOO_ENABLE_DEPRECATED_SINCE(5, 12)
1053 /**
1054 * @deprecated Since 5.12
1055 */
1056 FOO_DEPRECATED_VERSION(5, 12, "Use doBar2()")
1057 FOO_EXPORT void doBar();
1058 #endif
1059 class FOO_EXPORT Foo {
1061 public:
1062 #if FOO_BUILD_DEPRECATED_SINCE(5, 0)
1063 /**
1064 * @deprecated Since 5.0
1065 */
1066 FOO_DEPRECATED_VERSION(5, 0, "Feature removed")
1067 virtual void doWhat();
1068 #endif
1069 };
1070 #if FOO_BUILD_DEPRECATED_SINCE(5, 0)
1072 void doFoo()
1073 {
1074 // [...]
1075 }
1076 #endif
1077 #if FOO_BUILD_DEPRECATED_SINCE(5, 12)
1079 void doBar()
1080 {
1081 // [...]
1082 }
1083 #endif
1084 #if FOO_BUILD_DEPRECATED_SINCE(5, 0)
1086 void Foo::doWhat()
1087 {
1088 // [...]
1089 }
1090 #endif
1091 So e.g. if EXCLUDE_DEPRECATED_BEFORE_AND_AT is set to “5.0.0”, the enu‐
1093 merator Two as well as the methods ::doFoo() and Foo::doWhat() will be
1094 not available to library consumers. The methods will not have been com‐
1095 piled into the library binary, and the declarations will be hidden to
1096 the compiler, FOO_DISABLE_DEPRECATED_BEFORE_AND_AT also cannot be used
1097 to reactivate them.
1098 When using the NO_DEFINITION_EXPORT_TO_BUILD_INTERFACE and the project
1100 for the “Foo” library includes also tests and examples linking against
1101 the library and using deprecated API (like tests covering it), one bet‐
1102 ter explicitly sets FOO_DISABLE_DEPRECATED_BEFORE_AND_AT for those tar‐
1103 gets to the version before and at which all deprecated API has been
1104 excluded from the build. Even more when building against other
1105 libraries from the same group “Bar” and disabling some deprecated API
1106 of those libraries using the group macro BAR_DISABLE_DEPRE‐
1107 CATED_BEFORE_AND_AT, which also works as default for FOO_DISABLE_DEPRE‐
1108 CATED_BEFORE_AND_AT.
1109 To get the hex number style value the helper macro
1111 ecm_export_header_format_version() will be used:
1112 set(EXCLUDE_DEPRECATED_BEFORE_AND_AT 0 CACHE STRING "Control what part of deprecated API is excluded from build [default=0].")
1114 ecm_generate_export_header(foo
1116 VERSION ${FOO_VERSION}
1117 GROUP_BASE_NAME BAR
1118 EXCLUDE_DEPRECATED_BEFORE_AND_AT ${EXCLUDE_DEPRECATED_BEFORE_AND_AT}
1119 NO_DEFINITION_EXPORT_TO_BUILD_INTERFACE
1120 DEPRECATION_VERSIONS 5.0 5.12
1121 )
1122 ecm_export_header_format_version(${EXCLUDE_DEPRECATED_BEFORE_AND_AT}
1124 CURRENT_VERSION ${FOO_VERSION}
1125 HEXNUMBER_VAR foo_no_deprecated_before_and_at
1126 )
1127 # disable all deprecated API up to 5.9.0 from all other libs of group "BAR" that we use ourselves
1129 add_definitions(-DBAR_DISABLE_DEPRECATED_BEFORE_AND_AT=0x050900)
1130 add_executable(app app.cpp)
1132 target_link_libraries(app foo)
1133 target_compile_definitions(app
1134 PRIVATE "FOO_DISABLE_DEPRECATED_BEFORE_AND_AT=${foo_no_deprecated_before_and_at}")
1135 Since 5.64.0.
1137 ECMGenerateHeaders
1139 Generate C/C++ CamelCase forwarding headers.
1140 ecm_generate_headers(<camelcase_forwarding_headers_var>
1142 HEADER_NAMES <CamelCaseName> [<CamelCaseName> [...]]
1143 [ORIGINAL <CAMELCASE|LOWERCASE>]
1144 [HEADER_EXTENSION <header_extension>]
1145 [OUTPUT_DIR <output_dir>]
1146 [PREFIX <prefix>]
1147 [REQUIRED_HEADERS <variable>]
1148 [COMMON_HEADER <HeaderName>]
1149 [RELATIVE <relative_path>])
1150 For each CamelCase header name passed to HEADER_NAMES, a file of that
1152 name will be generated that will include a version with .h or, if set,
1153 .<header_extension> appended. For example, the generated header ClassA
1154 will include classa.h (or ClassA.h, see ORIGINAL). If a CamelCaseName
1155 consists of multiple comma-separated files, e.g. ClassA,ClassB,ClassC,
1156 then multiple camelcase header files will be generated which are redi‐
1157 rects to the first header file. The file locations of these generated
1158 headers will be stored in <camelcase_forwarding_headers_var>.
1159 ORIGINAL specifies how the name of the original header is written: low‐
1161 ercased or also camelcased. The default is LOWERCASE. Since 1.8.0.
1162 HEADER_EXTENSION specifies what file name extension is used for the
1164 header files. The default is “h”. Since 5.48.0.
1165 PREFIX places the generated headers in subdirectories. This should be
1167 a CamelCase name like KParts, which will cause the CamelCase forwarding
1168 headers to be placed in the KParts directory (e.g. KParts/Part). It
1169 will also, for the convenience of code in the source distribution, gen‐
1170 erate forwarding headers based on the original names (e.g.
1171 kparts/part.h). This allows includes like "#include <kparts/part.h>"
1172 to be used before installation, as long as the include_directories are
1173 set appropriately.
1174 OUTPUT_DIR specifies where the files will be generated; this should be
1176 within the build directory. By default, ${CMAKE_CURRENT_BINARY_DIR}
1177 will be used. This option can be used to avoid file conflicts.
1178 REQUIRED_HEADERS specifies an output variable name where all the
1180 required headers will be appended so that they can be installed
1181 together with the generated ones. This is mostly intended as a conve‐
1182 nience so that adding a new header to a project only requires specify‐
1183 ing the CamelCase variant in the CMakeLists.txt file; the original
1184 variant will then be added to this variable.
1185 COMMON_HEADER generates an additional convenience header which includes
1187 all other header files.
1188 The RELATIVE argument indicates where the original headers can be found
1190 relative to CMAKE_CURRENT_SOURCE_DIR. It does not affect the generated
1191 CamelCase forwarding files, but ecm_generate_headers() uses it when
1192 checking that the original header exists, and to generate originally
1193 named forwarding headers when PREFIX is set.
1194 To allow other parts of the source distribution (eg: tests) to use the
1196 generated headers before installation, it may be desirable to set the
1197 INCLUDE_DIRECTORIES property for the library target to output_dir. For
1198 example, if OUTPUT_DIR is CMAKE_CURRENT_BINARY_DIR (the default), you
1199 could do
1200 target_include_directories(MyLib PUBLIC "$<BUILD_INTERFACE:${CMAKE_CURRENT_BINARY_DIR}>")
1202 Example usage (without PREFIX):
1204 ecm_generate_headers(
1206 MyLib_FORWARDING_HEADERS
1207 HEADERS
1208 MLFoo
1209 MLBar
1210 # etc
1211 REQUIRED_HEADERS MyLib_HEADERS
1212 COMMON_HEADER MLGeneral
1213 )
1214 install(FILES ${MyLib_FORWARDING_HEADERS} ${MyLib_HEADERS}
1215 DESTINATION ${CMAKE_INSTALL_PREFIX}/include
1216 COMPONENT Devel)
1217 Example usage (with PREFIX):
1219 ecm_generate_headers(
1221 MyLib_FORWARDING_HEADERS
1222 HEADERS
1223 Foo
1224 # several classes are contained in bar.h, so generate
1225 # additional files
1226 Bar,BarList
1227 # etc
1228 PREFIX MyLib
1229 REQUIRED_HEADERS MyLib_HEADERS
1230 )
1231 install(FILES ${MyLib_FORWARDING_HEADERS}
1232 DESTINATION ${CMAKE_INSTALL_PREFIX}/include/MyLib
1233 COMPONENT Devel)
1234 install(FILES ${MyLib_HEADERS}
1235 DESTINATION ${CMAKE_INSTALL_PREFIX}/include/mylib
1236 COMPONENT Devel)
1237 Since pre-1.0.0.
1239 ECMGeneratePkgConfigFile
1241 Generate a pkg-config file for the benefit of autotools-based projects.
1242 ecm_generate_pkgconfig_file(BASE_NAME <baseName>
1244 [LIB_NAME <libName>]
1245 [DEPS "<dep> [<dep> [...]]"]
1246 [FILENAME_VAR <filename_variable>]
1247 [INCLUDE_INSTALL_DIR <dir>]
1248 [LIB_INSTALL_DIR <dir>]
1249 [DEFINES -D<variable=value>...]
1250 [DESCRIPTION <library description>] # since 5.41.0
1251 [INSTALL])
1252 BASE_NAME is the name of the module. It’s the name projects will use to
1254 find the module.
1255 LIB_NAME is the name of the library that is being exported. If unde‐
1257 fined, it will default to the BASE_NAME. That means the LIB_NAME will
1258 be set as the name field as well as the library to link to.
1259 FILENAME_VAR is specified with a variable name. This variable will
1261 receive the location of the generated file will be set, within the
1262 build directory. This way it can be used in case some processing is
1263 required. See also INSTALL.
1264 INCLUDE_INSTALL_DIR specifies where the includes will be installed. If
1266 it’s not specified, it will default to INSTALL_INCLUDEDIR,
1267 CMAKE_INSTALL_INCLUDEDIR or just “include/” in case they are specified,
1268 with the BASE_NAME postfixed.
1269 LIB_INSTALL_DIR specifies where the library is being installed. If it’s
1271 not specified, it will default to LIB_INSTALL_DIR, CMAKE_INSTALL_LIBDIR
1272 or just “lib/” in case they are specified.
1273 DEFINES is a list of preprocessor defines that it is recommended users
1275 of the library pass to the compiler when using it.
1276 DESCRIPTION describes what this library is. If it’s not specified,
1278 CMake will first try to get the description from the metainfo.yaml file
1279 or will create one based on LIB_NAME. Since 5.41.0.
1280 INSTALL will cause the module to be installed to the pkgconfig subdi‐
1282 rectory of LIB_INSTALL_DIR, unless the ECM_PKGCONFIG_INSTALL_DIR cache
1283 variable is set to something different. Note that the first call to
1284 ecm_generate_pkgconfig_file with the INSTALL argument will cause
1285 ECM_PKGCONFIG_INSTALL_DIR to be set to the cache, and will be used in
1286 any subsequent calls.
1287 To properly use this macro a version needs to be set. To retrieve it,
1289 ECM_PKGCONFIG_INSTALL_DIR uses PROJECT_VERSION. To set it, use the
1290 project() command (only available since CMake 3.0) or the ecm_set‐
1291 up_version() macro.
1292 Example usage:
1294 ecm_generate_pkgconfig_file(
1296 BASE_NAME KF5Archive
1297 DEPS Qt5Core
1298 FILENAME_VAR pkgconfig_filename
1299 INSTALL
1300 )
1301 Since 1.3.0.
1303 ECMGeneratePriFile
1305 Generate a .pri file for the benefit of qmake-based projects.
1306 As well as the function below, this module creates the cache variable
1308 ECM_MKSPECS_INSTALL_DIR and sets the default value to mkspecs/modules.
1309 This assumes Qt and the current project are both installed to the same
1310 non-system prefix. Packagers who use -DCMAKE_INSTALL_PREFIX=/usr will
1311 certainly want to set ECM_MKSPECS_INSTALL_DIR to something like
1312 share/qt5/mkspecs/modules.
1313 The main thing is that this should be the modules subdirectory of
1315 either the default qmake mkspecs directory or of a directory that will
1316 be in the $QMAKEPATH environment variable when qmake is run.
1317 ecm_generate_pri_file(BASE_NAME <baseName>
1319 LIB_NAME <libName>
1320 [DEPS "<dep> [<dep> [...]]"]
1321 [FILENAME_VAR <filename_variable>]
1322 [INCLUDE_INSTALL_DIR <dir>]
1323 [LIB_INSTALL_DIR <dir>])
1324 If your CMake project produces a Qt-based library, you may expect there
1326 to be applications that wish to use it that use a qmake-based build
1327 system, rather than a CMake-based one. Creating a .pri file will make
1328 use of your library convenient for them, in much the same way that
1329 CMake config files make things convenient for CMake-based applications.
1330 ecm_generate_pri_file() generates just such a file. It requires the
1332 PROJECT_VERSION_STRING variable to be set. This is typically set by
1333 ECMSetupVersion, although the project() command in CMake 3.0.0 and
1334 later can also set this.
1335 BASE_NAME specifies the name qmake project (.pro) files should use to
1337 refer to the library (eg: KArchive). LIB_NAME is the name of the
1338 actual library to link to (ie: the first argument to add_library()).
1339 DEPS is a space-separated list of the base names of other libraries
1340 (for Qt libraries, use the same names you use with the QT variable in a
1341 qmake project file, such as “core” for QtCore). FILENAME_VAR specifies
1342 the name of a variable to store the path to the generated file in.
1343 INCLUDE_INSTALL_DIR is the path (relative to CMAKE_INSTALL_PREFIX) that
1345 include files will be installed to. It defaults to
1346 ${INCLUDE_INSTALL_DIR}/<baseName> if the INCLUDE_INSTALL_DIR variable
1347 is set. If that variable is not set, the CMAKE_INSTALL_INCLUDEDIR vari‐
1348 able is used instead, and if neither are set include is used.
1349 LIB_INSTALL_DIR operates similarly for the installation location for
1350 libraries; it defaults to ${LIB_INSTALL_DIR}, ${CMAKE_INSTALL_LIBDIR}
1351 or lib, in that order.
1352 Example usage:
1354 ecm_generate_pri_file(
1356 BASE_NAME KArchive
1357 LIB_NAME KF5KArchive
1358 DEPS "core"
1359 FILENAME_VAR pri_filename
1360 )
1361 install(FILES ${pri_filename} DESTINATION ${ECM_MKSPECS_INSTALL_DIR})
1362 A qmake-based project that wished to use this would then do:
1364 QT += KArchive
1366 in their .pro file.
1368 Since pre-1.0.0.
1370 ECMGenerateQmlTypes
1372 Generates plugins.qmltypes files for QML plugins.
1373 ecm_generate_qmltypes(<org.kde.pluginname> 1.3
1375 DESTINATION <${KDE_INSTALL_QMLDIR}/org/kde/pluginname>)
1376 Makes it possible to generate plugins.qmltypes files for the QML plug‐
1378 ins that our project offers. These files offer introspection upon our
1379 plugin and are useful for integrating with IDE language support of our
1380 plugin. It offers information about the objects its methods and their
1381 argument types.
1382 The developer will be in charge of making sure that these files are up
1384 to date. The plugin.qmltypes file will sit in the source directory.
1385 This function will include the code that installs the file in the right
1386 place and a small unit test named qmltypes-pluginname-version that
1387 makes sure that it doesn’t need updating.
1388 Since 5.33.0
1390 ECMInstallIcons
1392 Installs icons, sorting them into the correct directories according to
1393 the FreeDesktop.org icon naming specification.
1394 ecm_install_icons(ICONS <icon> [<icon> [...]]
1396 DESTINATION <icon_install_dir>
1397 [LANG <l10n_code>]
1398 [THEME <theme>])
1399 The given icons, whose names must match the pattern:
1401 <size>-<group>-<name>.<ext>
1403 will be installed to the appropriate subdirectory of DESTINATION
1405 according to the FreeDesktop.org icon naming scheme. By default, they
1406 are installed to the “hicolor” theme, but this can be changed using the
1407 THEME argument. If the icons are localized, the LANG argument can be
1408 used to install them in a locale-specific directory.
1409 <size> is a numeric pixel size (typically 16, 22, 32, 48, 64, 128 or
1411 256) or sc for scalable (SVG) files, <group> is one of the standard
1412 FreeDesktop.org icon groups (actions, animations, apps, categories,
1413 devices, emblems, emotes, intl, mimetypes, places, status) and <ext> is
1414 one of .png, .mng or .svgz.
1415 The typical installation directory is share/icons.
1417 ecm_install_icons(ICONS 22-actions-menu_new.png
1419 DESTINATION share/icons)
1420 The above code will install the file 22-actions-menu_new.png as
1422 ${CMAKE_INSTALL_PREFIX}/share/icons/<theme>/22x22/actions/menu_new.png
1423 Users of the KDEInstallDirs module would normally use
1425 ${KDE_INSTALL_ICONDIR} as the DESTINATION, while users of the GNUIn‐
1426 stallDirs module should use ${CMAKE_INSTALL_DATAROOTDIR}/icons.
1427 An old form of arguments will also be accepted:
1429 ecm_install_icons(<icon_install_dir> [<l10n_code>])
1431 This matches files named like:
1433 <theme><size>-<group>-<name>.<ext>
1435 where <theme> is one of * hi for hicolor * lo for locolor * cr for the
1437 Crystal icon theme * ox for the Oxygen icon theme * br for the Breeze
1438 icon theme
1439 With this syntax, the file hi22-actions-menu_new.png would be installed
1441 into <icon_install_dir>/hicolor/22x22/actions/menu_new.png
1442 Since pre-1.0.0.
1444 ECMMarkAsTest
1446 Marks a target as only being required for tests.
1447 ecm_mark_as_test(<target1> [<target2> [...]])
1449 This will cause the specified targets to not be built unless either
1451 BUILD_TESTING is set to ON or the user invokes the buildtests target.
1452 BUILD_TESTING is created as a cache variable by the CTest module and by
1454 the KDECMakeSettings module.
1455 Since pre-1.0.0.
1457 ECMMarkNonGuiExecutable
1459 Marks an executable target as not being a GUI application.
1460 ecm_mark_nongui_executable(<target1> [<target2> [...]])
1462 This will indicate to CMake that the specified targets should not be
1464 included in a MACOSX_BUNDLE and should not be WIN32_EXECUTABLEs. On
1465 platforms other than MacOS X or Windows, this will have no effect.
1466 Since pre-1.0.0.
1468 ECMOptionalAddSubdirectory
1470 Make subdirectories optional.
1471 ecm_optional_add_subdirectory(<dir>)
1473 This behaves like add_subdirectory(), except that it does not complain
1475 if the directory does not exist. Additionally, if the directory does
1476 exist, it creates an option to allow the user to skip it. The option
1477 will be named BUILD_<dir>.
1478 This is useful for “meta-projects” that combine several mostly-indepen‐
1480 dent sub-projects.
1481 If the CMake variable DISABLE_ALL_OPTIONAL_SUBDIRECTORIES is set to
1483 TRUE for the first CMake run on the project, all optional subdirecto‐
1484 ries will be disabled by default (but can of course be enabled via the
1485 respective options). For example, the following will disable all
1486 optional subdirectories except the one named “foo”:
1487 cmake -DDISABLE_ALL_OPTIONAL_SUBDIRECTORIES=TRUE -DBUILD_foo=TRUE myproject
1489 Since pre-1.0.0.
1491 ECMPackageConfigHelpers
1493 Helper macros for generating CMake package config files.
1494 write_basic_package_version_file() is the same as the one provided by
1496 the CMakePackageConfigHelpers module in CMake; see that module’s docu‐
1497 mentation for more information.
1498 ecm_configure_package_config_file(<input> <output>
1500 INSTALL_DESTINATION <path>
1501 [PATH_VARS <var1> [<var2> [...]]
1502 [NO_SET_AND_CHECK_MACRO]
1503 [NO_CHECK_REQUIRED_COMPONENTS_MACRO])
1504 This behaves in the same way as configure_package_config_file() from
1506 CMake 2.8.12, except that it adds an extra helper macro: find_depen‐
1507 dency(). It is highly recommended that you read the documentation for
1508 CMakePackageConfigHelpers for more information, particularly with
1509 regard to the PATH_VARS argument.
1510 Note that there is no argument that will disable the find_dependency()
1512 macro; if you do not require this macro, you should use configure_pack‐
1513 age_config_file from the CMakePackageConfigHelpers module.
1514 CMake 3.0 includes a CMakeFindDependencyMacro module that provides the
1516 find_dependency() macro (which you can include() in your package config
1517 file), so this file is only useful for projects wishing to provide con‐
1518 fig files that will work with CMake 2.8.12.
1519 Additional Config File Macros
1521 find_dependency(<dep> [<version> [EXACT]])
1522 find_dependency() should be used instead of find_package() to find
1524 package dependencies. It forwards the correct parameters for EXACT,
1525 QUIET and REQUIRED which were passed to the original find_package()
1526 call. It also sets an informative diagnostic message if the dependency
1527 could not be found.
1528 Since pre-1.0.0.
1530 ECMPoQmTools
1532 This module provides the ecm_process_po_files_as_qm and
1533 ecm_install_po_files_as_qm functions for generating QTranslator (.qm)
1534 catalogs from Gettext (.po) catalogs, and the ecm_create_qm_loader
1535 function for generating the necessary code to load them in a Qt appli‐
1536 cation or library.
1537 ecm_process_po_files_as_qm(<lang> [ALL]
1539 [INSTALL_DESTINATION <install_destination>]
1540 PO_FILES <pofile> [<pofile> [...]])
1541 Compile .po files into .qm files for the given language.
1543 If INSTALL_DESTINATION is given, the .qm files are installed in
1545 <install_destination>/<lang>/LC_MESSAGES. Typically, <install_destina‐
1546 tion> is set to share/locale.
1547 ecm_process_po_files_as_qm creates a “translations” target. This target
1549 builds all .po files into .qm files. If ALL is specified, these rules
1550 are added to the “all” target (and so the .qm files will be built by
1551 default).
1552 ecm_create_qm_loader(<source_files_var> <catalog_name>)
1554 Generates C++ code which ensures translations are automatically loaded
1556 at startup. The generated files are appended to <source_files_var>.
1557 It assumes that the .qm file for the language code <lang> is installed
1559 as <sharedir>/locale/<lang>/LC_MESSAGES/<catalog_name>.qm, where
1560 <sharedir> is one of the directories given by the GenericDataLocation
1561 of QStandardPaths.
1562 Typical usage is like:
1564 set(mylib_SRCS foo.cpp bar.cpp)
1566 ecm_create_qm_loader(mylib_SRCS mylib)
1567 add_library(mylib ${mylib_SRCS})
1568 ecm_install_po_files_as_qm(<podir>)
1570 Searches for .po files and installs them to the standard location.
1572 This is a convenience function which relies on all .po files being kept
1574 in <podir>/<lang>/, where <lang> is the language the .po files are
1575 written in.
1576 For example, given the following directory structure:
1578 po/
1580 fr/
1581 mylib.po
1582 ecm_install_po_files_as_qm(po) compiles mylib.po into mylib.qm and
1584 installs it in <install_destination>/fr/LC_MESSAGES. <install_destina‐
1585 tion> defaults to ${LOCALE_INSTALL_DIR} if defined, otherwise it uses
1586 ${CMAKE_INSTALL_LOCALEDIR} if that is defined, otherwise it uses
1587 share/locale.
1588 Since pre-1.0.0.
1590 ECMQMLModules
1592 Find QML import modules through a find_qmlmodule() call. It uses the
1593 qmlplugindump application to find the plugins and sets them up as run‐
1594 time dependencies.
1595 This is useful so that when we configure a project we are noified when
1597 some QML imports are not present in the system, thus having the appli‐
1598 cation compilable but fail at runtime.
1599 ecm_find_qmlmodule(<module_name> <version>...)
1601 Any further arguments passed will be forwarded into a find_package()
1603 call. See find_package() documentation for more information.
1604 Usage example:
1606 ecm_find_qmlmodule(org.kde.kirigami 2.1)
1608 Since 5.38.0.
1610 ECMQtDeclareLoggingCategory
1612 This module provides the ecm_qt_declare_logging_category function for
1613 generating declarations for logging categories in Qt5, and the
1614 ecm_qt_install_logging_categories function for generating and
1615 installing a file in KDebugSettings format with the info about all
1616 those categories, as well as a file with info about any renamed cate‐
1617 gories if defined. To include in that file any logging categories that
1618 are manually defined also a function ecm_qt_export_logging_category is
1619 provided.
1620 ecm_qt_declare_logging_category(<sources_var>
1622 HEADER <filename>
1623 IDENTIFIER <identifier>
1624 CATEGORY_NAME <category_name>
1625 [OLD_CATEGORY_NAMES <oldest_cat_name> [<second_oldest_cat_name> [...]]]
1626 [DEFAULT_SEVERITY <Debug|Info|Warning|Critical|Fatal>]
1627 [EXPORT <exportid>]
1628 [DESCRIPTION <description>]
1629 )
1630 A header file, <filename>, will be generated along with a corresponding
1632 source file, which will be added to <sources_var>. These will provide a
1633 QLoggingCategory category that can be referred to from C++ code using
1634 <identifier>, and from the logging configuration using <category_name>.
1635 If <filename> is not absolute, it will be taken relative to the current
1637 binary directory.
1638 If the code is compiled against Qt 5.4 or later, by default it will
1640 only log output that is at least the severity specified by
1641 DEFAULT_SEVERITY, or “Info” level if DEFAULT_SEVERITY is not given.
1642 Note that, due to a bug in Qt 5.5, “Info” may be treated as more severe
1643 than “Fatal”.
1644 <identifier> may include namespaces (eg: foo::bar::IDENT).
1646 If EXPORT is passed, the category will be registered for the group id
1648 <exportid>. Info about the categories of that group can then be gener‐
1649 ated in a file and installed by that group id with the
1650 ecm_qt_install_logging_categories function. In that case also DESCRIP‐
1651 TION will need to be passed, with <description> being a short single
1652 line text. And OLD_CATEGORY_NAMES can be used to inform about any
1653 renamings of the category, so user settings can be migrated. Since
1654 5.68.0.
1655 Since 5.14.0.
1657 ecm_qt_export_logging_category(
1659 IDENTIFIER <identifier>
1660 CATEGORY_NAME <category_name>
1661 [OLD_CATEGORY_NAMES <oldest_category_name> [<second_oldest_category_name> [...]]]
1662 EXPORT <exportid>
1663 DESCRIPTION <description>
1664 [DEFAULT_SEVERITY <Debug|Info|Warning|Critical|Fatal>]
1665 )
1666 Registers a logging category for being included in the generated and
1668 installed KDebugSettings files. To be used for categories who are
1669 declared by manual code or other ways instead of code generated with
1670 ecm_qt_declare_logging_category.
1671 <identifier> may include namespaces (eg: foo::bar::IDENT).
1673 EXPORT specifies the group id with which the category will be regis‐
1675 tered. Info about the categories of that group can then be generated
1676 in a file and installed by that group id with the ecm_qt_install_log‐
1677 ging_categories function.
1678 DESCRIPTION specifies a short single line text describing the category.
1680 OLD_CATEGORY_NAMES can be used to inform about any renamings of the
1682 category, so user settings can be migrated.
1683 Since 5.68.0.
1685 ecm_qt_install_logging_categories(
1687 EXPORT <exportid>
1688 [FILE <filename>]
1689 DESTINATION <install_path>
1690 [SORT]
1691 [COMPONENT <component>]
1692 )
1693 Generates and installs a file in KDebugSettings format with the info
1695 about all the categories registered for the group <exportid>, as well
1696 as a file with info about any renamed categories, if there are.
1697 The method call needs to be after the last ecm_qt_declare_logging_cate‐
1699 gory call which uses the same <exportid>. This can be in the same
1700 directory, or any subdirectory or parent directory.
1701 EXPORT specifies the group id of categories whose informatipn should be
1703 stored in the file generated and installed.
1704 FILE specifies the name of the file generated and installed. It will
1706 default to lower-cased <exportid>.categories.
1707 DESTINATION specifies where the generated file will be installed.
1709 IF SORT is set, entries will be sorted by identifiers.
1711 COMPONENT specifies the installation component name with which the
1713 install rules for the generated file are associated.
1714 Example usage:
1716 ecm_qt_declare_logging_category(
1718 MYPROJECT_SRCS
1719 HEADER "myproject_debug.h"
1720 IDENTIFIER "MYPROJECT_DEBUG"
1721 CATEGORY_NAME "myproject"
1722 OLD_CATEGORY_NAMES "myprojectlog"
1723 DESCRIPTION "My project"
1724 EXPORT MyProject
1725 )
1726 ecm_qt_export_logging_category(
1728 IDENTIFIER "MYPROJECT_SUBMODULE_DEBUG"
1729 CATEGORY_NAME "myproject.submodule"
1730 DESCRIPTION "My project - submodule"
1731 EXPORT MyProject
1732 )
1733 ecm_qt_install_logging_categories(
1735 EXPORT MyProject
1736 FILE myproject.categories
1737 DESTINATION "${KDE_INSTALL_LOGGINGCATEGORIESDIR}"
1738 )
1739 Since 5.68.0.
1741 ECMSetupQtPluginMacroNames
1743 Instruct CMake’s automoc about C++ preprocessor macros used to define
1744 Qt-style plugins.
1745 ecm_setup_qtplugin_macro_names(
1747 [JSON_NONE <macro_name> [<macro_name> [...]]]
1748 [JSON_ARG1 <macro_name> [<macro_name> [...]]]
1749 [JSON_ARG2 <macro_name> [<macro_name> [...]]]
1750 [JSON_ARG3 <macro_name> [<macro_name> [...]]]
1751 [CONFIG_CODE_VARIABLE <variable_name>] )
1752 CMake’s automoc needs some support when parsing C++ source files to
1754 detect whether moc should be run on those files and if there are also
1755 dependencies on other files, like those with Qt plugin metadata in JSON
1756 format. Because automoc just greps overs the raw plain text of the
1757 sources without any C++ preprocessor-like processing. CMake in newer
1758 versions provides the variables CMAKE_AUTOMOC_DEPEND_FILTERS (CMake >=
1759 3.9.0) and CMAKE_AUTOMOC_MACRO_NAMES (CMake >= 3.10) to allow the
1760 developer to assist automoc.
1761 This macro cares for the explicit setup needed for those variables for
1763 common cases of C++ preprocessor macros used for Qt-style plugins.
1764 JSON_NONE lists the names of C++ preprocessor macros for Qt-style plug‐
1766 ins which do not refer to external files with the plugin metadata.
1767 JSON_ARG1 lists the names of C++ preprocessor macros for Qt-style plug‐
1769 ins where the first argument to the macro is the name of the external
1770 file with the plugin metadata.
1771 JSON_ARG2 is the same as JSON_ARG1 but with the file name being the
1773 second argument.
1774 JSON_ARG3 is the same as JSON_ARG1 but with the file name being the
1776 third argument.
1777 CONFIG_CODE_VARIABLE specifies the name of the variable which will get
1779 set as value some generated CMake code for instructing automoc for the
1780 given macro names, as useful in an installed CMake config file. The
1781 variable can then be used as usual in the template file for such a
1782 CMake config file, by @<variable_name>@.
1783 Example usage:
1785 Given some plugin-oriented Qt-based software which defines a custom C++
1787 preprocessor macro EXPORT_MYPLUGIN for declaring the central plugin
1788 object:
1789 #define EXPORT_MYPLUGIN_WITH_JSON(classname, jsonFile) \
1791 class classname : public QObject \
1792 { \
1793 Q_OBJECT \
1794 Q_PLUGIN_METADATA(IID "myplugin" FILE jsonFile) \
1795 explicit classname() {} \
1796 };
1797 In the CMake buildsystem of the library one calls
1799 ecm_setup_qtplugin_macro_names(
1801 JSON_ARG2
1802 EXPORT_MYPLUGIN_WITH_JSON
1803 )
1804 to instruct automoc about the usage of that macro in the sources of the
1806 library itself.
1807 Given the software installs a library including the header with the
1809 macro definition and a CMake config file, so 3rd-party can create addi‐
1810 tional plugins by linking against the library, one passes additionally
1811 the name of a variable which shall be set as value the CMake code
1812 needed to instruct automoc about the usage of that macro.
1813 ecm_setup_qtplugin_macro_names(
1815 JSON_ARG2
1816 EXPORT_MYPLUGIN_WITH_JSON
1817 CONFIG_CODE_VARIABLE
1818 PACKAGE_SETUP_AUTOMOC_VARIABLES
1819 )
1820 This variable then is used in the template file (e.g. MyProjectCon‐
1822 fig.cmake.in) for the libary’s installed CMake config file and that way
1823 will ensure that in the 3rd-party plugin’s buildsystem automoc is
1824 instructed as well as needed:
1825 @PACKAGE_SETUP_AUTOMOC_VARIABLES@
1827 Since 5.45.0.
1829 ECMSetupVersion
1831 Handle library version information.
1832 ecm_setup_version(<version>
1834 VARIABLE_PREFIX <prefix>
1835 [SOVERSION <soversion>]
1836 [VERSION_HEADER <filename>]
1837 [PACKAGE_VERSION_FILE <filename> [COMPATIBILITY <compat>]] )
1838 This parses a version string and sets up a standard set of version
1840 variables. It can optionally also create a C version header file and a
1841 CMake package version file to install along with the library.
1842 If the <version> argument is of the form <major>.<minor>.<patch> (or
1844 <major>.<minor>.<patch>.<tweak>), The following CMake variables are
1845 set:
1846 <prefix>_VERSION_MAJOR - <major>
1848 <prefix>_VERSION_MINOR - <minor>
1849 <prefix>_VERSION_PATCH - <patch>
1850 <prefix>_VERSION - <version>
1851 <prefix>_VERSION_STRING - <version> (for compatibility: use <prefix>_VERSION instead)
1852 <prefix>_SOVERSION - <soversion>, or <major> if SOVERSION was not given
1853 If CMake policy CMP0048 is not NEW, the following CMake variables will
1855 also be set:
1856 PROJECT_VERSION_MAJOR - <major>
1858 PROJECT_VERSION_MINOR - <minor>
1859 PROJECT_VERSION_PATCH - <patch>
1860 PROJECT_VERSION - <version>
1861 PROJECT_VERSION_STRING - <version> (for compatibility: use PROJECT_VERSION instead)
1862 If the VERSION_HEADER option is used, a simple C header is generated
1864 with the given filename. If filename is a relative path, it is inter‐
1865 preted as relative to CMAKE_CURRENT_BINARY_DIR. The generated header
1866 contains the following macros:
1867 <prefix>_VERSION_MAJOR - <major> as an integer
1869 <prefix>_VERSION_MINOR - <minor> as an integer
1870 <prefix>_VERSION_PATCH - <patch> as an integer
1871 <prefix>_VERSION_STRING - <version> as a C string
1872 <prefix>_VERSION - the version as an integer
1873 <prefix>_VERSION has <patch> in the bottom 8 bits, <minor> in the next
1875 8 bits and <major> in the remaining bits. Note that <patch> and
1876 <minor> must be less than 256.
1877 If the PACKAGE_VERSION_FILE option is used, a simple CMake package ver‐
1879 sion file is created using the write_basic_package_version_file() macro
1880 provided by CMake. It should be installed in the same location as the
1881 Config.cmake file of the library so that it can be found by find_pack‐
1882 age(). If the filename is a relative path, it is interpreted as rela‐
1883 tive to CMAKE_CURRENT_BINARY_DIR. The optional COMPATIBILITY option is
1884 forwarded to write_basic_package_version_file(), and defaults to
1885 AnyNewerVersion.
1886 If CMake policy CMP0048 is NEW, an alternative form of the command is
1888 available:
1889 ecm_setup_version(PROJECT
1891 [VARIABLE_PREFIX <prefix>]
1892 [SOVERSION <soversion>]
1893 [VERSION_HEADER <filename>]
1894 [PACKAGE_VERSION_FILE <filename>] )
1895 This will use the version information set by the project() command.
1897 VARIABLE_PREFIX defaults to the project name. Note that PROJECT must
1898 be the first argument. In all other respects, it behaves like the
1899 other form of the command.
1900 Since pre-1.0.0.
1902 COMPATIBILITY option available since 1.6.0.
1904 ECMSourceVersionControl
1906 Tries to determine whether the source is under version control (git
1907 clone, svn checkout, etc).
1908 ECM_SOURCE_UNDER_VERSION_CONTROL is set when indication is found that
1910 CMAKE_SOURCE_DIR is under version control.
1911 Since 5.63
1913 ECMUninstallTarget
1915 Add an uninstall target.
1916 By including this module, an uninstall target will be added to your
1918 CMake project. This will remove all files installed (or updated) by a
1919 previous invocation of the install target. It will not remove files
1920 created or modified by an install(SCRIPT) or install(CODE) command; you
1921 should create a custom uninstallation target for these and use
1922 add_dependency to make the uninstall target depend on it:
1923 include(ECMUninstallTarget)
1925 install(SCRIPT install-foo.cmake)
1926 add_custom_target(uninstall_foo COMMAND ${CMAKE_COMMAND} -P uninstall-foo.cmake)
1927 add_dependency(uninstall uninstall_foo)
1928 The target will fail if the install target has not yet been run (so it
1930 is not possible to run CMake on the project and then immediately run
1931 the uninstall target).
1932 WARNING:
1934 CMake deliberately does not provide an uninstall target by default
1935 on the basis that such a target has the potential to remove impor‐
1936 tant files from a user’s computer. Use with caution.
1937 Since 1.7.0.
1939 ECMUseFindModules
1941 Selectively use some of the find modules provided by extra-cmake-mod‐
1942 ules.
1943 This module is automatically available once extra-cmake-modules has
1945 been found, so it is not necessary to include(ECMUseFindModules)
1946 explicitly.
1947 ecm_use_find_modules(DIR <dir>
1949 MODULES module1.cmake [module2.cmake [...]]
1950 [NO_OVERRIDE])
1951 This allows selective use of the find modules provided by ECM, includ‐
1953 ing deferring to CMake’s versions of those modules if it has them.
1954 Rather than adding ${ECM_FIND_MODULE_DIR} to CMAKE_MODULE_PATH, you use
1955 ecm_use_find_modules() to copy the modules you want to a local (build)
1956 directory, and add that to CMAKE_MODULE_PATH.
1957 The find modules given to MODULES will be copied to the directory given
1959 by DIR (which should be located in ${CMAKE_BINARY_DIR} and added to
1960 CMAKE_MODULE_PATH). If NO_OVERRIDE is given, only modules not also
1961 provided by CMake will be copied.
1962 Example:
1964 find_package(ECM REQUIRED)
1966 ecm_use_find_modules(
1967 DIR ${CMAKE_BINARY_DIR}/cmake
1968 MODULES FindEGL.cmake
1969 NO_OVERRIDE
1970 )
1971 set(CMAKE_MODULE_PATH ${CMAKE_BINARY_DIR}/cmake)
1972 This example will make FindEGL.cmake available in your project, but
1974 only as long as it is not yet part of CMake. Calls to find_package(EGL)
1975 will then make use of this copied module (or the CMake module if it
1976 exists).
1977 Another possible use for this macro is to take copies of find modules
1979 that can be installed along with config files if they are required as a
1980 dependency (for example, if targets provided by the find module are in
1981 the link interface of a library).
1982 Since pre-1.0.0.
1984 ECMWinResolveSymlinks
1986 Resolve pseudo-symlinks created by git when cloning on Windows.
1987 ecm_win_resolve_symlinks(<dir>)
1989 When git checks out a repository with UNIX symlinks on Windows machine,
1991 it creates a text file for each symlink, containing a relative path to
1992 the real file. This function would recursively walk over specified
1993 directory and replace pseudo-symlinks with corresponding real file’s
1994 contents. It would then run git update-index –assume-unchanged on them
1995 to trick git.
1996 This is useful for projects like “breeze-icons” that contain many iden‐
1998 tical icons implemented as symlinks.
1999 Since 5.28
2001
2003 ecm(7), ecm-find-modules(7), ecm-kde-modules(7)
2004
2006 KDE Developers
20075.68 Mar 19, 2020 ECM-MODULES(7)