1ECM-MODULES(7) Extra CMake Modules ECM-MODULES(7)
2
6 ecm-modules - ECM Modules Reference
7
9 Extra CMake Modules (ECM) provides various modules that provide useful
10 functions for CMake scripts. ECM actually provides three types of mod‐
11 ules that can be used from CMake scripts: those that extend the func‐
12 tionality of the find_package command are documented in ecm-find-mod‐
13 ules(7); those that provide standard settings for software produced by
14 the KDE community are documented in ecm-kde-modules(7). The rest pro‐
15 vide macros and functions for general use by CMake scripts and are doc‐
16 umented here.
17 To use these modules, you need to tell CMake to find the ECM package,
19 and then add either ${ECM_MODULE_PATH} or ${ECM_MODULE_DIR} to the
20 CMAKE_MODULE_PATH variable:
21 find_package(ECM REQUIRED NO_MODULE)
23 set(CMAKE_MODULE_PATH ${ECM_MODULE_DIR})
24 Using ${ECM_MODULE_PATH} will also make the find modules and KDE mod‐
26 ules available.
27 Note that there are also toolchain modules, documented in
29 ecm-toolchains(7), but these are used by users building the software
30 rather than developers writing CMake scripts.
31
33 ECMAddAppIcon
34 Add icons to executable files and packages.
35 ecm_add_app_icon(<sources_var>
37 ICONS <icon> [<icon> [...]]
38 [SIDEBAR_ICONS <icon> [<icon> [...]] # Since 5.49
39 [OUTFILE_BASENAME <name>]) # Since 5.49
40 )
41 The given icons, whose names must match the pattern:
43 <size>-<other_text>.png
45 will be added to the executable target whose sources are specified by
47 <sources_var> on platforms that support it (Windows and Mac OS X).
48 Other icon files are ignored but on Mac SVG files can be supported and
49 it is thus possible to mix those with png files in a single macro call.
50 <size> is a numeric pixel size (typically 16, 32, 48, 64, 128 or 256).
52 <other_text> can be any other text. See the platform notes below for
53 any recommendations about icon sizes.
54 SIDEBAR_ICONS can be used to add Mac OS X sidebar icons to the gener‐
56 ated iconset. They are used when a folder monitored by the application
57 is dragged into Finder’s sidebar. Since 5.49.
58 OUTFILE_BASENAME will be used as the basename for the icon file. If you
60 specify it, the icon file will be called <OUTFILE_BASENAME>.icns on Mac
61 OS X and <OUTFILE_BASENAME>.ico on Windows. If you don’t specify it, it
62 defaults to <sources_var>.<ext>. Since 5.49.
63 Windows notes
65 · Icons are compiled into the executable using a resource file.
67 · Icons may not show up in Windows Explorer if the executable
69 target does not have the WIN32_EXECUTABLE property set.
70 · One of the tools png2ico (See FindPng2Ico) or icotool (see
72 FindIcoTool) is required.
73 · Supported sizes: 16, 24, 32, 48, 64, 128, 256, 512 and 1024.
75 Mac OS X notes
77 · The executable target must have the MACOSX_BUNDLE property
79 set.
80 · Icons are added to the bundle.
82 · If the ksvg2icns tool from KIconThemes is available, .svg and
84 .svgz files are accepted; the first that is converted success‐
85 fully to .icns will provide the application icon. SVG files
86 are ignored otherwise.
87 · The tool iconutil (provided by Apple) is required for bitmap
89 icons.
90 · Supported sizes: 16, 32, 64, 128, 256 (and 512, 1024 after OS
92 X 10.9).
93 · At least a 128x128px (or an SVG) icon is required.
95 · Larger sizes are automatically used to substitute for smaller
97 sizes on “Retina” (high-resolution) displays. For example, a
98 32px icon, if provided, will be used as a 32px icon on stan‐
99 dard-resolution displays, and as a 16px-equivalent icon (with
100 an “@2x” tag) on high-resolution displays. That is why you
101 should provide 64px and 1024px icons although they are not
102 supported anymore directly. Instead they will be used as
103 32px@2x and 512px@2x. ksvg2icns handles this internally.
104 · This function sets the MACOSX_BUNDLE_ICON_FILE variable to the
106 name of the generated icns file, so that it will be used as
107 the MACOSX_BUNDLE_ICON_FILE target property when you call
108 add_executable.
109 · Sidebar icons should typically provided in 16, 32, 64, 128 and
111 256px.
112 Since 1.7.0.
114 ECMAddQch
116 This module provides the ecm_add_qch function for generating API docu‐
117 mentation files in the QCH format, and the ecm_install_qch_export func‐
118 tion for generating and installing exported CMake targets for such gen‐
119 erated QCH files to enable builds of other software with generation of
120 QCH files to create links into the given QCH files.
121 ecm_add_qch(<target_name>
123 NAME <name>
124 VERSION <version>
125 QCH_INSTALL_DESTINATION <qchfile_install_path>
126 TAGFILE_INSTALL_DESTINATION <tagsfile_install_path>
127 [COMPONENT <component>]
128 [BASE_NAME <basename>]
129 [SOURCE_DIRS <dir> [<dir2> [...]]]
130 [SOURCES <file> [<file2> [...]]]
131 |MD_MAINPAGE <md_file>]
132 [INCLUDE_DIRS <incdir> [<incdir2> [...]]]
133 [IMAGE_DIRS <idir> [<idir2> [...]]]
134 [EXAMPLE_DIRS <edir> [<edir2> [...]]]
135 [ORG_DOMAIN <domain>]
136 [NAMESPACE <namespace>]
137 [LINK_QCHS <qch> [<qch2> [...]]]
138 [PREDEFINED_MACROS <macro[=content]> [<macro2[=content]> [...]]]
139 [BLANK_MACROS <macro> [<macro2> [...]]]
140 [CONFIG_TEMPLATE <configtemplate_file>]
141 [VERBOSE]
142 )
143 This macro adds a target called <target_name> for the creation of an
145 API documentation manual in the QCH format from the given sources. It
146 currently uses doxygen, future versions might optionally also allow
147 other tools. Next to the QCH file the target will generate a corre‐
148 sponding doxygen tag file, which enables creating links from other doc‐
149 umentation into the generated QCH file.
150 It is recommended to make the use of this macro optional, by depending
152 the call to ecm_add_qch on a CMake option being set, with a name like
153 BUILD_QCH and being TRUE by default. This will allow the developers to
154 saves resources on normal source development build cycles by setting
155 this option to FALSE.
156 The macro will set the target properties DOXYGEN_TAGFILE, QHP_NAMES‐
158 PACE, QHP_NAMESPACE_VERSIONED, QHP_VIRTUALFOLDER and LINK_QCHS to the
159 respective values, to allow other code access to them, e.g. the macro
160 ecm_install_qch_export. To enable the use of the target <target_name>
161 as item for LINK_QCHS in further ecm_add_qch calls in the current
162 build, additionally a target property DOXYGEN_TAGFILE_BUILD is set,
163 with the path of the created doxygen tag file in the build dir. If
164 existing, ecm_add_qch will use this property instead of DOXYGEN_TAGFILE
165 for access to the tags file.
166 NAME specifies the name for the generated documentation.
168 VERSION specifies the version of the library for which the documenta‐
170 tion is created.
171 BASE_NAME specifies the base name for the generated files. The default
173 basename is <name>.
174 SOURCE_DIRS specifies the dirs (incl. subdirs) with the source files
176 for which the API documentation should be generated. Dirs can be rela‐
177 tive to the current source dir. Dependencies to the files in the dirs
178 are not tracked currently, other than with the SOURCES argument. So do
179 not use for sources generated during the build. Needs to be used when
180 SOURCES or CONFIG_TEMPLATE are not used.
181 SOURCES specifies the source files for which the API documentation
183 should be generated. Needs to be used when SOURCE_DIRS or CONFIG_TEM‐
184 PLATE are not used.
185 MD_MAINPAGE specifies a file in Markdown format that should be used as
187 main page. This page will overrule any \mainpage command in the
188 included sources.
189 INCLUDE_DIRS specifies the dirs which should be searched for included
191 headers. Dirs can be relative to the current source dir. Since 5.63.
192 IMAGE_DIRS specifies the dirs which contain images that are included in
194 the documentation. Dirs can be relative to the current source dir.
195 EXAMPLE_DIRS specifies the dirs which contain examples that are
197 included in the documentation. Dirs can be relative to the current
198 source dir.
199 QCH_INSTALL_DESTINATION specifies where the generated QCH file will be
201 installed.
202 TAGFILE_INSTALL_DESTINATION specifies where the generated tag file will
204 be installed.
205 COMPONENT specifies the installation component name with which the
207 install rules for the generated QCH file and tag file are associated.
208 NAMESPACE can be used to set a custom namespace <namespace> of the gen‐
210 erated QCH file. The namepspace is used as the unique id by QHelpEngine
211 (cmp. https://doc.qt.io/qt-5/qthelpproject.html#namespace). The
212 default namespace is <domain>.<name>. Needs to be used when ORG_DOMAIN
213 is not used.
214 ORG_DOMAIN can be used to define the organization domain prefix for the
216 default namespace of the generated QCH file. Needs to be used when
217 NAMESPACE is not used.
218 LINK_QCHS specifies a list of other QCH targets which should be used
220 for creating references to API documentation of code in external
221 libraries. For each target <qch> in the list these target properties
222 are expected to be defined: DOXYGEN_TAGFILE, QHP_NAMESPACE and QHP_VIR‐
223 TUALFOLDER. If any of these is not existing, <qch> will be ignored.
224 Use the macro ecm_install_qch_export for exporting a target with these
225 properties with the CMake config of a library. Any target <qch> can
226 also be one created before in the same buildsystem by another call of
227 ecm_add_qch.
228 PREDEFINED_MACROS specifies a list of C/C++ macros which should be han‐
230 dled as given by the API dox generation tool. Examples are macros only
231 defined in generated files, so whose definition might be not available
232 to the tool.
233 BLANK_MACROS specifies a list of C/C++ macro names which should be
235 ignored by the API dox generation tool and handled as if they resolve
236 to empty strings. Examples are export macros only defined in generated
237 files, so whose definition might be not available to the tool.
238 CONFIG_TEMPLATE specifies a custom cmake template file for the config
240 file that is created to control the execution of the API dox generation
241 tool. The following CMake variables need to be used: ECM_QCH_DOXY‐
242 GEN_QHELPGENERATOR_EXECUTABLE, ECM_QCH_DOXYGEN_FILEPATH, ECM_QCH_DOXY‐
243 GEN_TAGFILE. The following CMake variables can be used: ECM_QCH_DOXY‐
244 GEN_PROJECTNAME, ECM_QCH_DOXYGEN_PROJECTVERSION, ECM_QCH_DOXYGEN_VIRTU‐
245 ALFOLDER, ECM_QCH_DOXYGEN_FULLNAMESPACE, ECM_QCH_DOXYGEN_TAGFILES,
246 ECM_QCH_DOXYGEN_WARN_LOGFILE, ECM_QCH_DOXYGEN_QUIET. There is no guar‐
247 antue that the other CMake variables currently used in the default con‐
248 fig file template will also be present with the same semantics in
249 future versions of this macro.
250 VERBOSE tells the API dox generation tool to be more verbose about its
252 activity.
253 Example usage:
255 ecm_add_qch(
257 MyLib_QCH
258 NAME MyLib
259 VERSION "0.42.0"
260 ORG_DOMAIN org.myorg
261 SOURCE_DIRS
262 src
263 LINK_QCHS
264 Qt5Core_QCH
265 Qt5Xml_QCH
266 Qt5Gui_QCH
267 Qt5Widgets_QCH
268 BLANK_MACROS
269 MyLib_EXPORT
270 MyLib_DEPRECATED
271 TAGFILE_INSTALL_DESTINATION ${CMAKE_INSTALL_PREFIX}/share/docs/tags
272 QCH_INSTALL_DESTINATION ${CMAKE_INSTALL_PREFIX}/share/docs/qch
273 COMPONENT Devel
274 )
275 Example usage (with two QCH files, second linking first):
277 ecm_add_qch(
279 MyLib_QCH
280 NAME MyLib
281 VERSION ${MyLib_VERSION}
282 ORG_DOMAIN org.myorg
283 SOURCES ${MyLib_PUBLIC_HEADERS}
284 MD_MAINPAGE src/mylib/README.md
285 LINK_QCHS Qt5Core_QCH
286 TAGFILE_INSTALL_DESTINATION ${CMAKE_INSTALL_PREFIX}/share/docs/tags
287 QCH_INSTALL_DESTINATION ${CMAKE_INSTALL_PREFIX}/share/docs/qch
288 COMPONENT Devel
289 )
290 ecm_add_qch(
291 MyOtherLib_QCH
292 NAME MyOtherLib
293 VERSION ${MyOtherLib_VERSION}
294 ORG_DOMAIN org.myorg
295 SOURCES ${MyOtherLib_PUBLIC_HEADERS}
296 MD_MAINPAGE src/myotherlib/README.md
297 LINK_QCHS Qt5Core_QCH MyLib_QCH
298 TAGFILE_INSTALL_DESTINATION ${CMAKE_INSTALL_PREFIX}/share/docs/tags
299 QCH_INSTALL_DESTINATION ${CMAKE_INSTALL_PREFIX}/share/docs/qch
300 COMPONENT Devel
301 )
302 ecm_install_qch_export(
304 TARGETS [<name> [<name2> [...]]]
305 FILE <file>
306 DESTINATION <dest>
307 [COMPONENT <component>]
308 )
309 This macro creates and installs a CMake file <file> which exports the
311 given QCH targets <name> etc., so they can be picked up by CMake-based
312 builds of other software that also generate QCH files (using
313 ecm_add_qch) and which should include links to the QCH files created by
314 the given targets. The installed CMake file <file> is expected to be
315 included by the CMake config file created for the software the related
316 QCH files are documenting.
317 TARGETS specifies the QCH targets which should be exported. If a target
319 does not exist or does not have all needed properties, a warning will
320 be generated and the target skipped. This behaviour might change in
321 future versions to result in a fail instead.
322 FILE specifies the name of the created CMake file, typically with a
324 .cmake extension.
325 DESTINATION specifies the directory on disk to which the file will be
327 installed. It usually is the same as the one where the CMake config
328 files for this software are installed.
329 COMPONENT specifies the installation component name with which the
331 install rule is associated.
332 Example usage:
334 ecm_install_qch_export(
336 TARGETS MyLib_QCH
337 FILE MyLibQCHTargets.cmake
338 DESTINATION "${CMAKE_INSTALL_PREFIX}/lib/cmake/MyLib"
339 COMPONENT Devel
340 )
341 Since 5.36.0.
343 ECMAddQtDesignerPlugin
345 This module provides the ecm_add_qtdesignerplugin function for generat‐
346 ing Qt Designer plugins for custom widgets. Each of those widgets is
347 described using a second function ecm_qtdesignerplugin_widget.
348 ecm_add_qtdesignerplugin(<target_name>
350 NAME <name>
351 WIDGETS <widgetid> [<widgetid2> [...]]
352 LINK_LIBRARIES <lib> [<lib2> [...]]
353 INSTALL_DESTINATION <install_path>
354 [OUTPUT_NAME <output_name>]
355 [DEFAULT_GROUP <group>]
356 [DEFAULT_HEADER_CASE <SAME_CASE|LOWER_CASE|UPPER_CASE>]
357 [DEFAULT_HEADER_EXTENSION <header_extension>]
358 [DEFAULT_ICON_DIR <icon_dir>]
359 [INCLUDE_FILES <include_file> [<include_file2> [...]]]
360 [SOURCES <src> [<src2> [...]]]
361 [COMPONENT <component>]
362 )
363 NAME specifies the base name to use in the generated sources. The
365 default is <target_name>.
366 WIDGETS specifies the widgets the plugin should support. Each widget
368 has to be defined before by a call of ecm_qtdesignerplugin_widget with
369 the respective <widgetid>, in a scope including the current call.
370 LINK_LIBRARIES specifies the libraries to link against. This will be at
372 least the library providing the widget class(es).
373 INSTALL_DESTINATION specifies where the generated plugin binary will be
375 installed.
376 OUTPUT_NAME specifies the name of the plugin binary. The default is
378 “<target_name>”.
379 DEFAULT_GROUP specifies the default group in Qt Designer where the wid‐
381 gets will be placed. The default is “Custom”.
382 DEFAULT_HEADER_CASE specifies how the name of the header is derived
384 from the widget class name. The default is “LOWER_CASE”.
385 DEFAULT_HEADER_EXTENSION specifies what file name extension is used for
387 the header file derived from the class name. The default is “h”.
388 DEFAULT_ICON_DIR specifies what file name extension is used for the
390 header file derived from the class name. The default is “pics”.
391 INCLUDE_FILES specifies additional include files to include with the
393 generated source file. This can be needed for custom code used in ini‐
394 tializing or creating widgets.
395 SOURCES specifies additional source files to build the plugin from.
397 This can be needed to support custom code used in initializing or cre‐
398 ating widgets.
399 COMPONENT specifies the installation component name with which the
401 install rules for the generated plugin are associated.
402 ecm_qtdesignerplugin_widget(<widgetid>
404 [CLASS_NAME <class_name>]
405 [INCLUDE_FILE <include_file>]
406 [CONTAINER]
407 [ICON <iconfile>]
408 [TOOLTIP <tooltip>]
409 [WHATSTHIS <whatsthis>]
410 [GROUP <group>]
411 [CREATE_WIDGET_CODE_FROM_VARIABLE <create_widget_code_variable>]
412 [INITIALIZE_CODE_FROM_VARIABLE <initialize_code_variable]
413 [DOM_XML_FROM_VARIABLE <dom_xml_variable>]
414 [IMPL_CLASS_NAME <impl_class_name>]
415 [CONSTRUCTOR_ARGS_CODE <constructor_args_code>]
416 [CONSTRUCTOR_ARGS_CODE_FROM_VARIABLE <constructor_args_code_variable>]
417 )
418 CLASS_NAME specifies the name of the widget class, including names‐
420 paces. The default is “<widgetid>”.
421 INCLUDE_FILE specifies the include file to use for the class of this
423 widget. The default is derived from <class_name> as configured by the
424 DEFAULT_HEADER_* options of ecm_add_qtdesignerplugin, also replacing
425 any namespace separators with “/”.
426 CONTAINER specifies, if set, that this widget is a container for other
428 widgets.
429 ICON specifies the icon file to use as symbol for this widget. The
431 default is “{lowercased <class_name>}.png” in the default icons dir as
432 configured by the DEFAULT_ICON_DIR option of ecm_add_qtdesignerplugin,
433 if such a file exists.
434 TOOLTIP specifies the tooltip text to use for this widget. Default is
436 “<class_name> Widget”.
437 WHATSTHIS specifies the What’s-This text to use for this widget.
439 Defaults to the tooltip.
440 GROUP specifies the group in Qt Designer where the widget will be
442 placed. The default is set as configured by the DEFAULT_GROUP option
443 of ecm_add_qtdesignerplugin.
444 CREATE_WIDGET_CODE_FROM_VARIABLE specifies the variable to get from the
446 C++ code to use as factory code to create an instance of the widget,
447 for the override of QDesignerCustomWidgetInterface::createWidget(QWid‐
448 get* parent). The default is “return new <impl_class_name><construc‐
449 tor_args_code>;”.
450 INITIALIZE_CODE_FROM_VARIABLE specifies the variable to get from the
452 C++ code to use with the override of QDesignerCustomWidgetInter‐
453 face::initialize(QDesignerFormEditorInterface* core). The code has to
454 use the present class member m_initialized to track and update the
455 state. The default code simply sets m_initialized to true, if it was
456 not before.
457 DOM_XML_FROM_VARIABLE specifies the variable to get from the string to
459 use with the optional override of QDesignerCustomWidgetInter‐
460 face::domXml(). Default does not override.
461 IMPL_CLASS_NAME specifies the name of the widget class to use for the
463 widget instance with Qt Designer. The default is “<class_name>”.
464 CONSTRUCTOR_ARGS_CODE specifies the C++ code to use for the constructor
466 arguments with the default of CREATE_WIDGET_CODE_FROM_VARIABLE. Note
467 that the parentheses are required. The default is “(parent)”.
468 CONSTRUCTOR_ARGS_CODE_FROM_VARIABLE specifies the variable to get from
470 the C++ code instead of passing it directly via CONSTRUCTOR_ARGS_CODE.
471 This can be needed if the code is more complex and e.g. includes “;”
472 chars.
473 Example usage:
475 ecm_qtdesignerplugin_widget(FooWidget
477 TOOLTIP "Enables to browse foo."
478 GROUP "Views (Foo)"
479 )
480 set(BarWidget_CREATE_WIDGET_CODE
482 "
483 auto* widget = new BarWidget(parent);
484 widget->setBar("Example bar");
485 return widget;
486 ")
487 ecm_qtdesignerplugin_widget(BarWidget
489 TOOLTIP "Displays bars."
490 GROUP "Display (Foo)"
491 CREATE_WIDGET_CODE_FROM_VARIABLE BarWidget_CREATE_WIDGET_CODE
492 )
493 ecm_add_qtdesignerplugin(foowidgets
495 NAME FooWidgets
496 OUTPUT_NAME foo2widgets
497 WIDGETS
498 FooWidget
499 BarWidget
500 LINK_LIBRARIES
501 Foo::Widgets
502 INSTALL_DESTINATION "${KDE_INSTALL_QTPLUGINDIR}/designer"
503 COMPONENT Devel
504 )
505 Since 5.62.0.
507 ECMAddTests
509 Convenience functions for adding tests.
510 ecm_add_tests(<sources> LINK_LIBRARIES <library> [<library> [...]]
512 [NAME_PREFIX <prefix>]
513 [GUI]
514 [TARGET_NAMES_VAR <target_names_var>]
515 [TEST_NAMES_VAR <test_names_var>])
516 A convenience function for adding multiple tests, each consisting of a
518 single source file. For each file in <sources>, an executable target
519 will be created (the name of which will be the basename of the source
520 file). This will be linked against the libraries given with
521 LINK_LIBRARIES. Each executable will be added as a test with the same
522 name.
523 If NAME_PREFIX is given, this prefix will be prepended to the test
525 names, but not the target names. As a result, it will not prevent
526 clashes between tests with the same name in different parts of the
527 project, but it can be used to give an indication of where to look for
528 a failing test.
529 If the flag GUI is passed the test binaries will be GUI executables,
531 otherwise the resulting binaries will be console applications (regard‐
532 less of the value of CMAKE_WIN32_EXECUTABLE or CMAKE_MACOSX_BUNDLE). Be
533 aware that this changes the executable entry point on Windows (although
534 some frameworks, such as Qt, abstract this difference away).
535 The TARGET_NAMES_VAR and TEST_NAMES_VAR arguments, if given, should
537 specify a variable name to receive the list of generated target and
538 test names, respectively. This makes it convenient to apply properties
539 to them as a whole, for example, using set_target_properties() or
540 set_tests_properties().
541 The generated target executables will have the effects of
543 ecm_mark_as_test() (from the ECMMarkAsTest module) applied to it.
544 ecm_add_test(<sources> LINK_LIBRARIES <library> [<library> [...]]
546 [TEST_NAME <name>]
547 [NAME_PREFIX <prefix>]
548 [GUI])
549 This is a single-test form of ecm_add_tests that allows multiple source
551 files to be used for a single test. If using multiple source files,
552 TEST_NAME must be given; this will be used for both the target and test
553 names (and, as with ecm_add_tests(), the NAME_PREFIX argument will be
554 prepended to the test name).
555 Since pre-1.0.0.
557 ECMCoverageOption
559 Allow users to easily enable GCov code coverage support.
560 Code coverage allows you to check how much of your codebase is covered
562 by your tests. This module makes it easy to build with support for
563 GCov.
564 When this module is included, a BUILD_COVERAGE option is added (default
566 OFF). Turning this option on enables GCC’s coverage instrumentation,
567 and links against libgcov.
568 Note that this will probably break the build if you are not using GCC.
570 Since 1.3.0.
572 ECMCreateQmFromPoFiles
574 WARNING:
575 This module is deprecated and will be removed by ECM 1.0. Use ECMPo‐
576 QmTools instead.
577 Generate QTranslator (.qm) catalogs from Gettext (.po) catalogs.
579 ecm_create_qm_from_po_files(PO_FILES <file1>... <fileN>
581 [CATALOG_NAME <catalog_name>]
582 [INSTALL_DESTINATION <install_destination>])
583 Creates the necessary rules to compile .po files into .qm files, and
585 install them.
586 The .qm files are installed in <install_destination>/<lang>/LC_MES‐
588 SAGES, where <install_destination> is the INSTALL_DESTINATION argument
589 and <lang> is extracted from the “Language” field inside the .po file.
590 INSTALL_DESTINATION defaults to ${LOCALE_INSTALL_DIR} if defined, oth‐
592 erwise it uses ${CMAKE_INSTALL_LOCALEDIR} if that is defined, otherwise
593 it uses share/locale.
594 CATALOG_NAME defines the name of the installed .qm files. If set, .qm
596 files will be installed as <catalog_name>.qm. If not set .qm files will
597 be named after the name of their source .po file.
598 Setting the catalog name is useful when all .po files for a target are
600 kept in a single source directory. For example, the “mylib” probject
601 might keep all its translations in a “po” directory, like this:
602 po/
604 es.po
605 fr.po
606 Without setting CATALOG_NAME, those .po will be turned into .qm and
608 installed as:
609 share/locale/fr/LC_MESSAGES/fr.qm
611 share/locale/es/LC_MESSAGES/es.qm
612 If CATALOG_NAME is set to “mylib”, they will be installed as:
614 share/locale/fr/LC_MESSAGES/mylib.qm
616 share/locale/es/LC_MESSAGES/mylib.qm
617 Which is what the loader created by ecm_create_qm_loader() expects.
619 ecm_create_qm_from_po_files() creates a “translation” target. This tar‐
621 get builds all .po files into .qm files.
622 ecm_create_qm_loader(<source_files_var> <catalog_name>)
624 ecm_create_qm_loader() generates a C++ file which ensures translations
626 are automatically loaded at startup. The path of the .cpp file is
627 appended to <source_files_var>. Typical usage is like:
628 set(mylib_SRCS foo.cpp bar.cpp)
630 ecm_create_qm_loader(mylib_SRCS mylib)
631 add_library(mylib ${mylib_SRCS})
632 This generates a C++ file which loads “mylib.qm” at startup, assuming
634 it has been installed by ecm_create_qm_from_po_files(), and compiles it
635 into mylib.
636 Since pre-1.0.0.
638 ECMEnableSanitizers
640 Enable compiler sanitizer flags.
641 The following sanitizers are supported:
643 · Address Sanitizer
645 · Memory Sanitizer
647 · Thread Sanitizer
649 · Leak Sanitizer
651 · Undefined Behaviour Sanitizer
653 All of them are implemented in Clang, depending on your version, and
655 there is an work in progress in GCC, where some of them are currently
656 implemented.
657 This module will check your current compiler version to see if it sup‐
659 ports the sanitizers that you want to enable
660 Usage
662 Simply add:
663 include(ECMEnableSanitizers)
665 to your CMakeLists.txt. Note that this module is included in KDECompil‐
667 erSettings, so projects using that module do not need to also include
668 this one.
669 The sanitizers are not enabled by default. Instead, you must set
671 ECM_ENABLE_SANITIZERS (either in your CMakeLists.txt or on the command
672 line) to a semicolon-separated list of sanitizers you wish to enable.
673 The options are:
674 · address
676 · memory
678 · thread
680 · leak
682 · undefined
684 · fuzzer
686 The sanitizers “address”, “memory” and “thread” are mutually exclusive.
688 You cannot enable two of them in the same build.
689 “leak” requires the “address” sanitizer.
691 NOTE:
693 To reduce the overhead induced by the instrumentation of the sani‐
694 tizers, it is advised to enable compiler optimizations (-O1 or
695 higher).
696 Example
698 This is an example of usage:
699 mkdir build
701 cd build
702 cmake -DECM_ENABLE_SANITIZERS='address;leak;undefined' ..
703 NOTE:
705 Most of the sanitizers will require Clang. To enable it, use:
706 -DCMAKE_CXX_COMPILER=clang++
708 Since 1.3.0.
710 ECMFindModuleHelpers
712 Helper macros for find modules: ecm_find_package_version_check(),
713 ecm_find_package_parse_components() and ecm_find_package_han‐
714 dle_library_components().
715 ecm_find_package_version_check(<name>)
717 Prints warnings if the CMake version or the project’s required CMake
719 version is older than that required by extra-cmake-modules.
720 ecm_find_package_parse_components(<name>
722 RESULT_VAR <variable>
723 KNOWN_COMPONENTS <component1> [<component2> [...]]
724 [SKIP_DEPENDENCY_HANDLING])
725 This macro will populate <variable> with a list of components found in
727 <name>_FIND_COMPONENTS, after checking that all those components are in
728 the list of KNOWN_COMPONENTS; if there are any unknown components, it
729 will print an error or warning (depending on the value of
730 <name>_FIND_REQUIRED) and call return().
731 The order of components in <variable> is guaranteed to match the order
733 they are listed in the KNOWN_COMPONENTS argument.
734 If SKIP_DEPENDENCY_HANDLING is not set, for each component the variable
736 <name>_<component>_component_deps will be checked for dependent compo‐
737 nents. If <component> is listed in <name>_FIND_COMPONENTS, then all
738 its (transitive) dependencies will also be added to <variable>.
739 ecm_find_package_handle_library_components(<name>
741 COMPONENTS <component> [<component> [...]]
742 [SKIP_DEPENDENCY_HANDLING])
743 [SKIP_PKG_CONFIG])
744 Creates an imported library target for each component. The operation
746 of this macro depends on the presence of a number of CMake variables.
747 The <name>_<component>_lib variable should contain the name of this
749 library, and <name>_<component>_header variable should contain the name
750 of a header file associated with it (whatever relative path is normally
751 passed to ‘#include’). <name>_<component>_header_subdir variable can be
752 used to specify which subdirectory of the include path the headers will
753 be found in. ecm_find_package_components() will then search for the
754 library and include directory (creating appropriate cache variables)
755 and create an imported library target named <name>::<component>.
756 Additional variables can be used to provide additional information:
758 If SKIP_PKG_CONFIG, the <name>_<component>_pkg_config variable is set,
760 and pkg-config is found, the pkg-config module given by <name>_<compo‐
761 nent>_pkg_config will be searched for and used to help locate the
762 library and header file. It will also be used to set <name>_<compo‐
763 nent>_VERSION.
764 Note that if version information is found via pkg-config, <name>_<com‐
766 ponent>_FIND_VERSION can be set to require a particular version for
767 each component.
768 If SKIP_DEPENDENCY_HANDLING is not set, the INTERFACE_LINK_LIBRARIES
770 property of the imported target for <component> will be set to contain
771 the imported targets for the components listed in <name>_<compo‐
772 nent>_component_deps. <component>_FOUND will also be set to false if
773 any of the compoments in <name>_<component>_component_deps are not
774 found. This requires the components in <name>_<component>_compo‐
775 nent_deps to be listed before <component> in the COMPONENTS argument.
776 The following variables will be set:
778 <name>_TARGETS
780 the imported targets
781 <name>_LIBRARIES
783 the found libraries
784 <name>_INCLUDE_DIRS
786 the combined required include directories for the components
787 <name>_DEFINITIONS
789 the “other” CFLAGS provided by pkg-config, if any
790 <name>_VERSION
792 the value of <name>_<component>_VERSION for the first component
793 that has this variable set (note that components are searched
794 for in the order they are passed to the macro), although if it
795 is already set, it will not be altered
796 Note that these variables are never cleared, so if ecm_find_pack‐
798 age_handle_library_components() is called multiple times with different
799 components (typically because of multiple find_package() calls) then
800 <name>_TARGETS, for example, will contain all the targets found in any
801 call (although no duplicates).
802 Since pre-1.0.0.
804 ECMGenerateExportHeader
806 This module provides the ecm_generate_export_header function for gener‐
807 ating export macros for libraries with version-based control over visi‐
808 bility of and compiler warnings for deprecated API for the library
809 user, as well as over excluding deprecated API and their implementation
810 when building the library itself.
811 For preparing some values useful in the context it also provides a
813 function ecm_export_header_format_version.
814 ecm_generate_export_header(<library_target_name>
816 VERSION <version>
817 [BASE_NAME <base_name>]
818 [GROUP_BASE_NAME <group_base_name>]
819 [EXPORT_MACRO_NAME <export_macro_name>]
820 [EXPORT_FILE_NAME <export_file_name>]
821 [DEPRECATED_MACRO_NAME <deprecated_macro_name>]
822 [NO_EXPORT_MACRO_NAME <no_export_macro_name>]
823 [INCLUDE_GUARD_NAME <include_guard_name>]
824 [STATIC_DEFINE <static_define>]
825 [PREFIX_NAME <prefix_name>]
826 [DEPRECATED_BASE_VERSION <deprecated_base_version>]
827 [DEPRECATION_VERSIONS <deprecation_version> [<deprecation_version2> [...]]]
828 [EXCLUDE_DEPRECATED_BEFORE_AND_AT <exclude_deprecated_before_and_at_version>]
829 [NO_DEFINITION_EXPORT_TO_BUILD_INTERFACE]
830 [CUSTOM_CONTENT_FROM_VARIABLE <variable>]
831 )
832 VERSION specifies the version of the library, given in the format
834 “<major>.<minor>.<patchlevel>”.
835 GROUP_BASE_NAME specifies the name to use for the macros defining
837 library group default values. If set, this will generate code support‐
838 ing <group_base_name>_NO_DEPRECATED_WARNINGS, <group_base_name>_DIS‐
839 ABLE_DEPRECATED_BEFORE_AND_AT, <group_base_name>_DEPRECATED_WARN‐
840 INGS_SINCE and <group_base_name>_NO_DEPRECATED (see below). If not
841 set, the generated code will ignore any such macros.
842 DEPRECATED_BASE_VERSION specifies the default version before and at
844 which deprecated API is disabled. The default is the value of
845 “<exclude_deprecated_before_and_at_version>” if set, or “<major>.0.0”,
846 with <major> taken from <version>.
847 DEPRECATION_VERSIONS specifies versions in “<major>.<minor>” format in
849 which API was declared deprecated. Any version used with the generated
850 macro <prefix_name><base_name>_DEPRECATED_VERSION(major, minor, text)
851 needs to be listed here, otherwise the macro will fail to work.
852 EXCLUDE_DEPRECATED_BEFORE_AND_AT specifies the version for which all
854 API deprecated before and at should be excluded from the build com‐
855 pletely. Possible values are “0” (default), “CURRENT” (which resolves
856 to <version>) and a version string in the format
857 “<major>.<minor>.<patchlevel>”.
858 NO_DEFINITION_EXPORT_TO_BUILD_INTERFACE specifies that the definition
860 <prefix_name><uppercase_base_name>_DISABLE_DEPRECATED_BEFORE_AND_AT
861 will not be set in the public interface of the library inside its own
862 build. The default is that it is set, to the version specified by
863 EXCLUDE_DEPRECATED_BEFORE_AND_AT, so e.g. test and examples part of the
864 project automatically build against the full API included in the build.
865 The function ecm_generate_export_header defines C++ preprocessor macros
867 in the generated export header, some for use in the sources of the
868 library the header is generated for, other for use by projects linking
869 agsinst the library.
870 The macros for use in the library C++ sources are these, next to those
872 also defined by GenerateExportHeader:
873 <prefix_name><uppercase_base_name>_DEPRECATED_VERSION(major, minor,
875 text)
876 to use to conditionally set a <prefix_name><upper‐
877 case_base_name>_DEPRECATED macro for a class, struct or function
878 (other elements to be supported in future versions), depending
879 on the visibility macro flags set (see below)
880 <prefix_name><uppercase_base_name>_ENABLE_DEPRECATED_SINCE(major,
882 minor)
883 evaluates to TRUE or FALSE depending on the visibility macro
884 flags set (see below). To be used mainly with #if/#endif to mark
885 sections of code which should be included depending on the visi‐
886 bility requested.
887 <prefix_name><uppercase_base_name>_BUILD_DEPRECATED_SINCE(major, minor)
889 evaluates to TRUE or FALSE depending on the value of
890 EXCLUDE_DEPRECATED_BEFORE_AND_AT. To be used mainly with
891 #if/#endif to mark sections of two types of code: implementation
892 code for deprecated API and declaration code of deprecated API
893 which only may be disabled at build time of the library for BC
894 reasons (e.g. virtual methods, see notes below).
895 <prefix_name><uppercase_base_name>_EXCLUDE_DEPRECATED_BEFORE_AND_AT
897 holds the version used to exclude deprecated API at build time
898 of the library.
899 The macros used to control visibility when building against the library
901 are:
902 <prefix_name><uppercase_base_name>_DISABLE_DEPRECATED_BEFORE_AND_AT
904 definition to set to a value in single hex number version nota‐
905 tion (0x<major><minor><patchlevel>).
906 <prefix_name><uppercase_base_name>_NO_DEPRECATED
908 flag to define to disable all deprecated API, being a shortcut
909 for settings <prefix_name><uppercase_base_name>_DISABLE_DEPRE‐
910 CATED_BEFORE_AND_AT to the current version. If both are set,
911 this flag overrules.
912 <prefix_name><uppercase_base_name>_DEPRECATED_WARNINGS_SINCE
914 definition to set to a value in single hex number version nota‐
915 tion (0x<major><minor><patchlevel>). Warnings will be only acti‐
916 vated for API deprecated up to and including the version. If
917 <prefix_name><uppercase_base_name>_DISABLE_DEPRE‐
918 CATED_BEFORE_AND_AT is set (directly or via the group default),
919 it will default to that version, resulting in no warnings. Oth‐
920 erwise the default is the current version, resulting in warnings
921 for all deprecated API.
922 <prefix_name><uppercase_base_name>_NO_DEPRECATED_WARNINGS
924 flag to define to disable all deprecation warnings, being a
925 shortcut for setting <prefix_name><uppercase_base_name>_DEPRE‐
926 CATED_WARNINGS_SINCE to “0”. If both are set, this flag over‐
927 rules.
928 When the GROUP_BASE_NAME has been used, the same macros but with the
930 given <group_base_name> prefix are available to define the defaults of
931 these macros, if not explicitely set.
932 Note: The tricks applied here for hiding deprecated API to the compiler
934 when building against a library do not work for all deprecated API:
935 · virtual methods need to stay visible to the compiler to build proper
937 virtual method tables for subclasses
938 · enumerators from enums cannot be simply removed, as this changes auto
940 values of following enumerators, also can poke holes in enumerator
941 series used as index into tables
942 In such cases the API can be only “hidden” at build time of the
944 library, itself, by generated hard coded macro settings, using <pre‐
945 fix_name><uppercase_base_name>_BUILD_DEPRECATED_SINCE(major, minor).
946 Examples:
948 Preparing a library “Foo” created by target “foo”, which is part of a
950 group of libraries “Bar”, where some API of “Foo” got deprecated at
951 versions 5.0 & 5.12:
952 ecm_generate_export_header(foo
954 GROUP_BASE_NAME BAR
955 VERSION ${FOO_VERSION}
956 DEPRECATION_VERSIONS 5.0 5.12
957 )
958 In the library “Foo” sources in the headers the API would be prepared
960 like this, using the generated macros FOO_ENABLE_DEPRECATED_SINCE and
961 FOO_DEPRECATED_VERSION:
962 #include <foo_export.h>
964 #if FOO_ENABLE_DEPRECATED_SINCE(5, 0)
966 /**
967 * @deprecated Since 5.0
968 */
969 FOO_DEPRECATED_VERSION(5, 0, "Use doFoo2()")
970 FOO_EXPORT void doFoo();
971 #endif
972 #if FOO_ENABLE_DEPRECATED_SINCE(5, 12)
974 /**
975 * @deprecated Since 5.12
976 */
977 FOO_DEPRECATED_VERSION(5, 12, "Use doBar2()")
978 FOO_EXPORT void doBar();
979 #endif
980 Projects linking against the “Foo” library can control which part of
982 its deprecated API should be hidden to the compiler by adding a defini‐
983 tion using the FOO_DISABLE_DEPRECATED_BEFORE_AND_AT macro variable set
984 to the desired value (in version hex number notation):
985 add_definitions(-DFOO_DISABLE_DEPRECATED_BEFORE_AND_AT=0x050000)
987 Or using the macro variable of the group:
989 add_definitions(-DBAR_DISABLE_DEPRECATED_BEFORE_AND_AT=0x050000)
991 If both are specified, FOO_DISABLE_DEPRECATED_BEFORE_AND_AT will take
993 precedence.
994 To build a variant of a library with some deprecated API completely
996 left out from the build, not only optionally invisible to consumers,
997 one uses the EXCLUDE_DEPRECATED_BEFORE_AND_AT parameter. This is best
998 combined with a cached CMake variable.
999 set(EXCLUDE_DEPRECATED_BEFORE_AND_AT 0 CACHE STRING "Control the range of deprecated API excluded from the build [default=0].")
1001 ecm_generate_export_header(foo
1003 VERSION ${FOO_VERSION}
1004 EXCLUDE_DEPRECATED_BEFORE_AND_AT ${EXCLUDE_DEPRECATED_BEFORE_AND_AT}
1005 DEPRECATION_VERSIONS 5.0 5.12
1006 )
1007 The macros used in the headers for library consumers are reused for
1009 disabling the API excluded in the build of the library. For disabling
1010 the implementation of that API as well as for disabling deprecated API
1011 which only can be disabled at build time of the library for BC reasons,
1012 one uses the generated macro FOO_BUILD_DEPRECATED_SINCE, like this:
1013 #include <foo_export.h>
1015 enum Bars {
1017 One,
1018 #if FOO_BUILD_DEPRECATED_SINCE(5, 0)
1019 Two,
1020 #endif
1021 Three,
1022 };
1023 #if FOO_ENABLE_DEPRECATED_SINCE(5, 0)
1025 /**
1026 * @deprecated Since 5.0
1027 */
1028 FOO_DEPRECATED_VERSION(5, 0, "Use doFoo2()")
1029 FOO_EXPORT void doFoo();
1030 #endif
1031 #if FOO_ENABLE_DEPRECATED_SINCE(5, 12)
1033 /**
1034 * @deprecated Since 5.12
1035 */
1036 FOO_DEPRECATED_VERSION(5, 12, "Use doBar2()")
1037 FOO_EXPORT void doBar();
1038 #endif
1039 class FOO_EXPORT Foo {
1041 public:
1042 #if FOO_BUILD_DEPRECATED_SINCE(5, 0)
1043 /**
1044 * @deprecated Since 5.0
1045 */
1046 FOO_DEPRECATED_VERSION(5, 0, "Feature removed")
1047 virtual void doWhat();
1048 #endif
1049 };
1050 #if FOO_BUILD_DEPRECATED_SINCE(5, 0)
1052 void doFoo()
1053 {
1054 // [...]
1055 }
1056 #endif
1057 #if FOO_BUILD_DEPRECATED_SINCE(5, 12)
1059 void doBar()
1060 {
1061 // [...]
1062 }
1063 #endif
1064 #if FOO_BUILD_DEPRECATED_SINCE(5, 0)
1066 void Foo::doWhat()
1067 {
1068 // [...]
1069 }
1070 #endif
1071 So e.g. if EXCLUDE_DEPRECATED_BEFORE_AND_AT is set to “5.0.0”, the enu‐
1073 merator Two as well as the methods ::doFoo() and Foo::doWhat() will be
1074 not available to library consumers. The methods will not have been com‐
1075 piled into the library binary, and the declarations will be hidden to
1076 the compiler, FOO_DISABLE_DEPRECATED_BEFORE_AND_AT also cannot be used
1077 to reactivate them.
1078 When using the NO_DEFINITION_EXPORT_TO_BUILD_INTERFACE and the project
1080 for the “Foo” library includes also tests and examples linking against
1081 the library and using deprecated API (like tests covering it), one bet‐
1082 ter explicitely sets FOO_DISABLE_DEPRECATED_BEFORE_AND_AT for those
1083 targets to the version before and at which all deprecated API has been
1084 excluded from the build. Even more when building against other
1085 libraries from the same group “Bar” and disabling some deprecated API
1086 of those libraries using the group macro BAR_DISABLE_DEPRE‐
1087 CATED_BEFORE_AND_AT, which also works as default for FOO_DISABLE_DEPRE‐
1088 CATED_BEFORE_AND_AT.
1089 To get the hex number style value the helper macro
1091 ecm_export_header_format_version() will be used:
1092 set(EXCLUDE_DEPRECATED_BEFORE_AND_AT 0 CACHE STRING "Control what part of deprecated API is excluded from build [default=0].")
1094 ecm_generate_export_header(foo
1096 VERSION ${FOO_VERSION}
1097 GROUP_BASE_NAME BAR
1098 EXCLUDE_DEPRECATED_BEFORE_AND_AT ${EXCLUDE_DEPRECATED_BEFORE_AND_AT}
1099 NO_DEFINITION_EXPORT_TO_BUILD_INTERFACE
1100 DEPRECATION_VERSIONS 5.0 5.12
1101 )
1102 ecm_export_header_format_version(${EXCLUDE_DEPRECATED_BEFORE_AND_AT}
1104 CURRENT_VERSION ${FOO_VERSION}
1105 HEXNUMBER_VAR foo_no_deprecated_before_and_at
1106 )
1107 # disable all deprecated API up to 5.9.0 from all other libs of group "BAR" that we use ourselves
1109 add_definitions(-DBAR_DISABLE_DEPRECATED_BEFORE_AND_AT=0x050900)
1110 add_executable(app app.cpp)
1112 target_link_libraries(app foo)
1113 target_compile_definitions(app
1114 PRIVATE "FOO_DISABLE_DEPRECATED_BEFORE_AND_AT=${foo_no_deprecated_before_and_at}")
1115 Since 5.64.0.
1117 ECMGenerateHeaders
1119 Generate C/C++ CamelCase forwarding headers.
1120 ecm_generate_headers(<camelcase_forwarding_headers_var>
1122 HEADER_NAMES <CamelCaseName> [<CamelCaseName> [...]]
1123 [ORIGINAL <CAMELCASE|LOWERCASE>]
1124 [HEADER_EXTENSION <header_extension>]
1125 [OUTPUT_DIR <output_dir>]
1126 [PREFIX <prefix>]
1127 [REQUIRED_HEADERS <variable>]
1128 [COMMON_HEADER <HeaderName>]
1129 [RELATIVE <relative_path>])
1130 For each CamelCase header name passed to HEADER_NAMES, a file of that
1132 name will be generated that will include a version with .h or, if set,
1133 .<header_extension> appended. For example, the generated header ClassA
1134 will include classa.h (or ClassA.h, see ORIGINAL). If a CamelCaseName
1135 consists of multiple comma-separated files, e.g. ClassA,ClassB,ClassC,
1136 then multiple camelcase header files will be generated which are redi‐
1137 rects to the first header file. The file locations of these generated
1138 headers will be stored in <camelcase_forwarding_headers_var>.
1139 ORIGINAL specifies how the name of the original header is written: low‐
1141 ercased or also camelcased. The default is LOWERCASE. Since 1.8.0.
1142 HEADER_EXTENSION specifies what file name extension is used for the
1144 header files. The default is “h”. Since 5.48.0.
1145 PREFIX places the generated headers in subdirectories. This should be
1147 a CamelCase name like KParts, which will cause the CamelCase forwarding
1148 headers to be placed in the KParts directory (e.g. KParts/Part). It
1149 will also, for the convenience of code in the source distribution, gen‐
1150 erate forwarding headers based on the original names (e.g.
1151 kparts/part.h). This allows includes like "#include <kparts/part.h>"
1152 to be used before installation, as long as the include_directories are
1153 set appropriately.
1154 OUTPUT_DIR specifies where the files will be generated; this should be
1156 within the build directory. By default, ${CMAKE_CURRENT_BINARY_DIR}
1157 will be used. This option can be used to avoid file conflicts.
1158 REQUIRED_HEADERS specifies an output variable name where all the
1160 required headers will be appended so that they can be installed
1161 together with the generated ones. This is mostly intended as a conve‐
1162 nience so that adding a new header to a project only requires specify‐
1163 ing the CamelCase variant in the CMakeLists.txt file; the original
1164 variant will then be added to this variable.
1165 COMMON_HEADER generates an additional convenience header which includes
1167 all other header files.
1168 The RELATIVE argument indicates where the original headers can be found
1170 relative to CMAKE_CURRENT_SOURCE_DIR. It does not affect the generated
1171 CamelCase forwarding files, but ecm_generate_headers() uses it when
1172 checking that the original header exists, and to generate originally
1173 named forwarding headers when PREFIX is set.
1174 To allow other parts of the source distribution (eg: tests) to use the
1176 generated headers before installation, it may be desirable to set the
1177 INCLUDE_DIRECTORIES property for the library target to output_dir. For
1178 example, if OUTPUT_DIR is CMAKE_CURRENT_BINARY_DIR (the default), you
1179 could do
1180 target_include_directories(MyLib PUBLIC "$<BUILD_INTERFACE:${CMAKE_CURRENT_BINARY_DIR}>")
1182 Example usage (without PREFIX):
1184 ecm_generate_headers(
1186 MyLib_FORWARDING_HEADERS
1187 HEADERS
1188 MLFoo
1189 MLBar
1190 # etc
1191 REQUIRED_HEADERS MyLib_HEADERS
1192 COMMON_HEADER MLGeneral
1193 )
1194 install(FILES ${MyLib_FORWARDING_HEADERS} ${MyLib_HEADERS}
1195 DESTINATION ${CMAKE_INSTALL_PREFIX}/include
1196 COMPONENT Devel)
1197 Example usage (with PREFIX):
1199 ecm_generate_headers(
1201 MyLib_FORWARDING_HEADERS
1202 HEADERS
1203 Foo
1204 # several classes are contained in bar.h, so generate
1205 # additional files
1206 Bar,BarList
1207 # etc
1208 PREFIX MyLib
1209 REQUIRED_HEADERS MyLib_HEADERS
1210 )
1211 install(FILES ${MyLib_FORWARDING_HEADERS}
1212 DESTINATION ${CMAKE_INSTALL_PREFIX}/include/MyLib
1213 COMPONENT Devel)
1214 install(FILES ${MyLib_HEADERS}
1215 DESTINATION ${CMAKE_INSTALL_PREFIX}/include/mylib
1216 COMPONENT Devel)
1217 Since pre-1.0.0.
1219 ECMGeneratePkgConfigFile
1221 Generate a pkg-config file for the benefit of autotools-based projects.
1222 ecm_generate_pkgconfig_file(BASE_NAME <baseName>
1224 [LIB_NAME <libName>]
1225 [DEPS "<dep> [<dep> [...]]"]
1226 [FILENAME_VAR <filename_variable>]
1227 [INCLUDE_INSTALL_DIR <dir>]
1228 [LIB_INSTALL_DIR <dir>]
1229 [DEFINES -D<variable=value>...]
1230 [DESCRIPTION <library description>] # since 5.41.0
1231 [INSTALL])
1232 BASE_NAME is the name of the module. It’s the name projects will use to
1234 find the module.
1235 LIB_NAME is the name of the library that is being exported. If unde‐
1237 fined, it will default to the BASE_NAME. That means the LIB_NAME will
1238 be set as the name field as well as the library to link to.
1239 FILENAME_VAR is specified with a variable name. This variable will
1241 receive the location of the generated file will be set, within the
1242 build directory. This way it can be used in case some processing is
1243 required. See also INSTALL.
1244 INCLUDE_INSTALL_DIR specifies where the includes will be installed. If
1246 it’s not specified, it will default to INSTALL_INCLUDEDIR,
1247 CMAKE_INSTALL_INCLUDEDIR or just “include/” in case they are specified,
1248 with the BASE_NAME postfixed.
1249 LIB_INSTALL_DIR specifies where the library is being installed. If it’s
1251 not specified, it will default to LIB_INSTALL_DIR, CMAKE_INSTALL_LIBDIR
1252 or just “lib/” in case they are specified.
1253 DEFINES is a list of preprocessor defines that it is recommended users
1255 of the library pass to the compiler when using it.
1256 DESCRIPTION describes what this library is. If it’s not specified,
1258 CMake will first try to get the description from the metainfo.yaml file
1259 or will create one based on LIB_NAME. Since 5.41.0.
1260 INSTALL will cause the module to be installed to the pkgconfig subdi‐
1262 rectory of LIB_INSTALL_DIR, unless the ECM_PKGCONFIG_INSTALL_DIR cache
1263 variable is set to something different. Note that the first call to
1264 ecm_generate_pkgconfig_file with the INSTALL argument will cause
1265 ECM_PKGCONFIG_INSTALL_DIR to be set to the cache, and will be used in
1266 any subsequent calls.
1267 To properly use this macro a version needs to be set. To retrieve it,
1269 ECM_PKGCONFIG_INSTALL_DIR uses PROJECT_VERSION. To set it, use the
1270 project() command (only available since CMake 3.0) or the ecm_set‐
1271 up_version() macro.
1272 Example usage:
1274 ecm_generate_pkgconfig_file(
1276 BASE_NAME KF5Archive
1277 DEPS Qt5Core
1278 FILENAME_VAR pkgconfig_filename
1279 INSTALL
1280 )
1281 Since 1.3.0.
1283 ECMGeneratePriFile
1285 Generate a .pri file for the benefit of qmake-based projects.
1286 As well as the function below, this module creates the cache variable
1288 ECM_MKSPECS_INSTALL_DIR and sets the default value to mkspecs/modules.
1289 This assumes Qt and the current project are both installed to the same
1290 non-system prefix. Packagers who use -DCMAKE_INSTALL_PREFIX=/usr will
1291 certainly want to set ECM_MKSPECS_INSTALL_DIR to something like
1292 share/qt5/mkspecs/modules.
1293 The main thing is that this should be the modules subdirectory of
1295 either the default qmake mkspecs directory or of a directory that will
1296 be in the $QMAKEPATH environment variable when qmake is run.
1297 ecm_generate_pri_file(BASE_NAME <baseName>
1299 LIB_NAME <libName>
1300 [DEPS "<dep> [<dep> [...]]"]
1301 [FILENAME_VAR <filename_variable>]
1302 [INCLUDE_INSTALL_DIR <dir>]
1303 [LIB_INSTALL_DIR <dir>])
1304 If your CMake project produces a Qt-based library, you may expect there
1306 to be applications that wish to use it that use a qmake-based build
1307 system, rather than a CMake-based one. Creating a .pri file will make
1308 use of your library convenient for them, in much the same way that
1309 CMake config files make things convenient for CMake-based applications.
1310 ecm_generate_pri_file() generates just such a file. It requires the
1312 PROJECT_VERSION_STRING variable to be set. This is typically set by
1313 ECMSetupVersion, although the project() command in CMake 3.0.0 and
1314 later can also set this.
1315 BASE_NAME specifies the name qmake project (.pro) files should use to
1317 refer to the library (eg: KArchive). LIB_NAME is the name of the
1318 actual library to link to (ie: the first argument to add_library()).
1319 DEPS is a space-separated list of the base names of other libraries
1320 (for Qt libraries, use the same names you use with the QT variable in a
1321 qmake project file, such as “core” for QtCore). FILENAME_VAR specifies
1322 the name of a variable to store the path to the generated file in.
1323 INCLUDE_INSTALL_DIR is the path (relative to CMAKE_INSTALL_PREFIX) that
1325 include files will be installed to. It defaults to
1326 ${INCLUDE_INSTALL_DIR}/<baseName> if the INCLUDE_INSTALL_DIR variable
1327 is set. If that variable is not set, the CMAKE_INSTALL_INCLUDEDIR vari‐
1328 able is used instead, and if neither are set include is used.
1329 LIB_INSTALL_DIR operates similarly for the installation location for
1330 libraries; it defaults to ${LIB_INSTALL_DIR}, ${CMAKE_INSTALL_LIBDIR}
1331 or lib, in that order.
1332 Example usage:
1334 ecm_generate_pri_file(
1336 BASE_NAME KArchive
1337 LIB_NAME KF5KArchive
1338 DEPS "core"
1339 FILENAME_VAR pri_filename
1340 )
1341 install(FILES ${pri_filename} DESTINATION ${ECM_MKSPECS_INSTALL_DIR})
1342 A qmake-based project that wished to use this would then do:
1344 QT += KArchive
1346 in their .pro file.
1348 Since pre-1.0.0.
1350 ECMGenerateQmlTypes
1352 Generates plugins.qmltypes files for QML plugins.
1353 ecm_generate_qmltypes(<org.kde.pluginname> 1.3
1355 DESTINATION <${KDE_INSTALL_QMLDIR}/org/kde/pluginname>)
1356 Makes it possible to generate plugins.qmltypes files for the QML plug‐
1358 ins that our project offers. These files offer introspection upon our
1359 plugin and are useful for integrating with IDE language support of our
1360 plugin. It offers information about the objects its methods and their
1361 argument types.
1362 The developer will be in charge of making sure that these files are up
1364 to date. The plugin.qmltypes file will sit in the source directory.
1365 This function will include the code that installs the file in the right
1366 place and a small unit test named qmltypes-pluginname-version that
1367 makes sure that it doesn’t need updating.
1368 Since 5.33.0
1370 ECMInstallIcons
1372 Installs icons, sorting them into the correct directories according to
1373 the FreeDesktop.org icon naming specification.
1374 ecm_install_icons(ICONS <icon> [<icon> [...]]
1376 DESTINATION <icon_install_dir>
1377 [LANG <l10n_code>]
1378 [THEME <theme>])
1379 The given icons, whose names must match the pattern:
1381 <size>-<group>-<name>.<ext>
1383 will be installed to the appropriate subdirectory of DESTINATION
1385 according to the FreeDesktop.org icon naming scheme. By default, they
1386 are installed to the “hicolor” theme, but this can be changed using the
1387 THEME argument. If the icons are localized, the LANG argument can be
1388 used to install them in a locale-specific directory.
1389 <size> is a numeric pixel size (typically 16, 22, 32, 48, 64, 128 or
1391 256) or sc for scalable (SVG) files, <group> is one of the standard
1392 FreeDesktop.org icon groups (actions, animations, apps, categories,
1393 devices, emblems, emotes, intl, mimetypes, places, status) and <ext> is
1394 one of .png, .mng or .svgz.
1395 The typical installation directory is share/icons.
1397 ecm_install_icons(ICONS 22-actions-menu_new.png
1399 DESTINATION share/icons)
1400 The above code will install the file 22-actions-menu_new.png as
1402 ${CMAKE_INSTALL_PREFIX}/share/icons/<theme>/22x22/actions/menu_new.png
1403 Users of the KDEInstallDirs module would normally use
1405 ${KDE_INSTALL_ICONDIR} as the DESTINATION, while users of the GNUIn‐
1406 stallDirs module should use ${CMAKE_INSTALL_DATAROOTDIR}/icons.
1407 An old form of arguments will also be accepted:
1409 ecm_install_icons(<icon_install_dir> [<l10n_code>])
1411 This matches files named like:
1413 <theme><size>-<group>-<name>.<ext>
1415 where <theme> is one of * hi for hicolor * lo for locolor * cr for the
1417 Crystal icon theme * ox for the Oxygen icon theme * br for the Breeze
1418 icon theme
1419 With this syntax, the file hi22-actions-menu_new.png would be installed
1421 into <icon_install_dir>/hicolor/22x22/actions/menu_new.png
1422 Since pre-1.0.0.
1424 ECMMarkAsTest
1426 Marks a target as only being required for tests.
1427 ecm_mark_as_test(<target1> [<target2> [...]])
1429 This will cause the specified targets to not be built unless either
1431 BUILD_TESTING is set to ON or the user invokes the buildtests target.
1432 BUILD_TESTING is created as a cache variable by the CTest module and by
1434 the KDECMakeSettings module.
1435 Since pre-1.0.0.
1437 ECMMarkNonGuiExecutable
1439 Marks an executable target as not being a GUI application.
1440 ecm_mark_nongui_executable(<target1> [<target2> [...]])
1442 This will indicate to CMake that the specified targets should not be
1444 included in a MACOSX_BUNDLE and should not be WIN32_EXECUTABLEs. On
1445 platforms other than MacOS X or Windows, this will have no effect.
1446 Since pre-1.0.0.
1448 ECMOptionalAddSubdirectory
1450 Make subdirectories optional.
1451 ecm_optional_add_subdirectory(<dir>)
1453 This behaves like add_subdirectory(), except that it does not complain
1455 if the directory does not exist. Additionally, if the directory does
1456 exist, it creates an option to allow the user to skip it. The option
1457 will be named BUILD_<dir>.
1458 This is useful for “meta-projects” that combine several mostly-indepen‐
1460 dent sub-projects.
1461 If the CMake variable DISABLE_ALL_OPTIONAL_SUBDIRECTORIES is set to
1463 TRUE for the first CMake run on the project, all optional subdirecto‐
1464 ries will be disabled by default (but can of course be enabled via the
1465 respective options). For example, the following will disable all
1466 optional subdirectories except the one named “foo”:
1467 cmake -DDISABLE_ALL_OPTIONAL_SUBDIRECTORIES=TRUE -DBUILD_foo=TRUE myproject
1469 Since pre-1.0.0.
1471 ECMPackageConfigHelpers
1473 Helper macros for generating CMake package config files.
1474 write_basic_package_version_file() is the same as the one provided by
1476 the CMakePackageConfigHelpers module in CMake; see that module’s docu‐
1477 mentation for more information.
1478 ecm_configure_package_config_file(<input> <output>
1480 INSTALL_DESTINATION <path>
1481 [PATH_VARS <var1> [<var2> [...]]
1482 [NO_SET_AND_CHECK_MACRO]
1483 [NO_CHECK_REQUIRED_COMPONENTS_MACRO])
1484 This behaves in the same way as configure_package_config_file() from
1486 CMake 2.8.12, except that it adds an extra helper macro: find_depen‐
1487 dency(). It is highly recommended that you read the documentation for
1488 CMakePackageConfigHelpers for more information, particularly with
1489 regard to the PATH_VARS argument.
1490 Note that there is no argument that will disable the find_dependency()
1492 macro; if you do not require this macro, you should use configure_pack‐
1493 age_config_file from the CMakePackageConfigHelpers module.
1494 CMake 3.0 includes a CMakeFindDependencyMacro module that provides the
1496 find_dependency() macro (which you can include() in your package config
1497 file), so this file is only useful for projects wishing to provide con‐
1498 fig files that will work with CMake 2.8.12.
1499 Additional Config File Macros
1501 find_dependency(<dep> [<version> [EXACT]])
1502 find_dependency() should be used instead of find_package() to find
1504 package dependencies. It forwards the correct parameters for EXACT,
1505 QUIET and REQUIRED which were passed to the original find_package()
1506 call. It also sets an informative diagnostic message if the dependency
1507 could not be found.
1508 Since pre-1.0.0.
1510 ECMPoQmTools
1512 This module provides the ecm_process_po_files_as_qm and
1513 ecm_install_po_files_as_qm functions for generating QTranslator (.qm)
1514 catalogs from Gettext (.po) catalogs, and the ecm_create_qm_loader
1515 function for generating the necessary code to load them in a Qt appli‐
1516 cation or library.
1517 ecm_process_po_files_as_qm(<lang> [ALL]
1519 [INSTALL_DESTINATION <install_destination>]
1520 PO_FILES <pofile> [<pofile> [...]])
1521 Compile .po files into .qm files for the given language.
1523 If INSTALL_DESTINATION is given, the .qm files are installed in
1525 <install_destination>/<lang>/LC_MESSAGES. Typically, <install_destina‐
1526 tion> is set to share/locale.
1527 ecm_process_po_files_as_qm creates a “translations” target. This target
1529 builds all .po files into .qm files. If ALL is specified, these rules
1530 are added to the “all” target (and so the .qm files will be built by
1531 default).
1532 ecm_create_qm_loader(<source_files_var> <catalog_name>)
1534 Generates C++ code which ensures translations are automatically loaded
1536 at startup. The generated files are appended to <source_files_var>.
1537 It assumes that the .qm file for the language code <lang> is installed
1539 as <sharedir>/locale/<lang>/LC_MESSAGES/<catalog_name>.qm, where
1540 <sharedir> is one of the directories given by the GenericDataLocation
1541 of QStandardPaths.
1542 Typical usage is like:
1544 set(mylib_SRCS foo.cpp bar.cpp)
1546 ecm_create_qm_loader(mylib_SRCS mylib)
1547 add_library(mylib ${mylib_SRCS})
1548 ecm_install_po_files_as_qm(<podir>)
1550 Searches for .po files and installs them to the standard location.
1552 This is a convenience function which relies on all .po files being kept
1554 in <podir>/<lang>/, where <lang> is the language the .po files are
1555 written in.
1556 For example, given the following directory structure:
1558 po/
1560 fr/
1561 mylib.po
1562 ecm_install_po_files_as_qm(po) compiles mylib.po into mylib.qm and
1564 installs it in <install_destination>/fr/LC_MESSAGES. <install_destina‐
1565 tion> defaults to ${LOCALE_INSTALL_DIR} if defined, otherwise it uses
1566 ${CMAKE_INSTALL_LOCALEDIR} if that is defined, otherwise it uses
1567 share/locale.
1568 Since pre-1.0.0.
1570 ECMQMLModules
1572 Find QML import modules through a find_qmlmodule() call. It uses the
1573 qmlplugindump application to find the plugins and sets them up as run‐
1574 time dependencies.
1575 This is useful so that when we configure a project we are noified when
1577 some QML imports are not present in the system, thus having the appli‐
1578 cation compilable but fail at runtime.
1579 ecm_find_qmlmodule(<module_name> <version>...)
1581 Any further arguments passed will be forwarded into a find_package()
1583 call. See find_package() documentation for more information.
1584 Usage example:
1586 ecm_find_qmlmodule(org.kde.kirigami 2.1)
1588 Since 5.38.0.
1590 ECMQtDeclareLoggingCategory
1592 Generate declarations for logging categories in Qt5.
1593 ecm_qt_declare_logging_category(<sources_var>
1595 HEADER <filename>
1596 IDENTIFIER <identifier>
1597 CATEGORY_NAME <category_name>
1598 [DEFAULT_SEVERITY
1599 <Debug|Info|Warning|
1600 Critical|Fatal>])
1601 A header file, <filename>, will be generated along with a corresponding
1603 source file, which will be added to <sources_var>. These will provide a
1604 QLoggingCategory category that can be referred to from C++ code using
1605 <identifier>, and from the logging configuration using <category_name>.
1606 If <filename> is not absolute, it will be taken relative to the current
1608 binary directory.
1609 If the code is compiled against Qt 5.4 or later, by default it will
1611 only log output that is at least the severity specified by
1612 DEFAULT_SEVERITY, or “Info” level if DEFAULT_SEVERITY is not given.
1613 Note that, due to a bug in Qt 5.5, “Info” may be treated as more severe
1614 than “Fatal”.
1615 <identifier> may include namespaces (eg: foo::bar::IDENT).
1617 Since 5.14.0.
1619 ECMSetupQtPluginMacroNames
1621 Instruct CMake’s automoc about C++ preprocessor macros used to define
1622 Qt-style plugins.
1623 ecm_setup_qtplugin_macro_names(
1625 [JSON_NONE <macro_name> [<macro_name> [...]]]
1626 [JSON_ARG1 <macro_name> [<macro_name> [...]]]
1627 [JSON_ARG2 <macro_name> [<macro_name> [...]]]
1628 [JSON_ARG3 <macro_name> [<macro_name> [...]]]
1629 [CONFIG_CODE_VARIABLE <variable_name>] )
1630 CMake’s automoc needs some support when parsing C++ source files to
1632 detect whether moc should be run on those files and if there are also
1633 dependencies on other files, like those with Qt plugin metadata in JSON
1634 format. Because automoc just greps overs the raw plain text of the
1635 sources without any C++ preprocessor-like processing. CMake in newer
1636 versions provides the variables CMAKE_AUTOMOC_DEPEND_FILTERS (CMake >=
1637 3.9.0) and CMAKE_AUTOMOC_MACRO_NAMES (CMake >= 3.10) to allow the
1638 developer to assist automoc.
1639 This macro cares for the explicit setup needed for those variables for
1641 common cases of C++ preprocessor macros used for Qt-style plugins.
1642 JSON_NONE lists the names of C++ preprocessor macros for Qt-style plug‐
1644 ins which do not refer to external files with the plugin metadata.
1645 JSON_ARG1 lists the names of C++ preprocessor macros for Qt-style plug‐
1647 ins where the first argument to the macro is the name of the external
1648 file with the plugin metadata.
1649 JSON_ARG2 is the same as JSON_ARG1 but with the file name being the
1651 second argument.
1652 JSON_ARG3 is the same as JSON_ARG1 but with the file name being the
1654 third argument.
1655 CONFIG_CODE_VARIABLE specifies the name of the variable which will get
1657 set as value some generated CMake code for instructing automoc for the
1658 given macro names, as useful in an installed CMake config file. The
1659 variable can then be used as usual in the template file for such a
1660 CMake config file, by @<variable_name>@.
1661 Example usage:
1663 Given some plugin-oriented Qt-based software which defines a custom C++
1665 preprocessor macro EXPORT_MYPLUGIN for declaring the central plugin
1666 object:
1667 #define EXPORT_MYPLUGIN_WITH_JSON(classname, jsonFile) \
1669 class classname : public QObject \
1670 { \
1671 Q_OBJECT \
1672 Q_PLUGIN_METADATA(IID "myplugin" FILE jsonFile) \
1673 explicit classname() {} \
1674 };
1675 In the CMake buildsystem of the library one calls
1677 ecm_setup_qtplugin_macro_names(
1679 JSON_ARG2
1680 EXPORT_MYPLUGIN_WITH_JSON
1681 )
1682 to instruct automoc about the usage of that macro in the sources of the
1684 library itself.
1685 Given the software installs a library including the header with the
1687 macro definition and a CMake config file, so 3rd-party can create addi‐
1688 tional plugins by linking against the library, one passes additionally
1689 the name of a variable which shall be set as value the CMake code
1690 needed to instruct automoc about the usage of that macro.
1691 ecm_setup_qtplugin_macro_names(
1693 JSON_ARG2
1694 EXPORT_MYPLUGIN_WITH_JSON
1695 CONFIG_CODE_VARIABLE
1696 PACKAGE_SETUP_AUTOMOC_VARIABLES
1697 )
1698 This variable then is used in the template file (e.g. MyProjectCon‐
1700 fig.cmake.in) for the libary’s installed CMake config file and that way
1701 will ensure that in the 3rd-party plugin’s buildsystem automoc is
1702 instructed as well as needed:
1703 @PACKAGE_SETUP_AUTOMOC_VARIABLES@
1705 Since 5.45.0.
1707 ECMSetupVersion
1709 Handle library version information.
1710 ecm_setup_version(<version>
1712 VARIABLE_PREFIX <prefix>
1713 [SOVERSION <soversion>]
1714 [VERSION_HEADER <filename>]
1715 [PACKAGE_VERSION_FILE <filename> [COMPATIBILITY <compat>]] )
1716 This parses a version string and sets up a standard set of version
1718 variables. It can optionally also create a C version header file and a
1719 CMake package version file to install along with the library.
1720 If the <version> argument is of the form <major>.<minor>.<patch> (or
1722 <major>.<minor>.<patch>.<tweak>), The following CMake variables are
1723 set:
1724 <prefix>_VERSION_MAJOR - <major>
1726 <prefix>_VERSION_MINOR - <minor>
1727 <prefix>_VERSION_PATCH - <patch>
1728 <prefix>_VERSION - <version>
1729 <prefix>_VERSION_STRING - <version> (for compatibility: use <prefix>_VERSION instead)
1730 <prefix>_SOVERSION - <soversion>, or <major> if SOVERSION was not given
1731 If CMake policy CMP0048 is not NEW, the following CMake variables will
1733 also be set:
1734 PROJECT_VERSION_MAJOR - <major>
1736 PROJECT_VERSION_MINOR - <minor>
1737 PROJECT_VERSION_PATCH - <patch>
1738 PROJECT_VERSION - <version>
1739 PROJECT_VERSION_STRING - <version> (for compatibility: use PROJECT_VERSION instead)
1740 If the VERSION_HEADER option is used, a simple C header is generated
1742 with the given filename. If filename is a relative path, it is inter‐
1743 preted as relative to CMAKE_CURRENT_BINARY_DIR. The generated header
1744 contains the following macros:
1745 <prefix>_VERSION_MAJOR - <major> as an integer
1747 <prefix>_VERSION_MINOR - <minor> as an integer
1748 <prefix>_VERSION_PATCH - <patch> as an integer
1749 <prefix>_VERSION_STRING - <version> as a C string
1750 <prefix>_VERSION - the version as an integer
1751 <prefix>_VERSION has <patch> in the bottom 8 bits, <minor> in the next
1753 8 bits and <major> in the remaining bits. Note that <patch> and
1754 <minor> must be less than 256.
1755 If the PACKAGE_VERSION_FILE option is used, a simple CMake package ver‐
1757 sion file is created using the write_basic_package_version_file() macro
1758 provided by CMake. It should be installed in the same location as the
1759 Config.cmake file of the library so that it can be found by find_pack‐
1760 age(). If the filename is a relative path, it is interpreted as rela‐
1761 tive to CMAKE_CURRENT_BINARY_DIR. The optional COMPATIBILITY option is
1762 forwarded to write_basic_package_version_file(), and defaults to
1763 AnyNewerVersion.
1764 If CMake policy CMP0048 is NEW, an alternative form of the command is
1766 available:
1767 ecm_setup_version(PROJECT
1769 [VARIABLE_PREFIX <prefix>]
1770 [SOVERSION <soversion>]
1771 [VERSION_HEADER <filename>]
1772 [PACKAGE_VERSION_FILE <filename>] )
1773 This will use the version information set by the project() command.
1775 VARIABLE_PREFIX defaults to the project name. Note that PROJECT must
1776 be the first argument. In all other respects, it behaves like the
1777 other form of the command.
1778 Since pre-1.0.0.
1780 COMPATIBILITY option available since 1.6.0.
1782 ECMSourceVersionControl
1784 Tries to determine whether the source is under version control (git
1785 clone, svn checkout, etc).
1786 ECM_SOURCE_UNDER_VERSION_CONTROL is set when indication is found that
1788 CMAKE_SOURCE_DIR is under version control.
1789 Since 5.63
1791 ECMUninstallTarget
1793 Add an uninstall target.
1794 By including this module, an uninstall target will be added to your
1796 CMake project. This will remove all files installed (or updated) by a
1797 previous invocation of the install target. It will not remove files
1798 created or modified by an install(SCRIPT) or install(CODE) command; you
1799 should create a custom uninstallation target for these and use
1800 add_dependency to make the uninstall target depend on it:
1801 include(ECMUninstallTarget)
1803 install(SCRIPT install-foo.cmake)
1804 add_custom_target(uninstall_foo COMMAND ${CMAKE_COMMAND} -P uninstall-foo.cmake)
1805 add_dependency(uninstall uninstall_foo)
1806 The target will fail if the install target has not yet been run (so it
1808 is not possible to run CMake on the project and then immediately run
1809 the uninstall target).
1810 WARNING:
1812 CMake deliberately does not provide an uninstall target by default
1813 on the basis that such a target has the potential to remove impor‐
1814 tant files from a user’s computer. Use with caution.
1815 Since 1.7.0.
1817 ECMUseFindModules
1819 Selectively use some of the find modules provided by extra-cmake-mod‐
1820 ules.
1821 This module is automatically available once extra-cmake-modules has
1823 been found, so it is not necessary to include(ECMUseFindModules)
1824 explicitly.
1825 ecm_use_find_modules(DIR <dir>
1827 MODULES module1.cmake [module2.cmake [...]]
1828 [NO_OVERRIDE])
1829 This allows selective use of the find modules provided by ECM, includ‐
1831 ing deferring to CMake’s versions of those modules if it has them.
1832 Rather than adding ${ECM_FIND_MODULE_DIR} to CMAKE_MODULE_PATH, you use
1833 ecm_use_find_modules() to copy the modules you want to a local (build)
1834 directory, and add that to CMAKE_MODULE_PATH.
1835 The find modules given to MODULES will be copied to the directory given
1837 by DIR (which should be located in ${CMAKE_BINARY_DIR} and added to
1838 CMAKE_MODULE_PATH). If NO_OVERRIDE is given, only modules not also
1839 provided by CMake will be copied.
1840 Example:
1842 find_package(ECM REQUIRED)
1844 ecm_use_find_modules(
1845 DIR ${CMAKE_BINARY_DIR}/cmake
1846 MODULES FindEGL.cmake
1847 NO_OVERRIDE
1848 )
1849 set(CMAKE_MODULE_PATH ${CMAKE_BINARY_DIR}/cmake)
1850 This example will make FindEGL.cmake available in your project, but
1852 only as long as it is not yet part of CMake. Calls to find_package(EGL)
1853 will then make use of this copied module (or the CMake module if it
1854 exists).
1855 Another possible use for this macro is to take copies of find modules
1857 that can be installed along with config files if they are required as a
1858 dependency (for example, if targets provided by the find module are in
1859 the link interface of a library).
1860 Since pre-1.0.0.
1862 ECMWinResolveSymlinks
1864 Resolve pseudo-symlinks created by git when cloning on Windows.
1865 ecm_win_resolve_symlinks(<dir>)
1867 When git checks out a repository with UNIX symlinks on Windows machine,
1869 it creates a text file for each symlink, containing a relative path to
1870 the real file. This function would recursively walk over specified
1871 directory and replace pseudo-symlinks with corresponding real file’s
1872 contents. It would then run git update-index –assume-unchanged on them
1873 to trick git.
1874 This is useful for projects like “breeze-icons” that contain many iden‐
1876 tical icons implemented as symlinks.
1877 Since 5.28
1879
1881 ecm(7), ecm-find-modules(7), ecm-kde-modules(7)
1882
1884 KDE Developers
18855.64 Nov 08, 2019 ECM-MODULES(7)