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 • Icotool (see FindIcoTool) is required.
72 • Supported sizes: 16, 24, 32, 48, 64, 128, 256, 512 and 1024.
74 Mac OS X notes
76 • The executable target must have the MACOSX_BUNDLE property
78 set.
79 • Icons are added to the bundle.
81 • If the ksvg2icns tool from KIconThemes is available, .svg and
83 .svgz files are accepted; the first that is converted success‐
84 fully to .icns will provide the application icon. SVG files
85 are ignored otherwise.
86 • The tool iconutil (provided by Apple) is required for bitmap
88 icons.
89 • Supported sizes: 16, 32, 64, 128, 256 (and 512, 1024 after OS
91 X 10.9).
92 • At least a 128x128px (or an SVG) icon is required.
94 • Larger sizes are automatically used to substitute for smaller
96 sizes on “Retina” (high-resolution) displays. For example, a
97 32px icon, if provided, will be used as a 32px icon on stan‐
98 dard-resolution displays, and as a 16px-equivalent icon (with
99 an “@2x” tag) on high-resolution displays. That is why you
100 should provide 64px and 1024px icons although they are not
101 supported anymore directly. Instead they will be used as
102 32px@2x and 512px@2x. ksvg2icns handles this internally.
103 • This function sets the MACOSX_BUNDLE_ICON_FILE variable to the
105 name of the generated icns file, so that it will be used as
106 the MACOSX_BUNDLE_ICON_FILE target property when you call
107 add_executable.
108 • Sidebar icons should typically provided in 16, 32, 64, 128 and
110 256px.
111 Since 1.7.0.
113 ECMAddQch
115 This module provides the ecm_add_qch function for generating API docu‐
116 mentation files in the QCH format, and the ecm_install_qch_export func‐
117 tion for generating and installing exported CMake targets for such gen‐
118 erated QCH files to enable builds of other software with generation of
119 QCH files to create links into the given QCH files.
120 ecm_add_qch(<target_name>
122 NAME <name>
123 VERSION <version>
124 QCH_INSTALL_DESTINATION <qchfile_install_path>
125 TAGFILE_INSTALL_DESTINATION <tagsfile_install_path>
126 [COMPONENT <component>]
127 [BASE_NAME <basename>]
128 [SOURCE_DIRS <dir> [<dir2> [...]]]
129 [SOURCES <file> [<file2> [...]]]
130 |MD_MAINPAGE <md_file>]
131 [INCLUDE_DIRS <incdir> [<incdir2> [...]]]
132 [IMAGE_DIRS <idir> [<idir2> [...]]]
133 [EXAMPLE_DIRS <edir> [<edir2> [...]]]
134 [ORG_DOMAIN <domain>]
135 [NAMESPACE <namespace>]
136 [LINK_QCHS <qch> [<qch2> [...]]]
137 [PREDEFINED_MACROS <macro[=content]> [<macro2[=content]> [...]]]
138 [BLANK_MACROS <macro> [<macro2> [...]]]
139 [CONFIG_TEMPLATE <configtemplate_file>]
140 [VERBOSE]
141 )
142 This macro adds a target called <target_name> for the creation of an
144 API documentation manual in the QCH format from the given sources. It
145 currently uses doxygen, future versions might optionally also allow
146 other tools. Next to the QCH file the target will generate a corre‐
147 sponding doxygen tag file, which enables creating links from other doc‐
148 umentation into the generated QCH file.
149 It is recommended to make the use of this macro optional, by depending
151 the call to ecm_add_qch on a CMake option being set, with a name like
152 BUILD_QCH and being TRUE by default. This will allow the developers to
153 saves resources on normal source development build cycles by setting
154 this option to FALSE.
155 The macro will set the target properties DOXYGEN_TAGFILE, QHP_NAME‐
157 SPACE, QHP_NAMESPACE_VERSIONED, QHP_VIRTUALFOLDER and LINK_QCHS to the
158 respective values, to allow other code access to them, e.g. the macro
159 ecm_install_qch_export. To enable the use of the target <target_name>
160 as item for LINK_QCHS in further ecm_add_qch calls in the current
161 build, additionally a target property DOXYGEN_TAGFILE_BUILD is set,
162 with the path of the created doxygen tag file in the build dir. If ex‐
163 isting, ecm_add_qch will use this property instead of DOXYGEN_TAGFILE
164 for access to the tags file.
165 NAME specifies the name for the generated documentation.
167 VERSION specifies the version of the library for which the documenta‐
169 tion is created.
170 BASE_NAME specifies the base name for the generated files. The default
172 basename is <name>.
173 SOURCE_DIRS specifies the dirs (incl. subdirs) with the source files
175 for which the API documentation should be generated. Dirs can be rela‐
176 tive to the current source dir. Dependencies to the files in the dirs
177 are not tracked currently, other than with the SOURCES argument. So do
178 not use for sources generated during the build. Needs to be used when
179 SOURCES or CONFIG_TEMPLATE are not used.
180 SOURCES specifies the source files for which the API documentation
182 should be generated. Needs to be used when SOURCE_DIRS or CONFIG_TEM‐
183 PLATE are not used.
184 MD_MAINPAGE specifies a file in Markdown format that should be used as
186 main page. This page will overrule any \mainpage command in the in‐
187 cluded sources.
188 INCLUDE_DIRS specifies the dirs which should be searched for included
190 headers. Dirs can be relative to the current source dir. Since 5.63.
191 IMAGE_DIRS specifies the dirs which contain images that are included in
193 the documentation. Dirs can be relative to the current source dir.
194 EXAMPLE_DIRS specifies the dirs which contain examples that are in‐
196 cluded in the documentation. Dirs can be relative to the current source
197 dir.
198 QCH_INSTALL_DESTINATION specifies where the generated QCH file will be
200 installed.
201 TAGFILE_INSTALL_DESTINATION specifies where the generated tag file will
203 be installed.
204 COMPONENT specifies the installation component name with which the in‐
206 stall rules for the generated QCH file and tag file are associated.
207 NAMESPACE can be used to set a custom namespace <namespace> of the gen‐
209 erated QCH file. The namepspace is used as the unique id by QHelpEngine
210 (cmp. https://doc.qt.io/qt-5/qthelpproject.html#namespace). The de‐
211 fault namespace is <domain>.<name>. Needs to be used when ORG_DOMAIN
212 is not used.
213 ORG_DOMAIN can be used to define the organization domain prefix for the
215 default namespace of the generated QCH file. Needs to be used when
216 NAMESPACE is not used.
217 LINK_QCHS specifies a list of other QCH targets which should be used
219 for creating references to API documentation of code in external li‐
220 braries. For each target <qch> in the list these target properties are
221 expected to be defined: DOXYGEN_TAGFILE, QHP_NAMESPACE and QHP_VIRTUAL‐
222 FOLDER. If any of these is not existing, <qch> will be ignored. Use
223 the macro ecm_install_qch_export for exporting a target with these
224 properties with the CMake config of a library. Any target <qch> can
225 also be one created before in the same buildsystem by another call of
226 ecm_add_qch.
227 PREDEFINED_MACROS specifies a list of C/C++ macros which should be han‐
229 dled as given by the API dox generation tool. Examples are macros only
230 defined in generated files, so whose definition might be not available
231 to the tool.
232 BLANK_MACROS specifies a list of C/C++ macro names which should be ig‐
234 nored by the API dox generation tool and handled as if they resolve to
235 empty strings. Examples are export macros only defined in generated
236 files, so whose definition might be not available to the tool.
237 CONFIG_TEMPLATE specifies a custom cmake template file for the config
239 file that is created to control the execution of the API dox generation
240 tool. The following CMake variables need to be used: - ECM_QCH_DOXY‐
241 GEN_QHELPGENERATOR_EXECUTABLE - ECM_QCH_DOXYGEN_FILEPATH, ECM_QCH_DOXY‐
242 GEN_TAGFILE The following CMake variables can be used: - ECM_QCH_DOXY‐
243 GEN_PROJECTNAME - ECM_QCH_DOXYGEN_PROJECTVERSION - ECM_QCH_DOXYGEN_VIR‐
244 TUALFOLDER - ECM_QCH_DOXYGEN_FULLNAMESPACE - ECM_QCH_DOXYGEN_TAGFILES -
245 ECM_QCH_DOXYGEN_WARN_LOGFILE - ECM_QCH_DOXYGEN_QUIET There is no guar‐
246 antue that the other CMake variables currently used in the default con‐
247 fig file template will also be present with the same semantics in fu‐
248 ture versions of this macro.
249 VERBOSE tells the API dox generation tool to be more verbose about its
251 activity.
252 The default config file for the API dox generation tool, so the one
254 when not using CONFIG_TEMPLATE, allows code to handle the case of being
255 processed by the tool by defining the C/C++ preprocessor macro K_DOXY‐
256 GEN when run (since v5.67.0). For backward-compatibility also the defi‐
257 nition DOXYGEN_SHOULD_SKIP_THIS is set, but its usage is deprecated.
258 Example usage:
260 ecm_add_qch(
262 MyLib_QCH
263 NAME MyLib
264 VERSION "0.42.0"
265 ORG_DOMAIN org.myorg
266 SOURCE_DIRS
267 src
268 LINK_QCHS
269 Qt5Core_QCH
270 Qt5Xml_QCH
271 Qt5Gui_QCH
272 Qt5Widgets_QCH
273 BLANK_MACROS
274 MyLib_EXPORT
275 MyLib_DEPRECATED
276 TAGFILE_INSTALL_DESTINATION ${CMAKE_INSTALL_PREFIX}/share/docs/tags
277 QCH_INSTALL_DESTINATION ${CMAKE_INSTALL_PREFIX}/share/docs/qch
278 COMPONENT Devel
279 )
280 Example usage (with two QCH files, second linking first):
282 ecm_add_qch(
284 MyLib_QCH
285 NAME MyLib
286 VERSION ${MyLib_VERSION}
287 ORG_DOMAIN org.myorg
288 SOURCES ${MyLib_PUBLIC_HEADERS}
289 MD_MAINPAGE src/mylib/README.md
290 LINK_QCHS Qt5Core_QCH
291 TAGFILE_INSTALL_DESTINATION ${CMAKE_INSTALL_PREFIX}/share/docs/tags
292 QCH_INSTALL_DESTINATION ${CMAKE_INSTALL_PREFIX}/share/docs/qch
293 COMPONENT Devel
294 )
295 ecm_add_qch(
296 MyOtherLib_QCH
297 NAME MyOtherLib
298 VERSION ${MyOtherLib_VERSION}
299 ORG_DOMAIN org.myorg
300 SOURCES ${MyOtherLib_PUBLIC_HEADERS}
301 MD_MAINPAGE src/myotherlib/README.md
302 LINK_QCHS Qt5Core_QCH MyLib_QCH
303 TAGFILE_INSTALL_DESTINATION ${CMAKE_INSTALL_PREFIX}/share/docs/tags
304 QCH_INSTALL_DESTINATION ${CMAKE_INSTALL_PREFIX}/share/docs/qch
305 COMPONENT Devel
306 )
307 ecm_install_qch_export(
309 TARGETS [<name> [<name2> [...]]]
310 FILE <file>
311 DESTINATION <dest>
312 [COMPONENT <component>]
313 )
314 This macro creates and installs a CMake file <file> which exports the
316 given QCH targets <name> etc., so they can be picked up by CMake-based
317 builds of other software that also generate QCH files (using
318 ecm_add_qch) and which should include links to the QCH files created by
319 the given targets. The installed CMake file <file> is expected to be
320 included by the CMake config file created for the software the related
321 QCH files are documenting.
322 TARGETS specifies the QCH targets which should be exported. If a target
324 does not exist or does not have all needed properties, a warning will
325 be generated and the target skipped. This behaviour might change in
326 future versions to result in a fail instead.
327 FILE specifies the name of the created CMake file, typically with a
329 .cmake extension.
330 DESTINATION specifies the directory on disk to which the file will be
332 installed. It usually is the same as the one where the CMake config
333 files for this software are installed.
334 COMPONENT specifies the installation component name with which the in‐
336 stall rule is associated.
337 Example usage:
339 ecm_install_qch_export(
341 TARGETS MyLib_QCH
342 FILE MyLibQCHTargets.cmake
343 DESTINATION "${CMAKE_INSTALL_PREFIX}/lib/cmake/MyLib"
344 COMPONENT Devel
345 )
346 Since 5.36.0.
348 ECMAddQtDesignerPlugin
350 This module provides the ecm_add_qtdesignerplugin function for generat‐
351 ing Qt Designer plugins for custom widgets. Each of those widgets is
352 described using a second function ecm_qtdesignerplugin_widget.
353 ecm_add_qtdesignerplugin(<target_name>
355 NAME <name>
356 WIDGETS <widgetid> [<widgetid2> [...]]
357 LINK_LIBRARIES <lib> [<lib2> [...]]
358 INSTALL_DESTINATION <install_path>
359 [OUTPUT_NAME <output_name>]
360 [DEFAULT_GROUP <group>]
361 [DEFAULT_HEADER_CASE <SAME_CASE|LOWER_CASE|UPPER_CASE>]
362 [DEFAULT_HEADER_EXTENSION <header_extension>]
363 [DEFAULT_ICON_DIR <icon_dir>]
364 [INCLUDE_FILES <include_file> [<include_file2> [...]]]
365 [SOURCES <src> [<src2> [...]]]
366 [COMPONENT <component>]
367 )
368 NAME specifies the base name to use in the generated sources. The de‐
370 fault is <target_name>.
371 WIDGETS specifies the widgets the plugin should support. Each widget
373 has to be defined before by a call of ecm_qtdesignerplugin_widget with
374 the respective <widgetid>, in a scope including the current call.
375 LINK_LIBRARIES specifies the libraries to link against. This will be at
377 least the library providing the widget class(es).
378 INSTALL_DESTINATION specifies where the generated plugin binary will be
380 installed.
381 OUTPUT_NAME specifies the name of the plugin binary. The default is
383 “<target_name>”.
384 DEFAULT_GROUP specifies the default group in Qt Designer where the wid‐
386 gets will be placed. The default is “Custom”.
387 DEFAULT_HEADER_CASE specifies how the name of the header is derived
389 from the widget class name. The default is “LOWER_CASE”.
390 DEFAULT_HEADER_EXTENSION specifies what file name extension is used for
392 the header file derived from the class name. The default is “h”.
393 DEFAULT_ICON_DIR specifies what file name extension is used for the
395 header file derived from the class name. The default is “pics”.
396 INCLUDE_FILES specifies additional include files to include with the
398 generated source file. This can be needed for custom code used in ini‐
399 tializing or creating widgets.
400 SOURCES specifies additional source files to build the plugin from.
402 This can be needed to support custom code used in initializing or cre‐
403 ating widgets.
404 COMPONENT specifies the installation component name with which the in‐
406 stall rules for the generated plugin are associated.
407 ecm_qtdesignerplugin_widget(<widgetid>
409 [CLASS_NAME <class_name>]
410 [INCLUDE_FILE <include_file>]
411 [CONTAINER]
412 [ICON <iconfile>]
413 [TOOLTIP <tooltip>]
414 [WHATSTHIS <whatsthis>]
415 [GROUP <group>]
416 [CREATE_WIDGET_CODE_FROM_VARIABLE <create_widget_code_variable>]
417 [INITIALIZE_CODE_FROM_VARIABLE <initialize_code_variable]
418 [DOM_XML_FROM_VARIABLE <dom_xml_variable>]
419 [IMPL_CLASS_NAME <impl_class_name>]
420 [CONSTRUCTOR_ARGS_CODE <constructor_args_code>]
421 [CONSTRUCTOR_ARGS_CODE_FROM_VARIABLE <constructor_args_code_variable>]
422 )
423 CLASS_NAME specifies the name of the widget class, including name‐
425 spaces. The default is “<widgetid>”.
426 INCLUDE_FILE specifies the include file to use for the class of this
428 widget. The default is derived from <class_name> as configured by the
429 DEFAULT_HEADER_* options of ecm_add_qtdesignerplugin, also replacing
430 any namespace separators with “/”.
431 CONTAINER specifies, if set, that this widget is a container for other
433 widgets.
434 ICON specifies the icon file to use as symbol for this widget. The de‐
436 fault is “{lowercased <class_name>}.png” in the default icons dir as
437 configured by the DEFAULT_ICON_DIR option of ecm_add_qtdesignerplugin,
438 if such a file exists.
439 TOOLTIP specifies the tooltip text to use for this widget. Default is
441 “<class_name> Widget”.
442 WHATSTHIS specifies the What’s-This text to use for this widget. De‐
444 faults to the tooltip.
445 GROUP specifies the group in Qt Designer where the widget will be
447 placed. The default is set as configured by the DEFAULT_GROUP option
448 of ecm_add_qtdesignerplugin.
449 CREATE_WIDGET_CODE_FROM_VARIABLE specifies the variable to get from the
451 C++ code to use as factory code to create an instance of the widget,
452 for the override of QDesignerCustomWidgetInterface::createWidget(QWid‐
453 get* parent). The default is “return new <impl_class_name><construc‐
454 tor_args_code>;”.
455 INITIALIZE_CODE_FROM_VARIABLE specifies the variable to get from the
457 C++ code to use with the override of QDesignerCustomWidgetInter‐
458 face::initialize(QDesignerFormEditorInterface* core). The code has to
459 use the present class member m_initialized to track and update the
460 state. The default code simply sets m_initialized to true, if it was
461 not before.
462 DOM_XML_FROM_VARIABLE specifies the variable to get from the string to
464 use with the optional override of QDesignerCustomWidgetInter‐
465 face::domXml(). Default does not override.
466 IMPL_CLASS_NAME specifies the name of the widget class to use for the
468 widget instance with Qt Designer. The default is “<class_name>”.
469 CONSTRUCTOR_ARGS_CODE specifies the C++ code to use for the constructor
471 arguments with the default of CREATE_WIDGET_CODE_FROM_VARIABLE. Note
472 that the parentheses are required. The default is “(parent)”.
473 CONSTRUCTOR_ARGS_CODE_FROM_VARIABLE specifies the variable to get from
475 the C++ code instead of passing it directly via CONSTRUCTOR_ARGS_CODE.
476 This can be needed if the code is more complex and e.g. includes “;”
477 chars.
478 Example usage:
480 ecm_qtdesignerplugin_widget(FooWidget
482 TOOLTIP "Enables to browse foo."
483 GROUP "Views (Foo)"
484 )
485 set(BarWidget_CREATE_WIDGET_CODE
487 "
488 auto* widget = new BarWidget(parent);
489 widget->setBar("Example bar");
490 return widget;
491 ")
492 ecm_qtdesignerplugin_widget(BarWidget
494 TOOLTIP "Displays bars."
495 GROUP "Display (Foo)"
496 CREATE_WIDGET_CODE_FROM_VARIABLE BarWidget_CREATE_WIDGET_CODE
497 )
498 ecm_add_qtdesignerplugin(foowidgets
500 NAME FooWidgets
501 OUTPUT_NAME foo2widgets
502 WIDGETS
503 FooWidget
504 BarWidget
505 LINK_LIBRARIES
506 Foo::Widgets
507 INSTALL_DESTINATION "${KDE_INSTALL_QTPLUGINDIR}/designer"
508 COMPONENT Devel
509 )
510 Since 5.62.0.
512 ECMAddTests
514 Convenience functions for adding tests.
515 ecm_add_tests(<sources> LINK_LIBRARIES <library> [<library> [...]]
517 [NAME_PREFIX <prefix>]
518 [GUI]
519 [TARGET_NAMES_VAR <target_names_var>]
520 [TEST_NAMES_VAR <test_names_var>])
521 A convenience function for adding multiple tests, each consisting of a
523 single source file. For each file in <sources>, an executable target
524 will be created (the name of which will be the basename of the source
525 file). This will be linked against the libraries given with LINK_LI‐
526 BRARIES. Each executable will be added as a test with the same name.
527 If NAME_PREFIX is given, this prefix will be prepended to the test
529 names, but not the target names. As a result, it will not prevent
530 clashes between tests with the same name in different parts of the
531 project, but it can be used to give an indication of where to look for
532 a failing test.
533 If the flag GUI is passed the test binaries will be GUI executables,
535 otherwise the resulting binaries will be console applications (regard‐
536 less of the value of CMAKE_WIN32_EXECUTABLE or CMAKE_MACOSX_BUNDLE). Be
537 aware that this changes the executable entry point on Windows (although
538 some frameworks, such as Qt, abstract this difference away).
539 The TARGET_NAMES_VAR and TEST_NAMES_VAR arguments, if given, should
541 specify a variable name to receive the list of generated target and
542 test names, respectively. This makes it convenient to apply properties
543 to them as a whole, for example, using set_target_properties() or
544 set_tests_properties().
545 The generated target executables will have the effects of
547 ecm_mark_as_test() (from the ECMMarkAsTest module) applied to it.
548 ecm_add_test(<sources> LINK_LIBRARIES <library> [<library> [...]]
550 [TEST_NAME <name>]
551 [NAME_PREFIX <prefix>]
552 [GUI])
553 This is a single-test form of ecm_add_tests that allows multiple source
555 files to be used for a single test. If using multiple source files,
556 TEST_NAME must be given; this will be used for both the target and test
557 names (and, as with ecm_add_tests(), the NAME_PREFIX argument will be
558 prepended to the test name).
559 Since pre-1.0.0.
561 ECMCheckOutboundLicense
563 Assert that source file licenses are compatible with a desired outbound
564 license of a compiled binary artifact (e.g., library, plugin or appli‐
565 cation).
566 This module provides the ecm_check_outbound_license function that gen‐
568 erates unit tests for checking the compatibility of license statements.
569 The license statements in all tested files are required to be added by
570 using the SPDX marker SPDX-License-Identifier.
571 During the CMake configuration of the project, a temporary license bill
573 of materials (BOM) in SPDX format is generated by calling the REUSE
574 tool (see <https://reuse.software>). That BOM is parsed and license
575 computations based on an internal compatibility matrix are performed.
576 Preconditions for using this module:
578 • All tested input source files must contain the SPDX-Li‐
580 cense-Identifier tag.
581 • Python3 must be available.
583 • The REUSE tool must be available, which generates the
585 bill-of-materials by running reuse spdx on the tested direc‐
586 tory.
587 When this module is included, a SKIP_LICENSE_TESTS option is added (de‐
589 fault OFF). Turning this option on skips the generation of license
590 tests, which might be convenient if licenses shall not be tested in all
591 build configurations.
592 ecm_check_outbound_license(LICENSES <outbound-licenses>
594 FILES <source-files>
595 [TEST_NAME <name>]
596 [WILL_FAIL])
597 This method adds a custom unit test to ensure the specified outbound
599 license to be compatible with the specified license headers. Note that
600 a convenient way is to use the CMake GLOB command of the FILE function.
601 LICENSES
603 List of one or multiple outbound license regarding which the
604 compatibility.INDENT 7.0
605 of the source code files shall be tested. Currently, the following
606 values
607 are supported (values are SPDX registry identifiers):
609 • MIT
611 • BSD-2-Clause
613 • BSD-3-Clause
615 • LGPL-2.0-only
617 • LGPL-2.1-only
619 • LGPL-3.0-only
621 • GPL-2.0-only
623 • GPL-3.0-only
625 FILES: List of source files that contain valid SPDX-License-Identifier
627 markers. The paths can be relative to the CMake file that gen‐
628 erates the test case or be absolute paths.
629 TEST_NAME
631 Optional parameter that defines the name of the generated test
632 case. If no name is defined, the relative path to the test di‐
633 rectory with appended license name is used. Every test has li‐
634 censecheck_ as prefix.
635 WILL_FAIL
637 Optional parameter that inverts the test result. This parameter
638 is usually only used for tests of the module.
639Since 5.75.0
641 ECMConfiguredInstall
643 Takes a list of files, runs configure_file on each and installs the re‐
644 sultant configured files in the given location.
645 Any suffix of “.in” in the passed file names wil be stripped from the
647 file name at the installed location.
648 ecm_install_configured_files(
650 INPUT <file> [<file2> [...]]
651 DESTINATION <INSTALL_DIRECTORY>
652 [COPYONLY]
653 [ESCAPE_QUOTES]
654 [@ONLY]
655 [COMPONENT <component>])
656 Example usage:
658 ecm_install_configured_files(INPUT foo.txt.in DESTINATION ${KDE_INSTALL_DATADIR} @ONLY)
660 This will install the file as foo.txt with any cmake variable replace‐
662 ments made into the data directory.
663 Since 5.73.0.
665 ECMCoverageOption
667 Allow users to easily enable GCov code coverage support.
668 Code coverage allows you to check how much of your codebase is covered
670 by your tests. This module makes it easy to build with support for
671 GCov.
672 When this module is included, a BUILD_COVERAGE option is added (default
674 OFF). Turning this option on enables GCC’s coverage instrumentation,
675 and links against libgcov.
676 Note that this will probably break the build if you are not using GCC.
678 Since 1.3.0.
680 ECMCreateQmFromPoFiles
682 WARNING:
683 This module is deprecated and will be removed by ECM 1.0. Use ECMPo‐
684 QmTools instead.
685 Generate QTranslator (.qm) catalogs from Gettext (.po) catalogs.
687 ecm_create_qm_from_po_files(PO_FILES <file1>... <fileN>
689 [CATALOG_NAME <catalog_name>]
690 [INSTALL_DESTINATION <install_destination>])
691 Creates the necessary rules to compile .po files into .qm files, and
693 install them.
694 The .qm files are installed in <install_destination>/<lang>/LC_MES‐
696 SAGES, where <install_destination> is the INSTALL_DESTINATION argument
697 and <lang> is extracted from the “Language” field inside the .po file.
698 INSTALL_DESTINATION defaults to ${LOCALE_INSTALL_DIR} if defined, oth‐
700 erwise it uses ${CMAKE_INSTALL_LOCALEDIR} if that is defined, otherwise
701 it uses share/locale.
702 CATALOG_NAME defines the name of the installed .qm files. If set, .qm
704 files will be installed as <catalog_name>.qm. If not set .qm files will
705 be named after the name of their source .po file.
706 Setting the catalog name is useful when all .po files for a target are
708 kept in a single source directory. For example, the “mylib” probject
709 might keep all its translations in a “po” directory, like this:
710 po/
712 es.po
713 fr.po
714 Without setting CATALOG_NAME, those .po will be turned into .qm and in‐
716 stalled as:
717 share/locale/fr/LC_MESSAGES/fr.qm
719 share/locale/es/LC_MESSAGES/es.qm
720 If CATALOG_NAME is set to “mylib”, they will be installed as:
722 share/locale/fr/LC_MESSAGES/mylib.qm
724 share/locale/es/LC_MESSAGES/mylib.qm
725 Which is what the loader created by ecm_create_qm_loader() expects.
727 ecm_create_qm_from_po_files() creates a “translation” target. This tar‐
729 get builds all .po files into .qm files.
730 ecm_create_qm_loader(<source_files_var> <catalog_name>)
732 ecm_create_qm_loader() generates a C++ file which ensures translations
734 are automatically loaded at startup. The path of the .cpp file is ap‐
735 pended to <source_files_var>. Typical usage is like:
736 set(mylib_SRCS foo.cpp bar.cpp)
738 ecm_create_qm_loader(mylib_SRCS mylib)
739 add_library(mylib ${mylib_SRCS})
740 This generates a C++ file which loads “mylib.qm” at startup, assuming
742 it has been installed by ecm_create_qm_from_po_files(), and compiles it
743 into mylib.
744 Since pre-1.0.0.
746 ECMEnableSanitizers
748 Enable compiler sanitizer flags.
749 The following sanitizers are supported:
751 • Address Sanitizer
753 • Memory Sanitizer
755 • Thread Sanitizer
757 • Leak Sanitizer
759 • Undefined Behaviour Sanitizer
761 All of them are implemented in Clang, depending on your version, and
763 there is an work in progress in GCC, where some of them are currently
764 implemented.
765 This module will check your current compiler version to see if it sup‐
767 ports the sanitizers that you want to enable
768 Usage
770 Simply add:
771 include(ECMEnableSanitizers)
773 to your CMakeLists.txt. Note that this module is included in KDECompil‐
775 erSettings, so projects using that module do not need to also include
776 this one.
777 The sanitizers are not enabled by default. Instead, you must set
779 ECM_ENABLE_SANITIZERS (either in your CMakeLists.txt or on the command
780 line) to a semicolon-separated list of sanitizers you wish to enable.
781 The options are:
782 • address
784 • memory
786 • thread
788 • leak
790 • undefined
792 • fuzzer
794 The sanitizers “address”, “memory” and “thread” are mutually exclusive.
796 You cannot enable two of them in the same build.
797 “leak” requires the “address” sanitizer.
799 NOTE:
801 To reduce the overhead induced by the instrumentation of the sani‐
802 tizers, it is advised to enable compiler optimizations (-O1 or
803 higher).
804 Example
806 This is an example of usage:
807 mkdir build
809 cd build
810 cmake -DECM_ENABLE_SANITIZERS='address;leak;undefined' ..
811 NOTE:
813 Most of the sanitizers will require Clang. To enable it, use:
814 -DCMAKE_CXX_COMPILER=clang++
816 Since 1.3.0.
818 ECMFindModuleHelpers
820 Helper macros for find modules: ecm_find_package_version_check(),
821 ecm_find_package_parse_components() and ecm_find_package_handle_li‐
822 brary_components().
823 ecm_find_package_version_check(<name>)
825 Prints warnings if the CMake version or the project’s required CMake
827 version is older than that required by extra-cmake-modules.
828 ecm_find_package_parse_components(<name>
830 RESULT_VAR <variable>
831 KNOWN_COMPONENTS <component1> [<component2> [...]]
832 [SKIP_DEPENDENCY_HANDLING])
833 This macro will populate <variable> with a list of components found in
835 <name>_FIND_COMPONENTS, after checking that all those components are in
836 the list of KNOWN_COMPONENTS; if there are any unknown components, it
837 will print an error or warning (depending on the value of
838 <name>_FIND_REQUIRED) and call return().
839 The order of components in <variable> is guaranteed to match the order
841 they are listed in the KNOWN_COMPONENTS argument.
842 If SKIP_DEPENDENCY_HANDLING is not set, for each component the variable
844 <name>_<component>_component_deps will be checked for dependent compo‐
845 nents. If <component> is listed in <name>_FIND_COMPONENTS, then all
846 its (transitive) dependencies will also be added to <variable>.
847 ecm_find_package_handle_library_components(<name>
849 COMPONENTS <component> [<component> [...]]
850 [SKIP_DEPENDENCY_HANDLING])
851 [SKIP_PKG_CONFIG])
852 Creates an imported library target for each component. The operation
854 of this macro depends on the presence of a number of CMake variables.
855 The <name>_<component>_lib variable should contain the name of this li‐
857 brary, and <name>_<component>_header variable should contain the name
858 of a header file associated with it (whatever relative path is normally
859 passed to ‘#include’). <name>_<component>_header_subdir variable can be
860 used to specify which subdirectory of the include path the headers will
861 be found in. ecm_find_package_components() will then search for the
862 library and include directory (creating appropriate cache variables)
863 and create an imported library target named <name>::<component>.
864 Additional variables can be used to provide additional information:
866 If SKIP_PKG_CONFIG, the <name>_<component>_pkg_config variable is set,
868 and pkg-config is found, the pkg-config module given by <name>_<compo‐
869 nent>_pkg_config will be searched for and used to help locate the li‐
870 brary and header file. It will also be used to set <name>_<compo‐
871 nent>_VERSION.
872 Note that if version information is found via pkg-config, <name>_<com‐
874 ponent>_FIND_VERSION can be set to require a particular version for
875 each component.
876 If SKIP_DEPENDENCY_HANDLING is not set, the INTERFACE_LINK_LIBRARIES
878 property of the imported target for <component> will be set to contain
879 the imported targets for the components listed in <name>_<compo‐
880 nent>_component_deps. <component>_FOUND will also be set to false if
881 any of the compoments in <name>_<component>_component_deps are not
882 found. This requires the components in <name>_<component>_compo‐
883 nent_deps to be listed before <component> in the COMPONENTS argument.
884 The following variables will be set:
886 <name>_TARGETS
888 the imported targets
889 <name>_LIBRARIES
891 the found libraries
892 <name>_INCLUDE_DIRS
894 the combined required include directories for the components
895 <name>_DEFINITIONS
897 the “other” CFLAGS provided by pkg-config, if any
898 <name>_VERSION
900 the value of <name>_<component>_VERSION for the first component
901 that has this variable set (note that components are searched
902 for in the order they are passed to the macro), although if it
903 is already set, it will not be altered
904 Note that these variables are never cleared, so if ecm_find_pack‐
906 age_handle_library_components() is called multiple times with different
907 components (typically because of multiple find_package() calls) then
908 <name>_TARGETS, for example, will contain all the targets found in any
909 call (although no duplicates).
910 Since pre-1.0.0.
912 ECMGenerateDBusServiceFile
914 This module provides the ecm_generate_dbus_service_file function for
915 generating and installing a D-Bus service file.
916 ecm_generate_dbus_service_file(
918 NAME <service name>
919 EXECUTABLE <executable>
920 [SYSTEMD_SERVICE <systemd service>]
921 DESTINATION <install_path>
922 [RENAME <dbus service filename>] # Since 5.75
923 )
924 A D-Bus service file <service name>.service will be generated and in‐
926 stalled in the relevant D-Bus config location. This filename can be
927 customized with RENAME.
928 <executable> must be an absolute path to the installed service exe‐
930 cutable. When using it with KDEInstallDirs it needs to be the _FULL_
931 variant of the path variable.
932 Note: On Windows, the macro will only use the file name part of <exe‐
934 cutable> since D-Bus service executables are to be installed in the
935 same directory as the D-Bus daemon.
936 Optionally, a <systemd service> can be specified to launch the corre‐
938 sponding systemd service instead of the <executable> if the D-Bus dae‐
939 mon is started by systemd.
940 Example usage:
942 ecm_generate_dbus_service_file(
944 NAME org.kde.kded5
945 EXECUTABLE ${KDE_INSTALL_FULL_BINDIR}/kded5
946 DESTINATION ${KDE_INSTALL_DBUSSERVICEDIR}
947 )
948 ecm_generate_dbus_service_file(
950 NAME org.kde.kded5
951 EXECUTABLE ${KDE_INSTALL_FULL_BINDIR}/kded5
952 SYSTEMD_SERVICE plasma-kded.service
953 DESTINATION ${KDE_INSTALL_DBUSSERVICEDIR}
954 RENAME org.kde.daemon.service
955 )
956 Since 5.73.0.
958 ECMGenerateExportHeader
960 This module provides the ecm_generate_export_header function for gener‐
961 ating export macros for libraries with version-based control over visi‐
962 bility of and compiler warnings for deprecated API for the library
963 user, as well as over excluding deprecated API and their implementation
964 when building the library itself.
965 For preparing some values useful in the context it also provides a
967 function ecm_export_header_format_version.
968 ecm_generate_export_header(<library_target_name>
970 VERSION <version>
971 [BASE_NAME <base_name>]
972 [GROUP_BASE_NAME <group_base_name>]
973 [EXPORT_MACRO_NAME <export_macro_name>]
974 [EXPORT_FILE_NAME <export_file_name>]
975 [DEPRECATED_MACRO_NAME <deprecated_macro_name>]
976 [NO_EXPORT_MACRO_NAME <no_export_macro_name>]
977 [INCLUDE_GUARD_NAME <include_guard_name>]
978 [STATIC_DEFINE <static_define>]
979 [PREFIX_NAME <prefix_name>]
980 [DEPRECATED_BASE_VERSION <deprecated_base_version>]
981 [DEPRECATION_VERSIONS <deprecation_version> [<deprecation_version2> [...]]]
982 [EXCLUDE_DEPRECATED_BEFORE_AND_AT <exclude_deprecated_before_and_at_version>]
983 [NO_BUILD_SET_DEPRECATED_WARNINGS_SINCE]
984 [NO_DEFINITION_EXPORT_TO_BUILD_INTERFACE]
985 [CUSTOM_CONTENT_FROM_VARIABLE <variable>]
986 )
987 VERSION specifies the version of the library, given in the format “<ma‐
989 jor>.<minor>.<patchlevel>”.
990 GROUP_BASE_NAME specifies the name to use for the macros defining li‐
992 brary group default values. If set, this will generate code supporting
993 <group_base_name>_NO_DEPRECATED_WARNINGS, <group_base_name>_DIS‐
994 ABLE_DEPRECATED_BEFORE_AND_AT, <group_base_name>_DEPRECATED_WARN‐
995 INGS_SINCE and <group_base_name>_NO_DEPRECATED (see below). If not
996 set, the generated code will ignore any such macros.
997 DEPRECATED_BASE_VERSION specifies the default version before and at
999 which deprecated API is disabled. Possible values are “0”, “CURRENT”
1000 (which resolves to <version>) and a version string in the format “<ma‐
1001 jor>.<minor>.<patchlevel>”. The default is the value of “<exclude_dep‐
1002 recated_before_and_at_version>” if set, or “<major>.0.0”, with <major>
1003 taken from <version>.
1004 DEPRECATION_VERSIONS specifies versions in “<major>.<minor>” format in
1006 which API was declared deprecated. Any version used with the generated
1007 macro <prefix_name><base_name>_DEPRECATED_VERSION(major, minor, text)
1008 or <prefix_name><base_name>_DEPRECATED_VERSION_BELATED(major, minor,
1009 textmajor, textminor, text) needs to be listed here, otherwise the
1010 macro will fail to work.
1011 EXCLUDE_DEPRECATED_BEFORE_AND_AT specifies the version for which all
1013 API deprecated before and at should be excluded from the build com‐
1014 pletely. Possible values are “0” (default), “CURRENT” (which resolves
1015 to <version>) and a version string in the format “<major>.<mi‐
1016 nor>.<patchlevel>”.
1017 NO_BUILD_SET_DEPRECATED_WARNINGS_SINCE specifies that the definition
1019 <prefix_name><uppercase_base_name>_DEPRECATED_WARNINGS_SINCE will not
1020 be set for the library inside its own build, and thus will be defined
1021 by either explicit definition in the build system configuration or by
1022 the default value mechanism (see below). The default is that it is set
1023 for the build, to the version specified by EXCLUDE_DEPRECATED_BE‐
1024 FORE_AND_AT, so no deprecation warnings are done for any own deprecated
1025 API used in the library implementation itself.
1026 NO_DEFINITION_EXPORT_TO_BUILD_INTERFACE specifies that the definition
1028 <prefix_name><uppercase_base_name>_DISABLE_DEPRECATED_BEFORE_AND_AT
1029 will not be set in the public interface of the library inside its own
1030 build, and the same for the definition <prefix_name><upper‐
1031 case_base_name>_DEPRECATED_WARNINGS_SINCE (if not disabled by
1032 NO_BUILD_SET_DEPRECATED_WARNINGS_SINCE already). The default is that
1033 they are set, to the version specified by EXCLUDE_DEPRECATED_BE‐
1034 FORE_AND_AT, so e.g. test and examples part of the project automati‐
1035 cally build against the full API included in the build and without any
1036 deprecation warnings for it.
1037 The function ecm_generate_export_header defines C++ preprocessor macros
1039 in the generated export header, some for use in the sources of the li‐
1040 brary the header is generated for, other for use by projects linking
1041 agsinst the library.
1042 The macros for use in the library C++ sources are these, next to those
1044 also defined by GenerateExportHeader:
1045 <prefix_name><uppercase_base_name>_DEPRECATED_VERSION(major, minor,
1047 text)
1048 to use to conditionally set a <prefix_name><upper‐
1049 case_base_name>_DEPRECATED macro for a class, struct or function
1050 (other elements to be supported in future versions), depending
1051 on the visibility macro flags set (see below)
1052 <prefix_name><uppercase_base_name>_DEPRECATED_VERSION_BELATED(major,
1054 minor, textmajor, textminor, text)
1055 to use to conditionally set a <prefix_name><upper‐
1056 case_base_name>_DEPRECATED macro for a class, struct or function
1057 (other elements to be supported in future versions), depending
1058 on the visibility macro flags set (see below), with major & mi‐
1059 nor applied for the logic and textmajor & textminor for the
1060 warnings message. Useful for retroactive tagging of API for the
1061 compiler without injecting the API into the compiler warning
1062 conditions of already released versions. Since 5.71.
1063 <prefix_name><uppercase_base_name>_ENUMERATOR_DEPRECATED_VERSION(major,
1065 minor, text)
1066 to use to conditionally set a <prefix_name><upper‐
1067 case_base_name>_DEPRECATED macro for an enumerator, depending on
1068 the warnings macro flags set (see below). In builds using C++14
1069 standard or earlier, where enumerator attributes are not yet
1070 supported, the macro will always yield an empty string. With
1071 MSVC it is also always an empty string for now. Since 5.82.
1072 <prefix_name><uppercase_base_name>_ENUMERATOR_DEPRECATED_VERSION_BE‐
1074 LATED(major, minor, textmajor, textminor, 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), with major & minor ap‐
1078 plied for the logic and textmajor & textminor for the warnings
1079 message. In builds using C++14 standard or earlier, where enu‐
1080 merator attributes are not yet supported, the macro will always
1081 yield an empty string. Useful for retroactive tagging of API
1082 for the compiler without injecting the API into the compiler
1083 warning conditions of already released versions. With MSVC it
1084 is also always an empty string for now. Since 5.82.
1085 <prefix_name><uppercase_base_name>_ENABLE_DEPRECATED_SINCE(major, mi‐
1087 nor)
1088 evaluates to TRUE or FALSE depending on the visibility macro
1089 flags set (see below). To be used mainly with #if/#endif to mark
1090 sections of code which should be included depending on the visi‐
1091 bility requested.
1092 <prefix_name><uppercase_base_name>_BUILD_DEPRECATED_SINCE(major, minor)
1094 evaluates to TRUE or FALSE depending on the value of EX‐
1095 CLUDE_DEPRECATED_BEFORE_AND_AT. To be used mainly with #if/#en‐
1096 dif to mark sections of two types of code: implementation code
1097 for deprecated API and declaration code of deprecated API which
1098 only may be disabled at build time of the library for BC reasons
1099 (e.g. virtual methods, see notes below).
1100 <prefix_name><uppercase_base_name>_EXCLUDE_DEPRECATED_BEFORE_AND_AT
1102 holds the version used to exclude deprecated API at build time
1103 of the library.
1104 The macros used to control visibility when building against the library
1106 are:
1107 <prefix_name><uppercase_base_name>_DISABLE_DEPRECATED_BEFORE_AND_AT
1109 definition to set to a value in single hex number version nota‐
1110 tion (0x<major><minor><patchlevel>).
1111 <prefix_name><uppercase_base_name>_NO_DEPRECATED
1113 flag to define to disable all deprecated API, being a shortcut
1114 for settings <prefix_name><uppercase_base_name>_DISABLE_DEPRE‐
1115 CATED_BEFORE_AND_AT to the current version. If both are set,
1116 this flag overrules.
1117 <prefix_name><uppercase_base_name>_DEPRECATED_WARNINGS_SINCE
1119 definition to set to a value in single hex number version nota‐
1120 tion (0x<major><minor><patchlevel>). Warnings will be only acti‐
1121 vated for API deprecated up to and including the version. If
1122 <prefix_name><uppercase_base_name>_DISABLE_DEPRECATED_BE‐
1123 FORE_AND_AT is set (directly or via the group default), it will
1124 default to that version, resulting in no warnings. Otherwise the
1125 default is the current version, resulting in warnings for all
1126 deprecated API.
1127 <prefix_name><uppercase_base_name>_NO_DEPRECATED_WARNINGS
1129 flag to define to disable all deprecation warnings, being a
1130 shortcut for setting <prefix_name><uppercase_base_name>_DEPRE‐
1131 CATED_WARNINGS_SINCE to “0”. If both are set, this flag over‐
1132 rules.
1133 When the GROUP_BASE_NAME has been used, the same macros but with the
1135 given <group_base_name> prefix are available to define the defaults of
1136 these macros, if not explicitly set.
1137 Note: The tricks applied here for hiding deprecated API to the compiler
1139 when building against a library do not work for all deprecated API:
1140 • virtual methods need to stay visible to the compiler to build proper
1142 virtual method tables for subclasses
1143 • enumerators from enums cannot be simply removed, as this changes auto
1145 values of following enumerators, also can poke holes in enumerator
1146 series used as index into tables
1147 In such cases the API can be only “hidden” at build time of the li‐
1149 brary, itself, by generated hard coded macro settings, using <pre‐
1150 fix_name><uppercase_base_name>_BUILD_DEPRECATED_SINCE(major, minor).
1151 Examples:
1153 Preparing a library “Foo” created by target “foo”, which is part of a
1155 group of libraries “Bar”, where some API of “Foo” got deprecated at
1156 versions 5.0 & 5.12:
1157 ecm_generate_export_header(foo
1159 GROUP_BASE_NAME BAR
1160 VERSION ${FOO_VERSION}
1161 DEPRECATION_VERSIONS 5.0 5.12
1162 )
1163 In the library “Foo” sources in the headers the API would be prepared
1165 like this, using the generated macros FOO_ENABLE_DEPRECATED_SINCE and
1166 FOO_DEPRECATED_VERSION:
1167 #include <foo_export.h>
1169 #if FOO_ENABLE_DEPRECATED_SINCE(5, 0)
1171 /**
1172 * @deprecated Since 5.0
1173 */
1174 FOO_DEPRECATED_VERSION(5, 0, "Use doFoo2()")
1175 FOO_EXPORT void doFoo();
1176 #endif
1177 #if FOO_ENABLE_DEPRECATED_SINCE(5, 12)
1179 /**
1180 * @deprecated Since 5.12
1181 */
1182 FOO_DEPRECATED_VERSION(5, 12, "Use doBar2()")
1183 FOO_EXPORT void doBar();
1184 #endif
1185 Projects linking against the “Foo” library can control which part of
1187 its deprecated API should be hidden to the compiler by adding a defini‐
1188 tion using the FOO_DISABLE_DEPRECATED_BEFORE_AND_AT macro variable set
1189 to the desired value (in version hex number notation):
1190 add_definitions(-DFOO_DISABLE_DEPRECATED_BEFORE_AND_AT=0x050000)
1192 Or using the macro variable of the group:
1194 add_definitions(-DBAR_DISABLE_DEPRECATED_BEFORE_AND_AT=0x050000)
1196 If both are specified, FOO_DISABLE_DEPRECATED_BEFORE_AND_AT will take
1198 precedence.
1199 To build a variant of a library with some deprecated API completely
1201 left out from the build, not only optionally invisible to consumers,
1202 one uses the EXCLUDE_DEPRECATED_BEFORE_AND_AT parameter. This is best
1203 combined with a cached CMake variable.
1204 set(EXCLUDE_DEPRECATED_BEFORE_AND_AT 0 CACHE STRING "Control the range of deprecated API excluded from the build [default=0].")
1206 ecm_generate_export_header(foo
1208 VERSION ${FOO_VERSION}
1209 EXCLUDE_DEPRECATED_BEFORE_AND_AT ${EXCLUDE_DEPRECATED_BEFORE_AND_AT}
1210 DEPRECATION_VERSIONS 5.0 5.12
1211 )
1212 The macros used in the headers for library consumers are reused for
1214 disabling the API excluded in the build of the library. For disabling
1215 the implementation of that API as well as for disabling deprecated API
1216 which only can be disabled at build time of the library for BC reasons,
1217 one uses the generated macro FOO_BUILD_DEPRECATED_SINCE, like this:
1218 #include <foo_export.h>
1220 enum Bars {
1222 One,
1223 #if FOO_BUILD_DEPRECATED_SINCE(5, 0)
1224 Two FOO_ENUMERATOR_DEPRECATED_VERSION(5, 0, "Use Three"), // macro available since 5.82
1225 #endif
1226 Three,
1227 };
1228 #if FOO_ENABLE_DEPRECATED_SINCE(5, 0)
1230 /**
1231 * @deprecated Since 5.0
1232 */
1233 FOO_DEPRECATED_VERSION(5, 0, "Use doFoo2()")
1234 FOO_EXPORT void doFoo();
1235 #endif
1236 #if FOO_ENABLE_DEPRECATED_SINCE(5, 12)
1238 /**
1239 * @deprecated Since 5.12
1240 */
1241 FOO_DEPRECATED_VERSION(5, 12, "Use doBar2()")
1242 FOO_EXPORT void doBar();
1243 #endif
1244 class FOO_EXPORT Foo {
1246 public:
1247 #if FOO_BUILD_DEPRECATED_SINCE(5, 0)
1248 /**
1249 * @deprecated Since 5.0
1250 */
1251 FOO_DEPRECATED_VERSION(5, 0, "Feature removed")
1252 virtual void doWhat();
1253 #endif
1254 };
1255 #if FOO_BUILD_DEPRECATED_SINCE(5, 0)
1257 void doFoo()
1258 {
1259 // [...]
1260 }
1261 #endif
1262 #if FOO_BUILD_DEPRECATED_SINCE(5, 12)
1264 void doBar()
1265 {
1266 // [...]
1267 }
1268 #endif
1269 #if FOO_BUILD_DEPRECATED_SINCE(5, 0)
1271 void Foo::doWhat()
1272 {
1273 // [...]
1274 }
1275 #endif
1276 So e.g. if EXCLUDE_DEPRECATED_BEFORE_AND_AT is set to “5.0.0”, the enu‐
1278 merator Two as well as the methods ::doFoo() and Foo::doWhat() will be
1279 not available to library consumers. The methods will not have been com‐
1280 piled into the library binary, and the declarations will be hidden to
1281 the compiler, FOO_DISABLE_DEPRECATED_BEFORE_AND_AT also cannot be used
1282 to reactivate them.
1283 When using the NO_DEFINITION_EXPORT_TO_BUILD_INTERFACE and the project
1285 for the “Foo” library includes also tests and examples linking against
1286 the library and using deprecated API (like tests covering it), one bet‐
1287 ter explicitly sets FOO_DISABLE_DEPRECATED_BEFORE_AND_AT for those tar‐
1288 gets to the version before and at which all deprecated API has been ex‐
1289 cluded from the build. Even more when building against other libraries
1290 from the same group “Bar” and disabling some deprecated API of those
1291 libraries using the group macro BAR_DISABLE_DEPRECATED_BEFORE_AND_AT,
1292 which also works as default for FOO_DISABLE_DEPRECATED_BEFORE_AND_AT.
1293 To get the hex number style value the helper macro ecm_ex‐
1295 port_header_format_version() will be used:
1296 set(EXCLUDE_DEPRECATED_BEFORE_AND_AT 0 CACHE STRING "Control what part of deprecated API is excluded from build [default=0].")
1298 ecm_generate_export_header(foo
1300 VERSION ${FOO_VERSION}
1301 GROUP_BASE_NAME BAR
1302 EXCLUDE_DEPRECATED_BEFORE_AND_AT ${EXCLUDE_DEPRECATED_BEFORE_AND_AT}
1303 NO_DEFINITION_EXPORT_TO_BUILD_INTERFACE
1304 DEPRECATION_VERSIONS 5.0 5.12
1305 )
1306 ecm_export_header_format_version(${EXCLUDE_DEPRECATED_BEFORE_AND_AT}
1308 CURRENT_VERSION ${FOO_VERSION}
1309 HEXNUMBER_VAR foo_no_deprecated_before_and_at
1310 )
1311 # disable all deprecated API up to 5.9.0 from all other libs of group "BAR" that we use ourselves
1313 add_definitions(-DBAR_DISABLE_DEPRECATED_BEFORE_AND_AT=0x050900)
1314 add_executable(app app.cpp)
1316 target_link_libraries(app foo)
1317 target_compile_definitions(app
1318 PRIVATE "FOO_DISABLE_DEPRECATED_BEFORE_AND_AT=${foo_no_deprecated_before_and_at}")
1319 Since 5.64.0.
1321 ECMGenerateHeaders
1323 Generate C/C++ CamelCase forwarding headers.
1324 ecm_generate_headers(<camelcase_forwarding_headers_var>
1326 HEADER_NAMES <CamelCaseName> [<CamelCaseName> [...]]
1327 [ORIGINAL <CAMELCASE|LOWERCASE>]
1328 [HEADER_EXTENSION <header_extension>]
1329 [OUTPUT_DIR <output_dir>]
1330 [PREFIX <prefix>]
1331 [REQUIRED_HEADERS <variable>]
1332 [COMMON_HEADER <HeaderName>]
1333 [RELATIVE <relative_path>])
1334 For each CamelCase header name passed to HEADER_NAMES, a file of that
1336 name will be generated that will include a version with .h or, if set,
1337 .<header_extension> appended. For example, the generated header ClassA
1338 will include classa.h (or ClassA.h, see ORIGINAL). If a CamelCaseName
1339 consists of multiple comma-separated files, e.g. ClassA,ClassB,ClassC,
1340 then multiple camelcase header files will be generated which are redi‐
1341 rects to the first header file. The file locations of these generated
1342 headers will be stored in <camelcase_forwarding_headers_var>.
1343 ORIGINAL specifies how the name of the original header is written: low‐
1345 ercased or also camelcased. The default is LOWERCASE. Since 1.8.0.
1346 HEADER_EXTENSION specifies what file name extension is used for the
1348 header files. The default is “h”. Since 5.48.0.
1349 PREFIX places the generated headers in subdirectories. This should be
1351 a CamelCase name like KParts, which will cause the CamelCase forwarding
1352 headers to be placed in the KParts directory (e.g. KParts/Part). It
1353 will also, for the convenience of code in the source distribution, gen‐
1354 erate forwarding headers based on the original names (e.g.
1355 kparts/part.h). This allows includes like "#include <kparts/part.h>"
1356 to be used before installation, as long as the include_directories are
1357 set appropriately.
1358 OUTPUT_DIR specifies where the files will be generated; this should be
1360 within the build directory. By default, ${CMAKE_CURRENT_BINARY_DIR}
1361 will be used. This option can be used to avoid file conflicts.
1362 REQUIRED_HEADERS specifies an output variable name where all the re‐
1364 quired headers will be appended so that they can be installed together
1365 with the generated ones. This is mostly intended as a convenience so
1366 that adding a new header to a project only requires specifying the
1367 CamelCase variant in the CMakeLists.txt file; the original variant will
1368 then be added to this variable.
1369 COMMON_HEADER generates an additional convenience header which includes
1371 all other header files.
1372 The RELATIVE argument indicates where the original headers can be found
1374 relative to CMAKE_CURRENT_SOURCE_DIR. It does not affect the generated
1375 CamelCase forwarding files, but ecm_generate_headers() uses it when
1376 checking that the original header exists, and to generate originally
1377 named forwarding headers when PREFIX is set.
1378 To allow other parts of the source distribution (eg: tests) to use the
1380 generated headers before installation, it may be desirable to set the
1381 INCLUDE_DIRECTORIES property for the library target to output_dir. For
1382 example, if OUTPUT_DIR is CMAKE_CURRENT_BINARY_DIR (the default), you
1383 could do
1384 target_include_directories(MyLib PUBLIC "$<BUILD_INTERFACE:${CMAKE_CURRENT_BINARY_DIR}>")
1386 Example usage (without PREFIX):
1388 ecm_generate_headers(
1390 MyLib_FORWARDING_HEADERS
1391 HEADERS
1392 MLFoo
1393 MLBar
1394 # etc
1395 REQUIRED_HEADERS MyLib_HEADERS
1396 COMMON_HEADER MLGeneral
1397 )
1398 install(FILES ${MyLib_FORWARDING_HEADERS} ${MyLib_HEADERS}
1399 DESTINATION ${CMAKE_INSTALL_PREFIX}/include
1400 COMPONENT Devel)
1401 Example usage (with PREFIX):
1403 ecm_generate_headers(
1405 MyLib_FORWARDING_HEADERS
1406 HEADERS
1407 Foo
1408 # several classes are contained in bar.h, so generate
1409 # additional files
1410 Bar,BarList
1411 # etc
1412 PREFIX MyLib
1413 REQUIRED_HEADERS MyLib_HEADERS
1414 )
1415 install(FILES ${MyLib_FORWARDING_HEADERS}
1416 DESTINATION ${CMAKE_INSTALL_PREFIX}/include/MyLib
1417 COMPONENT Devel)
1418 install(FILES ${MyLib_HEADERS}
1419 DESTINATION ${CMAKE_INSTALL_PREFIX}/include/mylib
1420 COMPONENT Devel)
1421 Since pre-1.0.0.
1423 ECMGeneratePkgConfigFile
1425 Generate a pkg-config file for the benefit of autotools-based projects.
1426 ecm_generate_pkgconfig_file(BASE_NAME <baseName>
1428 [LIB_NAME <libName>]
1429 [DEPS "<dep> [<dep> [...]]"]
1430 [FILENAME_VAR <filename_variable>]
1431 [INCLUDE_INSTALL_DIR <dir>]
1432 [LIB_INSTALL_DIR <dir>]
1433 [DEFINES -D<variable=value>...]
1434 [DESCRIPTION <library description>] # since 5.41.0
1435 [INSTALL])
1436 BASE_NAME is the name of the module. It’s the name projects will use to
1438 find the module.
1439 LIB_NAME is the name of the library that is being exported. If unde‐
1441 fined, it will default to the BASE_NAME. That means the LIB_NAME will
1442 be set as the name field as well as the library to link to.
1443 FILENAME_VAR is specified with a variable name. This variable will re‐
1445 ceive the location of the generated file will be set, within the build
1446 directory. This way it can be used in case some processing is required.
1447 See also INSTALL.
1448 INCLUDE_INSTALL_DIR specifies where the includes will be installed. If
1450 it’s not specified, it will default to INSTALL_INCLUDEDIR, CMAKE_IN‐
1451 STALL_INCLUDEDIR or just “include/” in case they are specified, with
1452 the BASE_NAME postfixed.
1453 LIB_INSTALL_DIR specifies where the library is being installed. If it’s
1455 not specified, it will default to LIB_INSTALL_DIR, CMAKE_INSTALL_LIBDIR
1456 or just “lib/” in case they are specified.
1457 DEFINES is a list of preprocessor defines that it is recommended users
1459 of the library pass to the compiler when using it.
1460 DESCRIPTION describes what this library is. If it’s not specified,
1462 CMake will first try to get the description from the metainfo.yaml file
1463 or will create one based on LIB_NAME. Since 5.41.0.
1464 INSTALL will cause the module to be installed to the pkgconfig subdi‐
1466 rectory of LIB_INSTALL_DIR, unless the ECM_PKGCONFIG_INSTALL_DIR cache
1467 variable is set to something different. Note that the first call to
1468 ecm_generate_pkgconfig_file with the INSTALL argument will cause
1469 ECM_PKGCONFIG_INSTALL_DIR to be set to the cache, and will be used in
1470 any subsequent calls.
1471 To properly use this macro a version needs to be set. To retrieve it,
1473 ECM_PKGCONFIG_INSTALL_DIR uses PROJECT_VERSION. To set it, use the
1474 project() command (only available since CMake 3.0) or the
1475 ecm_setup_version() macro.
1476 Example usage:
1478 ecm_generate_pkgconfig_file(
1480 BASE_NAME KF5Archive
1481 DEPS Qt5Core
1482 FILENAME_VAR pkgconfig_filename
1483 INSTALL
1484 )
1485 Since 1.3.0.
1487 ECMGeneratePriFile
1489 Generate a .pri file for the benefit of qmake-based projects.
1490 As well as the function below, this module creates the cache variable
1492 ECM_MKSPECS_INSTALL_DIR and sets the default value to mkspecs/modules.
1493 This assumes Qt and the current project are both installed to the same
1494 non-system prefix. Packagers who use -DCMAKE_INSTALL_PREFIX=/usr will
1495 certainly want to set ECM_MKSPECS_INSTALL_DIR to something like
1496 share/qt5/mkspecs/modules.
1497 The main thing is that this should be the modules subdirectory of ei‐
1499 ther the default qmake mkspecs directory or of a directory that will be
1500 in the $QMAKEPATH environment variable when qmake is run.
1501 ecm_generate_pri_file(BASE_NAME <baseName>
1503 LIB_NAME <libName>
1504 [DEPS "<dep> [<dep> [...]]"]
1505 [FILENAME_VAR <filename_variable>]
1506 [INCLUDE_INSTALL_DIR <dir>]
1507 [LIB_INSTALL_DIR <dir>])
1508 If your CMake project produces a Qt-based library, you may expect there
1510 to be applications that wish to use it that use a qmake-based build
1511 system, rather than a CMake-based one. Creating a .pri file will make
1512 use of your library convenient for them, in much the same way that
1513 CMake config files make things convenient for CMake-based applications.
1514 ecm_generate_pri_file() generates just such a file. It requires the
1516 PROJECT_VERSION_STRING variable to be set. This is typically set by
1517 ECMSetupVersion, although the project() command in CMake 3.0.0 and
1518 later can also set this.
1519 BASE_NAME specifies the name qmake project (.pro) files should use to
1521 refer to the library (eg: KArchive). LIB_NAME is the name of the ac‐
1522 tual library to link to (ie: the first argument to add_library()).
1523 DEPS is a space-separated list of the base names of other libraries
1524 (for Qt libraries, use the same names you use with the QT variable in a
1525 qmake project file, such as “core” for QtCore). FILENAME_VAR specifies
1526 the name of a variable to store the path to the generated file in.
1527 INCLUDE_INSTALL_DIR is the path (relative to CMAKE_INSTALL_PREFIX) that
1529 include files will be installed to. It defaults to ${INCLUDE_IN‐
1530 STALL_DIR}/<baseName> if the INCLUDE_INSTALL_DIR variable is set. If
1531 that variable is not set, the CMAKE_INSTALL_INCLUDEDIR variable is used
1532 instead, and if neither are set include is used. LIB_INSTALL_DIR oper‐
1533 ates similarly for the installation location for libraries; it defaults
1534 to ${LIB_INSTALL_DIR}, ${CMAKE_INSTALL_LIBDIR} or lib, in that order.
1535 Example usage:
1537 ecm_generate_pri_file(
1539 BASE_NAME KArchive
1540 LIB_NAME KF5KArchive
1541 DEPS "core"
1542 FILENAME_VAR pri_filename
1543 )
1544 install(FILES ${pri_filename} DESTINATION ${ECM_MKSPECS_INSTALL_DIR})
1545 A qmake-based project that wished to use this would then do:
1547 QT += KArchive
1549 in their .pro file.
1551 Since pre-1.0.0.
1553 ECMGenerateQmlTypes
1555 Generates plugins.qmltypes files for QML plugins.
1556 ecm_generate_qmltypes(<org.kde.pluginname> 1.3
1558 DESTINATION <${KDE_INSTALL_QMLDIR}/org/kde/pluginname>)
1559 Makes it possible to generate plugins.qmltypes files for the QML plug‐
1561 ins that our project offers. These files offer introspection upon our
1562 plugin and are useful for integrating with IDE language support of our
1563 plugin. It offers information about the objects its methods and their
1564 argument types.
1565 The developer will be in charge of making sure that these files are up
1567 to date. The plugin.qmltypes file will sit in the source directory.
1568 This function will include the code that installs the file in the right
1569 place and a small unit test named qmltypes-pluginname-version that
1570 makes sure that it doesn’t need updating.
1571 Since 5.33.0
1573 ECMInstallIcons
1575 Installs icons, sorting them into the correct directories according to
1576 the FreeDesktop.org icon naming specification.
1577 ecm_install_icons(ICONS <icon> [<icon> [...]]
1579 DESTINATION <icon_install_dir>
1580 [LANG <l10n_code>]
1581 [THEME <theme>])
1582 The given icons, whose names must match the pattern:
1584 <size>-<group>-<name>.<ext>
1586 will be installed to the appropriate subdirectory of DESTINATION ac‐
1588 cording to the FreeDesktop.org icon naming scheme. By default, they are
1589 installed to the “hicolor” theme, but this can be changed using the
1590 THEME argument. If the icons are localized, the LANG argument can be
1591 used to install them in a locale-specific directory.
1592 <size> is a numeric pixel size (typically 16, 22, 32, 48, 64, 128 or
1594 256) or sc for scalable (SVG) files, <group> is one of the standard
1595 FreeDesktop.org icon groups (actions, animations, apps, categories, de‐
1596 vices, emblems, emotes, intl, mimetypes, places, status) and <ext> is
1597 one of .png, .mng or .svgz.
1598 The typical installation directory is share/icons.
1600 ecm_install_icons(ICONS 22-actions-menu_new.png
1602 DESTINATION share/icons)
1603 The above code will install the file 22-actions-menu_new.png as
1605 ${CMAKE_INSTALL_PREFIX}/share/icons/<theme>/22x22/actions/menu_new.png
1606 Users of the KDEInstallDirs module would normally use ${KDE_IN‐
1608 STALL_ICONDIR} as the DESTINATION, while users of the GNUInstallDirs
1609 module should use ${CMAKE_INSTALL_DATAROOTDIR}/icons.
1610 An old form of arguments will also be accepted:
1612 ecm_install_icons(<icon_install_dir> [<l10n_code>])
1614 This matches files named like:
1616 <theme><size>-<group>-<name>.<ext>
1618 where <theme> is one of
1620 • hi for hicolor
1622 • lo for locolor
1624 • cr for the Crystal icon theme
1626 • ox for the Oxygen icon theme
1628 • br for the Breeze icon theme
1630 With this syntax, the file hi22-actions-menu_new.png would be installed
1632 into <icon_install_dir>/hicolor/22x22/actions/menu_new.png
1633 Since pre-1.0.0.
1635 ECMMarkAsTest
1637 Marks a target as only being required for tests.
1638 ecm_mark_as_test(<target1> [<target2> [...]])
1640 This will cause the specified targets to not be built unless either
1642 BUILD_TESTING is set to ON or the user invokes the buildtests target.
1643 BUILD_TESTING is created as a cache variable by the CTest module and by
1645 the KDECMakeSettings module.
1646 Since pre-1.0.0.
1648 ECMMarkNonGuiExecutable
1650 Marks an executable target as not being a GUI application.
1651 ecm_mark_nongui_executable(<target1> [<target2> [...]])
1653 This will indicate to CMake that the specified targets should not be
1655 included in a MACOSX_BUNDLE and should not be WIN32_EXECUTABLEs. On
1656 platforms other than MacOS X or Windows, this will have no effect.
1657 Since pre-1.0.0.
1659 ECMOptionalAddSubdirectory
1661 Make subdirectories optional.
1662 ecm_optional_add_subdirectory(<dir>)
1664 This behaves like add_subdirectory(), except that it does not complain
1666 if the directory does not exist. Additionally, if the directory does
1667 exist, it creates an option to allow the user to skip it. The option
1668 will be named BUILD_<dir>.
1669 This is useful for “meta-projects” that combine several mostly-indepen‐
1671 dent sub-projects.
1672 If the CMake variable DISABLE_ALL_OPTIONAL_SUBDIRECTORIES is set to
1674 TRUE for the first CMake run on the project, all optional subdirecto‐
1675 ries will be disabled by default (but can of course be enabled via the
1676 respective options). For example, the following will disable all op‐
1677 tional subdirectories except the one named “foo”:
1678 cmake -DDISABLE_ALL_OPTIONAL_SUBDIRECTORIES=TRUE -DBUILD_foo=TRUE myproject
1680 Since pre-1.0.0.
1682 ECMPackageConfigHelpers
1684 Helper macros for generating CMake package config files.
1685 write_basic_package_version_file() is the same as the one provided by
1687 the CMakePackageConfigHelpers module in CMake; see that module’s docu‐
1688 mentation for more information.
1689 ecm_configure_package_config_file(<input> <output>
1691 INSTALL_DESTINATION <path>
1692 [PATH_VARS <var1> [<var2> [...]]
1693 [NO_SET_AND_CHECK_MACRO]
1694 [NO_CHECK_REQUIRED_COMPONENTS_MACRO])
1695 This behaves in the same way as configure_package_config_file() from
1697 CMake 2.8.12, except that it adds an extra helper macro: find_depen‐
1698 dency(). It is highly recommended that you read the documentation for
1699 CMakePackageConfigHelpers for more information, particularly with re‐
1700 gard to the PATH_VARS argument.
1701 Note that there is no argument that will disable the find_dependency()
1703 macro; if you do not require this macro, you should use configure_pack‐
1704 age_config_file from the CMakePackageConfigHelpers module.
1705 CMake 3.0 includes a CMakeFindDependencyMacro module that provides the
1707 find_dependency() macro (which you can include() in your package config
1708 file), so this file is only useful for projects wishing to provide con‐
1709 fig files that will work with CMake 2.8.12.
1710 Additional Config File Macros
1712 find_dependency(<dep> [<version> [EXACT]])
1713 find_dependency() should be used instead of find_package() to find
1715 package dependencies. It forwards the correct parameters for EXACT,
1716 QUIET and REQUIRED which were passed to the original find_package()
1717 call. It also sets an informative diagnostic message if the dependency
1718 could not be found.
1719 Since pre-1.0.0.
1721 ECMPoQmTools
1723 This module provides the ecm_process_po_files_as_qm and ecm_in‐
1724 stall_po_files_as_qm functions for generating QTranslator (.qm) cata‐
1725 logs from Gettext (.po) catalogs, and the ecm_create_qm_loader function
1726 for generating the necessary code to load them in a Qt application or
1727 library.
1728 ecm_process_po_files_as_qm(<lang> [ALL]
1730 [INSTALL_DESTINATION <install_destination>]
1731 PO_FILES <pofile> [<pofile> [...]])
1732 Compile .po files into .qm files for the given language.
1734 If INSTALL_DESTINATION is given, the .qm files are installed in <in‐
1736 stall_destination>/<lang>/LC_MESSAGES. Typically, <install_destination>
1737 is set to share/locale.
1738 ecm_process_po_files_as_qm creates a “translations” target. This target
1740 builds all .po files into .qm files. If ALL is specified, these rules
1741 are added to the “all” target (and so the .qm files will be built by
1742 default).
1743 ecm_create_qm_loader(<source_files_var> <catalog_name>)
1745 Generates C++ code which ensures translations are automatically loaded
1747 at startup. The generated files are appended to <source_files_var>.
1748 It assumes that the .qm file for the language code <lang> is installed
1750 as <sharedir>/locale/<lang>/LC_MESSAGES/<catalog_name>.qm, where
1751 <sharedir> is one of the directories given by the GenericDataLocation
1752 of QStandardPaths.
1753 Typical usage is like:
1755 set(mylib_SRCS foo.cpp bar.cpp)
1757 ecm_create_qm_loader(mylib_SRCS mylib)
1758 add_library(mylib ${mylib_SRCS})
1759 ecm_install_po_files_as_qm(<podir>)
1761 Searches for .po files and installs them to the standard location.
1763 This is a convenience function which relies on all .po files being kept
1765 in <podir>/<lang>/, where <lang> is the language the .po files are
1766 written in.
1767 For example, given the following directory structure:
1769 po/
1771 fr/
1772 mylib.po
1773 ecm_install_po_files_as_qm(po) compiles mylib.po into mylib.qm and in‐
1775 stalls it in <install_destination>/fr/LC_MESSAGES. <install_destina‐
1776 tion> defaults to ${LOCALE_INSTALL_DIR} if defined, otherwise it uses
1777 ${CMAKE_INSTALL_LOCALEDIR} if that is defined, otherwise it uses
1778 share/locale.
1779 Since pre-1.0.0.
1781 ECMQMLModules
1783 Find QML import modules through a find_qmlmodule() call. It uses the
1784 qmlplugindump application to find the plugins and sets them up as run‐
1785 time dependencies.
1786 This is useful so that when we configure a project we are noified when
1788 some QML imports are not present in the system, thus having the appli‐
1789 cation compilable but fail at runtime.
1790 ecm_find_qmlmodule(<module_name> <version>...)
1792 Any further arguments passed will be forwarded into a find_package()
1794 call. See find_package() documentation for more information.
1795 Usage example:
1797 ecm_find_qmlmodule(org.kde.kirigami 2.1)
1799 Since 5.38.0.
1801 ECMQtDeclareLoggingCategory
1803 This module provides the ecm_qt_declare_logging_category function for
1804 generating declarations for logging categories in Qt5, and the
1805 ecm_qt_install_logging_categories function for generating and in‐
1806 stalling a file in KDebugSettings format with the info about all those
1807 categories, as well as a file with info about any renamed categories if
1808 defined. To include in that file any logging categories that are manu‐
1809 ally defined also a function ecm_qt_export_logging_category is pro‐
1810 vided.
1811 ecm_qt_declare_logging_category(<sources_var_name(|target (since 5.80))>
1813 HEADER <filename>
1814 IDENTIFIER <identifier>
1815 CATEGORY_NAME <category_name>
1816 [OLD_CATEGORY_NAMES <oldest_cat_name> [<second_oldest_cat_name> [...]]]
1817 [DEFAULT_SEVERITY <Debug|Info|Warning|Critical|Fatal>]
1818 [EXPORT <exportid>]
1819 [DESCRIPTION <description>]
1820 )
1821 A header file, <filename>, will be generated along with a corresponding
1823 source file. These will provide a QLoggingCategory category that can be
1824 referred to from C++ code using <identifier>, and from the logging con‐
1825 figuration using <category_name>.
1826 The generated source file will be added to the variable with the name
1828 <sources_var_name>. If the given argument is a target though, instead
1829 both the generated header file and the generated source file will be
1830 added to the target as private sources (since 5.80).
1831 If <filename> is not absolute, it will be taken relative to the current
1833 binary directory.
1834 If the code is compiled against Qt 5.4 or later, by default it will
1836 only log output that is at least the severity specified by DE‐
1837 FAULT_SEVERITY, or “Info” level if DEFAULT_SEVERITY is not given. Note
1838 that, due to a bug in Qt 5.5, “Info” may be treated as more severe than
1839 “Fatal”.
1840 <identifier> may include namespaces (eg: foo::bar::IDENT).
1842 If EXPORT is passed, the category will be registered for the group id
1844 <exportid>. Info about the categories of that group can then be gener‐
1845 ated in a file and installed by that group id with the ecm_qt_in‐
1846 stall_logging_categories function. In that case also DESCRIPTION will
1847 need to be passed, with <description> being a short single line text.
1848 And OLD_CATEGORY_NAMES can be used to inform about any renamings of the
1849 category, so user settings can be migrated. Since 5.68.0.
1850 Since 5.14.0.
1852 ecm_qt_export_logging_category(
1854 IDENTIFIER <identifier>
1855 CATEGORY_NAME <category_name>
1856 [OLD_CATEGORY_NAMES <oldest_category_name> [<second_oldest_category_name> [...]]]
1857 EXPORT <exportid>
1858 DESCRIPTION <description>
1859 [DEFAULT_SEVERITY <Debug|Info|Warning|Critical|Fatal>]
1860 )
1861 Registers a logging category for being included in the generated and
1863 installed KDebugSettings files. To be used for categories who are de‐
1864 clared by manual code or other ways instead of code generated with
1865 ecm_qt_declare_logging_category.
1866 <identifier> may include namespaces (eg: foo::bar::IDENT).
1868 EXPORT specifies the group id with which the category will be regis‐
1870 tered. Info about the categories of that group can then be generated
1871 in a file and installed by that group id with the ecm_qt_install_log‐
1872 ging_categories function.
1873 DESCRIPTION specifies a short single line text describing the category.
1875 OLD_CATEGORY_NAMES can be used to inform about any renamings of the
1877 category, so user settings can be migrated.
1878 Since 5.68.0.
1880 ecm_qt_install_logging_categories(
1882 EXPORT <exportid>
1883 [FILE <filename>]
1884 DESTINATION <install_path>
1885 [SORT]
1886 [COMPONENT <component>]
1887 )
1888 Generates and installs a file in KDebugSettings format with the info
1890 about all the categories registered for the group <exportid>, as well
1891 as a file with info about any renamed categories, if there are.
1892 The method call needs to be after the last ecm_qt_declare_logging_cate‐
1894 gory call which uses the same <exportid>. This can be in the same di‐
1895 rectory, or any subdirectory or parent directory.
1896 EXPORT specifies the group id of categories whose information should be
1898 stored in the file generated and installed.
1899 FILE specifies the name of the file generated and installed. It will
1901 default to lower-cased <exportid>.categories.
1902 DESTINATION specifies where the generated file will be installed.
1904 IF SORT is set, entries will be sorted by identifiers.
1906 COMPONENT specifies the installation component name with which the in‐
1908 stall rules for the generated file are associated.
1909 Example usage:
1911 ecm_qt_declare_logging_category(
1913 MYPROJECT_SRCS
1914 HEADER "myproject_debug.h"
1915 IDENTIFIER "MYPROJECT_DEBUG"
1916 CATEGORY_NAME "myproject"
1917 OLD_CATEGORY_NAMES "myprojectlog"
1918 DESCRIPTION "My project"
1919 EXPORT MyProject
1920 )
1921 ecm_qt_export_logging_category(
1923 IDENTIFIER "MYPROJECT_SUBMODULE_DEBUG"
1924 CATEGORY_NAME "myproject.submodule"
1925 DESCRIPTION "My project - submodule"
1926 EXPORT MyProject
1927 )
1928 ecm_qt_install_logging_categories(
1930 EXPORT MyProject
1931 FILE myproject.categories
1932 DESTINATION "${KDE_INSTALL_LOGGINGCATEGORIESDIR}"
1933 )
1934 Since 5.68.0.
1936 ECMSetupQtPluginMacroNames
1938 Instruct CMake’s automoc about C++ preprocessor macros used to define
1939 Qt-style plugins.
1940 ecm_setup_qtplugin_macro_names(
1942 [JSON_NONE <macro_name> [<macro_name> [...]]]
1943 [JSON_ARG1 <macro_name> [<macro_name> [...]]]
1944 [JSON_ARG2 <macro_name> [<macro_name> [...]]]
1945 [JSON_ARG3 <macro_name> [<macro_name> [...]]]
1946 [CONFIG_CODE_VARIABLE <variable_name>] )
1947 CMake’s automoc needs some support when parsing C++ source files to de‐
1949 tect whether moc should be run on those files and if there are also de‐
1950 pendencies on other files, like those with Qt plugin metadata in JSON
1951 format. Because automoc just greps overs the raw plain text of the
1952 sources without any C++ preprocessor-like processing. CMake in newer
1953 versions provides the variables CMAKE_AUTOMOC_DEPEND_FILTERS (CMake >=
1954 3.9.0) and CMAKE_AUTOMOC_MACRO_NAMES (CMake >= 3.10) to allow the de‐
1955 veloper to assist automoc.
1956 This macro cares for the explicit setup needed for those variables for
1958 common cases of C++ preprocessor macros used for Qt-style plugins.
1959 JSON_NONE lists the names of C++ preprocessor macros for Qt-style plug‐
1961 ins which do not refer to external files with the plugin metadata.
1962 JSON_ARG1 lists the names of C++ preprocessor macros for Qt-style plug‐
1964 ins where the first argument to the macro is the name of the external
1965 file with the plugin metadata.
1966 JSON_ARG2 is the same as JSON_ARG1 but with the file name being the
1968 second argument.
1969 JSON_ARG3 is the same as JSON_ARG1 but with the file name being the
1971 third argument.
1972 CONFIG_CODE_VARIABLE specifies the name of the variable which will get
1974 set as value some generated CMake code for instructing automoc for the
1975 given macro names, as useful in an installed CMake config file. The
1976 variable can then be used as usual in the template file for such a
1977 CMake config file, by @<variable_name>@.
1978 Example usage:
1980 Given some plugin-oriented Qt-based software which defines a custom C++
1982 preprocessor macro EXPORT_MYPLUGIN for declaring the central plugin ob‐
1983 ject:
1984 #define EXPORT_MYPLUGIN_WITH_JSON(classname, jsonFile) \
1986 class classname : public QObject \
1987 { \
1988 Q_OBJECT \
1989 Q_PLUGIN_METADATA(IID "myplugin" FILE jsonFile) \
1990 explicit classname() {} \
1991 };
1992 In the CMake buildsystem of the library one calls
1994 ecm_setup_qtplugin_macro_names(
1996 JSON_ARG2
1997 EXPORT_MYPLUGIN_WITH_JSON
1998 )
1999 to instruct automoc about the usage of that macro in the sources of the
2001 library itself.
2002 Given the software installs a library including the header with the
2004 macro definition and a CMake config file, so 3rd-party can create addi‐
2005 tional plugins by linking against the library, one passes additionally
2006 the name of a variable which shall be set as value the CMake code
2007 needed to instruct automoc about the usage of that macro.
2008 ecm_setup_qtplugin_macro_names(
2010 JSON_ARG2
2011 EXPORT_MYPLUGIN_WITH_JSON
2012 CONFIG_CODE_VARIABLE
2013 PACKAGE_SETUP_AUTOMOC_VARIABLES
2014 )
2015 This variable then is used in the template file (e.g. MyProjectCon‐
2017 fig.cmake.in) for the libary’s installed CMake config file and that way
2018 will ensure that in the 3rd-party plugin’s buildsystem automoc is in‐
2019 structed as well as needed:
2020 @PACKAGE_SETUP_AUTOMOC_VARIABLES@
2022 Since 5.45.0.
2024 ECMSetupVersion
2026 Handle library version information.
2027 ecm_setup_version(<version>
2029 VARIABLE_PREFIX <prefix>
2030 [SOVERSION <soversion>]
2031 [VERSION_HEADER <filename>]
2032 [PACKAGE_VERSION_FILE <filename> [COMPATIBILITY <compat>]] )
2033 This parses a version string and sets up a standard set of version
2035 variables. It can optionally also create a C version header file and a
2036 CMake package version file to install along with the library.
2037 If the <version> argument is of the form <major>.<minor>.<patch> (or
2039 <major>.<minor>.<patch>.<tweak>), The following CMake variables are
2040 set:
2041 <prefix>_VERSION_MAJOR - <major>
2043 <prefix>_VERSION_MINOR - <minor>
2044 <prefix>_VERSION_PATCH - <patch>
2045 <prefix>_VERSION - <version>
2046 <prefix>_VERSION_STRING - <version> (for compatibility: use <prefix>_VERSION instead)
2047 <prefix>_SOVERSION - <soversion>, or <major> if SOVERSION was not given
2048 If CMake policy CMP0048 is not NEW, the following CMake variables will
2050 also be set:
2051 PROJECT_VERSION_MAJOR - <major>
2053 PROJECT_VERSION_MINOR - <minor>
2054 PROJECT_VERSION_PATCH - <patch>
2055 PROJECT_VERSION - <version>
2056 PROJECT_VERSION_STRING - <version> (for compatibility: use PROJECT_VERSION instead)
2057 If the VERSION_HEADER option is used, a simple C header is generated
2059 with the given filename. If filename is a relative path, it is inter‐
2060 preted as relative to CMAKE_CURRENT_BINARY_DIR. The generated header
2061 contains the following macros:
2062 <prefix>_VERSION_MAJOR - <major> as an integer
2064 <prefix>_VERSION_MINOR - <minor> as an integer
2065 <prefix>_VERSION_PATCH - <patch> as an integer
2066 <prefix>_VERSION_STRING - <version> as a C string
2067 <prefix>_VERSION - the version as an integer
2068 <prefix>_VERSION has <patch> in the bottom 8 bits, <minor> in the next
2070 8 bits and <major> in the remaining bits. Note that <patch> and <mi‐
2071 nor> must be less than 256.
2072 If the PACKAGE_VERSION_FILE option is used, a simple CMake package ver‐
2074 sion file is created using the write_basic_package_version_file() macro
2075 provided by CMake. It should be installed in the same location as the
2076 Config.cmake file of the library so that it can be found by find_pack‐
2077 age(). If the filename is a relative path, it is interpreted as rela‐
2078 tive to CMAKE_CURRENT_BINARY_DIR. The optional COMPATIBILITY option is
2079 forwarded to write_basic_package_version_file(), and defaults to
2080 AnyNewerVersion.
2081 If CMake policy CMP0048 is NEW, an alternative form of the command is
2083 available:
2084 ecm_setup_version(PROJECT
2086 [VARIABLE_PREFIX <prefix>]
2087 [SOVERSION <soversion>]
2088 [VERSION_HEADER <filename>]
2089 [PACKAGE_VERSION_FILE <filename>] )
2090 This will use the version information set by the project() command.
2092 VARIABLE_PREFIX defaults to the project name. Note that PROJECT must
2093 be the first argument. In all other respects, it behaves like the
2094 other form of the command.
2095 Since pre-1.0.0.
2097 COMPATIBILITY option available since 1.6.0.
2099 ECMSourceVersionControl
2101 Tries to determine whether the source is under version control (git
2102 clone, svn checkout, etc).
2103 ECM_SOURCE_UNDER_VERSION_CONTROL is set when indication is found that
2105 CMAKE_SOURCE_DIR is under version control.
2106 Since 5.63
2108 ECMUninstallTarget
2110 Add an uninstall target.
2111 By including this module, an uninstall target will be added to your
2113 CMake project. This will remove all files installed (or updated) by a
2114 previous invocation of the install target. It will not remove files
2115 created or modified by an install(SCRIPT) or install(CODE) command; you
2116 should create a custom uninstallation target for these and use add_de‐
2117 pendency to make the uninstall target depend on it:
2118 include(ECMUninstallTarget)
2120 install(SCRIPT install-foo.cmake)
2121 add_custom_target(uninstall_foo COMMAND ${CMAKE_COMMAND} -P uninstall-foo.cmake)
2122 add_dependency(uninstall uninstall_foo)
2123 The target will fail if the install target has not yet been run (so it
2125 is not possible to run CMake on the project and then immediately run
2126 the uninstall target).
2127 WARNING:
2129 CMake deliberately does not provide an uninstall target by default
2130 on the basis that such a target has the potential to remove impor‐
2131 tant files from a user’s computer. Use with caution.
2132 Since 1.7.0.
2134 ECMUseFindModules
2136 Selectively use some of the find modules provided by extra-cmake-mod‐
2137 ules.
2138 This module is automatically available once extra-cmake-modules has
2140 been found, so it is not necessary to include(ECMUseFindModules) ex‐
2141 plicitly.
2142 ecm_use_find_modules(DIR <dir>
2144 MODULES module1.cmake [module2.cmake [...]]
2145 [NO_OVERRIDE])
2146 This allows selective use of the find modules provided by ECM, includ‐
2148 ing deferring to CMake’s versions of those modules if it has them.
2149 Rather than adding ${ECM_FIND_MODULE_DIR} to CMAKE_MODULE_PATH, you use
2150 ecm_use_find_modules() to copy the modules you want to a local (build)
2151 directory, and add that to CMAKE_MODULE_PATH.
2152 The find modules given to MODULES will be copied to the directory given
2154 by DIR (which should be located in ${CMAKE_BINARY_DIR} and added to
2155 CMAKE_MODULE_PATH). If NO_OVERRIDE is given, only modules not also
2156 provided by CMake will be copied.
2157 Example:
2159 find_package(ECM REQUIRED)
2161 ecm_use_find_modules(
2162 DIR ${CMAKE_BINARY_DIR}/cmake
2163 MODULES FindEGL.cmake
2164 NO_OVERRIDE
2165 )
2166 set(CMAKE_MODULE_PATH ${CMAKE_BINARY_DIR}/cmake)
2167 This example will make FindEGL.cmake available in your project, but
2169 only as long as it is not yet part of CMake. Calls to find_package(EGL)
2170 will then make use of this copied module (or the CMake module if it ex‐
2171 ists).
2172 Another possible use for this macro is to take copies of find modules
2174 that can be installed along with config files if they are required as a
2175 dependency (for example, if targets provided by the find module are in
2176 the link interface of a library).
2177 Since pre-1.0.0.
2179 ECMWinResolveSymlinks
2181 Resolve pseudo-symlinks created by git when cloning on Windows.
2182 ecm_win_resolve_symlinks(<dir>)
2184 When git checks out a repository with UNIX symlinks on Windows machine,
2186 it creates a text file for each symlink, containing a relative path to
2187 the real file. This function would recursively walk over specified di‐
2188 rectory and replace pseudo-symlinks with corresponding real file’s con‐
2189 tents. It would then run git update-index –assume-unchanged on them to
2190 trick git.
2191 This is useful for projects like “breeze-icons” that contain many iden‐
2193 tical icons implemented as symlinks.
2194 Since 5.28
2196
2198 ecm(7), ecm-find-modules(7), ecm-kde-modules(7)
2199
2201 KDE Developers
22025.82 May 03, 2021 ECM-MODULES(7)