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_name(|target (since 5.83))>
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 as platform-specific application icons to the variable
47 named <sources_var_name> or, if the first argument is a target (since
48 5.83), to the SOURCES property of <target>. Any target must be created
49 with add_executable() and not be an alias.
50 Other icon files are ignored but on Mac SVG files can be supported and
52 it is thus possible to mix those with png files in a single macro call.
53 The platforms currently supported are Windows and Mac OS X, on all oth‐
55 ers the call has no effect and is ignored.
56 <size> is a numeric pixel size (typically 16, 32, 48, 64, 128 or 256).
58 <other_text> can be any other text. See the platform notes below for
59 any recommendations about icon sizes.
60 SIDEBAR_ICONS can be used to add Mac OS X sidebar icons to the gener‐
62 ated iconset. They are used when a folder monitored by the application
63 is dragged into Finder’s sidebar. Since 5.49.
64 OUTFILE_BASENAME will be used as the basename for the icon file. If you
66 specify it, the icon file will be called <OUTFILE_BASENAME>.icns on Mac
67 OS X and <OUTFILE_BASENAME>.ico on Windows. If you don’t specify it, it
68 defaults to <sources_var_name>.<ext>. Since 5.49.
69 Windows notes
71 • Icons are compiled into the executable using a resource file.
73 • Icons may not show up in Windows Explorer if the executable
75 target does not have the WIN32_EXECUTABLE property set.
76 • Icotool (see FindIcoTool) is required.
78 • Supported sizes: 16, 24, 32, 48, 64, 128, 256, 512 and 1024.
80 Mac OS X notes
82 • The executable target must have the MACOSX_BUNDLE property
84 set.
85 • Icons are added to the bundle.
87 • If the ksvg2icns tool from KIconThemes is available, .svg and
89 .svgz files are accepted; the first that is converted success‐
90 fully to .icns will provide the application icon. SVG files
91 are ignored otherwise.
92 • The tool iconutil (provided by Apple) is required for bitmap
94 icons.
95 • Supported sizes: 16, 32, 64, 128, 256 (and 512, 1024 after OS
97 X 10.9).
98 • At least a 128x128px (or an SVG) icon is required.
100 • Larger sizes are automatically used to substitute for smaller
102 sizes on “Retina” (high-resolution) displays. For example, a
103 32px icon, if provided, will be used as a 32px icon on stan‐
104 dard-resolution displays, and as a 16px-equivalent icon (with
105 an “@2x” tag) on high-resolution displays. That is why you
106 should provide 64px and 1024px icons although they are not
107 supported anymore directly. Instead they will be used as
108 32px@2x and 512px@2x. ksvg2icns handles this internally.
109 • This function sets the MACOSX_BUNDLE_ICON_FILE variable to the
111 name of the generated icns file, so that it will be used as
112 the MACOSX_BUNDLE_ICON_FILE target property when you call
113 add_executable.
114 • Sidebar icons should typically provided in 16, 32, 64, 128 and
116 256px.
117 Since 1.7.0.
119 ECMAddQch
121 This module provides the ecm_add_qch function for generating API docu‐
122 mentation files in the QCH format, and the ecm_install_qch_export func‐
123 tion for generating and installing exported CMake targets for such gen‐
124 erated QCH files to enable builds of other software with generation of
125 QCH files to create links into the given QCH files.
126 ecm_add_qch(<target_name>
128 NAME <name>
129 VERSION <version>
130 QCH_INSTALL_DESTINATION <qchfile_install_path>
131 TAGFILE_INSTALL_DESTINATION <tagsfile_install_path>
132 [COMPONENT <component>]
133 [BASE_NAME <basename>]
134 [SOURCE_DIRS <dir> [<dir2> [...]]]
135 [SOURCES <file> [<file2> [...]]]
136 |MD_MAINPAGE <md_file>]
137 [INCLUDE_DIRS <incdir> [<incdir2> [...]]]
138 [IMAGE_DIRS <idir> [<idir2> [...]]]
139 [EXAMPLE_DIRS <edir> [<edir2> [...]]]
140 [ORG_DOMAIN <domain>]
141 [NAMESPACE <namespace>]
142 [LINK_QCHS <qch> [<qch2> [...]]]
143 [PREDEFINED_MACROS <macro[=content]> [<macro2[=content]> [...]]]
144 [BLANK_MACROS <macro> [<macro2> [...]]]
145 [CONFIG_TEMPLATE <configtemplate_file>]
146 [VERBOSE]
147 )
148 This macro adds a target called <target_name> for the creation of an
150 API documentation manual in the QCH format from the given sources. It
151 currently uses doxygen, future versions might optionally also allow
152 other tools. Next to the QCH file the target will generate a corre‐
153 sponding doxygen tag file, which enables creating links from other doc‐
154 umentation into the generated QCH file.
155 It is recommended to make the use of this macro optional, by depending
157 the call to ecm_add_qch on a CMake option being set, with a name like
158 BUILD_QCH and being TRUE by default. This will allow the developers to
159 saves resources on normal source development build cycles by setting
160 this option to FALSE.
161 The macro will set the target properties DOXYGEN_TAGFILE, QHP_NAME‐
163 SPACE, QHP_NAMESPACE_VERSIONED, QHP_VIRTUALFOLDER and LINK_QCHS to the
164 respective values, to allow other code access to them, e.g. the macro
165 ecm_install_qch_export. To enable the use of the target <target_name>
166 as item for LINK_QCHS in further ecm_add_qch calls in the current
167 build, additionally a target property DOXYGEN_TAGFILE_BUILD is set,
168 with the path of the created doxygen tag file in the build dir. If ex‐
169 isting, ecm_add_qch will use this property instead of DOXYGEN_TAGFILE
170 for access to the tags file.
171 NAME specifies the name for the generated documentation.
173 VERSION specifies the version of the library for which the documenta‐
175 tion is created.
176 BASE_NAME specifies the base name for the generated files. The default
178 basename is <name>.
179 SOURCE_DIRS specifies the dirs (incl. subdirs) with the source files
181 for which the API documentation should be generated. Dirs can be rela‐
182 tive to the current source dir. Dependencies to the files in the dirs
183 are not tracked currently, other than with the SOURCES argument. So do
184 not use for sources generated during the build. Needs to be used when
185 SOURCES or CONFIG_TEMPLATE are not used.
186 SOURCES specifies the source files for which the API documentation
188 should be generated. Needs to be used when SOURCE_DIRS or CONFIG_TEM‐
189 PLATE are not used.
190 MD_MAINPAGE specifies a file in Markdown format that should be used as
192 main page. This page will overrule any \mainpage command in the in‐
193 cluded sources.
194 INCLUDE_DIRS specifies the dirs which should be searched for included
196 headers. Dirs can be relative to the current source dir. Since 5.63.
197 IMAGE_DIRS specifies the dirs which contain images that are included in
199 the documentation. Dirs can be relative to the current source dir.
200 EXAMPLE_DIRS specifies the dirs which contain examples that are in‐
202 cluded in the documentation. Dirs can be relative to the current source
203 dir.
204 QCH_INSTALL_DESTINATION specifies where the generated QCH file will be
206 installed.
207 TAGFILE_INSTALL_DESTINATION specifies where the generated tag file will
209 be installed.
210 COMPONENT specifies the installation component name with which the in‐
212 stall rules for the generated QCH file and tag file are associated.
213 NAMESPACE can be used to set a custom namespace <namespace> of the gen‐
215 erated QCH file. The namepspace is used as the unique id by QHelpEngine
216 (cmp. https://doc.qt.io/qt-5/qthelpproject.html#namespace). The de‐
217 fault namespace is <domain>.<name>. Needs to be used when ORG_DOMAIN
218 is not used.
219 ORG_DOMAIN can be used to define the organization domain prefix for the
221 default namespace of the generated QCH file. Needs to be used when
222 NAMESPACE is not used.
223 LINK_QCHS specifies a list of other QCH targets which should be used
225 for creating references to API documentation of code in external li‐
226 braries. For each target <qch> in the list these target properties are
227 expected to be defined: DOXYGEN_TAGFILE, QHP_NAMESPACE and QHP_VIRTUAL‐
228 FOLDER. If any of these is not existing, <qch> will be ignored. Use
229 the macro ecm_install_qch_export for exporting a target with these
230 properties with the CMake config of a library. Any target <qch> can
231 also be one created before in the same buildsystem by another call of
232 ecm_add_qch.
233 PREDEFINED_MACROS specifies a list of C/C++ macros which should be han‐
235 dled as given by the API dox generation tool. Examples are macros only
236 defined in generated files, so whose definition might be not available
237 to the tool.
238 BLANK_MACROS specifies a list of C/C++ macro names which should be ig‐
240 nored by the API dox generation tool and handled as if they resolve to
241 empty strings. Examples are export macros only defined in generated
242 files, so whose definition might be not available to the tool.
243 CONFIG_TEMPLATE specifies a custom cmake template file for the config
245 file that is created to control the execution of the API dox generation
246 tool. The following CMake variables need to be used: - ECM_QCH_DOXY‐
247 GEN_QHELPGENERATOR_EXECUTABLE - ECM_QCH_DOXYGEN_FILEPATH, ECM_QCH_DOXY‐
248 GEN_TAGFILE The following CMake variables can be used: - ECM_QCH_DOXY‐
249 GEN_PROJECTNAME - ECM_QCH_DOXYGEN_PROJECTVERSION - ECM_QCH_DOXYGEN_VIR‐
250 TUALFOLDER - ECM_QCH_DOXYGEN_FULLNAMESPACE - ECM_QCH_DOXYGEN_TAGFILES -
251 ECM_QCH_DOXYGEN_WARN_LOGFILE - ECM_QCH_DOXYGEN_QUIET There is no guar‐
252 antue that the other CMake variables currently used in the default con‐
253 fig file template will also be present with the same semantics in fu‐
254 ture versions of this macro.
255 VERBOSE tells the API dox generation tool to be more verbose about its
257 activity.
258 The default config file for the API dox generation tool, so the one
260 when not using CONFIG_TEMPLATE, allows code to handle the case of being
261 processed by the tool by defining the C/C++ preprocessor macro K_DOXY‐
262 GEN when run (since v5.67.0). For backward-compatibility also the defi‐
263 nition DOXYGEN_SHOULD_SKIP_THIS is set, but its usage is deprecated.
264 Example usage:
266 ecm_add_qch(
268 MyLib_QCH
269 NAME MyLib
270 VERSION "0.42.0"
271 ORG_DOMAIN org.myorg
272 SOURCE_DIRS
273 src
274 LINK_QCHS
275 Qt5Core_QCH
276 Qt5Xml_QCH
277 Qt5Gui_QCH
278 Qt5Widgets_QCH
279 BLANK_MACROS
280 MyLib_EXPORT
281 MyLib_DEPRECATED
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 Example usage (with two QCH files, second linking first):
288 ecm_add_qch(
290 MyLib_QCH
291 NAME MyLib
292 VERSION ${MyLib_VERSION}
293 ORG_DOMAIN org.myorg
294 SOURCES ${MyLib_PUBLIC_HEADERS}
295 MD_MAINPAGE src/mylib/README.md
296 LINK_QCHS Qt5Core_QCH
297 TAGFILE_INSTALL_DESTINATION ${CMAKE_INSTALL_PREFIX}/share/docs/tags
298 QCH_INSTALL_DESTINATION ${CMAKE_INSTALL_PREFIX}/share/docs/qch
299 COMPONENT Devel
300 )
301 ecm_add_qch(
302 MyOtherLib_QCH
303 NAME MyOtherLib
304 VERSION ${MyOtherLib_VERSION}
305 ORG_DOMAIN org.myorg
306 SOURCES ${MyOtherLib_PUBLIC_HEADERS}
307 MD_MAINPAGE src/myotherlib/README.md
308 LINK_QCHS Qt5Core_QCH MyLib_QCH
309 TAGFILE_INSTALL_DESTINATION ${CMAKE_INSTALL_PREFIX}/share/docs/tags
310 QCH_INSTALL_DESTINATION ${CMAKE_INSTALL_PREFIX}/share/docs/qch
311 COMPONENT Devel
312 )
313 ecm_install_qch_export(
315 TARGETS [<name> [<name2> [...]]]
316 FILE <file>
317 DESTINATION <dest>
318 [COMPONENT <component>]
319 )
320 This macro creates and installs a CMake file <file> which exports the
322 given QCH targets <name> etc., so they can be picked up by CMake-based
323 builds of other software that also generate QCH files (using
324 ecm_add_qch) and which should include links to the QCH files created by
325 the given targets. The installed CMake file <file> is expected to be
326 included by the CMake config file created for the software the related
327 QCH files are documenting.
328 TARGETS specifies the QCH targets which should be exported. If a target
330 does not exist or does not have all needed properties, a warning will
331 be generated and the target skipped. This behaviour might change in
332 future versions to result in a fail instead.
333 FILE specifies the name of the created CMake file, typically with a
335 .cmake extension.
336 DESTINATION specifies the directory on disk to which the file will be
338 installed. It usually is the same as the one where the CMake config
339 files for this software are installed.
340 COMPONENT specifies the installation component name with which the in‐
342 stall rule is associated.
343 Example usage:
345 ecm_install_qch_export(
347 TARGETS MyLib_QCH
348 FILE MyLibQCHTargets.cmake
349 DESTINATION "${CMAKE_INSTALL_PREFIX}/lib/cmake/MyLib"
350 COMPONENT Devel
351 )
352 Since 5.36.0.
354 ECMAddQtDesignerPlugin
356 This module provides the ecm_add_qtdesignerplugin function for generat‐
357 ing Qt Designer plugins for custom widgets. Each of those widgets is
358 described using a second function ecm_qtdesignerplugin_widget.
359 ecm_add_qtdesignerplugin(<target_name>
361 NAME <name>
362 WIDGETS <widgetid> [<widgetid2> [...]]
363 LINK_LIBRARIES <lib> [<lib2> [...]]
364 INSTALL_DESTINATION <install_path>
365 [OUTPUT_NAME <output_name>]
366 [DEFAULT_GROUP <group>]
367 [DEFAULT_HEADER_CASE <SAME_CASE|LOWER_CASE|UPPER_CASE>]
368 [DEFAULT_HEADER_EXTENSION <header_extension>]
369 [DEFAULT_ICON_DIR <icon_dir>]
370 [INCLUDE_FILES <include_file> [<include_file2> [...]]]
371 [SOURCES <src> [<src2> [...]]]
372 [COMPONENT <component>]
373 )
374 NAME specifies the base name to use in the generated sources. The de‐
376 fault is <target_name>.
377 WIDGETS specifies the widgets the plugin should support. Each widget
379 has to be defined before by a call of ecm_qtdesignerplugin_widget with
380 the respective <widgetid>, in a scope including the current call.
381 LINK_LIBRARIES specifies the libraries to link against. This will be at
383 least the library providing the widget class(es).
384 INSTALL_DESTINATION specifies where the generated plugin binary will be
386 installed.
387 OUTPUT_NAME specifies the name of the plugin binary. The default is
389 “<target_name>”.
390 DEFAULT_GROUP specifies the default group in Qt Designer where the wid‐
392 gets will be placed. The default is “Custom”.
393 DEFAULT_HEADER_CASE specifies how the name of the header is derived
395 from the widget class name. The default is “LOWER_CASE”.
396 DEFAULT_HEADER_EXTENSION specifies what file name extension is used for
398 the header file derived from the class name. The default is “h”.
399 DEFAULT_ICON_DIR specifies what file name extension is used for the
401 header file derived from the class name. The default is “pics”.
402 INCLUDE_FILES specifies additional include files to include with the
404 generated source file. This can be needed for custom code used in ini‐
405 tializing or creating widgets.
406 SOURCES specifies additional source files to build the plugin from.
408 This can be needed to support custom code used in initializing or cre‐
409 ating widgets.
410 COMPONENT specifies the installation component name with which the in‐
412 stall rules for the generated plugin are associated.
413 ecm_qtdesignerplugin_widget(<widgetid>
415 [CLASS_NAME <class_name>]
416 [INCLUDE_FILE <include_file>]
417 [CONTAINER]
418 [ICON <iconfile>]
419 [TOOLTIP <tooltip>]
420 [WHATSTHIS <whatsthis>]
421 [GROUP <group>]
422 [CREATE_WIDGET_CODE_FROM_VARIABLE <create_widget_code_variable>]
423 [INITIALIZE_CODE_FROM_VARIABLE <initialize_code_variable]
424 [DOM_XML_FROM_VARIABLE <dom_xml_variable>]
425 [IMPL_CLASS_NAME <impl_class_name>]
426 [CONSTRUCTOR_ARGS_CODE <constructor_args_code>]
427 [CONSTRUCTOR_ARGS_CODE_FROM_VARIABLE <constructor_args_code_variable>]
428 )
429 CLASS_NAME specifies the name of the widget class, including name‐
431 spaces. The default is “<widgetid>”.
432 INCLUDE_FILE specifies the include file to use for the class of this
434 widget. The default is derived from <class_name> as configured by the
435 DEFAULT_HEADER_* options of ecm_add_qtdesignerplugin, also replacing
436 any namespace separators with “/”.
437 CONTAINER specifies, if set, that this widget is a container for other
439 widgets.
440 ICON specifies the icon file to use as symbol for this widget. The de‐
442 fault is “{lowercased <class_name>}.png” in the default icons dir as
443 configured by the DEFAULT_ICON_DIR option of ecm_add_qtdesignerplugin,
444 if such a file exists.
445 TOOLTIP specifies the tooltip text to use for this widget. Default is
447 “<class_name> Widget”.
448 WHATSTHIS specifies the What’s-This text to use for this widget. De‐
450 faults to the tooltip.
451 GROUP specifies the group in Qt Designer where the widget will be
453 placed. The default is set as configured by the DEFAULT_GROUP option
454 of ecm_add_qtdesignerplugin.
455 CREATE_WIDGET_CODE_FROM_VARIABLE specifies the variable to get from the
457 C++ code to use as factory code to create an instance of the widget,
458 for the override of QDesignerCustomWidgetInterface::createWidget(QWid‐
459 get* parent). The default is “return new <impl_class_name><construc‐
460 tor_args_code>;”.
461 INITIALIZE_CODE_FROM_VARIABLE specifies the variable to get from the
463 C++ code to use with the override of QDesignerCustomWidgetInter‐
464 face::initialize(QDesignerFormEditorInterface* core). The code has to
465 use the present class member m_initialized to track and update the
466 state. The default code simply sets m_initialized to true, if it was
467 not before.
468 DOM_XML_FROM_VARIABLE specifies the variable to get from the string to
470 use with the optional override of QDesignerCustomWidgetInter‐
471 face::domXml(). Default does not override.
472 IMPL_CLASS_NAME specifies the name of the widget class to use for the
474 widget instance with Qt Designer. The default is “<class_name>”.
475 CONSTRUCTOR_ARGS_CODE specifies the C++ code to use for the constructor
477 arguments with the default of CREATE_WIDGET_CODE_FROM_VARIABLE. Note
478 that the parentheses are required. The default is “(parent)”.
479 CONSTRUCTOR_ARGS_CODE_FROM_VARIABLE specifies the variable to get from
481 the C++ code instead of passing it directly via CONSTRUCTOR_ARGS_CODE.
482 This can be needed if the code is more complex and e.g. includes “;”
483 chars.
484 Example usage:
486 ecm_qtdesignerplugin_widget(FooWidget
488 TOOLTIP "Enables to browse foo."
489 GROUP "Views (Foo)"
490 )
491 set(BarWidget_CREATE_WIDGET_CODE
493 "
494 auto* widget = new BarWidget(parent);
495 widget->setBar("Example bar");
496 return widget;
497 ")
498 ecm_qtdesignerplugin_widget(BarWidget
500 TOOLTIP "Displays bars."
501 GROUP "Display (Foo)"
502 CREATE_WIDGET_CODE_FROM_VARIABLE BarWidget_CREATE_WIDGET_CODE
503 )
504 ecm_add_qtdesignerplugin(foowidgets
506 NAME FooWidgets
507 OUTPUT_NAME foo2widgets
508 WIDGETS
509 FooWidget
510 BarWidget
511 LINK_LIBRARIES
512 Foo::Widgets
513 INSTALL_DESTINATION "${KDE_INSTALL_QTPLUGINDIR}/designer"
514 COMPONENT Devel
515 )
516 Since 5.62.0.
518 ECMAddTests
520 Convenience functions for adding tests.
521 ecm_add_tests(<sources> LINK_LIBRARIES <library> [<library> [...]]
523 [NAME_PREFIX <prefix>]
524 [GUI]
525 [TARGET_NAMES_VAR <target_names_var>]
526 [TEST_NAMES_VAR <test_names_var>])
527 A convenience function for adding multiple tests, each consisting of a
529 single source file. For each file in <sources>, an executable target
530 will be created (the name of which will be the basename of the source
531 file). This will be linked against the libraries given with LINK_LI‐
532 BRARIES. Each executable will be added as a test with the same name.
533 If NAME_PREFIX is given, this prefix will be prepended to the test
535 names, but not the target names. As a result, it will not prevent
536 clashes between tests with the same name in different parts of the
537 project, but it can be used to give an indication of where to look for
538 a failing test.
539 If the flag GUI is passed the test binaries will be GUI executables,
541 otherwise the resulting binaries will be console applications (regard‐
542 less of the value of CMAKE_WIN32_EXECUTABLE or CMAKE_MACOSX_BUNDLE). Be
543 aware that this changes the executable entry point on Windows (although
544 some frameworks, such as Qt, abstract this difference away).
545 The tests will be build with -DQT_FORCE_ASSERTS to enable assertions in
547 the test executable even for release builds.
548 The TARGET_NAMES_VAR and TEST_NAMES_VAR arguments, if given, should
550 specify a variable name to receive the list of generated target and
551 test names, respectively. This makes it convenient to apply properties
552 to them as a whole, for example, using set_target_properties() or
553 set_tests_properties().
554 The generated target executables will have the effects of
556 ecm_mark_as_test() (from the ECMMarkAsTest module) applied to it.
557 ecm_add_test(<sources> LINK_LIBRARIES <library> [<library> [...]]
559 [TEST_NAME <name>]
560 [NAME_PREFIX <prefix>]
561 [GUI])
562 This is a single-test form of ecm_add_tests that allows multiple source
564 files to be used for a single test. If using multiple source files,
565 TEST_NAME must be given; this will be used for both the target and test
566 names (and, as with ecm_add_tests(), the NAME_PREFIX argument will be
567 prepended to the test name).
568 Since pre-1.0.0.
570 ECMCheckOutboundLicense
572 Assert that source file licenses are compatible with a desired outbound
573 license of a compiled binary artifact (e.g., library, plugin or appli‐
574 cation).
575 This module provides the ecm_check_outbound_license function that gen‐
577 erates unit tests for checking the compatibility of license statements.
578 The license statements in all tested files are required to be added by
579 using the SPDX marker SPDX-License-Identifier.
580 During the CMake configuration of the project, a temporary license bill
582 of materials (BOM) in SPDX format is generated by calling the REUSE
583 tool (see <https://reuse.software>). That BOM is parsed and license
584 computations based on an internal compatibility matrix are performed.
585 Preconditions for using this module:
587 • All tested input source files must contain the SPDX-Li‐
589 cense-Identifier tag.
590 • Python3 must be available.
592 • The REUSE tool must be available, which generates the
594 bill-of-materials by running reuse spdx on the tested direc‐
595 tory.
596 When this module is included, a SKIP_LICENSE_TESTS option is added (de‐
598 fault OFF). Turning this option on skips the generation of license
599 tests, which might be convenient if licenses shall not be tested in all
600 build configurations.
601 ecm_check_outbound_license(LICENSES <outbound-licenses>
603 FILES <source-files>
604 [TEST_NAME <name>]
605 [WILL_FAIL])
606 This method adds a custom unit test to ensure the specified outbound
608 license to be compatible with the specified license headers. Note that
609 a convenient way is to use the CMake GLOB command of the FILE function.
610 LICENSES
612 List of one or multiple outbound license regarding which the
613 compatibility of the source code files shall be tested..INDENT
614 7.0
615 Currently, the following values are supported (values are SPDX registry
617 identifiers):
618 • MIT
620 • BSD-2-Clause
622 • BSD-3-Clause
624 • LGPL-2.0-only
626 • LGPL-2.1-only
628 • LGPL-3.0-only
630 • GPL-2.0-only
632 • GPL-3.0-only
634 FILES: List of source files that contain valid SPDX-License-Identifier
636 markers. The paths can be relative to the CMake file that gen‐
637 erates the test case or be absolute paths.
638 TEST_NAME
640 Optional parameter that defines the name of the generated test
641 case. If no name is defined, the relative path to the test di‐
642 rectory with appended license name is used. Every test has li‐
643 censecheck_ as prefix.
644 WILL_FAIL
646 Optional parameter that inverts the test result. This parameter
647 is usually only used for tests of the module.
648Since 5.75.0
650 ECMConfiguredInstall
652 Takes a list of files, runs configure_file on each and installs the re‐
653 sultant configured files in the given location.
654 Any suffix of “.in” in the passed file names will be stripped from the
656 file name at the installed location.
657 ecm_install_configured_files(
659 INPUT <file> [<file2> [...]]
660 DESTINATION <INSTALL_DIRECTORY>
661 [COPYONLY]
662 [ESCAPE_QUOTES]
663 [@ONLY]
664 [COMPONENT <component>])
665 Example usage:
667 ecm_install_configured_files(INPUT foo.txt.in DESTINATION ${KDE_INSTALL_DATADIR} @ONLY)
669 This will install the file as foo.txt with any cmake variable replace‐
671 ments made into the data directory.
672 Since 5.73.0.
674 ECMCoverageOption
676 Allow users to easily enable GCov code coverage support.
677 Code coverage allows you to check how much of your codebase is covered
679 by your tests. This module makes it easy to build with support for
680 GCov.
681 When this module is included, a BUILD_COVERAGE option is added (default
683 OFF). Turning this option on enables GCC’s coverage instrumentation,
684 and links against libgcov.
685 Note that this will probably break the build if you are not using GCC.
687 Since 1.3.0.
689 ECMCreateQmFromPoFiles
691 WARNING:
692 This module is deprecated and will be removed by ECM 1.0. Use ECMPo‐
693 QmTools instead.
694 Generate QTranslator (.qm) catalogs from Gettext (.po) catalogs.
696 ecm_create_qm_from_po_files(PO_FILES <file1>... <fileN>
698 [CATALOG_NAME <catalog_name>]
699 [INSTALL_DESTINATION <install_destination>])
700 Creates the necessary rules to compile .po files into .qm files, and
702 install them.
703 The .qm files are installed in <install_destination>/<lang>/LC_MES‐
705 SAGES, where <install_destination> is the INSTALL_DESTINATION argument
706 and <lang> is extracted from the “Language” field inside the .po file.
707 INSTALL_DESTINATION defaults to ${LOCALE_INSTALL_DIR} if defined, oth‐
709 erwise it uses ${CMAKE_INSTALL_LOCALEDIR} if that is defined, otherwise
710 it uses share/locale.
711 CATALOG_NAME defines the name of the installed .qm files. If set, .qm
713 files will be installed as <catalog_name>.qm. If not set .qm files will
714 be named after the name of their source .po file.
715 Setting the catalog name is useful when all .po files for a target are
717 kept in a single source directory. For example, the “mylib” probject
718 might keep all its translations in a “po” directory, like this:
719 po/
721 es.po
722 fr.po
723 Without setting CATALOG_NAME, those .po will be turned into .qm and in‐
725 stalled as:
726 share/locale/fr/LC_MESSAGES/fr.qm
728 share/locale/es/LC_MESSAGES/es.qm
729 If CATALOG_NAME is set to “mylib”, they will be installed as:
731 share/locale/fr/LC_MESSAGES/mylib.qm
733 share/locale/es/LC_MESSAGES/mylib.qm
734 Which is what the loader created by ecm_create_qm_loader() expects.
736 ecm_create_qm_from_po_files() creates a “translation” target. This tar‐
738 get builds all .po files into .qm files.
739 ecm_create_qm_loader(<source_files_var> <catalog_name>)
741 ecm_create_qm_loader() generates a C++ file which ensures translations
743 are automatically loaded at startup. The path of the .cpp file is ap‐
744 pended to <source_files_var>. Typical usage is like:
745 set(mylib_SRCS foo.cpp bar.cpp)
747 ecm_create_qm_loader(mylib_SRCS mylib)
748 add_library(mylib ${mylib_SRCS})
749 This generates a C++ file which loads “mylib.qm” at startup, assuming
751 it has been installed by ecm_create_qm_from_po_files(), and compiles it
752 into mylib.
753 Since pre-1.0.0.
755 ECMEnableSanitizers
757 Enable compiler sanitizer flags.
758 The following sanitizers are supported:
760 • Address Sanitizer
762 • Memory Sanitizer
764 • Thread Sanitizer
766 • Leak Sanitizer
768 • Undefined Behaviour Sanitizer
770 All of them are implemented in Clang, depending on your version, and
772 there is an work in progress in GCC, where some of them are currently
773 implemented.
774 This module will check your current compiler version to see if it sup‐
776 ports the sanitizers that you want to enable
777 Usage
779 Simply add:
780 include(ECMEnableSanitizers)
782 to your CMakeLists.txt. Note that this module is included in KDECompil‐
784 erSettings, so projects using that module do not need to also include
785 this one.
786 The sanitizers are not enabled by default. Instead, you must set
788 ECM_ENABLE_SANITIZERS (either in your CMakeLists.txt or on the command
789 line) to a semicolon-separated list of sanitizers you wish to enable.
790 The options are:
791 • address
793 • memory
795 • thread
797 • leak
799 • undefined
801 • fuzzer
803 The sanitizers “address”, “memory” and “thread” are mutually exclusive.
805 You cannot enable two of them in the same build.
806 “leak” requires the “address” sanitizer.
808 NOTE:
810 To reduce the overhead induced by the instrumentation of the sani‐
811 tizers, it is advised to enable compiler optimizations (-O1 or
812 higher).
813 Example
815 This is an example of usage:
816 mkdir build
818 cd build
819 cmake -DECM_ENABLE_SANITIZERS='address;leak;undefined' ..
820 NOTE:
822 Most of the sanitizers will require Clang. To enable it, use:
823 -DCMAKE_CXX_COMPILER=clang++
825 Since 1.3.0.
827 ECMFindModuleHelpers
829 Helper macros for find modules: ecm_find_package_version_check(),
830 ecm_find_package_parse_components() and ecm_find_package_handle_li‐
831 brary_components().
832 ecm_find_package_version_check(<name>)
834 Prints warnings if the CMake version or the project’s required CMake
836 version is older than that required by extra-cmake-modules.
837 ecm_find_package_parse_components(<name>
839 RESULT_VAR <variable>
840 KNOWN_COMPONENTS <component1> [<component2> [...]]
841 [SKIP_DEPENDENCY_HANDLING])
842 This macro will populate <variable> with a list of components found in
844 <name>_FIND_COMPONENTS, after checking that all those components are in
845 the list of KNOWN_COMPONENTS; if there are any unknown components, it
846 will print an error or warning (depending on the value of
847 <name>_FIND_REQUIRED) and call return().
848 The order of components in <variable> is guaranteed to match the order
850 they are listed in the KNOWN_COMPONENTS argument.
851 If SKIP_DEPENDENCY_HANDLING is not set, for each component the variable
853 <name>_<component>_component_deps will be checked for dependent compo‐
854 nents. If <component> is listed in <name>_FIND_COMPONENTS, then all
855 its (transitive) dependencies will also be added to <variable>.
856 ecm_find_package_handle_library_components(<name>
858 COMPONENTS <component> [<component> [...]]
859 [SKIP_DEPENDENCY_HANDLING])
860 [SKIP_PKG_CONFIG])
861 Creates an imported library target for each component. The operation
863 of this macro depends on the presence of a number of CMake variables.
864 The <name>_<component>_lib variable should contain the name of this li‐
866 brary, and <name>_<component>_header variable should contain the name
867 of a header file associated with it (whatever relative path is normally
868 passed to ‘#include’). <name>_<component>_header_subdir variable can be
869 used to specify which subdirectory of the include path the headers will
870 be found in. ecm_find_package_components() will then search for the
871 library and include directory (creating appropriate cache variables)
872 and create an imported library target named <name>::<component>.
873 Additional variables can be used to provide additional information:
875 If SKIP_PKG_CONFIG, the <name>_<component>_pkg_config variable is set,
877 and pkg-config is found, the pkg-config module given by <name>_<compo‐
878 nent>_pkg_config will be searched for and used to help locate the li‐
879 brary and header file. It will also be used to set <name>_<compo‐
880 nent>_VERSION.
881 Note that if version information is found via pkg-config, <name>_<com‐
883 ponent>_FIND_VERSION can be set to require a particular version for
884 each component.
885 If SKIP_DEPENDENCY_HANDLING is not set, the INTERFACE_LINK_LIBRARIES
887 property of the imported target for <component> will be set to contain
888 the imported targets for the components listed in <name>_<compo‐
889 nent>_component_deps. <component>_FOUND will also be set to false if
890 any of the components in <name>_<component>_component_deps are not
891 found. This requires the components in <name>_<component>_compo‐
892 nent_deps to be listed before <component> in the COMPONENTS argument.
893 The following variables will be set:
895 <name>_TARGETS
897 the imported targets
898 <name>_LIBRARIES
900 the found libraries
901 <name>_INCLUDE_DIRS
903 the combined required include directories for the components
904 <name>_DEFINITIONS
906 the “other” CFLAGS provided by pkg-config, if any
907 <name>_VERSION
909 the value of <name>_<component>_VERSION for the first component
910 that has this variable set (note that components are searched
911 for in the order they are passed to the macro), although if it
912 is already set, it will not be altered
913 Note that these variables are never cleared, so if ecm_find_pack‐
915 age_handle_library_components() is called multiple times with different
916 components (typically because of multiple find_package() calls) then
917 <name>_TARGETS, for example, will contain all the targets found in any
918 call (although no duplicates).
919 Since pre-1.0.0.
921 ECMGenerateDBusServiceFile
923 This module provides the ecm_generate_dbus_service_file function for
924 generating and installing a D-Bus service file.
925 ecm_generate_dbus_service_file(
927 NAME <service name>
928 EXECUTABLE <executable>
929 [SYSTEMD_SERVICE <systemd service>]
930 DESTINATION <install_path>
931 [RENAME <dbus service filename>] # Since 5.75
932 )
933 A D-Bus service file <service name>.service will be generated and in‐
935 stalled in the relevant D-Bus config location. This filename can be
936 customized with RENAME.
937 <executable> must be an absolute path to the installed service exe‐
939 cutable. When using it with KDEInstallDirs it needs to be the _FULL_
940 variant of the path variable.
941 Note: On Windows, the macro will only use the file name part of <exe‐
943 cutable> since D-Bus service executables are to be installed in the
944 same directory as the D-Bus daemon.
945 Optionally, a <systemd service> can be specified to launch the corre‐
947 sponding systemd service instead of the <executable> if the D-Bus dae‐
948 mon is started by systemd.
949 Example usage:
951 ecm_generate_dbus_service_file(
953 NAME org.kde.kded5
954 EXECUTABLE ${KDE_INSTALL_FULL_BINDIR}/kded5
955 DESTINATION ${KDE_INSTALL_DBUSSERVICEDIR}
956 )
957 ecm_generate_dbus_service_file(
959 NAME org.kde.kded5
960 EXECUTABLE ${KDE_INSTALL_FULL_BINDIR}/kded5
961 SYSTEMD_SERVICE plasma-kded.service
962 DESTINATION ${KDE_INSTALL_DBUSSERVICEDIR}
963 RENAME org.kde.daemon.service
964 )
965 Since 5.73.0.
967 ECMGenerateExportHeader
969 This module provides the ecm_generate_export_header function for gener‐
970 ating export macros for libraries with version-based control over visi‐
971 bility of and compiler warnings for deprecated API for the library
972 user, as well as over excluding deprecated API and their implementation
973 when building the library itself.
974 For preparing some values useful in the context it also provides a
976 function ecm_export_header_format_version.
977 ecm_generate_export_header(<library_target_name>
979 VERSION <version>
980 [BASE_NAME <base_name>]
981 [GROUP_BASE_NAME <group_base_name>]
982 [EXPORT_MACRO_NAME <export_macro_name>]
983 [EXPORT_FILE_NAME <export_file_name>]
984 [DEPRECATED_MACRO_NAME <deprecated_macro_name>]
985 [NO_EXPORT_MACRO_NAME <no_export_macro_name>]
986 [INCLUDE_GUARD_NAME <include_guard_name>]
987 [STATIC_DEFINE <static_define>]
988 [PREFIX_NAME <prefix_name>]
989 [DEPRECATED_BASE_VERSION <deprecated_base_version>]
990 [DEPRECATION_VERSIONS <deprecation_version> [<deprecation_version2> [...]]]
991 [EXCLUDE_DEPRECATED_BEFORE_AND_AT <exclude_deprecated_before_and_at_version>]
992 [NO_BUILD_SET_DEPRECATED_WARNINGS_SINCE]
993 [NO_DEFINITION_EXPORT_TO_BUILD_INTERFACE]
994 [CUSTOM_CONTENT_FROM_VARIABLE <variable>]
995 )
996 VERSION specifies the version of the library, given in the format “<ma‐
998 jor>.<minor>.<patchlevel>”.
999 GROUP_BASE_NAME specifies the name to use for the macros defining li‐
1001 brary group default values. If set, this will generate code supporting
1002 <group_base_name>_NO_DEPRECATED_WARNINGS, <group_base_name>_DIS‐
1003 ABLE_DEPRECATED_BEFORE_AND_AT, <group_base_name>_DEPRECATED_WARN‐
1004 INGS_SINCE and <group_base_name>_NO_DEPRECATED (see below). If not
1005 set, the generated code will ignore any such macros.
1006 DEPRECATED_BASE_VERSION specifies the default version before and at
1008 which deprecated API is disabled. Possible values are “0”, “CURRENT”
1009 (which resolves to <version>) and a version string in the format “<ma‐
1010 jor>.<minor>.<patchlevel>”. The default is the value of “<exclude_dep‐
1011 recated_before_and_at_version>” if set, or “<major>.0.0”, with <major>
1012 taken from <version>.
1013 DEPRECATION_VERSIONS specifies versions in “<major>.<minor>” format in
1015 which API was declared deprecated. Any version used with the generated
1016 macro <prefix_name><base_name>_DEPRECATED_VERSION(major, minor, text)
1017 or <prefix_name><base_name>_DEPRECATED_VERSION_BELATED(major, minor,
1018 textmajor, textminor, text) needs to be listed here, otherwise the
1019 macro will fail to work.
1020 EXCLUDE_DEPRECATED_BEFORE_AND_AT specifies the version for which all
1022 API deprecated before and at should be excluded from the build com‐
1023 pletely. Possible values are “0” (default), “CURRENT” (which resolves
1024 to <version>) and a version string in the format “<major>.<mi‐
1025 nor>.<patchlevel>”.
1026 NO_BUILD_SET_DEPRECATED_WARNINGS_SINCE specifies that the definition
1028 <prefix_name><uppercase_base_name>_DEPRECATED_WARNINGS_SINCE will not
1029 be set for the library inside its own build, and thus will be defined
1030 by either explicit definition in the build system configuration or by
1031 the default value mechanism (see below). The default is that it is set
1032 for the build, to the version specified by EXCLUDE_DEPRECATED_BE‐
1033 FORE_AND_AT, so no deprecation warnings are done for any own deprecated
1034 API used in the library implementation itself.
1035 NO_DEFINITION_EXPORT_TO_BUILD_INTERFACE specifies that the definition
1037 <prefix_name><uppercase_base_name>_DISABLE_DEPRECATED_BEFORE_AND_AT
1038 will not be set in the public interface of the library inside its own
1039 build, and the same for the definition <prefix_name><upper‐
1040 case_base_name>_DEPRECATED_WARNINGS_SINCE (if not disabled by
1041 NO_BUILD_SET_DEPRECATED_WARNINGS_SINCE already). The default is that
1042 they are set, to the version specified by EXCLUDE_DEPRECATED_BE‐
1043 FORE_AND_AT, so e.g. test and examples part of the project automati‐
1044 cally build against the full API included in the build and without any
1045 deprecation warnings for it.
1046 The function ecm_generate_export_header defines C++ preprocessor macros
1048 in the generated export header, some for use in the sources of the li‐
1049 brary the header is generated for, other for use by projects linking
1050 agsinst the library.
1051 The macros for use in the library C++ sources are these, next to those
1053 also defined by GenerateExportHeader:
1054 <prefix_name><uppercase_base_name>_DEPRECATED_VERSION(major, minor,
1056 text)
1057 to use to conditionally set a <prefix_name><upper‐
1058 case_base_name>_DEPRECATED macro for a class, struct or function
1059 (other elements to be supported in future versions), depending
1060 on the visibility macro flags set (see below)
1061 <prefix_name><uppercase_base_name>_DEPRECATED_VERSION_BELATED(major,
1063 minor, textmajor, textminor, text)
1064 to use to conditionally set a <prefix_name><upper‐
1065 case_base_name>_DEPRECATED macro for a class, struct or function
1066 (other elements to be supported in future versions), depending
1067 on the visibility macro flags set (see below), with major & mi‐
1068 nor applied for the logic and textmajor & textminor for the
1069 warnings message. Useful for retroactive tagging of API for the
1070 compiler without injecting the API into the compiler warning
1071 conditions of already released versions. Since 5.71.
1072 <prefix_name><uppercase_base_name>_ENUMERATOR_DEPRECATED_VERSION(major,
1074 minor, text)
1075 to use to conditionally set a <prefix_name><upper‐
1076 case_base_name>_DEPRECATED macro for an enumerator, depending on
1077 the warnings macro flags set (see below). In builds using C++14
1078 standard or earlier, where enumerator attributes are not yet
1079 supported, the macro will always yield an empty string. With
1080 MSVC it is also always an empty string for now. Since 5.82.
1081 <prefix_name><uppercase_base_name>_ENUMERATOR_DEPRECATED_VERSION_BE‐
1083 LATED(major, minor, textmajor, textminor, text)
1084 to use to conditionally set a <prefix_name><upper‐
1085 case_base_name>_DEPRECATED macro for an enumerator, depending on
1086 the warnings macro flags set (see below), with major & minor ap‐
1087 plied for the logic and textmajor & textminor for the warnings
1088 message. In builds using C++14 standard or earlier, where enu‐
1089 merator attributes are not yet supported, the macro will always
1090 yield an empty string. Useful for retroactive tagging of API
1091 for the compiler without injecting the API into the compiler
1092 warning conditions of already released versions. With MSVC it
1093 is also always an empty string for now. Since 5.82.
1094 <prefix_name><uppercase_base_name>_ENABLE_DEPRECATED_SINCE(major, mi‐
1096 nor)
1097 evaluates to TRUE or FALSE depending on the visibility macro
1098 flags set (see below). To be used mainly with #if/#endif to mark
1099 sections of code which should be included depending on the visi‐
1100 bility requested.
1101 <prefix_name><uppercase_base_name>_BUILD_DEPRECATED_SINCE(major, minor)
1103 evaluates to TRUE or FALSE depending on the value of EX‐
1104 CLUDE_DEPRECATED_BEFORE_AND_AT. To be used mainly with #if/#en‐
1105 dif to mark sections of two types of code: implementation code
1106 for deprecated API and declaration code of deprecated API which
1107 only may be disabled at build time of the library for BC reasons
1108 (e.g. virtual methods, see notes below).
1109 <prefix_name><uppercase_base_name>_EXCLUDE_DEPRECATED_BEFORE_AND_AT
1111 holds the version used to exclude deprecated API at build time
1112 of the library.
1113 The macros used to control visibility when building against the library
1115 are:
1116 <prefix_name><uppercase_base_name>_DISABLE_DEPRECATED_BEFORE_AND_AT
1118 definition to set to a value in single hex number version nota‐
1119 tion (0x<major><minor><patchlevel>).
1120 <prefix_name><uppercase_base_name>_NO_DEPRECATED
1122 flag to define to disable all deprecated API, being a shortcut
1123 for settings <prefix_name><uppercase_base_name>_DISABLE_DEPRE‐
1124 CATED_BEFORE_AND_AT to the current version. If both are set,
1125 this flag overrules.
1126 <prefix_name><uppercase_base_name>_DEPRECATED_WARNINGS_SINCE
1128 definition to set to a value in single hex number version nota‐
1129 tion (0x<major><minor><patchlevel>). Warnings will be only acti‐
1130 vated for API deprecated up to and including the version. If
1131 <prefix_name><uppercase_base_name>_DISABLE_DEPRECATED_BE‐
1132 FORE_AND_AT is set (directly or via the group default), it will
1133 default to that version, resulting in no warnings. Otherwise the
1134 default is the current version, resulting in warnings for all
1135 deprecated API.
1136 <prefix_name><uppercase_base_name>_NO_DEPRECATED_WARNINGS
1138 flag to define to disable all deprecation warnings, being a
1139 shortcut for setting <prefix_name><uppercase_base_name>_DEPRE‐
1140 CATED_WARNINGS_SINCE to “0”. If both are set, this flag over‐
1141 rules.
1142 When the GROUP_BASE_NAME has been used, the same macros but with the
1144 given <group_base_name> prefix are available to define the defaults of
1145 these macros, if not explicitly set.
1146 Note: The tricks applied here for hiding deprecated API to the compiler
1148 when building against a library do not work for all deprecated API:
1149 • virtual methods need to stay visible to the compiler to build proper
1151 virtual method tables for subclasses
1152 • enumerators from enums cannot be simply removed, as this changes auto
1154 values of following enumerators, also can poke holes in enumerator
1155 series used as index into tables
1156 In such cases the API can be only “hidden” at build time of the li‐
1158 brary, itself, by generated hard coded macro settings, using <pre‐
1159 fix_name><uppercase_base_name>_BUILD_DEPRECATED_SINCE(major, minor).
1160 Examples:
1162 Preparing a library “Foo” created by target “foo”, which is part of a
1164 group of libraries “Bar”, where some API of “Foo” got deprecated at
1165 versions 5.0 & 5.12:
1166 ecm_generate_export_header(foo
1168 GROUP_BASE_NAME BAR
1169 VERSION ${FOO_VERSION}
1170 DEPRECATION_VERSIONS 5.0 5.12
1171 )
1172 In the library “Foo” sources in the headers the API would be prepared
1174 like this, using the generated macros FOO_ENABLE_DEPRECATED_SINCE and
1175 FOO_DEPRECATED_VERSION:
1176 #include <foo_export.h>
1178 #if FOO_ENABLE_DEPRECATED_SINCE(5, 0)
1180 /**
1181 * @deprecated Since 5.0
1182 */
1183 FOO_EXPORT
1184 FOO_DEPRECATED_VERSION(5, 0, "Use doFoo2()")
1185 void doFoo();
1186 #endif
1187 #if FOO_ENABLE_DEPRECATED_SINCE(5, 12)
1189 /**
1190 * @deprecated Since 5.12
1191 */
1192 FOO_EXPORT
1193 FOO_DEPRECATED_VERSION(5, 12, "Use doBar2()")
1194 void doBar();
1195 #endif
1196 Projects linking against the “Foo” library can control which part of
1198 its deprecated API should be hidden to the compiler by adding a defini‐
1199 tion using the FOO_DISABLE_DEPRECATED_BEFORE_AND_AT macro variable set
1200 to the desired value (in version hex number notation):
1201 add_definitions(-DFOO_DISABLE_DEPRECATED_BEFORE_AND_AT=0x050000)
1203 Or using the macro variable of the group:
1205 add_definitions(-DBAR_DISABLE_DEPRECATED_BEFORE_AND_AT=0x050000)
1207 If both are specified, FOO_DISABLE_DEPRECATED_BEFORE_AND_AT will take
1209 precedence.
1210 To build a variant of a library with some deprecated API completely
1212 left out from the build, not only optionally invisible to consumers,
1213 one uses the EXCLUDE_DEPRECATED_BEFORE_AND_AT parameter. This is best
1214 combined with a cached CMake variable.
1215 set(EXCLUDE_DEPRECATED_BEFORE_AND_AT 0 CACHE STRING "Control the range of deprecated API excluded from the build [default=0].")
1217 ecm_generate_export_header(foo
1219 VERSION ${FOO_VERSION}
1220 EXCLUDE_DEPRECATED_BEFORE_AND_AT ${EXCLUDE_DEPRECATED_BEFORE_AND_AT}
1221 DEPRECATION_VERSIONS 5.0 5.12
1222 )
1223 The macros used in the headers for library consumers are reused for
1225 disabling the API excluded in the build of the library. For disabling
1226 the implementation of that API as well as for disabling deprecated API
1227 which only can be disabled at build time of the library for BC reasons,
1228 one uses the generated macro FOO_BUILD_DEPRECATED_SINCE, like this:
1229 #include <foo_export.h>
1231 enum Bars {
1233 One,
1234 #if FOO_BUILD_DEPRECATED_SINCE(5, 0)
1235 Two FOO_ENUMERATOR_DEPRECATED_VERSION(5, 0, "Use Three"), // macro available since 5.82
1236 #endif
1237 Three,
1238 };
1239 #if FOO_ENABLE_DEPRECATED_SINCE(5, 0)
1241 /**
1242 * @deprecated Since 5.0
1243 */
1244 FOO_EXPORT
1245 FOO_DEPRECATED_VERSION(5, 0, "Use doFoo2()")
1246 void doFoo();
1247 #endif
1248 #if FOO_ENABLE_DEPRECATED_SINCE(5, 12)
1250 /**
1251 * @deprecated Since 5.12
1252 */
1253 FOO_EXPORT
1254 FOO_DEPRECATED_VERSION(5, 12, "Use doBar2()")
1255 void doBar();
1256 #endif
1257 class FOO_EXPORT Foo {
1259 public:
1260 #if FOO_BUILD_DEPRECATED_SINCE(5, 0)
1261 /**
1262 * @deprecated Since 5.0
1263 */
1264 FOO_DEPRECATED_VERSION(5, 0, "Feature removed")
1265 virtual void doWhat();
1266 #endif
1267 };
1268 #if FOO_BUILD_DEPRECATED_SINCE(5, 0)
1270 void doFoo()
1271 {
1272 // [...]
1273 }
1274 #endif
1275 #if FOO_BUILD_DEPRECATED_SINCE(5, 12)
1277 void doBar()
1278 {
1279 // [...]
1280 }
1281 #endif
1282 #if FOO_BUILD_DEPRECATED_SINCE(5, 0)
1284 void Foo::doWhat()
1285 {
1286 // [...]
1287 }
1288 #endif
1289 So e.g. if EXCLUDE_DEPRECATED_BEFORE_AND_AT is set to “5.0.0”, the enu‐
1291 merator Two as well as the methods ::doFoo() and Foo::doWhat() will be
1292 not available to library consumers. The methods will not have been com‐
1293 piled into the library binary, and the declarations will be hidden to
1294 the compiler, FOO_DISABLE_DEPRECATED_BEFORE_AND_AT also cannot be used
1295 to reactivate them.
1296 When using the NO_DEFINITION_EXPORT_TO_BUILD_INTERFACE and the project
1298 for the “Foo” library includes also tests and examples linking against
1299 the library and using deprecated API (like tests covering it), one bet‐
1300 ter explicitly sets FOO_DISABLE_DEPRECATED_BEFORE_AND_AT for those tar‐
1301 gets to the version before and at which all deprecated API has been ex‐
1302 cluded from the build. Even more when building against other libraries
1303 from the same group “Bar” and disabling some deprecated API of those
1304 libraries using the group macro BAR_DISABLE_DEPRECATED_BEFORE_AND_AT,
1305 which also works as default for FOO_DISABLE_DEPRECATED_BEFORE_AND_AT.
1306 To get the hex number style value the helper macro ecm_ex‐
1308 port_header_format_version() will be used:
1309 set(EXCLUDE_DEPRECATED_BEFORE_AND_AT 0 CACHE STRING "Control what part of deprecated API is excluded from build [default=0].")
1311 ecm_generate_export_header(foo
1313 VERSION ${FOO_VERSION}
1314 GROUP_BASE_NAME BAR
1315 EXCLUDE_DEPRECATED_BEFORE_AND_AT ${EXCLUDE_DEPRECATED_BEFORE_AND_AT}
1316 NO_DEFINITION_EXPORT_TO_BUILD_INTERFACE
1317 DEPRECATION_VERSIONS 5.0 5.12
1318 )
1319 ecm_export_header_format_version(${EXCLUDE_DEPRECATED_BEFORE_AND_AT}
1321 CURRENT_VERSION ${FOO_VERSION}
1322 HEXNUMBER_VAR foo_no_deprecated_before_and_at
1323 )
1324 # disable all deprecated API up to 5.9.0 from all other libs of group "BAR" that we use ourselves
1326 add_definitions(-DBAR_DISABLE_DEPRECATED_BEFORE_AND_AT=0x050900)
1327 add_executable(app app.cpp)
1329 target_link_libraries(app foo)
1330 target_compile_definitions(app
1331 PRIVATE "FOO_DISABLE_DEPRECATED_BEFORE_AND_AT=${foo_no_deprecated_before_and_at}")
1332 Since 5.64.0.
1334 ECMGenerateHeaders
1336 Generate C/C++ CamelCase forwarding headers.
1337 ecm_generate_headers(<camelcase_forwarding_headers_var>
1339 HEADER_NAMES <CamelCaseName> [<CamelCaseName> [...]]
1340 [ORIGINAL <CAMELCASE|LOWERCASE>]
1341 [HEADER_EXTENSION <header_extension>]
1342 [OUTPUT_DIR <output_dir>]
1343 [PREFIX <prefix>]
1344 [REQUIRED_HEADERS <variable>]
1345 [COMMON_HEADER <HeaderName>]
1346 [RELATIVE <relative_path>])
1347 For each CamelCase header name passed to HEADER_NAMES, a file of that
1349 name will be generated that will include a version with .h or, if set,
1350 .<header_extension> appended. For example, the generated header ClassA
1351 will include classa.h (or ClassA.h, see ORIGINAL). If a CamelCaseName
1352 consists of multiple comma-separated files, e.g. ClassA,ClassB,ClassC,
1353 then multiple camelcase header files will be generated which are redi‐
1354 rects to the first header file. The file locations of these generated
1355 headers will be stored in <camelcase_forwarding_headers_var>.
1356 ORIGINAL specifies how the name of the original header is written: low‐
1358 ercased or also camelcased. The default is LOWERCASE. Since 1.8.0.
1359 HEADER_EXTENSION specifies what file name extension is used for the
1361 header files. The default is “h”. Since 5.48.0.
1362 PREFIX places the generated headers in subdirectories. This should be
1364 a CamelCase name like KParts, which will cause the CamelCase forwarding
1365 headers to be placed in the KParts directory (e.g. KParts/Part). It
1366 will also, for the convenience of code in the source distribution, gen‐
1367 erate forwarding headers based on the original names (e.g.
1368 kparts/part.h). This allows includes like "#include <kparts/part.h>"
1369 to be used before installation, as long as the include_directories are
1370 set appropriately.
1371 OUTPUT_DIR specifies where the files will be generated; this should be
1373 within the build directory. By default, ${CMAKE_CURRENT_BINARY_DIR}
1374 will be used. This option can be used to avoid file conflicts.
1375 REQUIRED_HEADERS specifies an output variable name where all the re‐
1377 quired headers will be appended so that they can be installed together
1378 with the generated ones. This is mostly intended as a convenience so
1379 that adding a new header to a project only requires specifying the
1380 CamelCase variant in the CMakeLists.txt file; the original variant will
1381 then be added to this variable.
1382 COMMON_HEADER generates an additional convenience header which includes
1384 all other header files.
1385 The RELATIVE argument indicates where the original headers can be found
1387 relative to CMAKE_CURRENT_SOURCE_DIR. It does not affect the generated
1388 CamelCase forwarding files, but ecm_generate_headers() uses it when
1389 checking that the original header exists, and to generate originally
1390 named forwarding headers when PREFIX is set.
1391 To allow other parts of the source distribution (eg: tests) to use the
1393 generated headers before installation, it may be desirable to set the
1394 INCLUDE_DIRECTORIES property for the library target to output_dir. For
1395 example, if OUTPUT_DIR is CMAKE_CURRENT_BINARY_DIR (the default), you
1396 could do
1397 target_include_directories(MyLib PUBLIC "$<BUILD_INTERFACE:${CMAKE_CURRENT_BINARY_DIR}>")
1399 Example usage (without PREFIX):
1401 ecm_generate_headers(
1403 MyLib_FORWARDING_HEADERS
1404 HEADERS
1405 MLFoo
1406 MLBar
1407 # etc
1408 REQUIRED_HEADERS MyLib_HEADERS
1409 COMMON_HEADER MLGeneral
1410 )
1411 install(FILES ${MyLib_FORWARDING_HEADERS} ${MyLib_HEADERS}
1412 DESTINATION ${CMAKE_INSTALL_PREFIX}/include
1413 COMPONENT Devel)
1414 Example usage (with PREFIX):
1416 ecm_generate_headers(
1418 MyLib_FORWARDING_HEADERS
1419 HEADERS
1420 Foo
1421 # several classes are contained in bar.h, so generate
1422 # additional files
1423 Bar,BarList
1424 # etc
1425 PREFIX MyLib
1426 REQUIRED_HEADERS MyLib_HEADERS
1427 )
1428 install(FILES ${MyLib_FORWARDING_HEADERS}
1429 DESTINATION ${CMAKE_INSTALL_PREFIX}/include/MyLib
1430 COMPONENT Devel)
1431 install(FILES ${MyLib_HEADERS}
1432 DESTINATION ${CMAKE_INSTALL_PREFIX}/include/mylib
1433 COMPONENT Devel)
1434 Since pre-1.0.0.
1436 ECMGeneratePkgConfigFile
1438 Generate a pkg-config file for the benefit of autotools-based projects.
1439 ecm_generate_pkgconfig_file(BASE_NAME <baseName>
1441 [LIB_NAME <libName>]
1442 [DEPS "<dep> [<dep> [...]]"]
1443 [FILENAME_VAR <filename_variable>]
1444 [INCLUDE_INSTALL_DIR <dir>]
1445 [LIB_INSTALL_DIR <dir>]
1446 [DEFINES -D<variable=value>...]
1447 [DESCRIPTION <library description>] # since 5.41.0
1448 [INSTALL])
1449 BASE_NAME is the name of the module. It’s the name projects will use to
1451 find the module.
1452 LIB_NAME is the name of the library that is being exported. If unde‐
1454 fined, it will default to the BASE_NAME. That means the LIB_NAME will
1455 be set as the name field as well as the library to link to.
1456 FILENAME_VAR is specified with a variable name. This variable will re‐
1458 ceive the location of the generated file will be set, within the build
1459 directory. This way it can be used in case some processing is required.
1460 See also INSTALL.
1461 INCLUDE_INSTALL_DIR specifies where the includes will be installed. If
1463 it’s not specified, it will default to INSTALL_INCLUDEDIR, CMAKE_IN‐
1464 STALL_INCLUDEDIR or just “include/” in case they are specified, with
1465 the BASE_NAME postfixed.
1466 LIB_INSTALL_DIR specifies where the library is being installed. If it’s
1468 not specified, it will default to LIB_INSTALL_DIR, CMAKE_INSTALL_LIBDIR
1469 or just “lib/” in case they are specified.
1470 DEFINES is a list of preprocessor defines that it is recommended users
1472 of the library pass to the compiler when using it.
1473 DESCRIPTION describes what this library is. If it’s not specified,
1475 CMake will first try to get the description from the metainfo.yaml file
1476 or will create one based on LIB_NAME. Since 5.41.0.
1477 INSTALL will cause the module to be installed to the pkgconfig subdi‐
1479 rectory of LIB_INSTALL_DIR, unless the ECM_PKGCONFIG_INSTALL_DIR cache
1480 variable is set to something different. Note that the first call to
1481 ecm_generate_pkgconfig_file with the INSTALL argument will cause
1482 ECM_PKGCONFIG_INSTALL_DIR to be set to the cache, and will be used in
1483 any subsequent calls.
1484 To properly use this macro a version needs to be set. To retrieve it,
1486 ECM_PKGCONFIG_INSTALL_DIR uses PROJECT_VERSION. To set it, use the
1487 project() command or the ecm_setup_version() macro
1488 Example usage:
1490 ecm_generate_pkgconfig_file(
1492 BASE_NAME KF5Archive
1493 DEPS Qt5Core
1494 FILENAME_VAR pkgconfig_filename
1495 INSTALL
1496 )
1497 Since 1.3.0.
1499 ECMGeneratePriFile
1501 Generate a .pri file for the benefit of qmake-based projects.
1502 As well as the function below, this module creates the cache variable
1504 ECM_MKSPECS_INSTALL_DIR and sets the default value to mkspecs/modules.
1505 This assumes Qt and the current project are both installed to the same
1506 non-system prefix. Packagers who use -DCMAKE_INSTALL_PREFIX=/usr will
1507 certainly want to set ECM_MKSPECS_INSTALL_DIR to something like
1508 share/qt5/mkspecs/modules.
1509 The main thing is that this should be the modules subdirectory of ei‐
1511 ther the default qmake mkspecs directory or of a directory that will be
1512 in the $QMAKEPATH environment variable when qmake is run.
1513 ecm_generate_pri_file(BASE_NAME <baseName>
1515 LIB_NAME <libName>
1516 [VERSION <version>] # since 5.83
1517 [DEPS "<dep> [<dep> [...]]"]
1518 [FILENAME_VAR <filename_variable>]
1519 [INCLUDE_INSTALL_DIR <dir>]
1520 [LIB_INSTALL_DIR <dir>])
1521 If your CMake project produces a Qt-based library, you may expect there
1523 to be applications that wish to use it that use a qmake-based build
1524 system, rather than a CMake-based one. Creating a .pri file will make
1525 use of your library convenient for them, in much the same way that
1526 CMake config files make things convenient for CMake-based applications.
1527 ecm_generate_pri_file() generates just such a file.
1528 VERSION specifies the version of the library the .pri file describes.
1530 If not set, the value is taken from the context variable PROJECT_VER‐
1531 SION. This variable is usually set by the project(... VERSION ...)
1532 command or, if CMake policy CMP0048 is not NEW, by ECMSetupVersion.
1533 For backward-compatibility with older ECM versions the PROJECT_VER‐
1534 SION_STRING variable as set by ECMSetupVersion will be preferred over
1535 PROJECT_VERSION if set, unless the minimum required version of ECM is
1536 5.83 and newer. Since 5.83.
1537 BASE_NAME specifies the name qmake project (.pro) files should use to
1539 refer to the library (eg: KArchive). LIB_NAME is the name of the ac‐
1540 tual library to link to (ie: the first argument to add_library()).
1541 DEPS is a space-separated list of the base names of other libraries
1542 (for Qt libraries, use the same names you use with the QT variable in a
1543 qmake project file, such as “core” for QtCore). FILENAME_VAR specifies
1544 the name of a variable to store the path to the generated file in.
1545 INCLUDE_INSTALL_DIR is the path (relative to CMAKE_INSTALL_PREFIX) that
1547 include files will be installed to. It defaults to ${INCLUDE_IN‐
1548 STALL_DIR}/<baseName> if the INCLUDE_INSTALL_DIR variable is set. If
1549 that variable is not set, the CMAKE_INSTALL_INCLUDEDIR variable is used
1550 instead, and if neither are set include is used. LIB_INSTALL_DIR oper‐
1551 ates similarly for the installation location for libraries; it defaults
1552 to ${LIB_INSTALL_DIR}, ${CMAKE_INSTALL_LIBDIR} or lib, in that order.
1553 Example usage:
1555 ecm_generate_pri_file(
1557 BASE_NAME KArchive
1558 LIB_NAME KF5KArchive
1559 DEPS "core"
1560 FILENAME_VAR pri_filename
1561 VERSION 4.2.0
1562 )
1563 install(FILES ${pri_filename} DESTINATION ${ECM_MKSPECS_INSTALL_DIR})
1564 A qmake-based project that wished to use this would then do:
1566 QT += KArchive
1568 in their .pro file.
1570 Since pre-1.0.0.
1572 ECMGenerateQmlTypes
1574 Generates plugins.qmltypes files for QML plugins.
1575 ecm_generate_qmltypes(<org.kde.pluginname> 1.3
1577 DESTINATION <${KDE_INSTALL_QMLDIR}/org/kde/pluginname>)
1578 Makes it possible to generate plugins.qmltypes files for the QML plug‐
1580 ins that our project offers. These files offer introspection upon our
1581 plugin and are useful for integrating with IDE language support of our
1582 plugin. It offers information about the objects its methods and their
1583 argument types.
1584 The developer will be in charge of making sure that these files are up
1586 to date. The plugin.qmltypes file will sit in the source directory.
1587 This function will include the code that installs the file in the right
1588 place and a small unit test named qmltypes-pluginname-version that
1589 makes sure that it doesn’t need updating.
1590 Since 5.33.0
1592 ECMInstallIcons
1594 Installs icons, sorting them into the correct directories according to
1595 the FreeDesktop.org icon naming specification.
1596 ecm_install_icons(ICONS <icon> [<icon> [...]]
1598 DESTINATION <icon_install_dir>
1599 [LANG <l10n_code>]
1600 [THEME <theme>])
1601 The given icons, whose names must match the pattern:
1603 <size>-<group>-<name>.<ext>
1605 will be installed to the appropriate subdirectory of DESTINATION ac‐
1607 cording to the FreeDesktop.org icon naming scheme. By default, they are
1608 installed to the “hicolor” theme, but this can be changed using the
1609 THEME argument. If the icons are localized, the LANG argument can be
1610 used to install them in a locale-specific directory.
1611 <size> is a numeric pixel size (typically 16, 22, 32, 48, 64, 128 or
1613 256) or sc for scalable (SVG) files, <group> is one of the standard
1614 FreeDesktop.org icon groups (actions, animations, apps, categories, de‐
1615 vices, emblems, emotes, intl, mimetypes, places, status) and <ext> is
1616 one of .png, .mng or .svgz.
1617 The typical installation directory is share/icons.
1619 ecm_install_icons(ICONS 22-actions-menu_new.png
1621 DESTINATION share/icons)
1622 The above code will install the file 22-actions-menu_new.png as
1624 ${CMAKE_INSTALL_PREFIX}/share/icons/<theme>/22x22/actions/menu_new.png
1625 Users of the KDEInstallDirs module would normally use ${KDE_IN‐
1627 STALL_ICONDIR} as the DESTINATION, while users of the GNUInstallDirs
1628 module should use ${CMAKE_INSTALL_DATAROOTDIR}/icons.
1629 An old form of arguments will also be accepted:
1631 ecm_install_icons(<icon_install_dir> [<l10n_code>])
1633 This matches files named like:
1635 <theme><size>-<group>-<name>.<ext>
1637 where <theme> is one of
1639 • hi for hicolor
1641 • lo for locolor
1643 • cr for the Crystal icon theme
1645 • ox for the Oxygen icon theme
1647 • br for the Breeze icon theme
1649 With this syntax, the file hi22-actions-menu_new.png would be installed
1651 into <icon_install_dir>/hicolor/22x22/actions/menu_new.png
1652 Since pre-1.0.0.
1654 ECMMarkAsTest
1656 Marks a target as only being required for tests.
1657 ecm_mark_as_test(<target1> [<target2> [...]])
1659 This will cause the specified targets to not be built unless either
1661 BUILD_TESTING is set to ON or the user invokes the buildtests target.
1662 BUILD_TESTING is created as a cache variable by the CTest module and by
1664 the KDECMakeSettings module.
1665 Since pre-1.0.0.
1667 ECMMarkNonGuiExecutable
1669 Marks an executable target as not being a GUI application.
1670 ecm_mark_nongui_executable(<target1> [<target2> [...]])
1672 This will indicate to CMake that the specified targets should not be
1674 included in a MACOSX_BUNDLE and should not be WIN32_EXECUTABLEs. On
1675 platforms other than MacOS X or Windows, this will have no effect.
1676 Since pre-1.0.0.
1678 ECMOptionalAddSubdirectory
1680 Make subdirectories optional.
1681 ecm_optional_add_subdirectory(<dir>)
1683 This behaves like add_subdirectory(), except that it does not complain
1685 if the directory does not exist. Additionally, if the directory does
1686 exist, it creates an option to allow the user to skip it. The option
1687 will be named BUILD_<dir>.
1688 This is useful for “meta-projects” that combine several mostly-indepen‐
1690 dent sub-projects.
1691 If the CMake variable DISABLE_ALL_OPTIONAL_SUBDIRECTORIES is set to
1693 TRUE for the first CMake run on the project, all optional subdirecto‐
1694 ries will be disabled by default (but can of course be enabled via the
1695 respective options). For example, the following will disable all op‐
1696 tional subdirectories except the one named “foo”:
1697 cmake -DDISABLE_ALL_OPTIONAL_SUBDIRECTORIES=TRUE -DBUILD_foo=TRUE myproject
1699 Since pre-1.0.0.
1701 ECMPackageConfigHelpers
1703 Helper macros for generating CMake package config files.
1704 write_basic_package_version_file() is the same as the one provided by
1706 the CMakePackageConfigHelpers module in CMake; see that module’s docu‐
1707 mentation for more information.
1708 ecm_configure_package_config_file(<input> <output>
1710 INSTALL_DESTINATION <path>
1711 [PATH_VARS <var1> [<var2> [...]]
1712 [NO_SET_AND_CHECK_MACRO]
1713 [NO_CHECK_REQUIRED_COMPONENTS_MACRO])
1714 This behaves in the same way as configure_package_config_file() from
1716 CMake 2.8.12, except that it adds an extra helper macro: find_depen‐
1717 dency(). It is highly recommended that you read the documentation for
1718 CMakePackageConfigHelpers for more information, particularly with re‐
1719 gard to the PATH_VARS argument.
1720 Note that there is no argument that will disable the find_dependency()
1722 macro; if you do not require this macro, you should use configure_pack‐
1723 age_config_file from the CMakePackageConfigHelpers module.
1724 CMake 3.0 includes a CMakeFindDependencyMacro module that provides the
1726 find_dependency() macro (which you can include() in your package config
1727 file), so this file is only useful for projects wishing to provide con‐
1728 fig files that will work with CMake 2.8.12.
1729 Additional Config File Macros
1731 find_dependency(<dep> [<version> [EXACT]])
1732 find_dependency() should be used instead of find_package() to find
1734 package dependencies. It forwards the correct parameters for EXACT,
1735 QUIET and REQUIRED which were passed to the original find_package()
1736 call. It also sets an informative diagnostic message if the dependency
1737 could not be found.
1738 Since pre-1.0.0.
1740 ECMPoQmTools
1742 This module provides the ecm_process_po_files_as_qm and ecm_in‐
1743 stall_po_files_as_qm functions for generating QTranslator (.qm) cata‐
1744 logs from Gettext (.po) catalogs, and the ecm_create_qm_loader function
1745 for generating the necessary code to load them in a Qt application or
1746 library.
1747 ecm_process_po_files_as_qm(<lang> [ALL]
1749 [INSTALL_DESTINATION <install_destination>]
1750 PO_FILES <pofile> [<pofile> [...]])
1751 Compile .po files into .qm files for the given language.
1753 If INSTALL_DESTINATION is given, the .qm files are installed in <in‐
1755 stall_destination>/<lang>/LC_MESSAGES. Typically, <install_destination>
1756 is set to share/locale.
1757 ecm_process_po_files_as_qm creates a “translations” target. This target
1759 builds all .po files into .qm files. If ALL is specified, these rules
1760 are added to the “all” target (and so the .qm files will be built by
1761 default).
1762 ecm_create_qm_loader(<sources_var_name(|target (since 5.83))> <catalog_name>)
1764 Generates C++ code which ensures translations are automatically loaded
1766 at startup. The generated files are appended to the variable named
1767 <sources_var_name> or, if the first argument is a target (since 5.83),
1768 to the SOURCES property of <target>. Any target must be created with
1769 add_executable() or add_library() and not be an alias.
1770 It assumes that the .qm file for the language code <lang> is installed
1772 as <sharedir>/locale/<lang>/LC_MESSAGES/<catalog_name>.qm, where
1773 <sharedir> is one of the directories given by the GenericDataLocation
1774 of QStandardPaths.
1775 Typical usage is like:
1777 set(mylib_SRCS foo.cpp bar.cpp)
1779 ecm_create_qm_loader(mylib_SRCS mycatalog)
1780 add_library(mylib ${mylib_SRCS})
1781 # Or, since 5.83:
1783 add_library(mylib foo.cpp bar.cpp)
1784 ecm_create_qm_loader(mylib mycatalog)
1785 ecm_install_po_files_as_qm(<podir>)
1787 Searches for .po files and installs them to the standard location.
1789 This is a convenience function which relies on all .po files being kept
1791 in <podir>/<lang>/, where <lang> is the language the .po files are
1792 written in.
1793 For example, given the following directory structure:
1795 po/
1797 fr/
1798 mylib.po
1799 ecm_install_po_files_as_qm(po) compiles mylib.po into mylib.qm and in‐
1801 stalls it in <install_destination>/fr/LC_MESSAGES. <install_destina‐
1802 tion> defaults to ${LOCALE_INSTALL_DIR} if defined, otherwise it uses
1803 ${CMAKE_INSTALL_LOCALEDIR} if that is defined, otherwise it uses
1804 share/locale.
1805 Since pre-1.0.0.
1807 ECMQMLModules
1809 Find QML import modules through a find_qmlmodule() call. It uses the
1810 qmlplugindump application to find the plugins and sets them up as run‐
1811 time dependencies.
1812 This is useful so that when we configure a project we are noified when
1814 some QML imports are not present in the system, thus having the appli‐
1815 cation compilable but fail at runtime.
1816 ecm_find_qmlmodule(<module_name> <version>...)
1818 Any further arguments passed will be forwarded into a find_package()
1820 call. See find_package() documentation for more information.
1821 Usage example:
1823 ecm_find_qmlmodule(org.kde.kirigami 2.1)
1825 Since 5.38.0.
1827 ECMQtDeclareLoggingCategory
1829 This module provides the ecm_qt_declare_logging_category function for
1830 generating declarations for logging categories in Qt5, and the
1831 ecm_qt_install_logging_categories function for generating and in‐
1832 stalling a file in KDebugSettings format with the info about all those
1833 categories, as well as a file with info about any renamed categories if
1834 defined. To include in that file any logging categories that are manu‐
1835 ally defined also a function ecm_qt_export_logging_category is pro‐
1836 vided.
1837 ecm_qt_declare_logging_category(<sources_var_name(|target (since 5.80))>
1839 HEADER <filename>
1840 IDENTIFIER <identifier>
1841 CATEGORY_NAME <category_name>
1842 [OLD_CATEGORY_NAMES <oldest_cat_name> [<second_oldest_cat_name> [...]]]
1843 [DEFAULT_SEVERITY <Debug|Info|Warning|Critical|Fatal>]
1844 [EXPORT <exportid>]
1845 [DESCRIPTION <description>]
1846 )
1847 A header file, <filename>, will be generated along with a corresponding
1849 source file. These will provide a QLoggingCategory category that can be
1850 referred to from C++ code using <identifier>, and from the logging con‐
1851 figuration using <category_name>.
1852 The generated source file will be added to the variable with the name
1854 <sources_var_name>. If the given argument is a target though, instead
1855 both the generated header file and the generated source file will be
1856 added to the target as private sources (since 5.80). The target must
1857 not be an alias.
1858 If <filename> is not absolute, it will be taken relative to the current
1860 binary directory.
1861 If the code is compiled against Qt 5.4 or later, by default it will
1863 only log output that is at least the severity specified by DE‐
1864 FAULT_SEVERITY, or “Info” level if DEFAULT_SEVERITY is not given. Note
1865 that, due to a bug in Qt 5.5, “Info” may be treated as more severe than
1866 “Fatal”.
1867 <identifier> may include namespaces (eg: foo::bar::IDENT).
1869 If EXPORT is passed, the category will be registered for the group id
1871 <exportid>. Info about the categories of that group can then be gener‐
1872 ated in a file and installed by that group id with the ecm_qt_in‐
1873 stall_logging_categories function. In that case also DESCRIPTION will
1874 need to be passed, with <description> being a short single line text.
1875 And OLD_CATEGORY_NAMES can be used to inform about any renamings of the
1876 category, so user settings can be migrated. Since 5.68.0.
1877 Since 5.14.0.
1879 ecm_qt_export_logging_category(
1881 IDENTIFIER <identifier>
1882 CATEGORY_NAME <category_name>
1883 [OLD_CATEGORY_NAMES <oldest_category_name> [<second_oldest_category_name> [...]]]
1884 EXPORT <exportid>
1885 DESCRIPTION <description>
1886 [DEFAULT_SEVERITY <Debug|Info|Warning|Critical|Fatal>]
1887 )
1888 Registers a logging category for being included in the generated and
1890 installed KDebugSettings files. To be used for categories who are de‐
1891 clared by manual code or other ways instead of code generated with
1892 ecm_qt_declare_logging_category.
1893 <identifier> may include namespaces (eg: foo::bar::IDENT).
1895 EXPORT specifies the group id with which the category will be regis‐
1897 tered. Info about the categories of that group can then be generated
1898 in a file and installed by that group id with the ecm_qt_install_log‐
1899 ging_categories function.
1900 DESCRIPTION specifies a short single line text describing the category.
1902 OLD_CATEGORY_NAMES can be used to inform about any renamings of the
1904 category, so user settings can be migrated.
1905 Since 5.68.0.
1907 ecm_qt_install_logging_categories(
1909 EXPORT <exportid>
1910 [FILE <filename>]
1911 DESTINATION <install_path>
1912 [SORT]
1913 [COMPONENT <component>]
1914 )
1915 Generates and installs a file in KDebugSettings format with the info
1917 about all the categories registered for the group <exportid>, as well
1918 as a file with info about any renamed categories, if there are.
1919 The method call needs to be after the last ecm_qt_declare_logging_cate‐
1921 gory call which uses the same <exportid>. This can be in the same di‐
1922 rectory, or any subdirectory or parent directory.
1923 EXPORT specifies the group id of categories whose information should be
1925 stored in the file generated and installed.
1926 FILE specifies the name of the file generated and installed. It will
1928 default to lower-cased <exportid>.categories.
1929 DESTINATION specifies where the generated file will be installed.
1931 IF SORT is set, entries will be sorted by identifiers.
1933 COMPONENT specifies the installation component name with which the in‐
1935 stall rules for the generated file are associated.
1936 Since 5.85.0 this is a no-op when building for Android, as KDebugSet‐
1938 tings is not available on that platform and the logging category files
1939 therefore just bloat the APK.
1940 Example usage:
1942 ecm_qt_declare_logging_category(
1944 MYPROJECT_SRCS
1945 HEADER "myproject_debug.h"
1946 IDENTIFIER "MYPROJECT_DEBUG"
1947 CATEGORY_NAME "myproject"
1948 OLD_CATEGORY_NAMES "myprojectlog"
1949 DESCRIPTION "My project"
1950 EXPORT MyProject
1951 )
1952 ecm_qt_export_logging_category(
1954 IDENTIFIER "MYPROJECT_SUBMODULE_DEBUG"
1955 CATEGORY_NAME "myproject.submodule"
1956 DESCRIPTION "My project - submodule"
1957 EXPORT MyProject
1958 )
1959 ecm_qt_install_logging_categories(
1961 EXPORT MyProject
1962 FILE myproject.categories
1963 DESTINATION "${KDE_INSTALL_LOGGINGCATEGORIESDIR}"
1964 )
1965 Since 5.68.0.
1967 ECMSetupQtPluginMacroNames
1969 Instruct CMake’s automoc about C++ preprocessor macros used to define
1970 Qt-style plugins.
1971 ecm_setup_qtplugin_macro_names(
1973 [JSON_NONE <macro_name> [<macro_name> [...]]]
1974 [JSON_ARG1 <macro_name> [<macro_name> [...]]]
1975 [JSON_ARG2 <macro_name> [<macro_name> [...]]]
1976 [JSON_ARG3 <macro_name> [<macro_name> [...]]]
1977 [CONFIG_CODE_VARIABLE <variable_name>] )
1978 CMake’s automoc needs some support when parsing C++ source files to de‐
1980 tect whether moc should be run on those files and if there are also de‐
1981 pendencies on other files, like those with Qt plugin metadata in JSON
1982 format. Because automoc just greps overs the raw plain text of the
1983 sources without any C++ preprocessor-like processing. CMake in newer
1984 versions provides the variables CMAKE_AUTOMOC_DEPEND_FILTERS (CMake >=
1985 3.9.0) and CMAKE_AUTOMOC_MACRO_NAMES (CMake >= 3.10) to allow the de‐
1986 veloper to assist automoc.
1987 This macro cares for the explicit setup needed for those variables for
1989 common cases of C++ preprocessor macros used for Qt-style plugins.
1990 JSON_NONE lists the names of C++ preprocessor macros for Qt-style plug‐
1992 ins which do not refer to external files with the plugin metadata.
1993 JSON_ARG1 lists the names of C++ preprocessor macros for Qt-style plug‐
1995 ins where the first argument to the macro is the name of the external
1996 file with the plugin metadata.
1997 JSON_ARG2 is the same as JSON_ARG1 but with the file name being the
1999 second argument.
2000 JSON_ARG3 is the same as JSON_ARG1 but with the file name being the
2002 third argument.
2003 CONFIG_CODE_VARIABLE specifies the name of the variable which will get
2005 set as value some generated CMake code for instructing automoc for the
2006 given macro names, as useful in an installed CMake config file. The
2007 variable can then be used as usual in the template file for such a
2008 CMake config file, by @<variable_name>@.
2009 Example usage:
2011 Given some plugin-oriented Qt-based software which defines a custom C++
2013 preprocessor macro EXPORT_MYPLUGIN for declaring the central plugin ob‐
2014 ject:
2015 #define EXPORT_MYPLUGIN_WITH_JSON(classname, jsonFile) \
2017 class classname : public QObject \
2018 { \
2019 Q_OBJECT \
2020 Q_PLUGIN_METADATA(IID "myplugin" FILE jsonFile) \
2021 explicit classname() {} \
2022 };
2023 In the CMake buildsystem of the library one calls
2025 ecm_setup_qtplugin_macro_names(
2027 JSON_ARG2
2028 EXPORT_MYPLUGIN_WITH_JSON
2029 )
2030 to instruct automoc about the usage of that macro in the sources of the
2032 library itself.
2033 Given the software installs a library including the header with the
2035 macro definition and a CMake config file, so 3rd-party can create addi‐
2036 tional plugins by linking against the library, one passes additionally
2037 the name of a variable which shall be set as value the CMake code
2038 needed to instruct automoc about the usage of that macro.
2039 ecm_setup_qtplugin_macro_names(
2041 JSON_ARG2
2042 EXPORT_MYPLUGIN_WITH_JSON
2043 CONFIG_CODE_VARIABLE
2044 PACKAGE_SETUP_AUTOMOC_VARIABLES
2045 )
2046 This variable then is used in the template file (e.g. MyProjectCon‐
2048 fig.cmake.in) for the libary’s installed CMake config file and that way
2049 will ensure that in the 3rd-party plugin’s buildsystem automoc is in‐
2050 structed as well as needed:
2051 @PACKAGE_SETUP_AUTOMOC_VARIABLES@
2053 Since 5.45.0.
2055 ECMSetupVersion
2057 Handle library version information.
2058 ecm_setup_version(<version>
2060 VARIABLE_PREFIX <prefix>
2061 [SOVERSION <soversion>]
2062 [VERSION_HEADER <filename>]
2063 [PACKAGE_VERSION_FILE <filename> [COMPATIBILITY <compat>]] )
2064 This parses a version string and sets up a standard set of version
2066 variables. It can optionally also create a C version header file and a
2067 CMake package version file to install along with the library.
2068 If the <version> argument is of the form <major>.<minor>.<patch> (or
2070 <major>.<minor>.<patch>.<tweak>), The following CMake variables are
2071 set:
2072 <prefix>_VERSION_MAJOR - <major>
2074 <prefix>_VERSION_MINOR - <minor>
2075 <prefix>_VERSION_PATCH - <patch>
2076 <prefix>_VERSION - <version>
2077 <prefix>_SOVERSION - <soversion>, or <major> if SOVERSION was not given
2078 For backward-compatibility also this variable is set (only if the mini‐
2080 mum required version of ECM is < 5.83):
2081 <prefix>_VERSION_STRING - <version> (use <prefix>_VERSION instead)
2083 If CMake policy CMP0048 is not NEW, the following CMake variables will
2085 also be set:
2086 PROJECT_VERSION_MAJOR - <major>
2088 PROJECT_VERSION_MINOR - <minor>
2089 PROJECT_VERSION_PATCH - <patch>
2090 PROJECT_VERSION - <version>
2091 For backward-compatibility, if CMake policy CMP0048 is not NEW, also
2093 this variable is set (only if the minimum required version of ECM is <
2094 5.83):
2095 PROJECT_VERSION_STRING - <version> (use PROJECT_VERSION instead)
2097 If the VERSION_HEADER option is used, a simple C header is generated
2099 with the given filename. If filename is a relative path, it is inter‐
2100 preted as relative to CMAKE_CURRENT_BINARY_DIR. The generated header
2101 contains the following macros:
2102 <prefix>_VERSION_MAJOR - <major> as an integer
2104 <prefix>_VERSION_MINOR - <minor> as an integer
2105 <prefix>_VERSION_PATCH - <patch> as an integer
2106 <prefix>_VERSION_STRING - <version> as a C string
2107 <prefix>_VERSION - the version as an integer
2108 <prefix>_VERSION has <patch> in the bottom 8 bits, <minor> in the next
2110 8 bits and <major> in the remaining bits. Note that <patch> and <mi‐
2111 nor> must be less than 256.
2112 If the PACKAGE_VERSION_FILE option is used, a simple CMake package ver‐
2114 sion file is created using the write_basic_package_version_file() macro
2115 provided by CMake. It should be installed in the same location as the
2116 Config.cmake file of the library so that it can be found by find_pack‐
2117 age(). If the filename is a relative path, it is interpreted as rela‐
2118 tive to CMAKE_CURRENT_BINARY_DIR. The optional COMPATIBILITY option is
2119 forwarded to write_basic_package_version_file(), and defaults to
2120 AnyNewerVersion.
2121 If CMake policy CMP0048 is NEW, an alternative form of the command is
2123 available:
2124 ecm_setup_version(PROJECT
2126 [VARIABLE_PREFIX <prefix>]
2127 [SOVERSION <soversion>]
2128 [VERSION_HEADER <filename>]
2129 [PACKAGE_VERSION_FILE <filename>] )
2130 This will use the version information set by the project() command.
2132 VARIABLE_PREFIX defaults to the project name. Note that PROJECT must
2133 be the first argument. In all other respects, it behaves like the
2134 other form of the command.
2135 Since pre-1.0.0.
2137 COMPATIBILITY option available since 1.6.0.
2139 ECMSourceVersionControl
2141 Tries to determine whether the source is under version control (git
2142 clone, svn checkout, etc).
2143 ECM_SOURCE_UNDER_VERSION_CONTROL is set when indication is found that
2145 CMAKE_SOURCE_DIR is under version control.
2146 Since 5.63
2148 ECMUninstallTarget
2150 Add an uninstall target.
2151 By including this module, an uninstall target will be added to your
2153 CMake project. This will remove all files installed (or updated) by a
2154 previous invocation of the install target. It will not remove files
2155 created or modified by an install(SCRIPT) or install(CODE) command; you
2156 should create a custom uninstallation target for these and use add_de‐
2157 pendency to make the uninstall target depend on it:
2158 include(ECMUninstallTarget)
2160 install(SCRIPT install-foo.cmake)
2161 add_custom_target(uninstall_foo COMMAND ${CMAKE_COMMAND} -P uninstall-foo.cmake)
2162 add_dependency(uninstall uninstall_foo)
2163 The target will fail if the install target has not yet been run (so it
2165 is not possible to run CMake on the project and then immediately run
2166 the uninstall target).
2167 WARNING:
2169 CMake deliberately does not provide an uninstall target by default
2170 on the basis that such a target has the potential to remove impor‐
2171 tant files from a user’s computer. Use with caution.
2172 Since 1.7.0.
2174 ECMUseFindModules
2176 Selectively use some of the find modules provided by extra-cmake-mod‐
2177 ules.
2178 This module is automatically available once extra-cmake-modules has
2180 been found, so it is not necessary to include(ECMUseFindModules) ex‐
2181 plicitly.
2182 ecm_use_find_modules(DIR <dir>
2184 MODULES module1.cmake [module2.cmake [...]]
2185 [NO_OVERRIDE])
2186 This allows selective use of the find modules provided by ECM, includ‐
2188 ing deferring to CMake’s versions of those modules if it has them.
2189 Rather than adding ${ECM_FIND_MODULE_DIR} to CMAKE_MODULE_PATH, you use
2190 ecm_use_find_modules() to copy the modules you want to a local (build)
2191 directory, and add that to CMAKE_MODULE_PATH.
2192 The find modules given to MODULES will be copied to the directory given
2194 by DIR (which should be located in ${CMAKE_BINARY_DIR} and added to
2195 CMAKE_MODULE_PATH). If NO_OVERRIDE is given, only modules not also
2196 provided by CMake will be copied.
2197 Example:
2199 find_package(ECM REQUIRED)
2201 ecm_use_find_modules(
2202 DIR ${CMAKE_BINARY_DIR}/cmake
2203 MODULES FindEGL.cmake
2204 NO_OVERRIDE
2205 )
2206 set(CMAKE_MODULE_PATH ${CMAKE_BINARY_DIR}/cmake)
2207 This example will make FindEGL.cmake available in your project, but
2209 only as long as it is not yet part of CMake. Calls to find_package(EGL)
2210 will then make use of this copied module (or the CMake module if it ex‐
2211 ists).
2212 Another possible use for this macro is to take copies of find modules
2214 that can be installed along with config files if they are required as a
2215 dependency (for example, if targets provided by the find module are in
2216 the link interface of a library).
2217 Since pre-1.0.0.
2219 ECMWinResolveSymlinks
2221 Resolve pseudo-symlinks created by git when cloning on Windows.
2222 ecm_win_resolve_symlinks(<dir>)
2224 When git checks out a repository with UNIX symlinks on Windows machine,
2226 it creates a text file for each symlink, containing a relative path to
2227 the real file. This function would recursively walk over specified di‐
2228 rectory and replace pseudo-symlinks with corresponding real file’s con‐
2229 tents. It would then run git update-index –assume-unchanged on them to
2230 trick git.
2231 This is useful for projects like “breeze-icons” that contain many iden‐
2233 tical icons implemented as symlinks.
2234 Since 5.28
2236
2238 ecm(7), ecm-find-modules(7), ecm-kde-modules(7)
2239
2241 KDE Developers
22425.88 Nov 08, 2021 ECM-MODULES(7)