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 [IMAGE_DIRS <idir> [<idir2> [...]]]
133 [EXAMPLE_DIRS <edir> [<edir2> [...]]]
134 [ORG_DOMAIN <domain>]
135 [NAMESPACE <namespace>]
136 [LINK_QCHS <qch> [<qch2> [...]]]
137 [PREDEFINED_MACROS <macro[=content]> [<macro2[=content]> [...]]]
138 [BLANK_MACROS <macro> [<macro2> [...]]]
139 [CONFIG_TEMPLATE <configtemplate_file>]
140 [VERBOSE]
141 )
142 This macro adds a target called <target_name> for the creation of an
144 API documentation manual in the QCH format from the given sources. It
145 currently uses doxygen, future versions might optionally also allow
146 other tools. Next to the QCH file the target will generate a corre‐
147 sponding doxygen tag file, which enables creating links from other doc‐
148 umentation into the generated QCH file.
149 It is recommended to make the use of this macro optional, by depending
151 the call to ecm_add_qch on a CMake option being set, with a name like
152 BUILD_QCH and being TRUE by default. This will allow the developers to
153 saves resources on normal source development build cycles by setting
154 this option to FALSE.
155 The macro will set the target properties DOXYGEN_TAGFILE, QHP_NAMES‐
157 PACE, QHP_NAMESPACE_VERSIONED, QHP_VIRTUALFOLDER and LINK_QCHS to the
158 respective values, to allow other code access to them, e.g. the macro
159 ecm_install_qch_export. To enable the use of the target <target_name>
160 as item for LINK_QCHS in further ecm_add_qch calls in the current
161 build, additionally a target property DOXYGEN_TAGFILE_BUILD is set,
162 with the path of the created doxygen tag file in the build dir. If
163 existing, ecm_add_qch will use this property instead of DOXYGEN_TAGFILE
164 for access to the tags file.
165 NAME specifies the name for the generated documentation.
167 VERSION specifies the version of the library for which the documenta‐
169 tion is created.
170 BASE_NAME specifies the base name for the generated files. The default
172 basename is <name>.
173 SOURCE_DIRS specifies the dirs (incl. subdirs) with the source files
175 for which the API documentation should be generated. Dirs can be rela‐
176 tive to the current source dir. Dependencies to the files in the dirs
177 are not tracked currently, other than with the SOURCES argument. So do
178 not use for sources generated during the build. Needs to be used when
179 SOURCES or CONFIG_TEMPLATE are not used.
180 SOURCES specifies the source files for which the API documentation
182 should be generated. Needs to be used when SOURCE_DIRS or CONFIG_TEM‐
183 PLATE are not used.
184 MD_MAINPAGE specifies a file in Markdown format that should be used as
186 main page. This page will overrule any \mainpage command in the
187 included sources.
188 IMAGE_DIRS specifies the dirs which contain images that are included in
190 the documentation. Dirs can be relative to the current source dir.
191 EXAMPLE_DIRS specifies the dirs which contain examples that are
193 included in the documentation. Dirs can be relative to the current
194 source dir.
195 QCH_INSTALL_DESTINATION specifies where the generated QCH file will be
197 installed.
198 TAGFILE_INSTALL_DESTINATION specifies where the generated tag file will
200 be installed.
201 COMPONENT specifies the installation component name with which the
203 install rules for the generated QCH file and tag file are associated.
204 NAMESPACE can be used to set a custom namespace <namespace> of the gen‐
206 erated QCH file. The namepspace is used as the unique id by QHelpEngine
207 (cmp. https://doc.qt.io/qt-5/qthelpproject.html#namespace). The
208 default namespace is <domain>.<name>. Needs to be used when ORG_DOMAIN
209 is not used.
210 ORG_DOMAIN can be used to define the organization domain prefix for the
212 default namespace of the generated QCH file. Needs to be used when
213 NAMESPACE is not used.
214 LINK_QCHS specifies a list of other QCH targets which should be used
216 for creating references to API documentation of code in external
217 libraries. For each target <qch> in the list these target properties
218 are expected to be defined: DOXYGEN_TAGFILE, QHP_NAMESPACE and QHP_VIR‐
219 TUALFOLDER. If any of these is not existing, <qch> will be ignored.
220 Use the macro ecm_install_qch_export for exporting a target with these
221 properties with the CMake config of a library. Any target <qch> can
222 also be one created before in the same buildsystem by another call of
223 ecm_add_qch.
224 PREDEFINED_MACROS specifies a list of C/C++ macros which should be han‐
226 dled as given by the API dox generation tool. Examples are macros only
227 defined in generated files, so whose definition might be not available
228 to the tool.
229 BLANK_MACROS specifies a list of C/C++ macro names which should be
231 ignored by the API dox generation tool and handled as if they resolve
232 to empty strings. Examples are export macros only defined in generated
233 files, so whose definition might be not available to the tool.
234 CONFIG_TEMPLATE specifies a custom cmake template file for the config
236 file that is created to control the execution of the API dox generation
237 tool. The following CMake variables need to be used: ECM_QCH_DOXY‐
238 GEN_QHELPGENERATOR_EXECUTABLE, ECM_QCH_DOXYGEN_FILEPATH, ECM_QCH_DOXY‐
239 GEN_TAGFILE. The following CMake variables can be used: ECM_QCH_DOXY‐
240 GEN_PROJECTNAME, ECM_QCH_DOXYGEN_PROJECTVERSION, ECM_QCH_DOXYGEN_VIRTU‐
241 ALFOLDER, ECM_QCH_DOXYGEN_FULLNAMESPACE, ECM_QCH_DOXYGEN_TAGFILES,
242 ECM_QCH_DOXYGEN_WARN_LOGFILE, ECM_QCH_DOXYGEN_QUIET. There is no guar‐
243 antue that the other CMake variables currently used in the default con‐
244 fig file template will also be present with the same semantics in
245 future versions of this macro.
246 VERBOSE tells the API dox generation tool to be more verbose about its
248 activity.
249 Example usage:
251 ecm_add_qch(
253 MyLib_QCH
254 NAME MyLib
255 VERSION "0.42.0"
256 ORG_DOMAIN org.myorg
257 SOURCE_DIRS
258 src
259 LINK_QCHS
260 Qt5Core_QCH
261 Qt5Xml_QCH
262 Qt5Gui_QCH
263 Qt5Widgets_QCH
264 BLANK_MACROS
265 MyLib_EXPORT
266 MyLib_DEPRECATED
267 TAGFILE_INSTALL_DESTINATION ${CMAKE_INSTALL_PREFIX}/share/docs/tags
268 QCH_INSTALL_DESTINATION ${CMAKE_INSTALL_PREFIX}/share/docs/qch
269 COMPONENT Devel
270 )
271 Example usage (with two QCH files, second linking first):
273 ecm_add_qch(
275 MyLib_QCH
276 NAME MyLib
277 VERSION ${MyLib_VERSION}
278 ORG_DOMAIN org.myorg
279 SOURCES ${MyLib_PUBLIC_HEADERS}
280 MD_MAINPAGE src/mylib/README.md
281 LINK_QCHS Qt5Core_QCH
282 TAGFILE_INSTALL_DESTINATION ${CMAKE_INSTALL_PREFIX}/share/docs/tags
283 QCH_INSTALL_DESTINATION ${CMAKE_INSTALL_PREFIX}/share/docs/qch
284 COMPONENT Devel
285 )
286 ecm_add_qch(
287 MyOtherLib_QCH
288 NAME MyOtherLib
289 VERSION ${MyOtherLib_VERSION}
290 ORG_DOMAIN org.myorg
291 SOURCES ${MyOtherLib_PUBLIC_HEADERS}
292 MD_MAINPAGE src/myotherlib/README.md
293 LINK_QCHS Qt5Core_QCH MyLib_QCH
294 TAGFILE_INSTALL_DESTINATION ${CMAKE_INSTALL_PREFIX}/share/docs/tags
295 QCH_INSTALL_DESTINATION ${CMAKE_INSTALL_PREFIX}/share/docs/qch
296 COMPONENT Devel
297 )
298 ecm_install_qch_export(
300 TARGETS [<name> [<name2> [...]]]
301 FILE <file>
302 DESTINATION <dest>
303 [COMPONENT <component>]
304 )
305 This macro creates and installs a CMake file <file> which exports the
307 given QCH targets <name> etc., so they can be picked up by CMake-based
308 builds of other software that also generate QCH files (using
309 ecm_add_qch) and which should include links to the QCH files created by
310 the given targets. The installed CMake file <file> is expected to be
311 included by the CMake config file created for the software the related
312 QCH files are documenting.
313 TARGETS specifies the QCH targets which should be exported. If a target
315 does not exist or does not have all needed properties, a warning will
316 be generated and the target skipped. This behaviour might change in
317 future versions to result in a fail instead.
318 FILE specifies the name of the created CMake file, typically with a
320 .cmake extension.
321 DESTINATION specifies the directory on disk to which the file will be
323 installed. It usually is the same as the one where the CMake config
324 files for this software are installed.
325 COMPONENT specifies the installation component name with which the
327 install rule is associated.
328 Example usage:
330 ecm_install_qch_export(
332 TARGETS MyLib_QCH
333 FILE MyLibQCHTargets.cmake
334 DESTINATION "${CMAKE_INSTALL_PREFIX}/lib/cmake/MyLib"
335 COMPONENT Devel
336 )
337 Since 5.36.0.
339 ECMAddTests
341 Convenience functions for adding tests.
342 ecm_add_tests(<sources> LINK_LIBRARIES <library> [<library> [...]]
344 [NAME_PREFIX <prefix>]
345 [GUI]
346 [TARGET_NAMES_VAR <target_names_var>]
347 [TEST_NAMES_VAR <test_names_var>])
348 A convenience function for adding multiple tests, each consisting of a
350 single source file. For each file in <sources>, an executable target
351 will be created (the name of which will be the basename of the source
352 file). This will be linked against the libraries given with
353 LINK_LIBRARIES. Each executable will be added as a test with the same
354 name.
355 If NAME_PREFIX is given, this prefix will be prepended to the test
357 names, but not the target names. As a result, it will not prevent
358 clashes between tests with the same name in different parts of the
359 project, but it can be used to give an indication of where to look for
360 a failing test.
361 If the flag GUI is passed the test binaries will be GUI executables,
363 otherwise the resulting binaries will be console applications (regard‐
364 less of the value of CMAKE_WIN32_EXECUTABLE or CMAKE_MACOSX_BUNDLE). Be
365 aware that this changes the executable entry point on Windows (although
366 some frameworks, such as Qt, abstract this difference away).
367 The TARGET_NAMES_VAR and TEST_NAMES_VAR arguments, if given, should
369 specify a variable name to receive the list of generated target and
370 test names, respectively. This makes it convenient to apply properties
371 to them as a whole, for example, using set_target_properties() or
372 set_tests_properties().
373 The generated target executables will have the effects of
375 ecm_mark_as_test() (from the ECMMarkAsTest module) applied to it.
376 ecm_add_test(<sources> LINK_LIBRARIES <library> [<library> [...]]
378 [TEST_NAME <name>]
379 [NAME_PREFIX <prefix>]
380 [GUI])
381 This is a single-test form of ecm_add_tests that allows multiple source
383 files to be used for a single test. If using multiple source files,
384 TEST_NAME must be given; this will be used for both the target and test
385 names (and, as with ecm_add_tests(), the NAME_PREFIX argument will be
386 prepended to the test name).
387 Since pre-1.0.0.
389 ECMCoverageOption
391 Allow users to easily enable GCov code coverage support.
392 Code coverage allows you to check how much of your codebase is covered
394 by your tests. This module makes it easy to build with support for
395 GCov.
396 When this module is included, a BUILD_COVERAGE option is added (default
398 OFF). Turning this option on enables GCC’s coverage instrumentation,
399 and links against libgcov.
400 Note that this will probably break the build if you are not using GCC.
402 Since 1.3.0.
404 ECMCreateQmFromPoFiles
406 WARNING:
407 This module is deprecated and will be removed by ECM 1.0. Use ECMPo‐
408 QmTools instead.
409 Generate QTranslator (.qm) catalogs from Gettext (.po) catalogs.
411 ecm_create_qm_from_po_files(PO_FILES <file1>... <fileN>
413 [CATALOG_NAME <catalog_name>]
414 [INSTALL_DESTINATION <install_destination>])
415 Creates the necessary rules to compile .po files into .qm files, and
417 install them.
418 The .qm files are installed in <install_destination>/<lang>/LC_MES‐
420 SAGES, where <install_destination> is the INSTALL_DESTINATION argument
421 and <lang> is extracted from the “Language” field inside the .po file.
422 INSTALL_DESTINATION defaults to ${LOCALE_INSTALL_DIR} if defined, oth‐
424 erwise it uses ${CMAKE_INSTALL_LOCALEDIR} if that is defined, otherwise
425 it uses share/locale.
426 CATALOG_NAME defines the name of the installed .qm files. If set, .qm
428 files will be installed as <catalog_name>.qm. If not set .qm files will
429 be named after the name of their source .po file.
430 Setting the catalog name is useful when all .po files for a target are
432 kept in a single source directory. For example, the “mylib” probject
433 might keep all its translations in a “po” directory, like this:
434 po/
436 es.po
437 fr.po
438 Without setting CATALOG_NAME, those .po will be turned into .qm and
440 installed as:
441 share/locale/fr/LC_MESSAGES/fr.qm
443 share/locale/es/LC_MESSAGES/es.qm
444 If CATALOG_NAME is set to “mylib”, they will be installed as:
446 share/locale/fr/LC_MESSAGES/mylib.qm
448 share/locale/es/LC_MESSAGES/mylib.qm
449 Which is what the loader created by ecm_create_qm_loader() expects.
451 ecm_create_qm_from_po_files() creates a “translation” target. This tar‐
453 get builds all .po files into .qm files.
454 ecm_create_qm_loader(<source_files_var> <catalog_name>)
456 ecm_create_qm_loader() generates a C++ file which ensures translations
458 are automatically loaded at startup. The path of the .cpp file is
459 appended to <source_files_var>. Typical usage is like:
460 set(mylib_SRCS foo.cpp bar.cpp)
462 ecm_create_qm_loader(mylib_SRCS mylib)
463 add_library(mylib ${mylib_SRCS})
464 This generates a C++ file which loads “mylib.qm” at startup, assuming
466 it has been installed by ecm_create_qm_from_po_files(), and compiles it
467 into mylib.
468 Since pre-1.0.0.
470 ECMEnableSanitizers
472 Enable compiler sanitizer flags.
473 The following sanitizers are supported:
475 · Address Sanitizer
477 · Memory Sanitizer
479 · Thread Sanitizer
481 · Leak Sanitizer
483 · Undefined Behaviour Sanitizer
485 All of them are implemented in Clang, depending on your version, and
487 there is an work in progress in GCC, where some of them are currently
488 implemented.
489 This module will check your current compiler version to see if it sup‐
491 ports the sanitizers that you want to enable
492 Usage
494 Simply add:
495 include(ECMEnableSanitizers)
497 to your CMakeLists.txt. Note that this module is included in KDECompil‐
499 erSettings, so projects using that module do not need to also include
500 this one.
501 The sanitizers are not enabled by default. Instead, you must set
503 ECM_ENABLE_SANITIZERS (either in your CMakeLists.txt or on the command
504 line) to a semicolon-separated list of sanitizers you wish to enable.
505 The options are:
506 · address
508 · memory
510 · thread
512 · leak
514 · undefined
516 · fuzzer
518 The sanitizers “address”, “memory” and “thread” are mutually exclusive.
520 You cannot enable two of them in the same build.
521 “leak” requires the “address” sanitizer.
523 NOTE:
525 To reduce the overhead induced by the instrumentation of the sani‐
526 tizers, it is advised to enable compiler optimizations (-O1 or
527 higher).
528 Example
530 This is an example of usage:
531 mkdir build
533 cd build
534 cmake -DECM_ENABLE_SANITIZERS='address;leak;undefined' ..
535 NOTE:
537 Most of the sanitizers will require Clang. To enable it, use:
538 -DCMAKE_CXX_COMPILER=clang++
540 Since 1.3.0.
542 ECMFindModuleHelpers
544 Helper macros for find modules: ecm_find_package_version_check(),
545 ecm_find_package_parse_components() and ecm_find_package_han‐
546 dle_library_components().
547 ecm_find_package_version_check(<name>)
549 Prints warnings if the CMake version or the project’s required CMake
551 version is older than that required by extra-cmake-modules.
552 ecm_find_package_parse_components(<name>
554 RESULT_VAR <variable>
555 KNOWN_COMPONENTS <component1> [<component2> [...]]
556 [SKIP_DEPENDENCY_HANDLING])
557 This macro will populate <variable> with a list of components found in
559 <name>_FIND_COMPONENTS, after checking that all those components are in
560 the list of KNOWN_COMPONENTS; if there are any unknown components, it
561 will print an error or warning (depending on the value of
562 <name>_FIND_REQUIRED) and call return().
563 The order of components in <variable> is guaranteed to match the order
565 they are listed in the KNOWN_COMPONENTS argument.
566 If SKIP_DEPENDENCY_HANDLING is not set, for each component the variable
568 <name>_<component>_component_deps will be checked for dependent compo‐
569 nents. If <component> is listed in <name>_FIND_COMPONENTS, then all
570 its (transitive) dependencies will also be added to <variable>.
571 ecm_find_package_handle_library_components(<name>
573 COMPONENTS <component> [<component> [...]]
574 [SKIP_DEPENDENCY_HANDLING])
575 [SKIP_PKG_CONFIG])
576 Creates an imported library target for each component. The operation
578 of this macro depends on the presence of a number of CMake variables.
579 The <name>_<component>_lib variable should contain the name of this
581 library, and <name>_<component>_header variable should contain the name
582 of a header file associated with it (whatever relative path is normally
583 passed to ‘#include’). <name>_<component>_header_subdir variable can be
584 used to specify which subdirectory of the include path the headers will
585 be found in. ecm_find_package_components() will then search for the
586 library and include directory (creating appropriate cache variables)
587 and create an imported library target named <name>::<component>.
588 Additional variables can be used to provide additional information:
590 If SKIP_PKG_CONFIG, the <name>_<component>_pkg_config variable is set,
592 and pkg-config is found, the pkg-config module given by <name>_<compo‐
593 nent>_pkg_config will be searched for and used to help locate the
594 library and header file. It will also be used to set <name>_<compo‐
595 nent>_VERSION.
596 Note that if version information is found via pkg-config, <name>_<com‐
598 ponent>_FIND_VERSION can be set to require a particular version for
599 each component.
600 If SKIP_DEPENDENCY_HANDLING is not set, the INTERFACE_LINK_LIBRARIES
602 property of the imported target for <component> will be set to contain
603 the imported targets for the components listed in <name>_<compo‐
604 nent>_component_deps. <component>_FOUND will also be set to false if
605 any of the compoments in <name>_<component>_component_deps are not
606 found. This requires the components in <name>_<component>_compo‐
607 nent_deps to be listed before <component> in the COMPONENTS argument.
608 The following variables will be set:
610 <name>_TARGETS
612 the imported targets
613 <name>_LIBRARIES
615 the found libraries
616 <name>_INCLUDE_DIRS
618 the combined required include directories for the components
619 <name>_DEFINITIONS
621 the “other” CFLAGS provided by pkg-config, if any
622 <name>_VERSION
624 the value of <name>_<component>_VERSION for the first component
625 that has this variable set (note that components are searched
626 for in the order they are passed to the macro), although if it
627 is already set, it will not be altered
628 Note that these variables are never cleared, so if ecm_find_pack‐
630 age_handle_library_components() is called multiple times with different
631 components (typically because of multiple find_package() calls) then
632 <name>_TARGETS, for example, will contain all the targets found in any
633 call (although no duplicates).
634 Since pre-1.0.0.
636 ECMGenerateHeaders
638 Generate C/C++ CamelCase forwarding headers.
639 ecm_generate_headers(<camelcase_forwarding_headers_var>
641 HEADER_NAMES <CamelCaseName> [<CamelCaseName> [...]]
642 [ORIGINAL <CAMELCASE|LOWERCASE>]
643 [HEADER_EXTENSION <header_extension>]
644 [OUTPUT_DIR <output_dir>]
645 [PREFIX <prefix>]
646 [REQUIRED_HEADERS <variable>]
647 [COMMON_HEADER <HeaderName>]
648 [RELATIVE <relative_path>])
649 For each CamelCase header name passed to HEADER_NAMES, a file of that
651 name will be generated that will include a version with .h or, if set,
652 .<header_extension> appended. For example, the generated header ClassA
653 will include classa.h (or ClassA.h, see ORIGINAL). If a CamelCaseName
654 consists of multiple comma-separated files, e.g. ClassA,ClassB,ClassC,
655 then multiple camelcase header files will be generated which are redi‐
656 rects to the first header file. The file locations of these generated
657 headers will be stored in <camelcase_forwarding_headers_var>.
658 ORIGINAL specifies how the name of the original header is written: low‐
660 ercased or also camelcased. The default is LOWERCASE. Since 1.8.0.
661 HEADER_EXTENSION specifies what file name extension is used for the
663 header files. The default is “h”. Since 5.48.0.
664 PREFIX places the generated headers in subdirectories. This should be
666 a CamelCase name like KParts, which will cause the CamelCase forwarding
667 headers to be placed in the KParts directory (e.g. KParts/Part). It
668 will also, for the convenience of code in the source distribution, gen‐
669 erate forwarding headers based on the original names (e.g.
670 kparts/part.h). This allows includes like "#include <kparts/part.h>"
671 to be used before installation, as long as the include_directories are
672 set appropriately.
673 OUTPUT_DIR specifies where the files will be generated; this should be
675 within the build directory. By default, ${CMAKE_CURRENT_BINARY_DIR}
676 will be used. This option can be used to avoid file conflicts.
677 REQUIRED_HEADERS specifies an output variable name where all the
679 required headers will be appended so that they can be installed
680 together with the generated ones. This is mostly intended as a conve‐
681 nience so that adding a new header to a project only requires specify‐
682 ing the CamelCase variant in the CMakeLists.txt file; the original
683 variant will then be added to this variable.
684 COMMON_HEADER generates an additional convenience header which includes
686 all other header files.
687 The RELATIVE argument indicates where the original headers can be found
689 relative to CMAKE_CURRENT_SOURCE_DIR. It does not affect the generated
690 CamelCase forwarding files, but ecm_generate_headers() uses it when
691 checking that the original header exists, and to generate originally
692 named forwarding headers when PREFIX is set.
693 To allow other parts of the source distribution (eg: tests) to use the
695 generated headers before installation, it may be desirable to set the
696 INCLUDE_DIRECTORIES property for the library target to output_dir. For
697 example, if OUTPUT_DIR is CMAKE_CURRENT_BINARY_DIR (the default), you
698 could do
699 target_include_directories(MyLib PUBLIC "$<BUILD_INTERFACE:${CMAKE_CURRENT_BINARY_DIR}>")
701 Example usage (without PREFIX):
703 ecm_generate_headers(
705 MyLib_FORWARDING_HEADERS
706 HEADERS
707 MLFoo
708 MLBar
709 # etc
710 REQUIRED_HEADERS MyLib_HEADERS
711 COMMON_HEADER MLGeneral
712 )
713 install(FILES ${MyLib_FORWARDING_HEADERS} ${MyLib_HEADERS}
714 DESTINATION ${CMAKE_INSTALL_PREFIX}/include
715 COMPONENT Devel)
716 Example usage (with PREFIX):
718 ecm_generate_headers(
720 MyLib_FORWARDING_HEADERS
721 HEADERS
722 Foo
723 # several classes are contained in bar.h, so generate
724 # additional files
725 Bar,BarList
726 # etc
727 PREFIX MyLib
728 REQUIRED_HEADERS MyLib_HEADERS
729 )
730 install(FILES ${MyLib_FORWARDING_HEADERS}
731 DESTINATION ${CMAKE_INSTALL_PREFIX}/include/MyLib
732 COMPONENT Devel)
733 install(FILES ${MyLib_HEADERS}
734 DESTINATION ${CMAKE_INSTALL_PREFIX}/include/mylib
735 COMPONENT Devel)
736 Since pre-1.0.0.
738 ECMGeneratePkgConfigFile
740 Generate a pkg-config file for the benefit of autotools-based projects.
741 ecm_generate_pkgconfig_file(BASE_NAME <baseName>
743 [LIB_NAME <libName>]
744 [DEPS "<dep> [<dep> [...]]"]
745 [FILENAME_VAR <filename_variable>]
746 [INCLUDE_INSTALL_DIR <dir>]
747 [LIB_INSTALL_DIR <dir>]
748 [DEFINES -D<variable=value>...]
749 [DESCRIPTION <library description>] # since 5.41.0
750 [INSTALL])
751 BASE_NAME is the name of the module. It’s the name projects will use to
753 find the module.
754 LIB_NAME is the name of the library that is being exported. If unde‐
756 fined, it will default to the BASE_NAME. That means the LIB_NAME will
757 be set as the name field as well as the library to link to.
758 FILENAME_VAR is specified with a variable name. This variable will
760 receive the location of the generated file will be set, within the
761 build directory. This way it can be used in case some processing is
762 required. See also INSTALL.
763 INCLUDE_INSTALL_DIR specifies where the includes will be installed. If
765 it’s not specified, it will default to INSTALL_INCLUDEDIR,
766 CMAKE_INSTALL_INCLUDEDIR or just “include/” in case they are specified,
767 with the BASE_NAME postfixed.
768 LIB_INSTALL_DIR specifies where the library is being installed. If it’s
770 not specified, it will default to LIB_INSTALL_DIR, CMAKE_INSTALL_LIBDIR
771 or just “lib/” in case they are specified.
772 DEFINES is a list of preprocessor defines that it is recommended users
774 of the library pass to the compiler when using it.
775 DESCRIPTION describes what this library is. If it’s not specified,
777 CMake will first try to get the description from the metainfo.yaml file
778 or will create one based on LIB_NAME. Since 5.41.0.
779 INSTALL will cause the module to be installed to the pkgconfig subdi‐
781 rectory of LIB_INSTALL_DIR, unless the ECM_PKGCONFIG_INSTALL_DIR cache
782 variable is set to something different. Note that the first call to
783 ecm_generate_pkgconfig_file with the INSTALL argument will cause
784 ECM_PKGCONFIG_INSTALL_DIR to be set to the cache, and will be used in
785 any subsequent calls.
786 To properly use this macro a version needs to be set. To retrieve it,
788 ECM_PKGCONFIG_INSTALL_DIR uses PROJECT_VERSION. To set it, use the
789 project() command (only available since CMake 3.0) or the ecm_set‐
790 up_version() macro.
791 Example usage:
793 ecm_generate_pkgconfig_file(
795 BASE_NAME KF5Archive
796 DEPS Qt5Core
797 FILENAME_VAR pkgconfig_filename
798 INSTALL
799 )
800 Since 1.3.0.
802 ECMGeneratePriFile
804 Generate a .pri file for the benefit of qmake-based projects.
805 As well as the function below, this module creates the cache variable
807 ECM_MKSPECS_INSTALL_DIR and sets the default value to mkspecs/modules.
808 This assumes Qt and the current project are both installed to the same
809 non-system prefix. Packagers who use -DCMAKE_INSTALL_PREFIX=/usr will
810 certainly want to set ECM_MKSPECS_INSTALL_DIR to something like
811 share/qt5/mkspecs/modules.
812 The main thing is that this should be the modules subdirectory of
814 either the default qmake mkspecs directory or of a directory that will
815 be in the $QMAKEPATH environment variable when qmake is run.
816 ecm_generate_pri_file(BASE_NAME <baseName>
818 LIB_NAME <libName>
819 [DEPS "<dep> [<dep> [...]]"]
820 [FILENAME_VAR <filename_variable>]
821 [INCLUDE_INSTALL_DIR <dir>]
822 [LIB_INSTALL_DIR <dir>])
823 If your CMake project produces a Qt-based library, you may expect there
825 to be applications that wish to use it that use a qmake-based build
826 system, rather than a CMake-based one. Creating a .pri file will make
827 use of your library convenient for them, in much the same way that
828 CMake config files make things convenient for CMake-based applications.
829 ecm_generate_pri_file() generates just such a file. It requires the
831 PROJECT_VERSION_STRING variable to be set. This is typically set by
832 ECMSetupVersion, although the project() command in CMake 3.0.0 and
833 later can also set this.
834 BASE_NAME specifies the name qmake project (.pro) files should use to
836 refer to the library (eg: KArchive). LIB_NAME is the name of the
837 actual library to link to (ie: the first argument to add_library()).
838 DEPS is a space-separated list of the base names of other libraries
839 (for Qt libraries, use the same names you use with the QT variable in a
840 qmake project file, such as “core” for QtCore). FILENAME_VAR specifies
841 the name of a variable to store the path to the generated file in.
842 INCLUDE_INSTALL_DIR is the path (relative to CMAKE_INSTALL_PREFIX) that
844 include files will be installed to. It defaults to
845 ${INCLUDE_INSTALL_DIR}/<baseName> if the INCLUDE_INSTALL_DIR variable
846 is set. If that variable is not set, the CMAKE_INSTALL_INCLUDEDIR vari‐
847 able is used instead, and if neither are set include is used.
848 LIB_INSTALL_DIR operates similarly for the installation location for
849 libraries; it defaults to ${LIB_INSTALL_DIR}, ${CMAKE_INSTALL_LIBDIR}
850 or lib, in that order.
851 Example usage:
853 ecm_generate_pri_file(
855 BASE_NAME KArchive
856 LIB_NAME KF5KArchive
857 DEPS "core"
858 FILENAME_VAR pri_filename
859 )
860 install(FILES ${pri_filename} DESTINATION ${ECM_MKSPECS_INSTALL_DIR})
861 A qmake-based project that wished to use this would then do:
863 QT += KArchive
865 in their .pro file.
867 Since pre-1.0.0.
869 ECMGenerateQmlTypes
871 Generates plugins.qmltypes files for QML plugins.
872 ecm_generate_qmltypes(<org.kde.pluginname> 1.3
874 DESTINATION <${KDE_INSTALL_QMLDIR}/org/kde/pluginname>)
875 Makes it possible to generate plugins.qmltypes files for the QML plug‐
877 ins that our project offers. These files offer introspection upon our
878 plugin and are useful for integrating with IDE language support of our
879 plugin. It offers information about the objects its methods and their
880 argument types.
881 The developer will be in charge of making sure that these files are up
883 to date. The plugin.qmltypes file will sit in the source directory.
884 This function will include the code that installs the file in the right
885 place and a small unit test named qmltypes-pluginname-version that
886 makes sure that it doesn’t need updating.
887 Since 5.33.0
889 ECMInstallIcons
891 Installs icons, sorting them into the correct directories according to
892 the FreeDesktop.org icon naming specification.
893 ecm_install_icons(ICONS <icon> [<icon> [...]]
895 DESTINATION <icon_install_dir>
896 [LANG <l10n_code>]
897 [THEME <theme>])
898 The given icons, whose names must match the pattern:
900 <size>-<group>-<name>.<ext>
902 will be installed to the appropriate subdirectory of DESTINATION
904 according to the FreeDesktop.org icon naming scheme. By default, they
905 are installed to the “hicolor” theme, but this can be changed using the
906 THEME argument. If the icons are localized, the LANG argument can be
907 used to install them in a locale-specific directory.
908 <size> is a numeric pixel size (typically 16, 22, 32, 48, 64, 128 or
910 256) or sc for scalable (SVG) files, <group> is one of the standard
911 FreeDesktop.org icon groups (actions, animations, apps, categories,
912 devices, emblems, emotes, intl, mimetypes, places, status) and <ext> is
913 one of .png, .mng or .svgz.
914 The typical installation directory is share/icons.
916 ecm_install_icons(ICONS 22-actions-menu_new.png
918 DESTINATION share/icons)
919 The above code will install the file 22-actions-menu_new.png as
921 ${CMAKE_INSTALL_PREFIX}/share/icons/<theme>/22x22/actions/menu_new.png
922 Users of the KDEInstallDirs module would normally use
924 ${KDE_INSTALL_ICONDIR} as the DESTINATION, while users of the GNUIn‐
925 stallDirs module should use ${CMAKE_INSTALL_DATAROOTDIR}/icons.
926 An old form of arguments will also be accepted:
928 ecm_install_icons(<icon_install_dir> [<l10n_code>])
930 This matches files named like:
932 <theme><size>-<group>-<name>.<ext>
934 where <theme> is one of * hi for hicolor * lo for locolor * cr for the
936 Crystal icon theme * ox for the Oxygen icon theme * br for the Breeze
937 icon theme
938 With this syntax, the file hi22-actions-menu_new.png would be installed
940 into <icon_install_dir>/hicolor/22x22/actions/menu_new.png
941 Since pre-1.0.0.
943 ECMMarkAsTest
945 Marks a target as only being required for tests.
946 ecm_mark_as_test(<target1> [<target2> [...]])
948 This will cause the specified targets to not be built unless either
950 BUILD_TESTING is set to ON or the user invokes the buildtests target.
951 BUILD_TESTING is created as a cache variable by the CTest module and by
953 the KDECMakeSettings module.
954 Since pre-1.0.0.
956 ECMMarkNonGuiExecutable
958 Marks an executable target as not being a GUI application.
959 ecm_mark_nongui_executable(<target1> [<target2> [...]])
961 This will indicate to CMake that the specified targets should not be
963 included in a MACOSX_BUNDLE and should not be WIN32_EXECUTABLEs. On
964 platforms other than MacOS X or Windows, this will have no effect.
965 Since pre-1.0.0.
967 ECMOptionalAddSubdirectory
969 Make subdirectories optional.
970 ecm_optional_add_subdirectory(<dir>)
972 This behaves like add_subdirectory(), except that it does not complain
974 if the directory does not exist. Additionally, if the directory does
975 exist, it creates an option to allow the user to skip it. The option
976 will be named BUILD_<dir>.
977 This is useful for “meta-projects” that combine several mostly-indepen‐
979 dent sub-projects.
980 If the CMake variable DISABLE_ALL_OPTIONAL_SUBDIRECTORIES is set to
982 TRUE for the first CMake run on the project, all optional subdirecto‐
983 ries will be disabled by default (but can of course be enabled via the
984 respective options). For example, the following will disable all
985 optional subdirectories except the one named “foo”:
986 cmake -DDISABLE_ALL_OPTIONAL_SUBDIRECTORIES=TRUE -DBUILD_foo=TRUE myproject
988 Since pre-1.0.0.
990 ECMPackageConfigHelpers
992 Helper macros for generating CMake package config files.
993 write_basic_package_version_file() is the same as the one provided by
995 the CMakePackageConfigHelpers module in CMake; see that module’s docu‐
996 mentation for more information.
997 ecm_configure_package_config_file(<input> <output>
999 INSTALL_DESTINATION <path>
1000 [PATH_VARS <var1> [<var2> [...]]
1001 [NO_SET_AND_CHECK_MACRO]
1002 [NO_CHECK_REQUIRED_COMPONENTS_MACRO])
1003 This behaves in the same way as configure_package_config_file() from
1005 CMake 2.8.12, except that it adds an extra helper macro: find_depen‐
1006 dency(). It is highly recommended that you read the documentation for
1007 CMakePackageConfigHelpers for more information, particularly with
1008 regard to the PATH_VARS argument.
1009 Note that there is no argument that will disable the find_dependency()
1011 macro; if you do not require this macro, you should use configure_pack‐
1012 age_config_file from the CMakePackageConfigHelpers module.
1013 CMake 3.0 includes a CMakeFindDependencyMacro module that provides the
1015 find_dependency() macro (which you can include() in your package config
1016 file), so this file is only useful for projects wishing to provide con‐
1017 fig files that will work with CMake 2.8.12.
1018 Additional Config File Macros
1020 find_dependency(<dep> [<version> [EXACT]])
1021 find_dependency() should be used instead of find_package() to find
1023 package dependencies. It forwards the correct parameters for EXACT,
1024 QUIET and REQUIRED which were passed to the original find_package()
1025 call. It also sets an informative diagnostic message if the dependency
1026 could not be found.
1027 Since pre-1.0.0.
1029 ECMPoQmTools
1031 This module provides the ecm_process_po_files_as_qm and
1032 ecm_install_po_files_as_qm functions for generating QTranslator (.qm)
1033 catalogs from Gettext (.po) catalogs, and the ecm_create_qm_loader
1034 function for generating the necessary code to load them in a Qt appli‐
1035 cation or library.
1036 ecm_process_po_files_as_qm(<lang> [ALL]
1038 [INSTALL_DESTINATION <install_destination>]
1039 PO_FILES <pofile> [<pofile> [...]])
1040 Compile .po files into .qm files for the given language.
1042 If INSTALL_DESTINATION is given, the .qm files are installed in
1044 <install_destination>/<lang>/LC_MESSAGES. Typically, <install_destina‐
1045 tion> is set to share/locale.
1046 ecm_process_po_files_as_qm creates a “translations” target. This target
1048 builds all .po files into .qm files. If ALL is specified, these rules
1049 are added to the “all” target (and so the .qm files will be built by
1050 default).
1051 ecm_create_qm_loader(<source_files_var> <catalog_name>)
1053 Generates C++ code which ensures translations are automatically loaded
1055 at startup. The generated files are appended to <source_files_var>.
1056 It assumes that the .qm file for the language code <lang> is installed
1058 as <sharedir>/locale/<lang>/LC_MESSAGES/<catalog_name>.qm, where
1059 <sharedir> is one of the directories given by the GenericDataLocation
1060 of QStandardPaths.
1061 Typical usage is like:
1063 set(mylib_SRCS foo.cpp bar.cpp)
1065 ecm_create_qm_loader(mylib_SRCS mylib)
1066 add_library(mylib ${mylib_SRCS})
1067 ecm_install_po_files_as_qm(<podir>)
1069 Searches for .po files and installs them to the standard location.
1071 This is a convenience function which relies on all .po files being kept
1073 in <podir>/<lang>/, where <lang> is the language the .po files are
1074 written in.
1075 For example, given the following directory structure:
1077 po/
1079 fr/
1080 mylib.po
1081 ecm_install_po_files_as_qm(po) compiles mylib.po into mylib.qm and
1083 installs it in <install_destination>/fr/LC_MESSAGES. <install_destina‐
1084 tion> defaults to ${LOCALE_INSTALL_DIR} if defined, otherwise it uses
1085 ${CMAKE_INSTALL_LOCALEDIR} if that is defined, otherwise it uses
1086 share/locale.
1087 Since pre-1.0.0.
1089 ECMQMLModules
1091 Find QML import modules through a find_qmlmodule() call. It uses the
1092 qmlplugindump application to find the plugins and sets them up as run‐
1093 time dependencies.
1094 This is useful so that when we configure a project we are noified when
1096 some QML imports are not present in the system, thus having the appli‐
1097 cation compilable but fail at runtime.
1098 ecm_find_qmlmodule(<module_name> <version>...)
1100 Any further arguments passed will be forwarded into a find_package()
1102 call. See find_package() documentation for more information.
1103 Usage example:
1105 ecm_find_qmlmodule(org.kde.kirigami 2.1)
1107 Since 5.38.0.
1109 ECMQtDeclareLoggingCategory
1111 Generate declarations for logging categories in Qt5.
1112 ecm_qt_declare_logging_category(<sources_var>
1114 HEADER <filename>
1115 IDENTIFIER <identifier>
1116 CATEGORY_NAME <category_name>
1117 [DEFAULT_SEVERITY
1118 <Debug|Info|Warning|
1119 Critical|Fatal>])
1120 A header file, <filename>, will be generated along with a corresponding
1122 source file, which will be added to <sources_var>. These will provide a
1123 QLoggingCategory category that can be referred to from C++ code using
1124 <identifier>, and from the logging configuration using <category_name>.
1125 If <filename> is not absolute, it will be taken relative to the current
1127 binary directory.
1128 If the code is compiled against Qt 5.4 or later, by default it will
1130 only log output that is at least the severity specified by
1131 DEFAULT_SEVERITY, or “Info” level if DEFAULT_SEVERITY is not given.
1132 Note that, due to a bug in Qt 5.5, “Info” may be treated as more severe
1133 than “Fatal”.
1134 <identifier> may include namespaces (eg: foo::bar::IDENT).
1136 Since 5.14.0.
1138 ECMSetupQtPluginMacroNames
1140 Instruct CMake’s automoc about C++ preprocessor macros used to define
1141 Qt-style plugins.
1142 ecm_setup_qtplugin_macro_names(
1144 [JSON_NONE <macro_name> [<macro_name> [...]]]
1145 [JSON_ARG1 <macro_name> [<macro_name> [...]]]
1146 [JSON_ARG2 <macro_name> [<macro_name> [...]]]
1147 [JSON_ARG3 <macro_name> [<macro_name> [...]]]
1148 [CONFIG_CODE_VARIABLE <variable_name>] )
1149 CMake’s automoc needs some support when parsing C++ source files to
1151 detect whether moc should be run on those files and if there are also
1152 dependencies on other files, like those with Qt plugin metadata in JSON
1153 format. Because automoc just greps overs the raw plain text of the
1154 sources without any C++ preprocessor-like processing. CMake in newer
1155 versions provides the variables CMAKE_AUTOMOC_DEPEND_FILTERS (CMake >=
1156 3.9.0) and CMAKE_AUTOMOC_MACRO_NAMES (CMake >= 3.10) to allow the
1157 developer to assist automoc.
1158 This macro cares for the explicit setup needed for those variables for
1160 common cases of C++ preprocessor macros used for Qt-style plugins.
1161 JSON_NONE lists the names of C++ preprocessor macros for Qt-style plug‐
1163 ins which do not refer to external files with the plugin metadata.
1164 JSON_ARG1 lists the names of C++ preprocessor macros for Qt-style plug‐
1166 ins where the first argument to the macro is the name of the external
1167 file with the plugin metadata.
1168 JSON_ARG2 is the same as JSON_ARG1 but with the file name being the
1170 second argument.
1171 JSON_ARG3 is the same as JSON_ARG1 but with the file name being the
1173 third argument.
1174 CONFIG_CODE_VARIABLE specifies the name of the variable which will get
1176 set as value some generated CMake code for instructing automoc for the
1177 given macro names, as useful in an installed CMake config file. The
1178 variable can then be used as usual in the template file for such a
1179 CMake config file, by @<variable_name>@.
1180 Example usage:
1182 Given some plugin-oriented Qt-based software which defines a custom C++
1184 preprocessor macro EXPORT_MYPLUGIN for declaring the central plugin
1185 object:
1186 #define EXPORT_MYPLUGIN_WITH_JSON(classname, jsonFile) \
1188 class classname : public QObject \
1189 { \
1190 Q_OBJECT \
1191 Q_PLUGIN_METADATA(IID "myplugin" FILE jsonFile) \
1192 explicit classname() {} \
1193 };
1194 In the CMake buildsystem of the library one calls
1196 ecm_setup_qtplugin_macro_names(
1198 JSON_ARG2
1199 EXPORT_MYPLUGIN_WITH_JSON
1200 )
1201 to instruct automoc about the usage of that macro in the sources of the
1203 library itself.
1204 Given the software installs a library including the header with the
1206 macro definition and a CMake config file, so 3rd-party can create addi‐
1207 tional plugins by linking against the library, one passes additionally
1208 the name of a variable which shall be set as value the CMake code
1209 needed to instruct automoc about the usage of that macro.
1210 ecm_setup_qtplugin_macro_names(
1212 JSON_ARG2
1213 EXPORT_MYPLUGIN_WITH_JSON
1214 CONFIG_CODE_VARIABLE
1215 PACKAGE_SETUP_AUTOMOC_VARIABLES
1216 )
1217 This variable then is used in the template file (e.g. MyProjectCon‐
1219 fig.cmake.in) for the libary’s installed CMake config file and that way
1220 will ensure that in the 3rd-party plugin’s buildsystem automoc is
1221 instructed as well as needed:
1222 @PACKAGE_SETUP_AUTOMOC_VARIABLES@
1224 Since 5.45.0.
1226 ECMSetupVersion
1228 Handle library version information.
1229 ecm_setup_version(<version>
1231 VARIABLE_PREFIX <prefix>
1232 [SOVERSION <soversion>]
1233 [VERSION_HEADER <filename>]
1234 [PACKAGE_VERSION_FILE <filename> [COMPATIBILITY <compat>]] )
1235 This parses a version string and sets up a standard set of version
1237 variables. It can optionally also create a C version header file and a
1238 CMake package version file to install along with the library.
1239 If the <version> argument is of the form <major>.<minor>.<patch> (or
1241 <major>.<minor>.<patch>.<tweak>), The following CMake variables are
1242 set:
1243 <prefix>_VERSION_MAJOR - <major>
1245 <prefix>_VERSION_MINOR - <minor>
1246 <prefix>_VERSION_PATCH - <patch>
1247 <prefix>_VERSION - <version>
1248 <prefix>_VERSION_STRING - <version> (for compatibility: use <prefix>_VERSION instead)
1249 <prefix>_SOVERSION - <soversion>, or <major> if SOVERSION was not given
1250 If CMake policy CMP0048 is not NEW, the following CMake variables will
1252 also be set:
1253 PROJECT_VERSION_MAJOR - <major> PROJECT_VERSION_MINOR - <minor>
1254 PROJECT_VERSION_PATCH - <patch> PROJECT_VERSION - <ver‐
1255 sion> PROJECT_VERSION_STRING - <version> (for compatibility: use
1256 PROJECT_VERSION instead)
1257 If the VERSION_HEADER option is used, a simple C header is generated
1259 with the given filename. If filename is a relative path, it is inter‐
1260 preted as relative to CMAKE_CURRENT_BINARY_DIR. The generated header
1261 contains the following macros:
1262 <prefix>_VERSION_MAJOR - <major> as an integer
1264 <prefix>_VERSION_MINOR - <minor> as an integer
1265 <prefix>_VERSION_PATCH - <patch> as an integer
1266 <prefix>_VERSION_STRING - <version> as a C string
1267 <prefix>_VERSION - the version as an integer
1268 <prefix>_VERSION has <patch> in the bottom 8 bits, <minor> in the next
1270 8 bits and <major> in the remaining bits. Note that <patch> and
1271 <minor> must be less than 256.
1272 If the PACKAGE_VERSION_FILE option is used, a simple CMake package ver‐
1274 sion file is created using the write_basic_package_version_file() macro
1275 provided by CMake. It should be installed in the same location as the
1276 Config.cmake file of the library so that it can be found by find_pack‐
1277 age(). If the filename is a relative path, it is interpreted as rela‐
1278 tive to CMAKE_CURRENT_BINARY_DIR. The optional COMPATIBILITY option is
1279 forwarded to write_basic_package_version_file(), and defaults to
1280 AnyNewerVersion.
1281 If CMake policy CMP0048 is NEW, an alternative form of the command is
1283 available:
1284 ecm_setup_version(PROJECT
1286 [VARIABLE_PREFIX <prefix>]
1287 [SOVERSION <soversion>]
1288 [VERSION_HEADER <filename>]
1289 [PACKAGE_VERSION_FILE <filename>] )
1290 This will use the version information set by the project() command.
1292 VARIABLE_PREFIX defaults to the project name. Note that PROJECT must
1293 be the first argument. In all other respects, it behaves like the
1294 other form of the command.
1295 Since pre-1.0.0.
1297 COMPATIBILITY option available since 1.6.0.
1299 ECMUninstallTarget
1301 Add an uninstall target.
1302 By including this module, an uninstall target will be added to your
1304 CMake project. This will remove all files installed (or updated) by a
1305 previous invocation of the install target. It will not remove files
1306 created or modified by an install(SCRIPT) or install(CODE) command; you
1307 should create a custom uninstallation target for these and use
1308 add_dependency to make the uninstall target depend on it:
1309 include(ECMUninstallTarget)
1311 install(SCRIPT install-foo.cmake)
1312 add_custom_target(uninstall_foo COMMAND ${CMAKE_COMMAND} -P uninstall-foo.cmake)
1313 add_dependency(uninstall uninstall_foo)
1314 The target will fail if the install target has not yet been run (so it
1316 is not possible to run CMake on the project and then immediately run
1317 the uninstall target).
1318 WARNING:
1320 CMake deliberately does not provide an uninstall target by default
1321 on the basis that such a target has the potential to remove impor‐
1322 tant files from a user’s computer. Use with caution.
1323 Since 1.7.0.
1325 ECMUseFindModules
1327 Selectively use some of the find modules provided by extra-cmake-mod‐
1328 ules.
1329 This module is automatically available once extra-cmake-modules has
1331 been found, so it is not necessary to include(ECMUseFindModules)
1332 explicitly.
1333 ecm_use_find_modules(DIR <dir>
1335 MODULES module1.cmake [module2.cmake [...]]
1336 [NO_OVERRIDE])
1337 This allows selective use of the find modules provided by ECM, includ‐
1339 ing deferring to CMake’s versions of those modules if it has them.
1340 Rather than adding ${ECM_FIND_MODULE_DIR} to CMAKE_MODULE_PATH, you use
1341 ecm_use_find_modules() to copy the modules you want to a local (build)
1342 directory, and add that to CMAKE_MODULE_PATH.
1343 The find modules given to MODULES will be copied to the directory given
1345 by DIR (which should be located in ${CMAKE_BINARY_DIR} and added to
1346 CMAKE_MODULE_PATH). If NO_OVERRIDE is given, only modules not also
1347 provided by CMake will be copied.
1348 Example:
1350 find_package(ECM REQUIRED)
1352 ecm_use_find_modules(
1353 DIR ${CMAKE_BINARY_DIR}/cmake
1354 MODULES FindEGL.cmake
1355 NO_OVERRIDE
1356 )
1357 set(CMAKE_MODULE_PATH ${CMAKE_BINARY_DIR}/cmake)
1358 This example will make FindEGL.cmake available in your project, but
1360 only as long as it is not yet part of CMake. Calls to find_package(EGL)
1361 will then make use of this copied module (or the CMake module if it
1362 exists).
1363 Another possible use for this macro is to take copies of find modules
1365 that can be installed along with config files if they are required as a
1366 dependency (for example, if targets provided by the find module are in
1367 the link interface of a library).
1368 Since pre-1.0.0.
1370 ECMWinResolveSymlinks
1372 Resolve pseudo-symlinks created by git when cloning on Windows.
1373 ecm_win_resolve_symlinks(<dir>)
1375 When git checks out a repository with UNIX symlinks on Windows machine,
1377 it creates a text file for each symlink, containing a relative path to
1378 the real file. This function would recursively walk over specified
1379 directory and replace pseudo-symlinks with corresponding real file’s
1380 contents. It would then run git update-index –assume-unchanged on them
1381 to trick git.
1382 This is useful for projects like “breeze-icons” that contain many iden‐
1384 tical icons implemented as symlinks.
1385 Since 5.28
1387
1389 ecm(7), ecm-find-modules(7), ecm-kde-modules(7)
1390
1392 KDE Developers
13935.58 May 14, 2019 ECM-MODULES(7)