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
13 ecm-find-modules(7); those that provide standard settings for software
14 produced by the KDE community are documented in ecm-kde-modules(7).
15 The rest provide macros and functions for general use by CMake scripts
16 and are documented 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 CheckAtomic
34 Check if the compiler supports std:atomic out of the box or if li‐
35 batomic is needed for atomic support. If it is needed libatomicis added
36 to CMAKE_REQUIRED_LIBRARIES. So after running CheckAtomic you can use
37 std:atomic.
38 Since 5.75.0.
40 ECMAddAppIcon
42 Add icons to executable files and packages.
43 ecm_add_app_icon(<sources_var_name(|target (since 5.83))>
45 ICONS <icon> [<icon> [...]]
46 [SIDEBAR_ICONS <icon> [<icon> [...]] # Since 5.49
47 [OUTFILE_BASENAME <name>]) # Since 5.49
48 )
49 The given icons, whose names must match the pattern:
51 <size>-<other_text>.png
53 will be added as platform-specific application icons to the variable
55 named <sources_var_name> or, if the first argument is a target (since
56 5.83), to the SOURCES property of <target>. Any target must be created
57 with add_executable() and not be an alias.
58 Other icon files are ignored but on Mac SVG files can be supported and
60 it is thus possible to mix those with png files in a single macro call.
61 The platforms currently supported are Windows and Mac OS X, on all oth‐
63 ers the call has no effect and is ignored.
64 <size> is a numeric pixel size (typically 16, 32, 48, 64, 128 or 256).
66 <other_text> can be any other text. See the platform notes below for
67 any recommendations about icon sizes.
68 SIDEBAR_ICONS can be used to add Mac OS X sidebar icons to the gener‐
70 ated iconset. They are used when a folder monitored by the application
71 is dragged into Finder’s sidebar. Since 5.49.
72 OUTFILE_BASENAME will be used as the basename for the icon file. If you
74 specify it, the icon file will be called <OUTFILE_BASENAME>.icns on Mac
75 OS X and <OUTFILE_BASENAME>.ico on Windows. If you don’t specify it, it
76 defaults to <sources_var_name>.<ext>. Since 5.49.
77 Windows notes
79 • Icons are compiled into the executable using a resource file.
81 • Icons may not show up in Windows Explorer if the executable
83 target does not have the WIN32_EXECUTABLE property set.
84 • Icotool (see FindIcoTool) is required.
86 • Supported sizes: 16, 24, 32, 48, 64, 128, 256, 512 and 1024.
88 Mac OS X notes
90 • The executable target must have the MACOSX_BUNDLE property
92 set.
93 • Icons are added to the bundle.
95 • If the ksvg2icns tool from KIconThemes is available, .svg and
97 .svgz files are accepted; the first that is converted success‐
98 fully to .icns will provide the application icon. SVG files
99 are ignored otherwise.
100 • The tool iconutil (provided by Apple) is required for bitmap
102 icons.
103 • Supported sizes: 16, 32, 64, 128, 256 (and 512, 1024 after OS
105 X 10.9).
106 • At least a 128x128px (or an SVG) icon is required.
108 • Larger sizes are automatically used to substitute for smaller
110 sizes on “Retina” (high-resolution) displays. For example, a
111 32px icon, if provided, will be used as a 32px icon on stan‐
112 dard-resolution displays, and as a 16px-equivalent icon (with
113 an “@2x” tag) on high-resolution displays. That is why you
114 should provide 64px and 1024px icons although they are not
115 supported anymore directly. Instead they will be used as
116 32px@2x and 512px@2x. If an SVG icon is provided, ksvg2icns
117 will be used internally to automatically generate all appro‐
118 priate sizes, including the high-resolution ones.
119 • This function sets the MACOSX_BUNDLE_ICON_FILE variable to the
121 name of the generated icns file, so that it will be used as
122 the MACOSX_BUNDLE_ICON_FILE target property when you call
123 add_executable.
124 • Sidebar icons should typically provided in 16, 32, 64, 128 and
126 256px.
127 Since 1.7.0.
129 ECMAddQch
131 This module provides the ecm_add_qch function for generating API docu‐
132 mentation files in the QCH format, and the ecm_install_qch_export func‐
133 tion for generating and installing exported CMake targets for such gen‐
134 erated QCH files to enable builds of other software with generation of
135 QCH files to create links into the given QCH files.
136 ecm_add_qch(<target_name>
138 NAME <name>
139 VERSION <version>
140 QCH_INSTALL_DESTINATION <qchfile_install_path>
141 TAGFILE_INSTALL_DESTINATION <tagsfile_install_path>
142 [COMPONENT <component>]
143 [BASE_NAME <basename>]
144 [SOURCE_DIRS <dir> [<dir2> [...]]]
145 [SOURCES <file> [<file2> [...]]]
146 |MD_MAINPAGE <md_file>]
147 [INCLUDE_DIRS <incdir> [<incdir2> [...]]]
148 [IMAGE_DIRS <idir> [<idir2> [...]]]
149 [EXAMPLE_DIRS <edir> [<edir2> [...]]]
150 [ORG_DOMAIN <domain>]
151 [NAMESPACE <namespace>]
152 [LINK_QCHS <qch> [<qch2> [...]]]
153 [PREDEFINED_MACROS <macro[=content]> [<macro2[=content]> [...]]]
154 [BLANK_MACROS <macro> [<macro2> [...]]]
155 [CONFIG_TEMPLATE <configtemplate_file>]
156 [VERBOSE]
157 )
158 This macro adds a target called <target_name> for the creation of an
160 API documentation manual in the QCH format from the given sources. It
161 currently uses doxygen, future versions might optionally also allow
162 other tools. Next to the QCH file the target will generate a corre‐
163 sponding doxygen tag file, which enables creating links from other doc‐
164 umentation into the generated QCH file.
165 It is recommended to make the use of this macro optional, by depending
167 the call to ecm_add_qch on a CMake option being set, with a name like
168 BUILD_QCH and being TRUE by default. This will allow the developers to
169 saves resources on normal source development build cycles by setting
170 this option to FALSE.
171 The macro will set the target properties DOXYGEN_TAGFILE, QHP_NAME‐
173 SPACE, QHP_NAMESPACE_VERSIONED, QHP_VIRTUALFOLDER and LINK_QCHS to the
174 respective values, to allow other code access to them, e.g. the macro
175 ecm_install_qch_export. To enable the use of the target <target_name>
176 as item for LINK_QCHS in further ecm_add_qch calls in the current
177 build, additionally a target property DOXYGEN_TAGFILE_BUILD is set,
178 with the path of the created doxygen tag file in the build dir. If ex‐
179 isting, ecm_add_qch will use this property instead of DOXYGEN_TAGFILE
180 for access to the tags file.
181 NAME specifies the name for the generated documentation.
183 VERSION specifies the version of the library for which the documenta‐
185 tion is created.
186 BASE_NAME specifies the base name for the generated files. The default
188 basename is <name>.
189 SOURCE_DIRS specifies the dirs (incl. subdirs) with the source files
191 for which the API documentation should be generated. Dirs can be rela‐
192 tive to the current source dir. Dependencies to the files in the dirs
193 are not tracked currently, other than with the SOURCES argument. So do
194 not use for sources generated during the build. Needs to be used when
195 SOURCES or CONFIG_TEMPLATE are not used.
196 SOURCES specifies the source files for which the API documentation
198 should be generated. Needs to be used when SOURCE_DIRS or CONFIG_TEM‐
199 PLATE are not used.
200 MD_MAINPAGE specifies a file in Markdown format that should be used as
202 main page. This page will overrule any \mainpage command in the in‐
203 cluded sources.
204 INCLUDE_DIRS specifies the dirs which should be searched for included
206 headers. Dirs can be relative to the current source dir. Since 5.63.
207 IMAGE_DIRS specifies the dirs which contain images that are included in
209 the documentation. Dirs can be relative to the current source dir.
210 EXAMPLE_DIRS specifies the dirs which contain examples that are in‐
212 cluded in the documentation. Dirs can be relative to the current source
213 dir.
214 QCH_INSTALL_DESTINATION specifies where the generated QCH file will be
216 installed.
217 TAGFILE_INSTALL_DESTINATION specifies where the generated tag file will
219 be installed.
220 COMPONENT specifies the installation component name with which the in‐
222 stall rules for the generated QCH file and tag file are associated.
223 NAMESPACE can be used to set a custom namespace <namespace> of the gen‐
225 erated QCH file. The namepspace is used as the unique id by QHelpEngine
226 (cmp. https://doc.qt.io/qt-5/qthelpproject.html#namespace). The de‐
227 fault namespace is <domain>.<name>. Needs to be used when ORG_DOMAIN
228 is not used.
229 ORG_DOMAIN can be used to define the organization domain prefix for the
231 default namespace of the generated QCH file. Needs to be used when
232 NAMESPACE is not used.
233 LINK_QCHS specifies a list of other QCH targets which should be used
235 for creating references to API documentation of code in external li‐
236 braries. For each target <qch> in the list these target properties are
237 expected to be defined: DOXYGEN_TAGFILE, QHP_NAMESPACE and QHP_VIRTUAL‐
238 FOLDER. If any of these is not existing, <qch> will be ignored. Use
239 the macro ecm_install_qch_export for exporting a target with these
240 properties with the CMake config of a library. Any target <qch> can
241 also be one created before in the same buildsystem by another call of
242 ecm_add_qch.
243 PREDEFINED_MACROS specifies a list of C/C++ macros which should be han‐
245 dled as given by the API dox generation tool. Examples are macros only
246 defined in generated files, so whose definition might be not available
247 to the tool.
248 BLANK_MACROS specifies a list of C/C++ macro names which should be ig‐
250 nored by the API dox generation tool and handled as if they resolve to
251 empty strings. Examples are export macros only defined in generated
252 files, so whose definition might be not available to the tool.
253 CONFIG_TEMPLATE specifies a custom cmake template file for the config
255 file that is created to control the execution of the API dox generation
256 tool. The following CMake variables need to be used: - ECM_QCH_DOXY‐
257 GEN_QHELPGENERATOR_EXECUTABLE - ECM_QCH_DOXYGEN_FILEPATH, ECM_QCH_DOXY‐
258 GEN_TAGFILE The following CMake variables can be used: - ECM_QCH_DOXY‐
259 GEN_PROJECTNAME - ECM_QCH_DOXYGEN_PROJECTVERSION - ECM_QCH_DOXYGEN_VIR‐
260 TUALFOLDER - ECM_QCH_DOXYGEN_FULLNAMESPACE - ECM_QCH_DOXYGEN_TAGFILES -
261 ECM_QCH_DOXYGEN_WARN_LOGFILE - ECM_QCH_DOXYGEN_QUIET There is no guar‐
262 antue that the other CMake variables currently used in the default con‐
263 fig file template will also be present with the same semantics in fu‐
264 ture versions of this macro.
265 VERBOSE tells the API dox generation tool to be more verbose about its
267 activity.
268 The default config file for the API dox generation tool, so the one
270 when not using CONFIG_TEMPLATE, allows code to handle the case of being
271 processed by the tool by defining the C/C++ preprocessor macro K_DOXY‐
272 GEN when run (since v5.67.0). For backward-compatibility also the defi‐
273 nition DOXYGEN_SHOULD_SKIP_THIS is set, but its usage is deprecated.
274 Example usage:
276 ecm_add_qch(
278 MyLib_QCH
279 NAME MyLib
280 VERSION "0.42.0"
281 ORG_DOMAIN org.myorg
282 SOURCE_DIRS
283 src
284 LINK_QCHS
285 Qt5Core_QCH
286 Qt5Xml_QCH
287 Qt5Gui_QCH
288 Qt5Widgets_QCH
289 BLANK_MACROS
290 MyLib_EXPORT
291 MyLib_DEPRECATED
292 TAGFILE_INSTALL_DESTINATION ${CMAKE_INSTALL_PREFIX}/share/docs/tags
293 QCH_INSTALL_DESTINATION ${CMAKE_INSTALL_PREFIX}/share/docs/qch
294 COMPONENT Devel
295 )
296 Example usage (with two QCH files, second linking first):
298 ecm_add_qch(
300 MyLib_QCH
301 NAME MyLib
302 VERSION ${MyLib_VERSION}
303 ORG_DOMAIN org.myorg
304 SOURCES ${MyLib_PUBLIC_HEADERS}
305 MD_MAINPAGE src/mylib/README.md
306 LINK_QCHS Qt5Core_QCH
307 TAGFILE_INSTALL_DESTINATION ${CMAKE_INSTALL_PREFIX}/share/docs/tags
308 QCH_INSTALL_DESTINATION ${CMAKE_INSTALL_PREFIX}/share/docs/qch
309 COMPONENT Devel
310 )
311 ecm_add_qch(
312 MyOtherLib_QCH
313 NAME MyOtherLib
314 VERSION ${MyOtherLib_VERSION}
315 ORG_DOMAIN org.myorg
316 SOURCES ${MyOtherLib_PUBLIC_HEADERS}
317 MD_MAINPAGE src/myotherlib/README.md
318 LINK_QCHS Qt5Core_QCH MyLib_QCH
319 TAGFILE_INSTALL_DESTINATION ${CMAKE_INSTALL_PREFIX}/share/docs/tags
320 QCH_INSTALL_DESTINATION ${CMAKE_INSTALL_PREFIX}/share/docs/qch
321 COMPONENT Devel
322 )
323 ecm_install_qch_export(
325 TARGETS [<name> [<name2> [...]]]
326 FILE <file>
327 DESTINATION <dest>
328 [COMPONENT <component>]
329 )
330 This macro creates and installs a CMake file <file> which exports the
332 given QCH targets <name> etc., so they can be picked up by CMake-based
333 builds of other software that also generate QCH files (using
334 ecm_add_qch) and which should include links to the QCH files created by
335 the given targets. The installed CMake file <file> is expected to be
336 included by the CMake config file created for the software the related
337 QCH files are documenting.
338 TARGETS specifies the QCH targets which should be exported. If a target
340 does not exist or does not have all needed properties, a warning will
341 be generated and the target skipped. This behaviour might change in
342 future versions to result in a fail instead.
343 FILE specifies the name of the created CMake file, typically with a
345 .cmake extension.
346 DESTINATION specifies the directory on disk to which the file will be
348 installed. It usually is the same as the one where the CMake config
349 files for this software are installed.
350 COMPONENT specifies the installation component name with which the in‐
352 stall rule is associated.
353 Example usage:
355 ecm_install_qch_export(
357 TARGETS MyLib_QCH
358 FILE MyLibQCHTargets.cmake
359 DESTINATION "${CMAKE_INSTALL_PREFIX}/lib/cmake/MyLib"
360 COMPONENT Devel
361 )
362 Since 5.36.0.
364 ECMAddQtDesignerPlugin
366 This module provides the ecm_add_qtdesignerplugin function for generat‐
367 ing Qt Designer plugins for custom widgets. Each of those widgets is
368 described using a second function ecm_qtdesignerplugin_widget.
369 ecm_add_qtdesignerplugin(<target_name>
371 NAME <name>
372 WIDGETS <widgetid> [<widgetid2> [...]]
373 LINK_LIBRARIES <lib> [<lib2> [...]]
374 INSTALL_DESTINATION <install_path>
375 [OUTPUT_NAME <output_name>]
376 [DEFAULT_GROUP <group>]
377 [DEFAULT_HEADER_CASE <SAME_CASE|LOWER_CASE|UPPER_CASE>]
378 [DEFAULT_HEADER_EXTENSION <header_extension>]
379 [DEFAULT_ICON_DIR <icon_dir>]
380 [INCLUDE_FILES <include_file> [<include_file2> [...]]]
381 [SOURCES <src> [<src2> [...]]]
382 [COMPONENT <component>]
383 )
384 NAME specifies the base name to use in the generated sources. The de‐
386 fault is <target_name>.
387 WIDGETS specifies the widgets the plugin should support. Each widget
389 has to be defined before by a call of ecm_qtdesignerplugin_widget with
390 the respective <widgetid>, in a scope including the current call.
391 LINK_LIBRARIES specifies the libraries to link against. This will be at
393 least the library providing the widget class(es).
394 INSTALL_DESTINATION specifies where the generated plugin binary will be
396 installed.
397 OUTPUT_NAME specifies the name of the plugin binary. The default is
399 “<target_name>”.
400 DEFAULT_GROUP specifies the default group in Qt Designer where the wid‐
402 gets will be placed. The default is “Custom”.
403 DEFAULT_HEADER_CASE specifies how the name of the header is derived
405 from the widget class name. The default is “LOWER_CASE”.
406 DEFAULT_HEADER_EXTENSION specifies what file name extension is used for
408 the header file derived from the class name. The default is “h”.
409 DEFAULT_ICON_DIR specifies what file name extension is used for the
411 header file derived from the class name. The default is “pics”.
412 INCLUDE_FILES specifies additional include files to include with the
414 generated source file. This can be needed for custom code used in ini‐
415 tializing or creating widgets.
416 SOURCES specifies additional source files to build the plugin from.
418 This can be needed to support custom code used in initializing or cre‐
419 ating widgets.
420 COMPONENT specifies the installation component name with which the in‐
422 stall rules for the generated plugin are associated.
423 ecm_qtdesignerplugin_widget(<widgetid>
425 [CLASS_NAME <class_name>]
426 [INCLUDE_FILE <include_file>]
427 [CONTAINER]
428 [ICON <iconfile>]
429 [TOOLTIP <tooltip>]
430 [WHATSTHIS <whatsthis>]
431 [GROUP <group>]
432 [CREATE_WIDGET_CODE_FROM_VARIABLE <create_widget_code_variable>]
433 [INITIALIZE_CODE_FROM_VARIABLE <initialize_code_variable]
434 [DOM_XML_FROM_VARIABLE <dom_xml_variable>]
435 [IMPL_CLASS_NAME <impl_class_name>]
436 [CONSTRUCTOR_ARGS_CODE <constructor_args_code>]
437 [CONSTRUCTOR_ARGS_CODE_FROM_VARIABLE <constructor_args_code_variable>]
438 )
439 CLASS_NAME specifies the name of the widget class, including name‐
441 spaces. The default is “<widgetid>”.
442 INCLUDE_FILE specifies the include file to use for the class of this
444 widget. The default is derived from <class_name> as configured by the
445 DEFAULT_HEADER_* options of ecm_add_qtdesignerplugin, also replacing
446 any namespace separators with “/”.
447 CONTAINER specifies, if set, that this widget is a container for other
449 widgets.
450 ICON specifies the icon file to use as symbol for this widget. The de‐
452 fault is “{lowercased <class_name>}.png” in the default icons dir as
453 configured by the DEFAULT_ICON_DIR option of ecm_add_qtdesignerplugin,
454 if such a file exists.
455 TOOLTIP specifies the tooltip text to use for this widget. Default is
457 “<class_name> Widget”.
458 WHATSTHIS specifies the What’s-This text to use for this widget. De‐
460 faults to the tooltip.
461 GROUP specifies the group in Qt Designer where the widget will be
463 placed. The default is set as configured by the DEFAULT_GROUP option
464 of ecm_add_qtdesignerplugin.
465 CREATE_WIDGET_CODE_FROM_VARIABLE specifies the variable to get from the
467 C++ code to use as factory code to create an instance of the widget,
468 for the override of QDesignerCustomWidgetInterface::createWidget(QWid‐
469 get* parent). The default is “return new <impl_class_name><construc‐
470 tor_args_code>;”.
471 INITIALIZE_CODE_FROM_VARIABLE specifies the variable to get from the
473 C++ code to use with the override of QDesignerCustomWidgetInter‐
474 face::initialize(QDesignerFormEditorInterface* core). The code has to
475 use the present class member m_initialized to track and update the
476 state. The default code simply sets m_initialized to true, if it was
477 not before.
478 DOM_XML_FROM_VARIABLE specifies the variable to get from the string to
480 use with the optional override of QDesignerCustomWidgetInter‐
481 face::domXml(). Default does not override.
482 IMPL_CLASS_NAME specifies the name of the widget class to use for the
484 widget instance with Qt Designer. The default is “<class_name>”.
485 CONSTRUCTOR_ARGS_CODE specifies the C++ code to use for the constructor
487 arguments with the default of CREATE_WIDGET_CODE_FROM_VARIABLE. Note
488 that the parentheses are required. The default is “(parent)”.
489 CONSTRUCTOR_ARGS_CODE_FROM_VARIABLE specifies the variable to get from
491 the C++ code instead of passing it directly via CONSTRUCTOR_ARGS_CODE.
492 This can be needed if the code is more complex and e.g. includes “;”
493 chars.
494 Example usage:
496 ecm_qtdesignerplugin_widget(FooWidget
498 TOOLTIP "Enables to browse foo."
499 GROUP "Views (Foo)"
500 )
501 set(BarWidget_CREATE_WIDGET_CODE
503 "
504 auto* widget = new BarWidget(parent);
505 widget->setBar("Example bar");
506 return widget;
507 ")
508 ecm_qtdesignerplugin_widget(BarWidget
510 TOOLTIP "Displays bars."
511 GROUP "Display (Foo)"
512 CREATE_WIDGET_CODE_FROM_VARIABLE BarWidget_CREATE_WIDGET_CODE
513 )
514 ecm_add_qtdesignerplugin(foowidgets
516 NAME FooWidgets
517 OUTPUT_NAME foo2widgets
518 WIDGETS
519 FooWidget
520 BarWidget
521 LINK_LIBRARIES
522 Foo::Widgets
523 INSTALL_DESTINATION "${KDE_INSTALL_QTPLUGINDIR}/designer"
524 COMPONENT Devel
525 )
526 Since 5.62.0.
528 ECMAddTests
530 Convenience functions for adding tests.
531 ecm_add_tests(<sources>
533 LINK_LIBRARIES <library> [<library> [...]]
534 [NAME_PREFIX <prefix>]
535 [GUI]
536 [TARGET_NAMES_VAR <target_names_var>]
537 [TEST_NAMES_VAR <test_names_var>]
538 [WORKING_DIRECTORY <dir>] # Since 5.111
539 )
540 A convenience function for adding multiple tests, each consisting of a
542 single source file. For each file in <sources>, an executable target
543 will be created (the name of which will be the basename of the source
544 file). This will be linked against the libraries given with LINK_LI‐
545 BRARIES. Each executable will be added as a test with the same name.
546 If NAME_PREFIX is given, this prefix will be prepended to the test
548 names, but not the target names. As a result, it will not prevent
549 clashes between tests with the same name in different parts of the
550 project, but it can be used to give an indication of where to look for
551 a failing test.
552 If the flag GUI is passed the test binaries will be GUI executables,
554 otherwise the resulting binaries will be console applications (regard‐
555 less of the value of CMAKE_WIN32_EXECUTABLE or CMAKE_MACOSX_BUNDLE). Be
556 aware that this changes the executable entry point on Windows (although
557 some frameworks, such as Qt, abstract this difference away).
558 The tests will be build with -DQT_FORCE_ASSERTS to enable assertions in
560 the test executable even for release builds.
561 The TARGET_NAMES_VAR and TEST_NAMES_VAR arguments, if given, should
563 specify a variable name to receive the list of generated target and
564 test names, respectively. This makes it convenient to apply properties
565 to them as a whole, for example, using set_target_properties() or
566 set_tests_properties().
567 The generated target executables will have the effects of
569 ecm_mark_as_test() (from the ECMMarkAsTest module) applied to it.
570 WORKING_DIRECTORY sets the test property WORKING_DIRECTORY in which to
572 execute the test. By default the test will be run in ${CMAKE_CUR‐
573 RENT_BINARY_DIR}. The working directory can be specified using genera‐
574 tor expressions. Since 5.111.
575 ecm_add_test(
577 <sources>
578 LINK_LIBRARIES <library> [<library> [...]]
579 [TEST_NAME <name>]
580 [NAME_PREFIX <prefix>]
581 [GUI]
582 [WORKING_DIRECTORY <dir>] # Since 5.111
583 )
584 This is a single-test form of ecm_add_tests that allows multiple source
586 files to be used for a single test. If using multiple source files,
587 TEST_NAME must be given; this will be used for both the target and test
588 names (and, as with ecm_add_tests(), the NAME_PREFIX argument will be
589 prepended to the test name).
590 WORKING_DIRECTORY sets the test property WORKING_DIRECTORY in which to
592 execute the test. By default the test will be run in ${CMAKE_CUR‐
593 RENT_BINARY_DIR}. The working directory can be specified using genera‐
594 tor expressions. Since 5.111.
595 Since pre-1.0.0.
597 ECMCheckOutboundLicense
599 Assert that source file licenses are compatible with a desired outbound
600 license of a compiled binary artifact (e.g., library, plugin or appli‐
601 cation).
602 This module provides the ecm_check_outbound_license function that gen‐
604 erates unit tests for checking the compatibility of license statements.
605 The license statements in all tested files are required to be added by
606 using the SPDX marker SPDX-License-Identifier.
607 During the CMake configuration of the project, a temporary license bill
609 of materials (BOM) in SPDX format is generated by calling the REUSE
610 tool (see <https://reuse.software>). That BOM is parsed and license
611 computations based on an internal compatibility matrix are performed.
612 Preconditions for using this module:
614 • All tested input source files must contain the SPDX-Li‐
616 cense-Identifier tag.
617 • Python3 must be available.
619 • The REUSE tool must be available, which generates the
621 bill-of-materials by running reuse spdx on the tested direc‐
622 tory.
623 When this module is included, a SKIP_LICENSE_TESTS option is added (de‐
625 fault OFF). Turning this option on skips the generation of license
626 tests, which might be convenient if licenses shall not be tested in all
627 build configurations.
628 ecm_check_outbound_license(LICENSES <outbound-licenses>
630 FILES <source-files>
631 [TEST_NAME <name>]
632 [WILL_FAIL])
633 This method adds a custom unit test to ensure the specified outbound
635 license to be compatible with the specified license headers. Note that
636 a convenient way is to use the CMake GLOB argument of the FILE func‐
637 tion.
638 LICENSES
640 List of one or multiple outbound license regarding which the
641 compatibility of the source code files shall be tested..INDENT
642 7.0
643 Currently, the following values are supported (values are SPDX registry
645 identifiers):
646 • MIT
648 • BSD-2-Clause
650 • BSD-3-Clause
652 • LGPL-2.0-only
654 • LGPL-2.1-only
656 • LGPL-3.0-only
658 • GPL-2.0-only
660 • GPL-3.0-only
662 FILES: List of source files that contain valid SPDX-License-Identifier
664 markers. The paths can be relative to the CMake file that gen‐
665 erates the test case or be absolute paths.
666 TEST_NAME
668 Optional parameter that defines the name of the generated test
669 case. If no name is defined, the relative path to the test di‐
670 rectory with appended license name is used. Every test has li‐
671 censecheck_ as prefix.
672 WILL_FAIL
674 Optional parameter that inverts the test result. This parameter
675 is usually only used for tests of the module.
676Since 5.75.0
678 ECMConfiguredInstall
680 Takes a list of files, runs configure_file on each and installs the re‐
681 sultant configured files in the given location.
682 Any suffix of “.in” in the passed file names will be stripped from the
684 file name at the installed location.
685 ecm_install_configured_files(
687 INPUT <file> [<file2> [...]]
688 DESTINATION <INSTALL_DIRECTORY>
689 [COPYONLY]
690 [ESCAPE_QUOTES]
691 [@ONLY]
692 [COMPONENT <component>])
693 Example usage:
695 ecm_install_configured_files(INPUT foo.txt.in DESTINATION ${KDE_INSTALL_DATADIR} @ONLY)
697 This will install the file as foo.txt with any cmake variable replace‐
699 ments made into the data directory.
700 Since 5.73.0.
702 ECMCoverageOption
704 Allow users to easily enable GCov code coverage support.
705 Code coverage allows you to check how much of your codebase is covered
707 by your tests. This module makes it easy to build with support for
708 GCov.
709 When this module is included, a BUILD_COVERAGE option is added (default
711 OFF). Turning this option on enables GCC’s coverage instrumentation,
712 and links against libgcov.
713 NOTE:
715 This will probably break the build if you are not using GCC.
716 Since 1.3.0.
718 ECMCreateQmFromPoFiles
720 WARNING:
721 This module is deprecated and will be removed by ECM 1.0. Use
722 ECMPoQmTools instead.
723 Generate QTranslator (.qm) catalogs from Gettext (.po) catalogs.
725 ecm_create_qm_from_po_files(PO_FILES <file1>... <fileN>
727 [CATALOG_NAME <catalog_name>]
728 [INSTALL_DESTINATION <install_destination>])
729 Creates the necessary rules to compile .po files into .qm files, and
731 install them.
732 The .qm files are installed in <install_destination>/<lang>/LC_MES‐
734 SAGES, where <install_destination> is the INSTALL_DESTINATION argument
735 and <lang> is extracted from the “Language” field inside the .po file.
736 INSTALL_DESTINATION defaults to ${LOCALE_INSTALL_DIR} if defined, oth‐
738 erwise it uses ${CMAKE_INSTALL_LOCALEDIR} if that is defined, otherwise
739 it uses share/locale.
740 CATALOG_NAME defines the name of the installed .qm files. If set, .qm
742 files will be installed as <catalog_name>.qm. If not set .qm files will
743 be named after the name of their source .po file.
744 Setting the catalog name is useful when all .po files for a target are
746 kept in a single source directory. For example, the “mylib” probject
747 might keep all its translations in a “po” directory, like this:
748 po/
750 es.po
751 fr.po
752 Without setting CATALOG_NAME, those .po will be turned into .qm and in‐
754 stalled as:
755 share/locale/fr/LC_MESSAGES/fr.qm
757 share/locale/es/LC_MESSAGES/es.qm
758 If CATALOG_NAME is set to “mylib”, they will be installed as:
760 share/locale/fr/LC_MESSAGES/mylib.qm
762 share/locale/es/LC_MESSAGES/mylib.qm
763 Which is what the loader created by ecm_create_qm_loader() expects.
765 ecm_create_qm_from_po_files() creates a “translation” target. This tar‐
767 get builds all .po files into .qm files.
768 ecm_create_qm_loader(<source_files_var> <catalog_name>)
770 ecm_create_qm_loader() generates a C++ file which ensures translations
772 are automatically loaded at startup. The path of the .cpp file is ap‐
773 pended to <source_files_var>. Typical usage is like:
774 set(mylib_SRCS foo.cpp bar.cpp)
776 ecm_create_qm_loader(mylib_SRCS mylib)
777 add_library(mylib ${mylib_SRCS})
778 This generates a C++ file which loads “mylib.qm” at startup, assuming
780 it has been installed by ecm_create_qm_from_po_files(), and compiles it
781 into mylib.
782 Since pre-1.0.0.
784 ECMDeprecationSettings
786 This module provides the ecm_set_disabled_deprecation_versions function
787 setting the excluding deprecated API for Qt and KF projects.
788 This method expects pairs of the identifier and deprecation version.
790 For the identifier QT this functions adds the definition QT_DIS‐
791 ABLE_DEPRECATED_BEFORE with the given version in a hexadecimal format.
792 Otherwise the name for the definition is generated using ${IDENTI‐
793 FIER}_DISABLE_DEPRECATED_BEFORE_AND_AT, following the naming of the
794 generated code in ECMGenerateExportHeader. The version for the defini‐
795 tion can be overwritten, by passing definition name and the deprecation
796 version as a CMake definition. This allows one to exclude deprecations
797 without having to edit the CMakeLists.txt file.
798 This module provides the following function:
800 ecm_set_disabled_deprecation_versions(
802 [DISABLE_NEWER_WARNINGS] # since 5.96
803 [<identifier> <deprecation_version>]
804 [<identifier2> <deprecation_version2>]
805 )
806 DISABLE_NEWER_WARNINGS disables additionally the compiler warnings for
808 API deprecated in newer versions of the same major version.
809 Example usage:
811 set(QT_MIN_VERSION "5.15.2")
813 set(KF5_MIN_VERSION "5.90")
814 ecm_set_disabled_deprecation_versions(
816 QT ${QT_MIN_VERSION}
817 KF ${KF5_MIN_VERSION}
818 KCOREADDONS 5.89.0 # In case we depend on deprecated KCoreAddons API
819 )
820 Since 5.91
822 ECMEnableSanitizers
824 Enable compiler sanitizer flags.
825 The following sanitizers are supported:
827 • Address Sanitizer
829 • Memory Sanitizer
831 • Thread Sanitizer
833 • Leak Sanitizer
835 • Undefined Behaviour Sanitizer
837 All of them are implemented in Clang, depending on your version, and
839 there is an work in progress in GCC, where some of them are currently
840 implemented.
841 This module will check your current compiler version to see if it sup‐
843 ports the sanitizers that you want to enable
844 Usage
846 Simply add:
847 include(ECMEnableSanitizers)
849 to your CMakeLists.txt. Note that this module is included in
851 KDECompilerSettings, so projects using that module do not need to also
852 include this one.
853 The sanitizers are not enabled by default. Instead, you must set
855 ECM_ENABLE_SANITIZERS (either in your CMakeLists.txt or on the command
856 line) to a semicolon-separated list of sanitizers you wish to enable.
857 The options are:
858 • address
860 • memory
862 • thread
864 • leak
866 • undefined
868 • fuzzer
870 The sanitizers “address”, “memory” and “thread” are mutually exclusive.
872 You cannot enable two of them in the same build.
873 “leak” requires the “address” sanitizer.
875 NOTE:
877 To reduce the overhead induced by the instrumentation of the sani‐
878 tizers, it is advised to enable compiler optimizations (-O1 or
879 higher).
880 Example
882 This is an example of usage:
883 mkdir build
885 cd build
886 cmake -DECM_ENABLE_SANITIZERS='address;leak;undefined' ..
887 NOTE:
889 Most of the sanitizers will require Clang. To enable it, use:
890 -DCMAKE_CXX_COMPILER=clang++
892 Since 1.3.0.
894 ECMFindModuleHelpers
896 Helper macros for find modules: ecm_find_package_version_check(),
897 ecm_find_package_parse_components() and ecm_find_package_handle_li‐
898 brary_components().
899 ecm_find_package_version_check(<name>)
901 Prints warnings if the CMake version or the project’s required CMake
903 version is older than that required by extra-cmake-modules.
904 ecm_find_package_parse_components(<name>
906 RESULT_VAR <variable>
907 KNOWN_COMPONENTS <component1> [<component2> [...]]
908 [SKIP_DEPENDENCY_HANDLING])
909 This macro will populate <variable> with a list of components found in
911 <name>_FIND_COMPONENTS, after checking that all those components are in
912 the list of KNOWN_COMPONENTS; if there are any unknown components, it
913 will print an error or warning (depending on the value of
914 <name>_FIND_REQUIRED) and call return().
915 The order of components in <variable> is guaranteed to match the order
917 they are listed in the KNOWN_COMPONENTS argument.
918 If SKIP_DEPENDENCY_HANDLING is not set, for each component the variable
920 <name>_<component>_component_deps will be checked for dependent compo‐
921 nents. If <component> is listed in <name>_FIND_COMPONENTS, then all
922 its (transitive) dependencies will also be added to <variable>.
923 ecm_find_package_handle_library_components(<name>
925 COMPONENTS <component> [<component> [...]]
926 [SKIP_DEPENDENCY_HANDLING])
927 [SKIP_PKG_CONFIG])
928 Creates an imported library target for each component. The operation
930 of this macro depends on the presence of a number of CMake variables.
931 The <name>_<component>_lib variable should contain the name of this li‐
933 brary, and <name>_<component>_header variable should contain the name
934 of a header file associated with it (whatever relative path is normally
935 passed to ‘#include’). <name>_<component>_header_subdir variable can be
936 used to specify which subdirectory of the include path the headers will
937 be found in. ecm_find_package_components() will then search for the
938 library and include directory (creating appropriate cache variables)
939 and create an imported library target named <name>::<component>.
940 Additional variables can be used to provide additional information:
942 If SKIP_PKG_CONFIG, the <name>_<component>_pkg_config variable is set,
944 and pkg-config is found, the pkg-config module given by <name>_<compo‐
945 nent>_pkg_config will be searched for and used to help locate the li‐
946 brary and header file. It will also be used to set <name>_<compo‐
947 nent>_VERSION.
948 Note that if version information is found via pkg-config, <name>_<com‐
950 ponent>_FIND_VERSION can be set to require a particular version for
951 each component.
952 If SKIP_DEPENDENCY_HANDLING is not set, the INTERFACE_LINK_LIBRARIES
954 property of the imported target for <component> will be set to contain
955 the imported targets for the components listed in <name>_<compo‐
956 nent>_component_deps. <component>_FOUND will also be set to FALSE if
957 any of the components in <name>_<component>_component_deps are not
958 found. This requires the components in <name>_<component>_compo‐
959 nent_deps to be listed before <component> in the COMPONENTS argument.
960 The following variables will be set:
962 <name>_TARGETS
964 the imported targets
965 <name>_LIBRARIES
967 the found libraries
968 <name>_INCLUDE_DIRS
970 the combined required include directories for the components
971 <name>_DEFINITIONS
973 the “other” CFLAGS provided by pkg-config, if any
974 <name>_VERSION
976 the value of <name>_<component>_VERSION for the first component
977 that has this variable set (note that components are searched
978 for in the order they are passed to the macro), although if it
979 is already set, it will not be altered
980 NOTE:
982 These variables are never cleared, so if ecm_find_package_handle_li‐
983 brary_components() is called multiple times with different compo‐
984 nents (typically because of multiple find_package() calls) then
985 <name>_TARGETS, for example, will contain all the targets found in
986 any call (although no duplicates).
987 Since pre-1.0.0.
989 ECMFindQmlModule
991 Find QML import modules through a find_qmlmodule() call. It uses the
992 qmlplugindump application to find the plugins and sets them up as run‐
993 time dependencies.
994 This is useful so that when we configure a project we are notified when
996 some QML imports are not present in the system, thus having the appli‐
997 cation compilable but fail at runtime.
998 ecm_find_qmlmodule(<module_name> <version>...)
1000 Any further arguments passed will be forwarded into a find_package()
1002 call. See find_package() documentation for more information.
1003 Usage example:
1005 ecm_find_qmlmodule(org.kde.kirigami 2.1)
1007 Since 5.38.0.
1009 ECMGenerateDBusServiceFile
1011 This module provides the ecm_generate_dbus_service_file function for
1012 generating and installing a D-Bus service file.
1013 ecm_generate_dbus_service_file(
1015 NAME <service name>
1016 EXECUTABLE <executable>
1017 [SYSTEMD_SERVICE <systemd service>]
1018 DESTINATION <install_path>
1019 [RENAME <dbus service filename>] # Since 5.75
1020 )
1021 A D-Bus service file <service name>.service will be generated and in‐
1023 stalled in the relevant D-Bus config location. This filename can be
1024 customized with RENAME.
1025 <executable> must be an absolute path to the installed service exe‐
1027 cutable. When using it with KDEInstallDirs it needs to be the _FULL_
1028 variant of the path variable.
1029 NOTE:
1031 On Windows, the macro will only use the file name part of <exe‐
1032 cutable> since D-Bus service executables are to be installed in the
1033 same directory as the D-Bus daemon.
1034 Optionally, a <systemd service> can be specified to launch the corre‐
1036 sponding systemd service instead of the <executable> if the D-Bus dae‐
1037 mon is started by systemd.
1038 Example usage:
1040 ecm_generate_dbus_service_file(
1042 NAME org.kde.kded5
1043 EXECUTABLE ${KDE_INSTALL_FULL_BINDIR}/kded5
1044 DESTINATION ${KDE_INSTALL_DBUSSERVICEDIR}
1045 )
1046 ecm_generate_dbus_service_file(
1048 NAME org.kde.kded5
1049 EXECUTABLE ${KDE_INSTALL_FULL_BINDIR}/kded5
1050 SYSTEMD_SERVICE plasma-kded.service
1051 DESTINATION ${KDE_INSTALL_DBUSSERVICEDIR}
1052 RENAME org.kde.daemon.service
1053 )
1054 Since 5.73.0.
1056 ECMGenerateExportHeader
1058 This module provides the ecm_generate_export_header function for gener‐
1059 ating export macros for libraries with version-based control over visi‐
1060 bility of and compiler warnings for deprecated API for the library
1061 user, as well as over excluding deprecated API and their implementation
1062 when building the library itself.
1063 For preparing some values useful in the context it also provides a
1065 function ecm_export_header_format_version.
1066 ecm_generate_export_header(<library_target_name>
1068 VERSION <version>
1069 [BASE_NAME <base_name>]
1070 [GROUP_BASE_NAME <group_base_name>]
1071 [EXPORT_MACRO_NAME <export_macro_name>]
1072 [EXPORT_FILE_NAME <export_file_name>]
1073 [DEPRECATED_MACRO_NAME <deprecated_macro_name>]
1074 [NO_EXPORT_MACRO_NAME <no_export_macro_name>]
1075 [INCLUDE_GUARD_NAME <include_guard_name>]
1076 [STATIC_DEFINE <static_define>]
1077 [PREFIX_NAME <prefix_name>]
1078 [DEPRECATED_BASE_VERSION <deprecated_base_version>]
1079 [DEPRECATION_VERSIONS <deprecation_version> [<deprecation_version2> [...]]]
1080 [EXCLUDE_DEPRECATED_BEFORE_AND_AT <exclude_deprecated_before_and_at_version>]
1081 [NO_BUILD_SET_DEPRECATED_WARNINGS_SINCE]
1082 [NO_DEFINITION_EXPORT_TO_BUILD_INTERFACE]
1083 [USE_VERSION_HEADER [<version_file_name>]] # Since 5.106
1084 [VERSION_BASE_NAME <version_base_name>] # Since 5.106
1085 [VERSION_MACRO_NAME <version_macro_name>] # Since 5.106
1086 [CUSTOM_CONTENT_FROM_VARIABLE <variable>]
1087 )
1088 VERSION specifies the version of the library, given in the format “<ma‐
1090 jor>.<minor>.<patchlevel>”.
1091 GROUP_BASE_NAME specifies the name to use for the macros defining li‐
1093 brary group default values. If set, this will generate code supporting
1094 <group_base_name>_NO_DEPRECATED_WARNINGS, <group_base_name>_DIS‐
1095 ABLE_DEPRECATED_BEFORE_AND_AT, <group_base_name>_DEPRECATED_WARN‐
1096 INGS_SINCE and <group_base_name>_NO_DEPRECATED (see below). If not
1097 set, the generated code will ignore any such macros.
1098 DEPRECATED_BASE_VERSION specifies the default version before and at
1100 which deprecated API is disabled. Possible values are “0”, “CURRENT”
1101 (which resolves to <version>) and a version string in the format “<ma‐
1102 jor>.<minor>.<patchlevel>”. The default is the value of “<exclude_dep‐
1103 recated_before_and_at_version>” if set, or “<major>.0.0”, with <major>
1104 taken from <version>.
1105 DEPRECATION_VERSIONS specifies versions in “<major>.<minor>” format in
1107 which API was declared deprecated. Any version used with the generated
1108 macro <prefix_name><base_name>_DEPRECATED_VERSION(major, minor, text)
1109 or <prefix_name><base_name>_DEPRECATED_VERSION_BELATED(major, minor,
1110 textmajor, textminor, text) needs to be listed here, otherwise the
1111 macro will fail to work.
1112 EXCLUDE_DEPRECATED_BEFORE_AND_AT specifies the version for which all
1114 API deprecated before and at should be excluded from the build com‐
1115 pletely. Possible values are “0” (default), “CURRENT” (which resolves
1116 to <version>) and a version string in the format “<major>.<mi‐
1117 nor>.<patchlevel>”.
1118 NO_BUILD_SET_DEPRECATED_WARNINGS_SINCE specifies that the definition
1120 <prefix_name><uppercase_base_name>_DEPRECATED_WARNINGS_SINCE will not
1121 be set for the library inside its own build, and thus will be defined
1122 by either explicit definition in the build system configuration or by
1123 the default value mechanism (see below). The default is that it is set
1124 for the build, to the version specified by EXCLUDE_DEPRECATED_BE‐
1125 FORE_AND_AT, so no deprecation warnings are done for any own deprecated
1126 API used in the library implementation itself.
1127 NO_DEFINITION_EXPORT_TO_BUILD_INTERFACE specifies that the definition
1129 <prefix_name><uppercase_base_name>_DISABLE_DEPRECATED_BEFORE_AND_AT
1130 will not be set in the public interface of the library inside its own
1131 build, and the same for the definition <prefix_name><upper‐
1132 case_base_name>_DEPRECATED_WARNINGS_SINCE (if not disabled by
1133 NO_BUILD_SET_DEPRECATED_WARNINGS_SINCE already). The default is that
1134 they are set, to the version specified by EXCLUDE_DEPRECATED_BE‐
1135 FORE_AND_AT, so e.g. test and examples part of the project automati‐
1136 cally build against the full API included in the build and without any
1137 deprecation warnings for it.
1138 USE_VERSION_HEADER defines whether a given header file <ver‐
1140 sion_file_name> providing macros specifying the library version should
1141 be included in the generated header file. By default angle-brackets are
1142 used for the include statement. To generate includes with double
1143 quotes, add double quotes to the argument string (needs escaping), e.g.
1144 \"version.h\". The macro from the included version header holding the
1145 library version is given as <version_macro_name> by the argument VER‐
1146 SION_MACRO_NAME and used in the generated code for calculating de‐
1147 faults. If not specified, the defaults for the version file name and
1148 the version macro are derived from <version_base_name> as passed with
1149 VERSION_BASE_NAME, which again defaults to <base_name> or otherwise
1150 <library_target_name>. The macro name defaults to <uppercase_ver‐
1151 sion_base_name>_VERSION, the version file name to <lowercase_ver‐
1152 sion_base_name>_version.h. Since 5.106.
1153 CUSTOM_CONTENT_FROM_VARIABLE specifies the name of a variable whose
1155 content will be appended at the end of the generated file, before any
1156 final inclusion guard closing. Note that before 5.98 this was broken
1157 and would only append the string passed as argument value.
1158 The function ecm_generate_export_header defines C++ preprocessor macros
1160 in the generated export header, some for use in the sources of the li‐
1161 brary the header is generated for, other for use by projects linking
1162 agsinst the library.
1163 The macros for use in the library C++ sources are these, next to those
1165 also defined by GenerateExportHeader:
1166 <prefix_name><uppercase_base_name>_DEPRECATED_VERSION(major, minor,
1168 text)
1169 to use to conditionally set a <prefix_name><upper‐
1170 case_base_name>_DEPRECATED macro for a class, struct or function
1171 (other elements to be supported in future versions), depending
1172 on the visibility macro flags set (see below)
1173 <prefix_name><uppercase_base_name>_DEPRECATED_VERSION_BELATED(major,
1175 minor, textmajor, textminor, text)
1176 to use to conditionally set a <prefix_name><upper‐
1177 case_base_name>_DEPRECATED macro for a class, struct or function
1178 (other elements to be supported in future versions), depending
1179 on the visibility macro flags set (see below), with major & mi‐
1180 nor applied for the logic and textmajor & textminor for the
1181 warnings message. Useful for retroactive tagging of API for the
1182 compiler without injecting the API into the compiler warning
1183 conditions of already released versions. Since 5.71.
1184 <prefix_name><uppercase_base_name>_ENUMERATOR_DEPRECATED_VERSION(major,
1186 minor, text)
1187 to use to conditionally set a <prefix_name><upper‐
1188 case_base_name>_DEPRECATED macro for an enumerator, depending on
1189 the warnings macro flags set (see below). In builds using C++14
1190 standard or earlier, where enumerator attributes are not yet
1191 supported, the macro will always yield an empty string. With
1192 MSVC it is also always an empty string for now. Since 5.82.
1193 <prefix_name><uppercase_base_name>_ENUMERATOR_DEPRECATED_VERSION_BE‐
1195 LATED(major, minor, textmajor, textminor, text)
1196 to use to conditionally set a <prefix_name><upper‐
1197 case_base_name>_DEPRECATED macro for an enumerator, depending on
1198 the warnings macro flags set (see below), with major & minor ap‐
1199 plied for the logic and textmajor & textminor for the warnings
1200 message. In builds using C++14 standard or earlier, where enu‐
1201 merator attributes are not yet supported, the macro will always
1202 yield an empty string. Useful for retroactive tagging of API
1203 for the compiler without injecting the API into the compiler
1204 warning conditions of already released versions. With MSVC it
1205 is also always an empty string for now. Since 5.82.
1206 <prefix_name><uppercase_base_name>_ENABLE_DEPRECATED_SINCE(major, mi‐
1208 nor)
1209 evaluates to TRUE or FALSE depending on the visibility macro
1210 flags set (see below). To be used mainly with #if/#endif to mark
1211 sections of code which should be included depending on the visi‐
1212 bility requested.
1213 <prefix_name><uppercase_base_name>_BUILD_DEPRECATED_SINCE(major, minor)
1215 evaluates to TRUE or FALSE depending on the value of EX‐
1216 CLUDE_DEPRECATED_BEFORE_AND_AT. To be used mainly with #if/#en‐
1217 dif to mark sections of two types of code: implementation code
1218 for deprecated API and declaration code of deprecated API which
1219 only may be disabled at build time of the library for BC reasons
1220 (e.g. virtual methods, see notes below).
1221 <prefix_name><uppercase_base_name>_EXCLUDE_DEPRECATED_BEFORE_AND_AT
1223 holds the version used to exclude deprecated API at build time
1224 of the library.
1225 The macros used to control visibility when building against the library
1227 are:
1228 <prefix_name><uppercase_base_name>_DISABLE_DEPRECATED_BEFORE_AND_AT
1230 definition to set to a value in single hex number version nota‐
1231 tion (0x<major><minor><patchlevel>).
1232 <prefix_name><uppercase_base_name>_NO_DEPRECATED
1234 flag to define to disable all deprecated API, being a shortcut
1235 for settings <prefix_name><uppercase_base_name>_DISABLE_DEPRE‐
1236 CATED_BEFORE_AND_AT to the current version. If both are set,
1237 this flag overrules.
1238 <prefix_name><uppercase_base_name>_DEPRECATED_WARNINGS_SINCE
1240 definition to set to a value in single hex number version nota‐
1241 tion (0x<major><minor><patchlevel>). Warnings will be only acti‐
1242 vated for API deprecated up to and including the version. If
1243 <prefix_name><uppercase_base_name>_DISABLE_DEPRECATED_BE‐
1244 FORE_AND_AT is set (directly or via the group default), it will
1245 default to that version, resulting in no warnings. Otherwise the
1246 default is the current version, resulting in warnings for all
1247 deprecated API.
1248 <prefix_name><uppercase_base_name>_NO_DEPRECATED_WARNINGS
1250 flag to define to disable all deprecation warnings, being a
1251 shortcut for setting <prefix_name><uppercase_base_name>_DEPRE‐
1252 CATED_WARNINGS_SINCE to “0”. If both are set, this flag over‐
1253 rules.
1254 When the GROUP_BASE_NAME has been used, the same macros but with the
1256 given <group_base_name> prefix are available to define the defaults of
1257 these macros, if not explicitly set.
1258 WARNING:
1260 The tricks applied here for hiding deprecated API to the compiler
1261 when building against a library do not work for all deprecated API:
1262 • virtual methods need to stay visible to the compiler to build
1264 proper virtual method tables for subclasses
1265 • enumerators from enums cannot be simply removed, as this changes
1267 auto values of following enumerators, also can poke holes in enu‐
1268 merator series used as index into tables
1269 In such cases the API can be only “hidden” at build time of the li‐
1271 brary, itself, by generated hard coded macro settings, using <pre‐
1272 fix_name><uppercase_base_name>_BUILD_DEPRECATED_SINCE(major, minor).
1273 Examples:
1275 Preparing a library “Foo” created by target “foo”, which is part of a
1277 group of libraries “Bar”, where some API of “Foo” got deprecated at
1278 versions 5.0 & 5.12:
1279 ecm_generate_export_header(foo
1281 GROUP_BASE_NAME BAR
1282 VERSION ${FOO_VERSION}
1283 DEPRECATION_VERSIONS 5.0 5.12
1284 )
1285 In the library “Foo” sources in the headers the API would be prepared
1287 like this, using the generated macros FOO_ENABLE_DEPRECATED_SINCE and
1288 FOO_DEPRECATED_VERSION:
1289 #include <foo_export.h>
1291 #if FOO_ENABLE_DEPRECATED_SINCE(5, 0)
1293 /**
1294 * @deprecated Since 5.0
1295 */
1296 FOO_EXPORT
1297 FOO_DEPRECATED_VERSION(5, 0, "Use doFoo2()")
1298 void doFoo();
1299 #endif
1300 #if FOO_ENABLE_DEPRECATED_SINCE(5, 12)
1302 /**
1303 * @deprecated Since 5.12
1304 */
1305 FOO_EXPORT
1306 FOO_DEPRECATED_VERSION(5, 12, "Use doBar2()")
1307 void doBar();
1308 #endif
1309 Projects linking against the “Foo” library can control which part of
1311 its deprecated API should be hidden to the compiler by adding a defini‐
1312 tion using the FOO_DISABLE_DEPRECATED_BEFORE_AND_AT macro variable set
1313 to the desired value (in version hex number notation):
1314 add_definitions(-DFOO_DISABLE_DEPRECATED_BEFORE_AND_AT=0x050000)
1316 Or using the macro variable of the group:
1318 add_definitions(-DBAR_DISABLE_DEPRECATED_BEFORE_AND_AT=0x050000)
1320 If both are specified, FOO_DISABLE_DEPRECATED_BEFORE_AND_AT will take
1322 precedence.
1323 To build a variant of a library with some deprecated API completely
1325 left out from the build, not only optionally invisible to consumers,
1326 one uses the EXCLUDE_DEPRECATED_BEFORE_AND_AT parameter. This is best
1327 combined with a cached CMake variable.
1328 set(EXCLUDE_DEPRECATED_BEFORE_AND_AT 0 CACHE STRING "Control the range of deprecated API excluded from the build [default=0].")
1330 ecm_generate_export_header(foo
1332 VERSION ${FOO_VERSION}
1333 EXCLUDE_DEPRECATED_BEFORE_AND_AT ${EXCLUDE_DEPRECATED_BEFORE_AND_AT}
1334 DEPRECATION_VERSIONS 5.0 5.12
1335 )
1336 The macros used in the headers for library consumers are reused for
1338 disabling the API excluded in the build of the library. For disabling
1339 the implementation of that API as well as for disabling deprecated API
1340 which only can be disabled at build time of the library for BC reasons,
1341 one uses the generated macro FOO_BUILD_DEPRECATED_SINCE, like this:
1342 #include <foo_export.h>
1344 enum Bars {
1346 One,
1347 #if FOO_BUILD_DEPRECATED_SINCE(5, 0)
1348 Two FOO_ENUMERATOR_DEPRECATED_VERSION(5, 0, "Use Three"), // macro available since 5.82
1349 #endif
1350 Three,
1351 };
1352 #if FOO_ENABLE_DEPRECATED_SINCE(5, 0)
1354 /**
1355 * @deprecated Since 5.0
1356 */
1357 FOO_EXPORT
1358 FOO_DEPRECATED_VERSION(5, 0, "Use doFoo2()")
1359 void doFoo();
1360 #endif
1361 #if FOO_ENABLE_DEPRECATED_SINCE(5, 12)
1363 /**
1364 * @deprecated Since 5.12
1365 */
1366 FOO_EXPORT
1367 FOO_DEPRECATED_VERSION(5, 12, "Use doBar2()")
1368 void doBar();
1369 #endif
1370 class FOO_EXPORT Foo {
1372 public:
1373 #if FOO_BUILD_DEPRECATED_SINCE(5, 0)
1374 /**
1375 * @deprecated Since 5.0
1376 */
1377 FOO_DEPRECATED_VERSION(5, 0, "Feature removed")
1378 virtual void doWhat();
1379 #endif
1380 };
1381 #if FOO_BUILD_DEPRECATED_SINCE(5, 0)
1383 void doFoo()
1384 {
1385 // [...]
1386 }
1387 #endif
1388 #if FOO_BUILD_DEPRECATED_SINCE(5, 12)
1390 void doBar()
1391 {
1392 // [...]
1393 }
1394 #endif
1395 #if FOO_BUILD_DEPRECATED_SINCE(5, 0)
1397 void Foo::doWhat()
1398 {
1399 // [...]
1400 }
1401 #endif
1402 So e.g. if EXCLUDE_DEPRECATED_BEFORE_AND_AT is set to “5.0.0”, the enu‐
1404 merator Two as well as the methods ::doFoo() and Foo::doWhat() will be
1405 not available to library consumers. The methods will not have been com‐
1406 piled into the library binary, and the declarations will be hidden to
1407 the compiler, FOO_DISABLE_DEPRECATED_BEFORE_AND_AT also cannot be used
1408 to reactivate them.
1409 When using the NO_DEFINITION_EXPORT_TO_BUILD_INTERFACE and the project
1411 for the “Foo” library includes also tests and examples linking against
1412 the library and using deprecated API (like tests covering it), one bet‐
1413 ter explicitly sets FOO_DISABLE_DEPRECATED_BEFORE_AND_AT for those tar‐
1414 gets to the version before and at which all deprecated API has been ex‐
1415 cluded from the build. Even more when building against other libraries
1416 from the same group “Bar” and disabling some deprecated API of those
1417 libraries using the group macro BAR_DISABLE_DEPRECATED_BEFORE_AND_AT,
1418 which also works as default for FOO_DISABLE_DEPRECATED_BEFORE_AND_AT.
1419 To get the hex number style value the helper macro ecm_ex‐
1421 port_header_format_version() will be used:
1422 set(EXCLUDE_DEPRECATED_BEFORE_AND_AT 0 CACHE STRING "Control what part of deprecated API is excluded from build [default=0].")
1424 ecm_generate_export_header(foo
1426 VERSION ${FOO_VERSION}
1427 GROUP_BASE_NAME BAR
1428 EXCLUDE_DEPRECATED_BEFORE_AND_AT ${EXCLUDE_DEPRECATED_BEFORE_AND_AT}
1429 NO_DEFINITION_EXPORT_TO_BUILD_INTERFACE
1430 DEPRECATION_VERSIONS 5.0 5.12
1431 )
1432 ecm_export_header_format_version(${EXCLUDE_DEPRECATED_BEFORE_AND_AT}
1434 CURRENT_VERSION ${FOO_VERSION}
1435 HEXNUMBER_VAR foo_no_deprecated_before_and_at
1436 )
1437 # disable all deprecated API up to 5.9.0 from all other libs of group "BAR" that we use ourselves
1439 add_definitions(-DBAR_DISABLE_DEPRECATED_BEFORE_AND_AT=0x050900)
1440 add_executable(app app.cpp)
1442 target_link_libraries(app foo)
1443 target_compile_definitions(app
1444 PRIVATE "FOO_DISABLE_DEPRECATED_BEFORE_AND_AT=${foo_no_deprecated_before_and_at}")
1445 Since 5.64.0.
1447 ECMGenerateHeaders
1449 Generate C/C++ CamelCase forwarding headers.
1450 ecm_generate_headers(<camelcase_forwarding_headers_var>
1452 HEADER_NAMES <CamelCaseName> [<CamelCaseName> [...]]
1453 [ORIGINAL <CAMELCASE|LOWERCASE>]
1454 [HEADER_EXTENSION <header_extension>]
1455 [OUTPUT_DIR <output_dir>]
1456 [PREFIX <prefix>]
1457 [REQUIRED_HEADERS <variable>]
1458 [COMMON_HEADER <HeaderName>]
1459 [RELATIVE <relative_path>])
1460 For each CamelCase header name passed to HEADER_NAMES, a file of that
1462 name will be generated that will include a version with .h or, if set,
1463 .<header_extension> appended. For example, the generated header ClassA
1464 will include classa.h (or ClassA.h, see ORIGINAL). If a CamelCaseName
1465 consists of multiple comma-separated files, e.g. ClassA,ClassB,ClassC,
1466 then multiple camelcase header files will be generated which are redi‐
1467 rects to the first header file. The file locations of these generated
1468 headers will be stored in <camelcase_forwarding_headers_var>.
1469 ORIGINAL specifies how the name of the original header is written: low‐
1471 ercased or also camelcased. The default is “LOWERCASE”. Since 1.8.0.
1472 HEADER_EXTENSION specifies what file name extension is used for the
1474 header files. The default is “h”. Since 5.48.0.
1475 PREFIX places the generated headers in subdirectories. This should be
1477 a CamelCase name like KParts, which will cause the CamelCase forwarding
1478 headers to be placed in the KParts directory (e.g. KParts/Part). It
1479 will also, for the convenience of code in the source distribution, gen‐
1480 erate forwarding headers based on the original names (e.g.
1481 kparts/part.h). This allows includes like "#include <kparts/part.h>"
1482 to be used before installation, as long as the include_directories are
1483 set appropriately.
1484 OUTPUT_DIR specifies where the files will be generated; this should be
1486 within the build directory. By default, ${CMAKE_CURRENT_BINARY_DIR}
1487 will be used. This option can be used to avoid file conflicts.
1488 REQUIRED_HEADERS specifies an output variable name where all the re‐
1490 quired headers will be appended so that they can be installed together
1491 with the generated ones. This is mostly intended as a convenience so
1492 that adding a new header to a project only requires specifying the
1493 CamelCase variant in the CMakeLists.txt file; the original variant will
1494 then be added to this variable.
1495 COMMON_HEADER generates an additional convenience header which includes
1497 all other header files.
1498 The RELATIVE argument indicates where the original headers can be found
1500 relative to CMAKE_CURRENT_SOURCE_DIR. It does not affect the generated
1501 CamelCase forwarding files, but ecm_generate_headers() uses it when
1502 checking that the original header exists, and to generate originally
1503 named forwarding headers when PREFIX is set.
1504 To allow other parts of the source distribution (eg: tests) to use the
1506 generated headers before installation, it may be desirable to set the
1507 INCLUDE_DIRECTORIES property for the library target to output_dir. For
1508 example, if OUTPUT_DIR is CMAKE_CURRENT_BINARY_DIR (the default), you
1509 could do
1510 target_include_directories(MyLib PUBLIC "$<BUILD_INTERFACE:${CMAKE_CURRENT_BINARY_DIR}>")
1512 Example usage (without PREFIX):
1514 ecm_generate_headers(
1516 MyLib_FORWARDING_HEADERS
1517 HEADERS
1518 MLFoo
1519 MLBar
1520 # etc
1521 REQUIRED_HEADERS MyLib_HEADERS
1522 COMMON_HEADER MLGeneral
1523 )
1524 install(FILES ${MyLib_FORWARDING_HEADERS} ${MyLib_HEADERS}
1525 DESTINATION ${CMAKE_INSTALL_PREFIX}/include
1526 COMPONENT Devel)
1527 Example usage (with PREFIX):
1529 ecm_generate_headers(
1531 MyLib_FORWARDING_HEADERS
1532 HEADERS
1533 Foo
1534 # several classes are contained in bar.h, so generate
1535 # additional files
1536 Bar,BarList
1537 # etc
1538 PREFIX MyLib
1539 REQUIRED_HEADERS MyLib_HEADERS
1540 )
1541 install(FILES ${MyLib_FORWARDING_HEADERS}
1542 DESTINATION ${CMAKE_INSTALL_PREFIX}/include/MyLib
1543 COMPONENT Devel)
1544 install(FILES ${MyLib_HEADERS}
1545 DESTINATION ${CMAKE_INSTALL_PREFIX}/include/mylib
1546 COMPONENT Devel)
1547 Since pre-1.0.0.
1549 ECMGeneratePkgConfigFile
1551 Generate a pkg-config file for the benefit of autotools-based projects.
1552 ecm_generate_pkgconfig_file(BASE_NAME <baseName>
1554 [LIB_NAME <libName>]
1555 [DEPS [PRIVATE|PUBLIC] <dep> [[PRIVATE|PUBLIC] <dep> [...]]]
1556 [FILENAME_VAR <filename_variable>]
1557 [INCLUDE_INSTALL_DIR <dir>]
1558 [LIB_INSTALL_DIR <dir>]
1559 [DEFINES -D<variable=value>...]
1560 [DESCRIPTION <library description>] # since 5.41.0
1561 [URL <url>] # since 5.89.0
1562 [INSTALL])
1563 BASE_NAME is the name of the module. It’s the name projects will use to
1565 find the module.
1566 LIB_NAME is the name of the library that is being exported. If unde‐
1568 fined, it will default to the BASE_NAME. That means the LIB_NAME will
1569 be set as the name field as well as the library to link to.
1570 DEPS is the list of libraries required by this library. Libraries that
1572 are not exposed to applications should be marked with PRIVATE. The de‐
1573 fault is PUBLIC, but note that according to the Guide to pkg-config
1574 marking dependencies as private is usually preferred. The PUBLIC and
1575 PRIVATE keywords are supported since 5.89.0.
1576 FILENAME_VAR is specified with a variable name. This variable will re‐
1578 ceive the location of the generated file will be set, within the build
1579 directory. This way it can be used in case some processing is required.
1580 See also INSTALL.
1581 INCLUDE_INSTALL_DIR specifies where the includes will be installed. If
1583 it’s not specified, it will default to INSTALL_INCLUDEDIR, CMAKE_IN‐
1584 STALL_INCLUDEDIR or just “include/” in case they are specified, with
1585 the BASE_NAME postfixed.
1586 LIB_INSTALL_DIR specifies where the library is being installed. If it’s
1588 not specified, it will default to LIB_INSTALL_DIR, CMAKE_INSTALL_LIBDIR
1589 or just “lib/” in case they are specified.
1590 DEFINES is a list of preprocessor defines that it is recommended users
1592 of the library pass to the compiler when using it.
1593 DESCRIPTION describes what this library is. If it’s not specified,
1595 CMake will first try to get the description from the metainfo.yaml file
1596 or will create one based on LIB_NAME. Since 5.41.0.
1597 URL An URL where people can get more information about and download the
1599 package. Defaults to “https://www.kde.org/”. Since 5.89.0.
1600 INSTALL will cause the module to be installed to the pkgconfig subdi‐
1602 rectory of LIB_INSTALL_DIR, unless the ECM_PKGCONFIG_INSTALL_DIR cache
1603 variable is set to something different.
1604 NOTE:
1606 The first call to ecm_generate_pkgconfig_file() with the INSTALL ar‐
1607 gument will cause ECM_PKGCONFIG_INSTALL_DIR to be set to the cache,
1608 and will be used in any subsequent calls.
1609 To properly use this macro a version needs to be set. To retrieve it,
1611 ECM_PKGCONFIG_INSTALL_DIR uses PROJECT_VERSION. To set it, use the
1612 project() command or the ecm_setup_version() macro
1613 Example usage:
1615 ecm_generate_pkgconfig_file(
1617 BASE_NAME KF5Archive
1618 DEPS Qt5Core
1619 FILENAME_VAR pkgconfig_filename
1620 INSTALL
1621 )
1622 Since 1.3.0.
1624 ECMGeneratePriFile
1626 Generate a .pri file for the benefit of qmake-based projects.
1627 As well as the function below, this module creates the cache variable
1629 ECM_MKSPECS_INSTALL_DIR and sets the default value to mkspecs/modules.
1630 This assumes Qt and the current project are both installed to the same
1631 non-system prefix. Packagers who use -DCMAKE_INSTALL_PREFIX=/usr will
1632 certainly want to set ECM_MKSPECS_INSTALL_DIR to something like
1633 share/qt5/mkspecs/modules.
1634 The main thing is that this should be the modules subdirectory of ei‐
1636 ther the default qmake mkspecs directory or of a directory that will be
1637 in the $QMAKEPATH environment variable when qmake is run.
1638 ecm_generate_pri_file(BASE_NAME <baseName>
1640 LIB_NAME <libName>
1641 [VERSION <version>] # since 5.83
1642 [DEPS "<dep> [<dep> [...]]"]
1643 [FILENAME_VAR <filename_variable>]
1644 [INCLUDE_INSTALL_DIRS <dir> [<dir> [...]]] # since 5.92
1645 [INCLUDE_INSTALL_DIR <dir>] # deprecated since 5.92
1646 [LIB_INSTALL_DIR <dir>])
1647 If your CMake project produces a Qt-based library, you may expect there
1649 to be applications that wish to use it that use a qmake-based build
1650 system, rather than a CMake-based one. Creating a .pri file will make
1651 use of your library convenient for them, in much the same way that
1652 CMake config files make things convenient for CMake-based applications.
1653 ecm_generate_pri_file() generates just such a file.
1654 VERSION specifies the version of the library the .pri file describes.
1656 If not set, the value is taken from the context variable PROJECT_VER‐
1657 SION. This variable is usually set by the project(... VERSION ...)
1658 command or, if CMake policy CMP0048 is not NEW, by ECMSetupVersion.
1659 For backward-compatibility with older ECM versions the PROJECT_VER‐
1660 SION_STRING variable as set by ECMSetupVersion will be preferred over
1661 PROJECT_VERSION if set, unless the minimum required version of ECM is
1662 5.83 and newer. Since 5.83.
1663 BASE_NAME specifies the name qmake project (.pro) files should use to
1665 refer to the library (eg: KArchive). LIB_NAME is the name of the ac‐
1666 tual library to link to (ie: the first argument to add_library()).
1667 DEPS is a space-separated list of the base names of other libraries
1668 (for Qt libraries, use the same names you use with the QT variable in a
1669 qmake project file, such as “core” for QtCore). FILENAME_VAR specifies
1670 the name of a variable to store the path to the generated file in.
1671 INCLUDE_INSTALL_DIRS are the paths (relative to CMAKE_INSTALL_PREFIX)
1673 that include files will be installed to. It defaults to ${INCLUDE_IN‐
1674 STALL_DIR}/<baseName> if the INCLUDE_INSTALL_DIR variable is set. If
1675 that variable is not set, the CMAKE_INSTALL_INCLUDEDIR variable is used
1676 instead, and if neither are set include is used. LIB_INSTALL_DIR oper‐
1677 ates similarly for the installation location for libraries; it defaults
1678 to ${LIB_INSTALL_DIR}, ${CMAKE_INSTALL_LIBDIR} or lib, in that order.
1679 INCLUDE_INSTALL_DIR is the old variant of INCLUDE_INSTALL_DIRS, taking
1681 only one directory.
1682 Example usage:
1684 ecm_generate_pri_file(
1686 BASE_NAME KArchive
1687 LIB_NAME KF5KArchive
1688 DEPS "core"
1689 FILENAME_VAR pri_filename
1690 VERSION 4.2.0
1691 )
1692 install(FILES ${pri_filename} DESTINATION ${ECM_MKSPECS_INSTALL_DIR})
1693 A qmake-based project that wished to use this would then do:
1695 QT += KArchive
1697 in their .pro file.
1699 Since pre-1.0.0.
1701 ECMGenerateQmlTypes
1703 Generates plugins.qmltypes files for QML plugins.
1704 ecm_generate_qmltypes(<org.kde.pluginname> 1.3
1706 DESTINATION <${KDE_INSTALL_QMLDIR}/org/kde/pluginname>)
1707 Makes it possible to generate plugins.qmltypes files for the QML plug‐
1709 ins that our project offers. These files offer introspection upon our
1710 plugin and are useful for integrating with IDE language support of our
1711 plugin. It offers information about the objects its methods and their
1712 argument types.
1713 The developer will be in charge of making sure that these files are up
1715 to date. The plugin.qmltypes file will sit in the source directory.
1716 This function will include the code that installs the file in the right
1717 place and a small unit test named qmltypes-pluginname-version that
1718 makes sure that it doesn’t need updating.
1719 Since 5.33.0
1721 ECMInstallIcons
1723 Installs icons, sorting them into the correct directories according to
1724 the FreeDesktop.org icon naming specification.
1725 ecm_install_icons(ICONS <icon> [<icon> [...]]
1727 DESTINATION <icon_install_dir>
1728 [LANG <l10n_code>]
1729 [THEME <theme>])
1730 The given icons, whose names must match the pattern:
1732 <size>-<group>-<name>.<ext>
1734 will be installed to the appropriate subdirectory of DESTINATION ac‐
1736 cording to the FreeDesktop.org icon naming scheme. By default, they are
1737 installed to the “hicolor” theme, but this can be changed using the
1738 THEME argument. If the icons are localized, the LANG argument can be
1739 used to install them in a locale-specific directory.
1740 <size> is a numeric pixel size (typically 16, 22, 32, 48, 64, 128 or
1742 256) or sc for scalable (SVG) files, <group> is one of the standard
1743 FreeDesktop.org icon groups (actions, animations, apps, categories, de‐
1744 vices, emblems, emotes, intl, mimetypes, places, status) and <ext> is
1745 one of .png, .mng or .svgz.
1746 The typical installation directory is share/icons.
1748 ecm_install_icons(ICONS 22-actions-menu_new.png
1750 DESTINATION share/icons)
1751 The above code will install the file 22-actions-menu_new.png as
1753 ${CMAKE_INSTALL_PREFIX}/share/icons/<theme>/22x22/actions/menu_new.png
1754 Users of the KDEInstallDirs module would normally use ${KDE_IN‐
1756 STALL_ICONDIR} as the DESTINATION, while users of the GNUInstallDirs
1757 module should use ${CMAKE_INSTALL_DATAROOTDIR}/icons.
1758 An old form of arguments will also be accepted:
1760 ecm_install_icons(<icon_install_dir> [<l10n_code>])
1762 This matches files named like:
1764 <theme><size>-<group>-<name>.<ext>
1766 where <theme> is one of
1768 • hi for hicolor
1770 • lo for locolor
1772 • cr for the Crystal icon theme
1774 • ox for the Oxygen icon theme
1776 • br for the Breeze icon theme
1778 With this syntax, the file hi22-actions-menu_new.png would be installed
1780 into <icon_install_dir>/hicolor/22x22/actions/menu_new.png
1781 Since pre-1.0.0.
1783 ECMMarkAsTest
1785 Marks a target as only being required for tests.
1786 ecm_mark_as_test(<target1> [<target2> [...]])
1788 This will cause the specified targets to not be built unless either
1790 BUILD_TESTING is set to ON or the user invokes the buildtests target.
1791 BUILD_TESTING is created as a cache variable by the CTest module and by
1793 the KDECMakeSettings module.
1794 Since pre-1.0.0.
1796 ECMMarkNonGuiExecutable
1798 Marks an executable target as not being a GUI application.
1799 ecm_mark_nongui_executable(<target1> [<target2> [...]])
1801 This will indicate to CMake that the specified targets should not be
1803 included in a MACOSX_BUNDLE and should not be WIN32_EXECUTABLEs. On
1804 platforms other than MacOS X or Windows, this will have no effect.
1805 Since pre-1.0.0.
1807 ECMOptionalAddSubdirectory
1809 Make subdirectories optional.
1810 ecm_optional_add_subdirectory(<dir>)
1812 This behaves like add_subdirectory(), except that it does not complain
1814 if the directory does not exist. Additionally, if the directory does
1815 exist, it creates an option to allow the user to skip it. The option
1816 will be named BUILD_<dir>.
1817 This is useful for “meta-projects” that combine several mostly-indepen‐
1819 dent sub-projects.
1820 If the CMake variable DISABLE_ALL_OPTIONAL_SUBDIRECTORIES is set to
1822 TRUE for the first CMake run on the project, all optional subdirecto‐
1823 ries will be disabled by default (but can of course be enabled via the
1824 respective options). For example, the following will disable all op‐
1825 tional subdirectories except the one named “foo”:
1826 cmake -DDISABLE_ALL_OPTIONAL_SUBDIRECTORIES=TRUE -DBUILD_foo=TRUE myproject
1828 Since pre-1.0.0.
1830 ECMPackageConfigHelpers
1832 Helper macros for generating CMake package config files.
1833 write_basic_package_version_file() is the same as the one provided by
1835 the CMakePackageConfigHelpers module in CMake; see that module’s docu‐
1836 mentation for more information.
1837 ecm_configure_package_config_file(<input> <output>
1839 INSTALL_DESTINATION <path>
1840 [PATH_VARS <var1> [<var2> [...]]
1841 [NO_SET_AND_CHECK_MACRO]
1842 [NO_CHECK_REQUIRED_COMPONENTS_MACRO])
1843 This behaves in the same way as configure_package_config_file() from
1845 CMake 2.8.12, except that it adds an extra helper macro: find_depen‐
1846 dency(). It is highly recommended that you read the documentation for
1847 CMakePackageConfigHelpers for more information, particularly with re‐
1848 gard to the PATH_VARS argument.
1849 Note that there is no argument that will disable the find_dependency()
1851 macro; if you do not require this macro, you should use configure_pack‐
1852 age_config_file from the CMakePackageConfigHelpers module.
1853 CMake 3.0 includes a CMakeFindDependencyMacro module that provides the
1855 find_dependency() macro (which you can include() in your package config
1856 file), so this file is only useful for projects wishing to provide con‐
1857 fig files that will work with CMake 2.8.12.
1858 Additional Config File Macros
1860 find_dependency(<dep> [<version> [EXACT]])
1861 find_dependency() should be used instead of find_package() to find
1863 package dependencies. It forwards the correct parameters for EXACT,
1864 QUIET and REQUIRED which were passed to the original find_package()
1865 call. It also sets an informative diagnostic message if the dependency
1866 could not be found.
1867 Since pre-1.0.0.
1869 ECMPoQmTools
1871 This module provides the ecm_process_po_files_as_qm and ecm_in‐
1872 stall_po_files_as_qm functions for generating QTranslator (.qm) cata‐
1873 logs from Gettext (.po) catalogs, and the ecm_create_qm_loader function
1874 for generating the necessary code to load them in a Qt application or
1875 library.
1876 ecm_process_po_files_as_qm(<lang> [ALL]
1878 [INSTALL_DESTINATION <install_destination>]
1879 PO_FILES <pofile> [<pofile> [...]])
1880 Compile .po files into .qm files for the given language.
1882 If INSTALL_DESTINATION is given, the .qm files are installed in <in‐
1884 stall_destination>/<lang>/LC_MESSAGES. Typically, <install_destination>
1885 is set to share/locale.
1886 ecm_process_po_files_as_qm creates a “translations” target. This target
1888 builds all .po files into .qm files. If ALL is specified, these rules
1889 are added to the “all” target (and so the .qm files will be built by
1890 default).
1891 ecm_create_qm_loader(<sources_var_name(|target (since 5.83))> <catalog_name>)
1893 Generates C++ code which ensures translations are automatically loaded
1895 at startup. The generated files are appended to the variable named
1896 <sources_var_name> or, if the first argument is a target (since 5.83),
1897 to the SOURCES property of <target>. Any target must be created with
1898 add_executable() or add_library() and not be an alias.
1899 It assumes that the .qm file for the language code <lang> is installed
1901 as <sharedir>/locale/<lang>/LC_MESSAGES/<catalog_name>.qm, where
1902 <sharedir> is one of the directories given by the GenericDataLocation
1903 of QStandardPaths.
1904 Typical usage is like:
1906 set(mylib_SRCS foo.cpp bar.cpp)
1908 ecm_create_qm_loader(mylib_SRCS mycatalog)
1909 add_library(mylib ${mylib_SRCS})
1910 # Or, since 5.83:
1912 add_library(mylib foo.cpp bar.cpp)
1913 ecm_create_qm_loader(mylib mycatalog)
1914 ecm_install_po_files_as_qm(<podir>)
1916 Searches for .po files and installs them to the standard location.
1918 This is a convenience function which relies on all .po files being kept
1920 in <podir>/<lang>/, where <lang> is the language the .po files are
1921 written in.
1922 For example, given the following directory structure:
1924 po/
1926 fr/
1927 mylib.po
1928 ecm_install_po_files_as_qm(po) compiles mylib.po into mylib.qm and in‐
1930 stalls it in <install_destination>/fr/LC_MESSAGES. <install_destina‐
1931 tion> defaults to ${LOCALE_INSTALL_DIR} if defined, otherwise it uses
1932 ${CMAKE_INSTALL_LOCALEDIR} if that is defined, otherwise it uses
1933 share/locale.
1934 Since pre-1.0.0.
1936 ECMQmlModule
1938 This file contains helper functions to make it easier to create QML
1939 modules. It takes care of a number of things that often need to be re‐
1940 peated. It also takes care of special handling of QML modules between
1941 shared and static builds. When building a static version of a QML mod‐
1942 ule, the relevant QML source files are bundled into the static library.
1943 When using a shared build, the QML plugin and relevant QML files are
1944 copied to the target’s RUNTIME_OUTPUT_DIRECTORY to make it easier to
1945 run things directly from the build directory.
1946 Example usage:
1948 ecm_add_qml_module(ExampleModule URI "org.example.Example" VERSION 1.4)
1950 target_sources(ExampleModule PRIVATE ExamplePlugin.cpp)
1952 target_link_libraries(ExampleModule PRIVATE Qt::Quick)
1953 ecm_target_qml_sources(ExampleModule SOURCES ExampleItem.qml)
1955 ecm_target_qml_sources(ExampleModule SOURCES AnotherExampleItem.qml VERSION 1.5)
1956 ecm_finalize_qml_module(ExampleModule DESTINATION ${KDE_INSTALL_QMLDIR})
1958 ecm_add_qml_module(<target name> URI <module uri> [VERSION <module version>] [NO_PLUGIN] [CLASSNAME <class name>])
1960 This will declare a new CMake target called <target name>. The URI ar‐
1962 gument is required and should be a proper QML module URI. The URI is
1963 used, among others, to generate a subdirectory where the module will be
1964 installed to.
1965 If the VERSION argument is specified, it is used to initialize the de‐
1967 fault version that is used by ecm_target_qml_sources when adding QML
1968 files. If it is not specified, a default of 1.0 is used. Additionally,
1969 if a version greater than or equal to 2.0 is specified, the major ver‐
1970 sion is appended to the installation path of the module.
1971 If the option NO_PLUGIN is set, a target is declared that is not ex‐
1973 pected to contain any C++ QML plugin.
1974 If the optional CLASSNAME argument is supplied, it will be used as
1976 class name in the generated QMLDIR file. If it is not specified, the
1977 target name will be used instead.
1978 You can add C++ and QML source files to the target using target_sources
1980 and ecm_target_qml_sources, respectively.
1981 Since 5.91.0
1983 ecm_add_qml_module_dependencies(<target> DEPENDS <module string> [<module string> ...])
1985 Add the list of dependencies specified by the DEPENDS argument to be
1987 listed as dependencies in the generated QMLDIR file of <target>.
1988 Since 5.91.0
1990 ecm_target_qml_sources(<target> SOURCES <source.qml> [<source.qml> ...] [VERSION <version>] [PATH <path>] [PRIVATE])
1992 Add the list of QML files specified by the SOURCES argument as source
1994 files to the QML module target <target>.
1995 If the optional VERSION argument is specified, all QML files will be
1997 added with the specified version. If it is not specified, they will use
1998 the version of the QML module target.
1999 If the optional PRIVATE argument is specified, the QML files will be
2001 included in the target but not in the generated qmldir file. Any ver‐
2002 sion argument will be ignored.
2003 The optional PATH argument declares a subdirectory of the module where
2005 the files should be copied to. By default, files will be copied to the
2006 module root.
2007 This function will fail if <target> is not a QML module target or any
2009 of the specified files do not exist.
2010 Since 5.91.0
2012 ecm_finalize_qml_module(<target> DESTINATION <QML install destination>)
2014 Finalize the specified QML module target. This must be called after all
2016 other setup (like adding sources) on the target has been done. It will
2017 perform a number of tasks:
2018 • It will generate a qmldir file from the QML files added to the tar‐
2020 get. If the module has a C++ plugin, this will also be included in
2021 the qmldir file.
2022 • If BUILD_SHARED_LIBS is off, a QRC file is generated from the QML
2024 files added to the target. This QRC file will be included when com‐
2025 piling the C++ QML module. The built static library will be installed
2026 in a subdirection of DESTINATION based on the QML module’s uri. Note
2027 that if NO_PLUGIN is set, a C++ QML plugin will be generated to in‐
2028 clude the QRC files.
2029 • If BUILD_SHARED_LIBS in on, all generated files, QML sources and the
2031 C++ plugin will be installed in a subdirectory of DESTINATION based
2032 upon the QML module’s uri. In addition, these files will also be
2033 copied to the target’s RUNTIME_OUTPUT_DIRECTORY in a similar subdi‐
2034 rectory.
2035 This function will fail if <target> is not a QML module target.
2037 Since 5.91.0
2039 ECMQtDeclareLoggingCategory
2041 This module provides the ecm_qt_declare_logging_category function for
2042 generating declarations for logging categories in Qt5, and the
2043 ecm_qt_install_logging_categories function for generating and in‐
2044 stalling a file in KDebugSettings format with the info about all those
2045 categories, as well as a file with info about any renamed categories if
2046 defined. To include in that file any logging categories that are manu‐
2047 ally defined also a function ecm_qt_export_logging_category is pro‐
2048 vided.
2049 ecm_qt_declare_logging_category(<sources_var_name(|target (since 5.80))>
2051 HEADER <filename>
2052 IDENTIFIER <identifier>
2053 CATEGORY_NAME <category_name>
2054 [OLD_CATEGORY_NAMES <oldest_cat_name> [<second_oldest_cat_name> [...]]]
2055 [DEFAULT_SEVERITY <Debug|Info|Warning|Critical|Fatal>]
2056 [EXPORT <exportid>]
2057 [DESCRIPTION <description>]
2058 )
2059 A header file, <filename>, will be generated along with a corresponding
2061 source file. These will provide a QLoggingCategory category that can be
2062 referred to from C++ code using <identifier>, and from the logging con‐
2063 figuration using <category_name>.
2064 The generated source file will be added to the variable with the name
2066 <sources_var_name>. If the given argument is a target though, instead
2067 both the generated header file and the generated source file will be
2068 added to the target as private sources (since 5.80). The target must
2069 not be an alias.
2070 If <filename> is not absolute, it will be taken relative to the current
2072 binary directory.
2073 <identifier> may include namespaces (eg: foo::bar::IDENT).
2075 If EXPORT is passed, the category will be registered for the group id
2077 <exportid>. Info about the categories of that group can then be gener‐
2078 ated in a file and installed by that group id with the ecm_qt_in‐
2079 stall_logging_categories function. In that case also DESCRIPTION will
2080 need to be passed, with <description> being a short single line text.
2081 And OLD_CATEGORY_NAMES can be used to inform about any renamings of the
2082 category, so user settings can be migrated. Since 5.68.0.
2083 Since 5.14.0.
2085 ecm_qt_export_logging_category(
2087 IDENTIFIER <identifier>
2088 CATEGORY_NAME <category_name>
2089 [OLD_CATEGORY_NAMES <oldest_category_name> [<second_oldest_category_name> [...]]]
2090 EXPORT <exportid>
2091 DESCRIPTION <description>
2092 [DEFAULT_SEVERITY <Debug|Info|Warning|Critical|Fatal>]
2093 )
2094 Registers a logging category for being included in the generated and
2096 installed KDebugSettings files. To be used for categories who are de‐
2097 clared by manual code or other ways instead of code generated with
2098 ecm_qt_declare_logging_category.
2099 <identifier> may include namespaces (eg: foo::bar::IDENT).
2101 EXPORT specifies the group id with which the category will be regis‐
2103 tered. Info about the categories of that group can then be generated
2104 in a file and installed by that group id with the ecm_qt_install_log‐
2105 ging_categories function.
2106 DESCRIPTION specifies a short single line text describing the category.
2108 OLD_CATEGORY_NAMES can be used to inform about any renamings of the
2110 category, so user settings can be migrated.
2111 Since 5.68.0.
2113 ecm_qt_install_logging_categories(
2115 EXPORT <exportid>
2116 [FILE <filename>]
2117 DESTINATION <install_path>
2118 [SORT]
2119 [COMPONENT <component>]
2120 )
2121 Generates and installs a file in KDebugSettings format with the info
2123 about all the categories registered for the group <exportid>, as well
2124 as a file with info about any renamed categories, if there are.
2125 The method call needs to be after the last ecm_qt_declare_logging_cate‐
2127 gory call which uses the same <exportid>. This can be in the same di‐
2128 rectory, or any subdirectory or parent directory.
2129 EXPORT specifies the group id of categories whose information should be
2131 stored in the file generated and installed.
2132 FILE specifies the name of the file generated and installed. It will
2134 default to lower-cased <exportid>.categories.
2135 DESTINATION specifies where the generated file will be installed.
2137 IF SORT is set, entries will be sorted by identifiers.
2139 COMPONENT specifies the installation component name with which the in‐
2141 stall rules for the generated file are associated.
2142 Since 5.85.0 this is a no-op when building for Android, as KDebugSet‐
2144 tings is not available on that platform and the logging category files
2145 therefore just bloat the APK.
2146 Example usage:
2148 ecm_qt_declare_logging_category(
2150 MYPROJECT_SRCS
2151 HEADER "myproject_debug.h"
2152 IDENTIFIER "MYPROJECT_DEBUG"
2153 CATEGORY_NAME "myproject"
2154 OLD_CATEGORY_NAMES "myprojectlog"
2155 DESCRIPTION "My project"
2156 EXPORT MyProject
2157 )
2158 ecm_qt_export_logging_category(
2160 IDENTIFIER "MYPROJECT_SUBMODULE_DEBUG"
2161 CATEGORY_NAME "myproject.submodule"
2162 DESCRIPTION "My project - submodule"
2163 EXPORT MyProject
2164 )
2165 ecm_qt_install_logging_categories(
2167 EXPORT MyProject
2168 FILE myproject.categories
2169 DESTINATION "${KDE_INSTALL_LOGGINGCATEGORIESDIR}"
2170 )
2171 Since 5.68.0.
2173 ECMQueryQt
2175 This module can be used to query the installation paths used by Qt.
2176 For Qt5 this uses qmake, and for Qt6 this used qtpaths (the latter has
2178 built-in support to query the paths of a target platform when
2179 cross-compiling).
2180 This module defines the following function:
2182 ecm_query_qt(<result_variable> <qt_variable> [TRY])
2184 Passing TRY will result in the method not making the build fail if the
2186 executable used for querying has not been found, but instead simply
2187 print a warning message and return an empty string.
2188 Example usage:
2190 include(ECMQueryQt)
2192 ecm_query_qt(bin_dir QT_INSTALL_BINS)
2193 If the call succeeds ${bin_dir} will be set to <prefix>/path/to/bin/dir
2195 (e.g. /usr/lib64/qt/bin/).
2196 Since: 5.93
2198 ECMSetupQtPluginMacroNames
2200 Instruct CMake’s automoc about C++ preprocessor macros used to define
2201 Qt-style plugins.
2202 ecm_setup_qtplugin_macro_names(
2204 [JSON_NONE <macro_name> [<macro_name> [...]]]
2205 [JSON_ARG1 <macro_name> [<macro_name> [...]]]
2206 [JSON_ARG2 <macro_name> [<macro_name> [...]]]
2207 [JSON_ARG3 <macro_name> [<macro_name> [...]]]
2208 [CONFIG_CODE_VARIABLE <variable_name>] )
2209 CMake’s automoc needs some support when parsing C++ source files to de‐
2211 tect whether moc should be run on those files and if there are also de‐
2212 pendencies on other files, like those with Qt plugin metadata in JSON
2213 format. Because automoc just greps overs the raw plain text of the
2214 sources without any C++ preprocessor-like processing. CMake in newer
2215 versions provides the variables CMAKE_AUTOMOC_DEPEND_FILTERS (CMake >=
2216 3.9.0) and CMAKE_AUTOMOC_MACRO_NAMES (CMake >= 3.10) to allow the de‐
2217 veloper to assist automoc.
2218 This macro cares for the explicit setup needed for those variables for
2220 common cases of C++ preprocessor macros used for Qt-style plugins.
2221 JSON_NONE lists the names of C++ preprocessor macros for Qt-style plug‐
2223 ins which do not refer to external files with the plugin metadata.
2224 JSON_ARG1 lists the names of C++ preprocessor macros for Qt-style plug‐
2226 ins where the first argument to the macro is the name of the external
2227 file with the plugin metadata.
2228 JSON_ARG2 is the same as JSON_ARG1 but with the file name being the
2230 second argument.
2231 JSON_ARG3 is the same as JSON_ARG1 but with the file name being the
2233 third argument.
2234 CONFIG_CODE_VARIABLE specifies the name of the variable which will get
2236 set as value some generated CMake code for instructing automoc for the
2237 given macro names, as useful in an installed CMake config file. The
2238 variable can then be used as usual in the template file for such a
2239 CMake config file, by @<variable_name>@.
2240 Example usage:
2242 Given some plugin-oriented Qt-based software which defines a custom C++
2244 preprocessor macro EXPORT_MYPLUGIN for declaring the central plugin ob‐
2245 ject:
2246 #define EXPORT_MYPLUGIN_WITH_JSON(classname, jsonFile) \
2248 class classname : public QObject \
2249 { \
2250 Q_OBJECT \
2251 Q_PLUGIN_METADATA(IID "myplugin" FILE jsonFile) \
2252 explicit classname() {} \
2253 };
2254 In the CMake buildsystem of the library one calls
2256 ecm_setup_qtplugin_macro_names(
2258 JSON_ARG2
2259 EXPORT_MYPLUGIN_WITH_JSON
2260 )
2261 to instruct automoc about the usage of that macro in the sources of the
2263 library itself.
2264 Given the software installs a library including the header with the
2266 macro definition and a CMake config file, so 3rd-party can create addi‐
2267 tional plugins by linking against the library, one passes additionally
2268 the name of a variable which shall be set as value the CMake code
2269 needed to instruct automoc about the usage of that macro.
2270 ecm_setup_qtplugin_macro_names(
2272 JSON_ARG2
2273 EXPORT_MYPLUGIN_WITH_JSON
2274 CONFIG_CODE_VARIABLE
2275 PACKAGE_SETUP_AUTOMOC_VARIABLES
2276 )
2277 This variable then is used in the template file (e.g. MyProjectCon‐
2279 fig.cmake.in) for the libary’s installed CMake config file and that way
2280 will ensure that in the 3rd-party plugin’s buildsystem automoc is in‐
2281 structed as well as needed:
2282 @PACKAGE_SETUP_AUTOMOC_VARIABLES@
2284 Since 5.45.0.
2286 ECMSetupVersion
2288 Handle library version information.
2289 ecm_setup_version(<version>
2291 VARIABLE_PREFIX <prefix>
2292 [SOVERSION <soversion>]
2293 [VERSION_HEADER <filename>]
2294 [PACKAGE_VERSION_FILE <filename> [COMPATIBILITY <compat>]] )
2295 This parses a version string and sets up a standard set of version
2297 variables. It can optionally also create a C version header file and a
2298 CMake package version file to install along with the library.
2299 If the <version> argument is of the form <major>.<minor>.<patch> (or
2301 <major>.<minor>.<patch>.<tweak>), The following CMake variables are
2302 set:
2303 <prefix>_VERSION_MAJOR - <major>
2305 <prefix>_VERSION_MINOR - <minor>
2306 <prefix>_VERSION_PATCH - <patch>
2307 <prefix>_VERSION - <version>
2308 <prefix>_SOVERSION - <soversion>, or <major> if SOVERSION was not given
2309 For backward-compatibility also this variable is set (only if the mini‐
2311 mum required version of ECM is < 5.83):
2312 <prefix>_VERSION_STRING - <version> (use <prefix>_VERSION instead)
2314 If CMake policy CMP0048 is not NEW, the following CMake variables will
2316 also be set:
2317 PROJECT_VERSION_MAJOR - <major>
2319 PROJECT_VERSION_MINOR - <minor>
2320 PROJECT_VERSION_PATCH - <patch>
2321 PROJECT_VERSION - <version>
2322 For backward-compatibility, if CMake policy CMP0048 is not NEW, also
2324 this variable is set (only if the minimum required version of ECM is <
2325 5.83):
2326 PROJECT_VERSION_STRING - <version> (use PROJECT_VERSION instead)
2328 If the VERSION_HEADER option is used, a simple C header is generated
2330 with the given filename. If filename is a relative path, it is inter‐
2331 preted as relative to CMAKE_CURRENT_BINARY_DIR. The generated header
2332 contains the following macros:
2333 <prefix>_VERSION_MAJOR - <major> as an integer
2335 <prefix>_VERSION_MINOR - <minor> as an integer
2336 <prefix>_VERSION_PATCH - <patch> as an integer
2337 <prefix>_VERSION_STRING - <version> as a C string
2338 <prefix>_VERSION - the version as an integer
2339 <prefix>_VERSION has <patch> in the bottom 8 bits, <minor> in the next
2341 8 bits and <major> in the remaining bits. Note that <patch> and <mi‐
2342 nor> must be less than 256.
2343 If the PACKAGE_VERSION_FILE option is used, a simple CMake package ver‐
2345 sion file is created using the write_basic_package_version_file() macro
2346 provided by CMake. It should be installed in the same location as the
2347 Config.cmake file of the library so that it can be found by find_pack‐
2348 age(). If the filename is a relative path, it is interpreted as rela‐
2349 tive to CMAKE_CURRENT_BINARY_DIR. The optional COMPATIBILITY option is
2350 forwarded to write_basic_package_version_file(), and defaults to
2351 AnyNewerVersion.
2352 If CMake policy CMP0048 is NEW, an alternative form of the command is
2354 available:
2355 ecm_setup_version(PROJECT
2357 [VARIABLE_PREFIX <prefix>]
2358 [SOVERSION <soversion>]
2359 [VERSION_HEADER <filename>]
2360 [PACKAGE_VERSION_FILE <filename>] )
2361 This will use the version information set by the project() command.
2363 VARIABLE_PREFIX defaults to the project name. Note that PROJECT must
2364 be the first argument. In all other respects, it behaves like the
2365 other form of the command.
2366 Since pre-1.0.0.
2368 COMPATIBILITY option available since 1.6.0.
2370 ECMSourceVersionControl
2372 Tries to determine whether the source is under version control (git
2373 clone, svn checkout, etc).
2374 ECM_SOURCE_UNDER_VERSION_CONTROL is set when indication is found that
2376 CMAKE_SOURCE_DIR is under version control.
2377 Since 5.63
2379 ECMUninstallTarget
2381 Add an uninstall target.
2382 By including this module, an uninstall target will be added to your
2384 CMake project. This will remove all files installed (or updated) by a
2385 previous invocation of the install target. It will not remove files
2386 created or modified by an install(SCRIPT) or install(CODE) command; you
2387 should create a custom uninstallation target for these and use add_de‐
2388 pendency to make the uninstall target depend on it:
2389 include(ECMUninstallTarget)
2391 install(SCRIPT install-foo.cmake)
2392 add_custom_target(uninstall_foo COMMAND ${CMAKE_COMMAND} -P uninstall-foo.cmake)
2393 add_dependency(uninstall uninstall_foo)
2394 The target will fail if the install target has not yet been run (so it
2396 is not possible to run CMake on the project and then immediately run
2397 the uninstall target).
2398 WARNING:
2400 CMake deliberately does not provide an uninstall target by default
2401 on the basis that such a target has the potential to remove impor‐
2402 tant files from a user’s computer. Use with caution.
2403 Since 1.7.0.
2405 ECMUseFindModules
2407 Selectively use some of the find modules provided by extra-cmake-mod‐
2408 ules.
2409 This module is automatically available once extra-cmake-modules has
2411 been found, so it is not necessary to include(ECMUseFindModules) ex‐
2412 plicitly.
2413 ecm_use_find_modules(DIR <dir>
2415 MODULES module1.cmake [module2.cmake [...]]
2416 [NO_OVERRIDE])
2417 This allows selective use of the find modules provided by ECM, includ‐
2419 ing deferring to CMake’s versions of those modules if it has them.
2420 Rather than adding ${ECM_FIND_MODULE_DIR} to CMAKE_MODULE_PATH, you use
2421 ecm_use_find_modules() to copy the modules you want to a local (build)
2422 directory, and add that to CMAKE_MODULE_PATH.
2423 The find modules given to MODULES will be copied to the directory given
2425 by DIR (which should be located in ${CMAKE_BINARY_DIR} and added to
2426 CMAKE_MODULE_PATH). If NO_OVERRIDE is given, only modules not also
2427 provided by CMake will be copied.
2428 Example:
2430 find_package(ECM REQUIRED)
2432 ecm_use_find_modules(
2433 DIR ${CMAKE_BINARY_DIR}/cmake
2434 MODULES FindEGL.cmake
2435 NO_OVERRIDE
2436 )
2437 set(CMAKE_MODULE_PATH ${CMAKE_BINARY_DIR}/cmake)
2438 This example will make FindEGL.cmake available in your project, but
2440 only as long as it is not yet part of CMake. Calls to find_package(EGL)
2441 will then make use of this copied module (or the CMake module if it ex‐
2442 ists).
2443 Another possible use for this macro is to take copies of find modules
2445 that can be installed along with config files if they are required as a
2446 dependency (for example, if targets provided by the find module are in
2447 the link interface of a library).
2448 Since pre-1.0.0.
2450 ECMWinResolveSymlinks
2452 Resolve pseudo-symlinks created by git when cloning on Windows.
2453 ecm_win_resolve_symlinks(<dir>)
2455 When git checks out a repository with UNIX symlinks on Windows machine,
2457 it creates a text file for each symlink, containing a relative path to
2458 the real file. This function would recursively walk over specified di‐
2459 rectory and replace pseudo-symlinks with corresponding real file’s con‐
2460 tents. It would then run git update-index --assume-unchanged on them to
2461 trick git.
2462 This is useful for projects like “breeze-icons” that contain many iden‐
2464 tical icons implemented as symlinks.
2465 Since 5.28
2467 QtVersionOption
2469 Adds a build option to select the major Qt version if necessary, that
2470 is, if the major Qt version has not yet been determined otherwise (e.g.
2471 by a corresponding find_package() call). This module is typically in‐
2472 cluded by other modules requiring knowledge about the major Qt version.
2473 QT_MAJOR_VERSION is defined to either be “5” or “6”.
2475 Since 5.82.0.
2477
2479 ecm(7), ecm-find-modules(7), ecm-kde-modules(7)
2480
2482 KDE Developers
24835.111 Oct 14, 2023 ECM-MODULES(7)