Provided by: extra-cmake-modules_5.68.0-0ubuntu1_amd64 
NAME
ecm-modules - ECM Modules Reference
INTRODUCTION
Extra CMake Modules (ECM) provides various modules that provide useful functions for CMake
scripts. ECM actually provides three types of modules that can be used from CMake scripts:
those that extend the functionality of the find_package command are documented in
ecm-find-modules(7); those that provide standard settings for software produced by the KDE
community are documented in ecm-kde-modules(7). The rest provide macros and functions for
general use by CMake scripts and are documented here.
To use these modules, you need to tell CMake to find the ECM package, and then add either
${ECM_MODULE_PATH} or ${ECM_MODULE_DIR} to the CMAKE_MODULE_PATH variable:
find_package(ECM REQUIRED NO_MODULE)
set(CMAKE_MODULE_PATH ${ECM_MODULE_DIR})
Using ${ECM_MODULE_PATH} will also make the find modules and KDE modules available.
Note that there are also toolchain modules, documented in ecm-toolchains(7), but these are
used by users building the software rather than developers writing CMake scripts.
ALL MODULES
ECMAddAppIcon
Add icons to executable files and packages.
ecm_add_app_icon(<sources_var>
ICONS <icon> [<icon> [...]]
[SIDEBAR_ICONS <icon> [<icon> [...]] # Since 5.49
[OUTFILE_BASENAME <name>]) # Since 5.49
)
The given icons, whose names must match the pattern:
<size>-<other_text>.png
will be added to the executable target whose sources are specified by <sources_var> on
platforms that support it (Windows and Mac OS X). Other icon files are ignored but on Mac
SVG files can be supported and it is thus possible to mix those with png files in a single
macro call.
<size> is a numeric pixel size (typically 16, 32, 48, 64, 128 or 256). <other_text> can
be any other text. See the platform notes below for any recommendations about icon sizes.
SIDEBAR_ICONS can be used to add Mac OS X sidebar icons to the generated iconset. They are
used when a folder monitored by the application is dragged into Finder’s sidebar. Since
5.49.
OUTFILE_BASENAME will be used as the basename for the icon file. If you specify it, the
icon file will be called <OUTFILE_BASENAME>.icns on Mac OS X and <OUTFILE_BASENAME>.ico on
Windows. If you don’t specify it, it defaults to <sources_var>.<ext>. Since 5.49.
Windows notes
• Icons are compiled into the executable using a resource file.
• Icons may not show up in Windows Explorer if the executable target does not have
the WIN32_EXECUTABLE property set.
• One of the tools png2ico (See FindPng2Ico) or icotool (see FindIcoTool) is
required.
• Supported sizes: 16, 24, 32, 48, 64, 128, 256, 512 and 1024.
Mac OS X notes
• The executable target must have the MACOSX_BUNDLE property set.
• Icons are added to the bundle.
• If the ksvg2icns tool from KIconThemes is available, .svg and .svgz files are
accepted; the first that is converted successfully to .icns will provide the
application icon. SVG files are ignored otherwise.
• The tool iconutil (provided by Apple) is required for bitmap icons.
• Supported sizes: 16, 32, 64, 128, 256 (and 512, 1024 after OS X 10.9).
• At least a 128x128px (or an SVG) icon is required.
• Larger sizes are automatically used to substitute for smaller sizes on “Retina”
(high-resolution) displays. For example, a 32px icon, if provided, will be used
as a 32px icon on standard-resolution displays, and as a 16px-equivalent icon
(with an “@2x” tag) on high-resolution displays. That is why you should provide
64px and 1024px icons although they are not supported anymore directly. Instead
they will be used as 32px@2x and 512px@2x. ksvg2icns handles this internally.
• This function sets the MACOSX_BUNDLE_ICON_FILE variable to the name of the
generated icns file, so that it will be used as the MACOSX_BUNDLE_ICON_FILE
target property when you call add_executable.
• Sidebar icons should typically provided in 16, 32, 64, 128 and 256px.
Since 1.7.0.
ECMAddQch
This module provides the ecm_add_qch function for generating API documentation files in
the QCH format, and the ecm_install_qch_export function for generating and installing
exported CMake targets for such generated QCH files to enable builds of other software
with generation of QCH files to create links into the given QCH files.
ecm_add_qch(<target_name>
NAME <name>
VERSION <version>
QCH_INSTALL_DESTINATION <qchfile_install_path>
TAGFILE_INSTALL_DESTINATION <tagsfile_install_path>
[COMPONENT <component>]
[BASE_NAME <basename>]
[SOURCE_DIRS <dir> [<dir2> [...]]]
[SOURCES <file> [<file2> [...]]]
|MD_MAINPAGE <md_file>]
[INCLUDE_DIRS <incdir> [<incdir2> [...]]]
[IMAGE_DIRS <idir> [<idir2> [...]]]
[EXAMPLE_DIRS <edir> [<edir2> [...]]]
[ORG_DOMAIN <domain>]
[NAMESPACE <namespace>]
[LINK_QCHS <qch> [<qch2> [...]]]
[PREDEFINED_MACROS <macro[=content]> [<macro2[=content]> [...]]]
[BLANK_MACROS <macro> [<macro2> [...]]]
[CONFIG_TEMPLATE <configtemplate_file>]
[VERBOSE]
)
This macro adds a target called <target_name> for the creation of an API documentation
manual in the QCH format from the given sources. It currently uses doxygen, future
versions might optionally also allow other tools. Next to the QCH file the target will
generate a corresponding doxygen tag file, which enables creating links from other
documentation into the generated QCH file.
It is recommended to make the use of this macro optional, by depending the call to
ecm_add_qch on a CMake option being set, with a name like BUILD_QCH and being TRUE by
default. This will allow the developers to saves resources on normal source development
build cycles by setting this option to FALSE.
The macro will set the target properties DOXYGEN_TAGFILE, QHP_NAMESPACE,
QHP_NAMESPACE_VERSIONED, QHP_VIRTUALFOLDER and LINK_QCHS to the respective values, to
allow other code access to them, e.g. the macro ecm_install_qch_export. To enable the use
of the target <target_name> as item for LINK_QCHS in further ecm_add_qch calls in the
current build, additionally a target property DOXYGEN_TAGFILE_BUILD is set, with the path
of the created doxygen tag file in the build dir. If existing, ecm_add_qch will use this
property instead of DOXYGEN_TAGFILE for access to the tags file.
NAME specifies the name for the generated documentation.
VERSION specifies the version of the library for which the documentation is created.
BASE_NAME specifies the base name for the generated files. The default basename is
<name>.
SOURCE_DIRS specifies the dirs (incl. subdirs) with the source files for which the API
documentation should be generated. Dirs can be relative to the current source dir.
Dependencies to the files in the dirs are not tracked currently, other than with the
SOURCES argument. So do not use for sources generated during the build. Needs to be used
when SOURCES or CONFIG_TEMPLATE are not used.
SOURCES specifies the source files for which the API documentation should be generated.
Needs to be used when SOURCE_DIRS or CONFIG_TEMPLATE are not used.
MD_MAINPAGE specifies a file in Markdown format that should be used as main page. This
page will overrule any \mainpage command in the included sources.
INCLUDE_DIRS specifies the dirs which should be searched for included headers. Dirs can be
relative to the current source dir. Since 5.63.
IMAGE_DIRS specifies the dirs which contain images that are included in the documentation.
Dirs can be relative to the current source dir.
EXAMPLE_DIRS specifies the dirs which contain examples that are included in the
documentation. Dirs can be relative to the current source dir.
QCH_INSTALL_DESTINATION specifies where the generated QCH file will be installed.
TAGFILE_INSTALL_DESTINATION specifies where the generated tag file will be installed.
COMPONENT specifies the installation component name with which the install rules for the
generated QCH file and tag file are associated.
NAMESPACE can be used to set a custom namespace <namespace> of the generated QCH file. The
namepspace is used as the unique id by QHelpEngine (cmp.
https://doc.qt.io/qt-5/qthelpproject.html#namespace). The default namespace is
<domain>.<name>. Needs to be used when ORG_DOMAIN is not used.
ORG_DOMAIN can be used to define the organization domain prefix for the default namespace
of the generated QCH file. Needs to be used when NAMESPACE is not used.
LINK_QCHS specifies a list of other QCH targets which should be used for creating
references to API documentation of code in external libraries. For each target <qch> in
the list these target properties are expected to be defined: DOXYGEN_TAGFILE,
QHP_NAMESPACE and QHP_VIRTUALFOLDER. If any of these is not existing, <qch> will be
ignored. Use the macro ecm_install_qch_export for exporting a target with these
properties with the CMake config of a library. Any target <qch> can also be one created
before in the same buildsystem by another call of ecm_add_qch.
PREDEFINED_MACROS specifies a list of C/C++ macros which should be handled as given by the
API dox generation tool. Examples are macros only defined in generated files, so whose
definition might be not available to the tool.
BLANK_MACROS specifies a list of C/C++ macro names which should be ignored by the API dox
generation tool and handled as if they resolve to empty strings. Examples are export
macros only defined in generated files, so whose definition might be not available to the
tool.
CONFIG_TEMPLATE specifies a custom cmake template file for the config file that is created
to control the execution of the API dox generation tool. The following CMake variables
need to be used: ECM_QCH_DOXYGEN_QHELPGENERATOR_EXECUTABLE, ECM_QCH_DOXYGEN_FILEPATH,
ECM_QCH_DOXYGEN_TAGFILE. The following CMake variables can be used:
ECM_QCH_DOXYGEN_PROJECTNAME, ECM_QCH_DOXYGEN_PROJECTVERSION,
ECM_QCH_DOXYGEN_VIRTUALFOLDER, ECM_QCH_DOXYGEN_FULLNAMESPACE, ECM_QCH_DOXYGEN_TAGFILES,
ECM_QCH_DOXYGEN_WARN_LOGFILE, ECM_QCH_DOXYGEN_QUIET. There is no guarantue that the other
CMake variables currently used in the default config file template will also be present
with the same semantics in future versions of this macro.
VERBOSE tells the API dox generation tool to be more verbose about its activity.
The default config file for the API dox generation tool, so the one when not using
CONFIG_TEMPLATE, allows code to handle the case of being processed by the tool by defining
the C/C++ preprocessor macro K_DOXYGEN when run (since v5.67.0). For
backward-compatibility also the definition DOXYGEN_SHOULD_SKIP_THIS is set, but its usage
is deprecated.
Example usage:
ecm_add_qch(
MyLib_QCH
NAME MyLib
VERSION "0.42.0"
ORG_DOMAIN org.myorg
SOURCE_DIRS
src
LINK_QCHS
Qt5Core_QCH
Qt5Xml_QCH
Qt5Gui_QCH
Qt5Widgets_QCH
BLANK_MACROS
MyLib_EXPORT
MyLib_DEPRECATED
TAGFILE_INSTALL_DESTINATION ${CMAKE_INSTALL_PREFIX}/share/docs/tags
QCH_INSTALL_DESTINATION ${CMAKE_INSTALL_PREFIX}/share/docs/qch
COMPONENT Devel
)
Example usage (with two QCH files, second linking first):
ecm_add_qch(
MyLib_QCH
NAME MyLib
VERSION ${MyLib_VERSION}
ORG_DOMAIN org.myorg
SOURCES ${MyLib_PUBLIC_HEADERS}
MD_MAINPAGE src/mylib/README.md
LINK_QCHS Qt5Core_QCH
TAGFILE_INSTALL_DESTINATION ${CMAKE_INSTALL_PREFIX}/share/docs/tags
QCH_INSTALL_DESTINATION ${CMAKE_INSTALL_PREFIX}/share/docs/qch
COMPONENT Devel
)
ecm_add_qch(
MyOtherLib_QCH
NAME MyOtherLib
VERSION ${MyOtherLib_VERSION}
ORG_DOMAIN org.myorg
SOURCES ${MyOtherLib_PUBLIC_HEADERS}
MD_MAINPAGE src/myotherlib/README.md
LINK_QCHS Qt5Core_QCH MyLib_QCH
TAGFILE_INSTALL_DESTINATION ${CMAKE_INSTALL_PREFIX}/share/docs/tags
QCH_INSTALL_DESTINATION ${CMAKE_INSTALL_PREFIX}/share/docs/qch
COMPONENT Devel
)
ecm_install_qch_export(
TARGETS [<name> [<name2> [...]]]
FILE <file>
DESTINATION <dest>
[COMPONENT <component>]
)
This macro creates and installs a CMake file <file> which exports the given QCH targets
<name> etc., so they can be picked up by CMake-based builds of other software that also
generate QCH files (using ecm_add_qch) and which should include links to the QCH files
created by the given targets. The installed CMake file <file> is expected to be included
by the CMake config file created for the software the related QCH files are documenting.
TARGETS specifies the QCH targets which should be exported. If a target does not exist or
does not have all needed properties, a warning will be generated and the target skipped.
This behaviour might change in future versions to result in a fail instead.
FILE specifies the name of the created CMake file, typically with a .cmake extension.
DESTINATION specifies the directory on disk to which the file will be installed. It
usually is the same as the one where the CMake config files for this software are
installed.
COMPONENT specifies the installation component name with which the install rule is
associated.
Example usage:
ecm_install_qch_export(
TARGETS MyLib_QCH
FILE MyLibQCHTargets.cmake
DESTINATION "${CMAKE_INSTALL_PREFIX}/lib/cmake/MyLib"
COMPONENT Devel
)
Since 5.36.0.
ECMAddQtDesignerPlugin
This module provides the ecm_add_qtdesignerplugin function for generating Qt Designer
plugins for custom widgets. Each of those widgets is described using a second function
ecm_qtdesignerplugin_widget.
ecm_add_qtdesignerplugin(<target_name>
NAME <name>
WIDGETS <widgetid> [<widgetid2> [...]]
LINK_LIBRARIES <lib> [<lib2> [...]]
INSTALL_DESTINATION <install_path>
[OUTPUT_NAME <output_name>]
[DEFAULT_GROUP <group>]
[DEFAULT_HEADER_CASE <SAME_CASE|LOWER_CASE|UPPER_CASE>]
[DEFAULT_HEADER_EXTENSION <header_extension>]
[DEFAULT_ICON_DIR <icon_dir>]
[INCLUDE_FILES <include_file> [<include_file2> [...]]]
[SOURCES <src> [<src2> [...]]]
[COMPONENT <component>]
)
NAME specifies the base name to use in the generated sources. The default is
<target_name>.
WIDGETS specifies the widgets the plugin should support. Each widget has to be defined
before by a call of ecm_qtdesignerplugin_widget with the respective <widgetid>, in a scope
including the current call.
LINK_LIBRARIES specifies the libraries to link against. This will be at least the library
providing the widget class(es).
INSTALL_DESTINATION specifies where the generated plugin binary will be installed.
OUTPUT_NAME specifies the name of the plugin binary. The default is “<target_name>”.
DEFAULT_GROUP specifies the default group in Qt Designer where the widgets will be placed.
The default is “Custom”.
DEFAULT_HEADER_CASE specifies how the name of the header is derived from the widget class
name. The default is “LOWER_CASE”.
DEFAULT_HEADER_EXTENSION specifies what file name extension is used for the header file
derived from the class name. The default is “h”.
DEFAULT_ICON_DIR specifies what file name extension is used for the header file derived
from the class name. The default is “pics”.
INCLUDE_FILES specifies additional include files to include with the generated source
file. This can be needed for custom code used in initializing or creating widgets.
SOURCES specifies additional source files to build the plugin from. This can be needed to
support custom code used in initializing or creating widgets.
COMPONENT specifies the installation component name with which the install rules for the
generated plugin are associated.
ecm_qtdesignerplugin_widget(<widgetid>
[CLASS_NAME <class_name>]
[INCLUDE_FILE <include_file>]
[CONTAINER]
[ICON <iconfile>]
[TOOLTIP <tooltip>]
[WHATSTHIS <whatsthis>]
[GROUP <group>]
[CREATE_WIDGET_CODE_FROM_VARIABLE <create_widget_code_variable>]
[INITIALIZE_CODE_FROM_VARIABLE <initialize_code_variable]
[DOM_XML_FROM_VARIABLE <dom_xml_variable>]
[IMPL_CLASS_NAME <impl_class_name>]
[CONSTRUCTOR_ARGS_CODE <constructor_args_code>]
[CONSTRUCTOR_ARGS_CODE_FROM_VARIABLE <constructor_args_code_variable>]
)
CLASS_NAME specifies the name of the widget class, including namespaces. The default is
“<widgetid>”.
INCLUDE_FILE specifies the include file to use for the class of this widget. The default
is derived from <class_name> as configured by the DEFAULT_HEADER_* options of
ecm_add_qtdesignerplugin, also replacing any namespace separators with “/”.
CONTAINER specifies, if set, that this widget is a container for other widgets.
ICON specifies the icon file to use as symbol for this widget. The default is
“{lowercased <class_name>}.png” in the default icons dir as configured by the
DEFAULT_ICON_DIR option of ecm_add_qtdesignerplugin, if such a file exists.
TOOLTIP specifies the tooltip text to use for this widget. Default is “<class_name>
Widget”.
WHATSTHIS specifies the What’s-This text to use for this widget. Defaults to the tooltip.
GROUP specifies the group in Qt Designer where the widget will be placed. The default is
set as configured by the DEFAULT_GROUP option of ecm_add_qtdesignerplugin.
CREATE_WIDGET_CODE_FROM_VARIABLE specifies the variable to get from the C++ code to use as
factory code to create an instance of the widget, for the override of
QDesignerCustomWidgetInterface::createWidget(QWidget* parent). The default is “return new
<impl_class_name><constructor_args_code>;”.
INITIALIZE_CODE_FROM_VARIABLE specifies the variable to get from the C++ code to use with
the override of QDesignerCustomWidgetInterface::initialize(QDesignerFormEditorInterface*
core). The code has to use the present class member m_initialized to track and update the
state. The default code simply sets m_initialized to true, if it was not before.
DOM_XML_FROM_VARIABLE specifies the variable to get from the string to use with the
optional override of QDesignerCustomWidgetInterface::domXml(). Default does not override.
IMPL_CLASS_NAME specifies the name of the widget class to use for the widget instance with
Qt Designer. The default is “<class_name>”.
CONSTRUCTOR_ARGS_CODE specifies the C++ code to use for the constructor arguments with the
default of CREATE_WIDGET_CODE_FROM_VARIABLE. Note that the parentheses are required. The
default is “(parent)”.
CONSTRUCTOR_ARGS_CODE_FROM_VARIABLE specifies the variable to get from the C++ code
instead of passing it directly via CONSTRUCTOR_ARGS_CODE. This can be needed if the code
is more complex and e.g. includes “;” chars.
Example usage:
ecm_qtdesignerplugin_widget(FooWidget
TOOLTIP "Enables to browse foo."
GROUP "Views (Foo)"
)
set(BarWidget_CREATE_WIDGET_CODE
"
auto* widget = new BarWidget(parent);
widget->setBar("Example bar");
return widget;
")
ecm_qtdesignerplugin_widget(BarWidget
TOOLTIP "Displays bars."
GROUP "Display (Foo)"
CREATE_WIDGET_CODE_FROM_VARIABLE BarWidget_CREATE_WIDGET_CODE
)
ecm_add_qtdesignerplugin(foowidgets
NAME FooWidgets
OUTPUT_NAME foo2widgets
WIDGETS
FooWidget
BarWidget
LINK_LIBRARIES
Foo::Widgets
INSTALL_DESTINATION "${KDE_INSTALL_QTPLUGINDIR}/designer"
COMPONENT Devel
)
Since 5.62.0.
ECMAddTests
Convenience functions for adding tests.
ecm_add_tests(<sources> LINK_LIBRARIES <library> [<library> [...]]
[NAME_PREFIX <prefix>]
[GUI]
[TARGET_NAMES_VAR <target_names_var>]
[TEST_NAMES_VAR <test_names_var>])
A convenience function for adding multiple tests, each consisting of a single source file.
For each file in <sources>, an executable target will be created (the name of which will
be the basename of the source file). This will be linked against the libraries given with
LINK_LIBRARIES. Each executable will be added as a test with the same name.
If NAME_PREFIX is given, this prefix will be prepended to the test names, but not the
target names. As a result, it will not prevent clashes between tests with the same name in
different parts of the project, but it can be used to give an indication of where to look
for a failing test.
If the flag GUI is passed the test binaries will be GUI executables, otherwise the
resulting binaries will be console applications (regardless of the value of
CMAKE_WIN32_EXECUTABLE or CMAKE_MACOSX_BUNDLE). Be aware that this changes the executable
entry point on Windows (although some frameworks, such as Qt, abstract this difference
away).
The TARGET_NAMES_VAR and TEST_NAMES_VAR arguments, if given, should specify a variable
name to receive the list of generated target and test names, respectively. This makes it
convenient to apply properties to them as a whole, for example, using
set_target_properties() or set_tests_properties().
The generated target executables will have the effects of ecm_mark_as_test() (from the
ECMMarkAsTest module) applied to it.
ecm_add_test(<sources> LINK_LIBRARIES <library> [<library> [...]]
[TEST_NAME <name>]
[NAME_PREFIX <prefix>]
[GUI])
This is a single-test form of ecm_add_tests that allows multiple source files to be used
for a single test. If using multiple source files, TEST_NAME must be given; this will be
used for both the target and test names (and, as with ecm_add_tests(), the NAME_PREFIX
argument will be prepended to the test name).
Since pre-1.0.0.
ECMCoverageOption
Allow users to easily enable GCov code coverage support.
Code coverage allows you to check how much of your codebase is covered by your tests. This
module makes it easy to build with support for GCov.
When this module is included, a BUILD_COVERAGE option is added (default OFF). Turning this
option on enables GCC’s coverage instrumentation, and links against libgcov.
Note that this will probably break the build if you are not using GCC.
Since 1.3.0.
ECMCreateQmFromPoFiles
WARNING:
This module is deprecated and will be removed by ECM 1.0. Use ECMPoQmTools instead.
Generate QTranslator (.qm) catalogs from Gettext (.po) catalogs.
ecm_create_qm_from_po_files(PO_FILES <file1>... <fileN>
[CATALOG_NAME <catalog_name>]
[INSTALL_DESTINATION <install_destination>])
Creates the necessary rules to compile .po files into .qm files, and install them.
The .qm files are installed in <install_destination>/<lang>/LC_MESSAGES, where
<install_destination> is the INSTALL_DESTINATION argument and <lang> is extracted from the
“Language” field inside the .po file.
INSTALL_DESTINATION defaults to ${LOCALE_INSTALL_DIR} if defined, otherwise it uses
${CMAKE_INSTALL_LOCALEDIR} if that is defined, otherwise it uses share/locale.
CATALOG_NAME defines the name of the installed .qm files. If set, .qm files will be
installed as <catalog_name>.qm. If not set .qm files will be named after the name of their
source .po file.
Setting the catalog name is useful when all .po files for a target are kept in a single
source directory. For example, the “mylib” probject might keep all its translations in a
“po” directory, like this:
po/
es.po
fr.po
Without setting CATALOG_NAME, those .po will be turned into .qm and installed as:
share/locale/fr/LC_MESSAGES/fr.qm
share/locale/es/LC_MESSAGES/es.qm
If CATALOG_NAME is set to “mylib”, they will be installed as:
share/locale/fr/LC_MESSAGES/mylib.qm
share/locale/es/LC_MESSAGES/mylib.qm
Which is what the loader created by ecm_create_qm_loader() expects.
ecm_create_qm_from_po_files() creates a “translation” target. This target builds all .po
files into .qm files.
ecm_create_qm_loader(<source_files_var> <catalog_name>)
ecm_create_qm_loader() generates a C++ file which ensures translations are automatically
loaded at startup. The path of the .cpp file is appended to <source_files_var>. Typical
usage is like:
set(mylib_SRCS foo.cpp bar.cpp)
ecm_create_qm_loader(mylib_SRCS mylib)
add_library(mylib ${mylib_SRCS})
This generates a C++ file which loads “mylib.qm” at startup, assuming it has been
installed by ecm_create_qm_from_po_files(), and compiles it into mylib.
Since pre-1.0.0.
ECMEnableSanitizers
Enable compiler sanitizer flags.
The following sanitizers are supported:
• Address Sanitizer
• Memory Sanitizer
• Thread Sanitizer
• Leak Sanitizer
• Undefined Behaviour Sanitizer
All of them are implemented in Clang, depending on your version, and there is an work in
progress in GCC, where some of them are currently implemented.
This module will check your current compiler version to see if it supports the sanitizers
that you want to enable
Usage
Simply add:
include(ECMEnableSanitizers)
to your CMakeLists.txt. Note that this module is included in KDECompilerSettings, so
projects using that module do not need to also include this one.
The sanitizers are not enabled by default. Instead, you must set ECM_ENABLE_SANITIZERS
(either in your CMakeLists.txt or on the command line) to a semicolon-separated list of
sanitizers you wish to enable. The options are:
• address
• memory
• thread
• leak
• undefined
• fuzzer
The sanitizers “address”, “memory” and “thread” are mutually exclusive. You cannot enable
two of them in the same build.
“leak” requires the “address” sanitizer.
NOTE:
To reduce the overhead induced by the instrumentation of the sanitizers, it is advised
to enable compiler optimizations (-O1 or higher).
Example
This is an example of usage:
mkdir build
cd build
cmake -DECM_ENABLE_SANITIZERS='address;leak;undefined' ..
NOTE:
Most of the sanitizers will require Clang. To enable it, use:
-DCMAKE_CXX_COMPILER=clang++
Since 1.3.0.
ECMFindModuleHelpers
Helper macros for find modules: ecm_find_package_version_check(),
ecm_find_package_parse_components() and ecm_find_package_handle_library_components().
ecm_find_package_version_check(<name>)
Prints warnings if the CMake version or the project’s required CMake version is older than
that required by extra-cmake-modules.
ecm_find_package_parse_components(<name>
RESULT_VAR <variable>
KNOWN_COMPONENTS <component1> [<component2> [...]]
[SKIP_DEPENDENCY_HANDLING])
This macro will populate <variable> with a list of components found in
<name>_FIND_COMPONENTS, after checking that all those components are in the list of
KNOWN_COMPONENTS; if there are any unknown components, it will print an error or warning
(depending on the value of <name>_FIND_REQUIRED) and call return().
The order of components in <variable> is guaranteed to match the order they are listed in
the KNOWN_COMPONENTS argument.
If SKIP_DEPENDENCY_HANDLING is not set, for each component the variable
<name>_<component>_component_deps will be checked for dependent components. If
<component> is listed in <name>_FIND_COMPONENTS, then all its (transitive) dependencies
will also be added to <variable>.
ecm_find_package_handle_library_components(<name>
COMPONENTS <component> [<component> [...]]
[SKIP_DEPENDENCY_HANDLING])
[SKIP_PKG_CONFIG])
Creates an imported library target for each component. The operation of this macro
depends on the presence of a number of CMake variables.
The <name>_<component>_lib variable should contain the name of this library, and
<name>_<component>_header variable should contain the name of a header file associated
with it (whatever relative path is normally passed to ‘#include’).
<name>_<component>_header_subdir variable can be used to specify which subdirectory of the
include path the headers will be found in. ecm_find_package_components() will then search
for the library and include directory (creating appropriate cache variables) and create an
imported library target named <name>::<component>.
Additional variables can be used to provide additional information:
If SKIP_PKG_CONFIG, the <name>_<component>_pkg_config variable is set, and pkg-config is
found, the pkg-config module given by <name>_<component>_pkg_config will be searched for
and used to help locate the library and header file. It will also be used to set
<name>_<component>_VERSION.
Note that if version information is found via pkg-config, <name>_<component>_FIND_VERSION
can be set to require a particular version for each component.
If SKIP_DEPENDENCY_HANDLING is not set, the INTERFACE_LINK_LIBRARIES property of the
imported target for <component> will be set to contain the imported targets for the
components listed in <name>_<component>_component_deps. <component>_FOUND will also be
set to false if any of the compoments in <name>_<component>_component_deps are not found.
This requires the components in <name>_<component>_component_deps to be listed before
<component> in the COMPONENTS argument.
The following variables will be set:
<name>_TARGETS
the imported targets
<name>_LIBRARIES
the found libraries
<name>_INCLUDE_DIRS
the combined required include directories for the components
<name>_DEFINITIONS
the “other” CFLAGS provided by pkg-config, if any
<name>_VERSION
the value of <name>_<component>_VERSION for the first component that has this
variable set (note that components are searched for in the order they are passed to
the macro), although if it is already set, it will not be altered
Note that these variables are never cleared, so if
ecm_find_package_handle_library_components() is called multiple times with different
components (typically because of multiple find_package() calls) then <name>_TARGETS, for
example, will contain all the targets found in any call (although no duplicates).
Since pre-1.0.0.
ECMGenerateExportHeader
This module provides the ecm_generate_export_header function for generating export macros
for libraries with version-based control over visibility of and compiler warnings for
deprecated API for the library user, as well as over excluding deprecated API and their
implementation when building the library itself.
For preparing some values useful in the context it also provides a function
ecm_export_header_format_version.
ecm_generate_export_header(<library_target_name>
VERSION <version>
[BASE_NAME <base_name>]
[GROUP_BASE_NAME <group_base_name>]
[EXPORT_MACRO_NAME <export_macro_name>]
[EXPORT_FILE_NAME <export_file_name>]
[DEPRECATED_MACRO_NAME <deprecated_macro_name>]
[NO_EXPORT_MACRO_NAME <no_export_macro_name>]
[INCLUDE_GUARD_NAME <include_guard_name>]
[STATIC_DEFINE <static_define>]
[PREFIX_NAME <prefix_name>]
[DEPRECATED_BASE_VERSION <deprecated_base_version>]
[DEPRECATION_VERSIONS <deprecation_version> [<deprecation_version2> [...]]]
[EXCLUDE_DEPRECATED_BEFORE_AND_AT <exclude_deprecated_before_and_at_version>]
[NO_BUILD_SET_DEPRECATED_WARNINGS_SINCE]
[NO_DEFINITION_EXPORT_TO_BUILD_INTERFACE]
[CUSTOM_CONTENT_FROM_VARIABLE <variable>]
)
VERSION specifies the version of the library, given in the format
“<major>.<minor>.<patchlevel>”.
GROUP_BASE_NAME specifies the name to use for the macros defining library group default
values. If set, this will generate code supporting
<group_base_name>_NO_DEPRECATED_WARNINGS,
<group_base_name>_DISABLE_DEPRECATED_BEFORE_AND_AT,
<group_base_name>_DEPRECATED_WARNINGS_SINCE and <group_base_name>_NO_DEPRECATED (see
below). If not set, the generated code will ignore any such macros.
DEPRECATED_BASE_VERSION specifies the default version before and at which deprecated API
is disabled. The default is the value of “<exclude_deprecated_before_and_at_version>” if
set, or “<major>.0.0”, with <major> taken from <version>.
DEPRECATION_VERSIONS specifies versions in “<major>.<minor>” format in which API was
declared deprecated. Any version used with the generated macro
<prefix_name><base_name>_DEPRECATED_VERSION(major, minor, text) needs to be listed here,
otherwise the macro will fail to work.
EXCLUDE_DEPRECATED_BEFORE_AND_AT specifies the version for which all API deprecated before
and at should be excluded from the build completely. Possible values are “0” (default),
“CURRENT” (which resolves to <version>) and a version string in the format
“<major>.<minor>.<patchlevel>”.
NO_BUILD_SET_DEPRECATED_WARNINGS_SINCE specifies that the definition
<prefix_name><uppercase_base_name>_DEPRECATED_WARNINGS_SINCE will not be set for the
library inside its own build, and thus will be defined by either explicit definition in
the build system configuration or by the default value mechanism (see below). The default
is that it is set for the build, to the version specified by
EXCLUDE_DEPRECATED_BEFORE_AND_AT, so no deprecation warnings are done for any own
deprecated API used in the library implementation itself.
NO_DEFINITION_EXPORT_TO_BUILD_INTERFACE specifies that the definition
<prefix_name><uppercase_base_name>_DISABLE_DEPRECATED_BEFORE_AND_AT will not be set in the
public interface of the library inside its own build, and the same for the definition
<prefix_name><uppercase_base_name>_DEPRECATED_WARNINGS_SINCE (if not disabled by
NO_BUILD_SET_DEPRECATED_WARNINGS_SINCE already). The default is that they are set, to the
version specified by EXCLUDE_DEPRECATED_BEFORE_AND_AT, so e.g. test and examples part of
the project automatically build against the full API included in the build and without any
deprecation warnings for it.
The function ecm_generate_export_header defines C++ preprocessor macros in the generated
export header, some for use in the sources of the library the header is generated for,
other for use by projects linking agsinst the library.
The macros for use in the library C++ sources are these, next to those also defined by
GenerateExportHeader:
<prefix_name><uppercase_base_name>_DEPRECATED_VERSION(major, minor, text)
to use to conditionally set a <prefix_name><uppercase_base_name>_DEPRECATED macro
for a class, struct or function (other elements to be supported in future
versions), depending on the visibility macro flags set (see below)
<prefix_name><uppercase_base_name>_ENABLE_DEPRECATED_SINCE(major, minor)
evaluates to TRUE or FALSE depending on the visibility macro flags set (see below).
To be used mainly with #if/#endif to mark sections of code which should be included
depending on the visibility requested.
<prefix_name><uppercase_base_name>_BUILD_DEPRECATED_SINCE(major, minor)
evaluates to TRUE or FALSE depending on the value of
EXCLUDE_DEPRECATED_BEFORE_AND_AT. To be used mainly with #if/#endif to mark
sections of two types of code: implementation code for deprecated API and
declaration code of deprecated API which only may be disabled at build time of the
library for BC reasons (e.g. virtual methods, see notes below).
<prefix_name><uppercase_base_name>_EXCLUDE_DEPRECATED_BEFORE_AND_AT
holds the version used to exclude deprecated API at build time of the library.
The macros used to control visibility when building against the library are:
<prefix_name><uppercase_base_name>_DISABLE_DEPRECATED_BEFORE_AND_AT
definition to set to a value in single hex number version notation
(0x<major><minor><patchlevel>).
<prefix_name><uppercase_base_name>_NO_DEPRECATED
flag to define to disable all deprecated API, being a shortcut for settings
<prefix_name><uppercase_base_name>_DISABLE_DEPRECATED_BEFORE_AND_AT to the current
version. If both are set, this flag overrules.
<prefix_name><uppercase_base_name>_DEPRECATED_WARNINGS_SINCE
definition to set to a value in single hex number version notation
(0x<major><minor><patchlevel>). Warnings will be only activated for API deprecated
up to and including the version. If
<prefix_name><uppercase_base_name>_DISABLE_DEPRECATED_BEFORE_AND_AT is set
(directly or via the group default), it will default to that version, resulting in
no warnings. Otherwise the default is the current version, resulting in warnings
for all deprecated API.
<prefix_name><uppercase_base_name>_NO_DEPRECATED_WARNINGS
flag to define to disable all deprecation warnings, being a shortcut for setting
<prefix_name><uppercase_base_name>_DEPRECATED_WARNINGS_SINCE to “0”. If both are
set, this flag overrules.
When the GROUP_BASE_NAME has been used, the same macros but with the given
<group_base_name> prefix are available to define the defaults of these macros, if not
explicitly set.
Note: The tricks applied here for hiding deprecated API to the compiler when building
against a library do not work for all deprecated API:
• virtual methods need to stay visible to the compiler to build proper virtual method
tables for subclasses
• enumerators from enums cannot be simply removed, as this changes auto values of
following enumerators, also can poke holes in enumerator series used as index into
tables
In such cases the API can be only “hidden” at build time of the library, itself, by
generated hard coded macro settings, using
<prefix_name><uppercase_base_name>_BUILD_DEPRECATED_SINCE(major, minor).
Examples:
Preparing a library “Foo” created by target “foo”, which is part of a group of libraries
“Bar”, where some API of “Foo” got deprecated at versions 5.0 & 5.12:
ecm_generate_export_header(foo
GROUP_BASE_NAME BAR
VERSION ${FOO_VERSION}
DEPRECATION_VERSIONS 5.0 5.12
)
In the library “Foo” sources in the headers the API would be prepared like this, using the
generated macros FOO_ENABLE_DEPRECATED_SINCE and FOO_DEPRECATED_VERSION:
#include <foo_export.h>
#if FOO_ENABLE_DEPRECATED_SINCE(5, 0)
/**
* @deprecated Since 5.0
*/
FOO_DEPRECATED_VERSION(5, 0, "Use doFoo2()")
FOO_EXPORT void doFoo();
#endif
#if FOO_ENABLE_DEPRECATED_SINCE(5, 12)
/**
* @deprecated Since 5.12
*/
FOO_DEPRECATED_VERSION(5, 12, "Use doBar2()")
FOO_EXPORT void doBar();
#endif
Projects linking against the “Foo” library can control which part of its deprecated API
should be hidden to the compiler by adding a definition using the
FOO_DISABLE_DEPRECATED_BEFORE_AND_AT macro variable set to the desired value (in version
hex number notation):
add_definitions(-DFOO_DISABLE_DEPRECATED_BEFORE_AND_AT=0x050000)
Or using the macro variable of the group:
add_definitions(-DBAR_DISABLE_DEPRECATED_BEFORE_AND_AT=0x050000)
If both are specified, FOO_DISABLE_DEPRECATED_BEFORE_AND_AT will take precedence.
To build a variant of a library with some deprecated API completely left out from the
build, not only optionally invisible to consumers, one uses the
EXCLUDE_DEPRECATED_BEFORE_AND_AT parameter. This is best combined with a cached CMake
variable.
set(EXCLUDE_DEPRECATED_BEFORE_AND_AT 0 CACHE STRING "Control the range of deprecated API excluded from the build [default=0].")
ecm_generate_export_header(foo
VERSION ${FOO_VERSION}
EXCLUDE_DEPRECATED_BEFORE_AND_AT ${EXCLUDE_DEPRECATED_BEFORE_AND_AT}
DEPRECATION_VERSIONS 5.0 5.12
)
The macros used in the headers for library consumers are reused for disabling the API
excluded in the build of the library. For disabling the implementation of that API as well
as for disabling deprecated API which only can be disabled at build time of the library
for BC reasons, one uses the generated macro FOO_BUILD_DEPRECATED_SINCE, like this:
#include <foo_export.h>
enum Bars {
One,
#if FOO_BUILD_DEPRECATED_SINCE(5, 0)
Two,
#endif
Three,
};
#if FOO_ENABLE_DEPRECATED_SINCE(5, 0)
/**
* @deprecated Since 5.0
*/
FOO_DEPRECATED_VERSION(5, 0, "Use doFoo2()")
FOO_EXPORT void doFoo();
#endif
#if FOO_ENABLE_DEPRECATED_SINCE(5, 12)
/**
* @deprecated Since 5.12
*/
FOO_DEPRECATED_VERSION(5, 12, "Use doBar2()")
FOO_EXPORT void doBar();
#endif
class FOO_EXPORT Foo {
public:
#if FOO_BUILD_DEPRECATED_SINCE(5, 0)
/**
* @deprecated Since 5.0
*/
FOO_DEPRECATED_VERSION(5, 0, "Feature removed")
virtual void doWhat();
#endif
};
#if FOO_BUILD_DEPRECATED_SINCE(5, 0)
void doFoo()
{
// [...]
}
#endif
#if FOO_BUILD_DEPRECATED_SINCE(5, 12)
void doBar()
{
// [...]
}
#endif
#if FOO_BUILD_DEPRECATED_SINCE(5, 0)
void Foo::doWhat()
{
// [...]
}
#endif
So e.g. if EXCLUDE_DEPRECATED_BEFORE_AND_AT is set to “5.0.0”, the enumerator Two as well
as the methods ::doFoo() and Foo::doWhat() will be not available to library consumers. The
methods will not have been compiled into the library binary, and the declarations will be
hidden to the compiler, FOO_DISABLE_DEPRECATED_BEFORE_AND_AT also cannot be used to
reactivate them.
When using the NO_DEFINITION_EXPORT_TO_BUILD_INTERFACE and the project for the “Foo”
library includes also tests and examples linking against the library and using deprecated
API (like tests covering it), one better explicitly sets
FOO_DISABLE_DEPRECATED_BEFORE_AND_AT for those targets to the version before and at which
all deprecated API has been excluded from the build. Even more when building against
other libraries from the same group “Bar” and disabling some deprecated API of those
libraries using the group macro BAR_DISABLE_DEPRECATED_BEFORE_AND_AT, which also works as
default for FOO_DISABLE_DEPRECATED_BEFORE_AND_AT.
To get the hex number style value the helper macro ecm_export_header_format_version() will
be used:
set(EXCLUDE_DEPRECATED_BEFORE_AND_AT 0 CACHE STRING "Control what part of deprecated API is excluded from build [default=0].")
ecm_generate_export_header(foo
VERSION ${FOO_VERSION}
GROUP_BASE_NAME BAR
EXCLUDE_DEPRECATED_BEFORE_AND_AT ${EXCLUDE_DEPRECATED_BEFORE_AND_AT}
NO_DEFINITION_EXPORT_TO_BUILD_INTERFACE
DEPRECATION_VERSIONS 5.0 5.12
)
ecm_export_header_format_version(${EXCLUDE_DEPRECATED_BEFORE_AND_AT}
CURRENT_VERSION ${FOO_VERSION}
HEXNUMBER_VAR foo_no_deprecated_before_and_at
)
# disable all deprecated API up to 5.9.0 from all other libs of group "BAR" that we use ourselves
add_definitions(-DBAR_DISABLE_DEPRECATED_BEFORE_AND_AT=0x050900)
add_executable(app app.cpp)
target_link_libraries(app foo)
target_compile_definitions(app
PRIVATE "FOO_DISABLE_DEPRECATED_BEFORE_AND_AT=${foo_no_deprecated_before_and_at}")
Since 5.64.0.
ECMGenerateHeaders
Generate C/C++ CamelCase forwarding headers.
ecm_generate_headers(<camelcase_forwarding_headers_var>
HEADER_NAMES <CamelCaseName> [<CamelCaseName> [...]]
[ORIGINAL <CAMELCASE|LOWERCASE>]
[HEADER_EXTENSION <header_extension>]
[OUTPUT_DIR <output_dir>]
[PREFIX <prefix>]
[REQUIRED_HEADERS <variable>]
[COMMON_HEADER <HeaderName>]
[RELATIVE <relative_path>])
For each CamelCase header name passed to HEADER_NAMES, a file of that name will be
generated that will include a version with .h or, if set, .<header_extension> appended.
For example, the generated header ClassA will include classa.h (or ClassA.h, see
ORIGINAL). If a CamelCaseName consists of multiple comma-separated files, e.g.
ClassA,ClassB,ClassC, then multiple camelcase header files will be generated which are
redirects to the first header file. The file locations of these generated headers will be
stored in <camelcase_forwarding_headers_var>.
ORIGINAL specifies how the name of the original header is written: lowercased or also
camelcased. The default is LOWERCASE. Since 1.8.0.
HEADER_EXTENSION specifies what file name extension is used for the header files. The
default is “h”. Since 5.48.0.
PREFIX places the generated headers in subdirectories. This should be a CamelCase name
like KParts, which will cause the CamelCase forwarding headers to be placed in the KParts
directory (e.g. KParts/Part). It will also, for the convenience of code in the source
distribution, generate forwarding headers based on the original names (e.g.
kparts/part.h). This allows includes like "#include <kparts/part.h>" to be used before
installation, as long as the include_directories are set appropriately.
OUTPUT_DIR specifies where the files will be generated; this should be within the build
directory. By default, ${CMAKE_CURRENT_BINARY_DIR} will be used. This option can be used
to avoid file conflicts.
REQUIRED_HEADERS specifies an output variable name where all the required headers will be
appended so that they can be installed together with the generated ones. This is mostly
intended as a convenience so that adding a new header to a project only requires
specifying the CamelCase variant in the CMakeLists.txt file; the original variant will
then be added to this variable.
COMMON_HEADER generates an additional convenience header which includes all other header
files.
The RELATIVE argument indicates where the original headers can be found relative to
CMAKE_CURRENT_SOURCE_DIR. It does not affect the generated CamelCase forwarding files,
but ecm_generate_headers() uses it when checking that the original header exists, and to
generate originally named forwarding headers when PREFIX is set.
To allow other parts of the source distribution (eg: tests) to use the generated headers
before installation, it may be desirable to set the INCLUDE_DIRECTORIES property for the
library target to output_dir. For example, if OUTPUT_DIR is CMAKE_CURRENT_BINARY_DIR (the
default), you could do
target_include_directories(MyLib PUBLIC "$<BUILD_INTERFACE:${CMAKE_CURRENT_BINARY_DIR}>")
Example usage (without PREFIX):
ecm_generate_headers(
MyLib_FORWARDING_HEADERS
HEADERS
MLFoo
MLBar
# etc
REQUIRED_HEADERS MyLib_HEADERS
COMMON_HEADER MLGeneral
)
install(FILES ${MyLib_FORWARDING_HEADERS} ${MyLib_HEADERS}
DESTINATION ${CMAKE_INSTALL_PREFIX}/include
COMPONENT Devel)
Example usage (with PREFIX):
ecm_generate_headers(
MyLib_FORWARDING_HEADERS
HEADERS
Foo
# several classes are contained in bar.h, so generate
# additional files
Bar,BarList
# etc
PREFIX MyLib
REQUIRED_HEADERS MyLib_HEADERS
)
install(FILES ${MyLib_FORWARDING_HEADERS}
DESTINATION ${CMAKE_INSTALL_PREFIX}/include/MyLib
COMPONENT Devel)
install(FILES ${MyLib_HEADERS}
DESTINATION ${CMAKE_INSTALL_PREFIX}/include/mylib
COMPONENT Devel)
Since pre-1.0.0.
ECMGeneratePkgConfigFile
Generate a pkg-config file for the benefit of autotools-based projects.
ecm_generate_pkgconfig_file(BASE_NAME <baseName>
[LIB_NAME <libName>]
[DEPS "<dep> [<dep> [...]]"]
[FILENAME_VAR <filename_variable>]
[INCLUDE_INSTALL_DIR <dir>]
[LIB_INSTALL_DIR <dir>]
[DEFINES -D<variable=value>...]
[DESCRIPTION <library description>] # since 5.41.0
[INSTALL])
BASE_NAME is the name of the module. It’s the name projects will use to find the module.
LIB_NAME is the name of the library that is being exported. If undefined, it will default
to the BASE_NAME. That means the LIB_NAME will be set as the name field as well as the
library to link to.
FILENAME_VAR is specified with a variable name. This variable will receive the location of
the generated file will be set, within the build directory. This way it can be used in
case some processing is required. See also INSTALL.
INCLUDE_INSTALL_DIR specifies where the includes will be installed. If it’s not specified,
it will default to INSTALL_INCLUDEDIR, CMAKE_INSTALL_INCLUDEDIR or just “include/” in case
they are specified, with the BASE_NAME postfixed.
LIB_INSTALL_DIR specifies where the library is being installed. If it’s not specified, it
will default to LIB_INSTALL_DIR, CMAKE_INSTALL_LIBDIR or just “lib/” in case they are
specified.
DEFINES is a list of preprocessor defines that it is recommended users of the library pass
to the compiler when using it.
DESCRIPTION describes what this library is. If it’s not specified, CMake will first try to
get the description from the metainfo.yaml file or will create one based on LIB_NAME.
Since 5.41.0.
INSTALL will cause the module to be installed to the pkgconfig subdirectory of
LIB_INSTALL_DIR, unless the ECM_PKGCONFIG_INSTALL_DIR cache variable is set to something
different. Note that the first call to ecm_generate_pkgconfig_file with the INSTALL
argument will cause ECM_PKGCONFIG_INSTALL_DIR to be set to the cache, and will be used in
any subsequent calls.
To properly use this macro a version needs to be set. To retrieve it,
ECM_PKGCONFIG_INSTALL_DIR uses PROJECT_VERSION. To set it, use the project() command (only
available since CMake 3.0) or the ecm_setup_version() macro.
Example usage:
ecm_generate_pkgconfig_file(
BASE_NAME KF5Archive
DEPS Qt5Core
FILENAME_VAR pkgconfig_filename
INSTALL
)
Since 1.3.0.
ECMGeneratePriFile
Generate a .pri file for the benefit of qmake-based projects.
As well as the function below, this module creates the cache variable
ECM_MKSPECS_INSTALL_DIR and sets the default value to mkspecs/modules. This assumes Qt
and the current project are both installed to the same non-system prefix. Packagers who
use -DCMAKE_INSTALL_PREFIX=/usr will certainly want to set ECM_MKSPECS_INSTALL_DIR to
something like share/qt5/mkspecs/modules.
The main thing is that this should be the modules subdirectory of either the default qmake
mkspecs directory or of a directory that will be in the $QMAKEPATH environment variable
when qmake is run.
ecm_generate_pri_file(BASE_NAME <baseName>
LIB_NAME <libName>
[DEPS "<dep> [<dep> [...]]"]
[FILENAME_VAR <filename_variable>]
[INCLUDE_INSTALL_DIR <dir>]
[LIB_INSTALL_DIR <dir>])
If your CMake project produces a Qt-based library, you may expect there to be applications
that wish to use it that use a qmake-based build system, rather than a CMake-based one.
Creating a .pri file will make use of your library convenient for them, in much the same
way that CMake config files make things convenient for CMake-based applications.
ecm_generate_pri_file() generates just such a file. It requires the
PROJECT_VERSION_STRING variable to be set. This is typically set by ECMSetupVersion,
although the project() command in CMake 3.0.0 and later can also set this.
BASE_NAME specifies the name qmake project (.pro) files should use to refer to the library
(eg: KArchive). LIB_NAME is the name of the actual library to link to (ie: the first
argument to add_library()). DEPS is a space-separated list of the base names of other
libraries (for Qt libraries, use the same names you use with the QT variable in a qmake
project file, such as “core” for QtCore). FILENAME_VAR specifies the name of a variable
to store the path to the generated file in.
INCLUDE_INSTALL_DIR is the path (relative to CMAKE_INSTALL_PREFIX) that include files will
be installed to. It defaults to ${INCLUDE_INSTALL_DIR}/<baseName> if the
INCLUDE_INSTALL_DIR variable is set. If that variable is not set, the
CMAKE_INSTALL_INCLUDEDIR variable is used instead, and if neither are set include is used.
LIB_INSTALL_DIR operates similarly for the installation location for libraries; it
defaults to ${LIB_INSTALL_DIR}, ${CMAKE_INSTALL_LIBDIR} or lib, in that order.
Example usage:
ecm_generate_pri_file(
BASE_NAME KArchive
LIB_NAME KF5KArchive
DEPS "core"
FILENAME_VAR pri_filename
)
install(FILES ${pri_filename} DESTINATION ${ECM_MKSPECS_INSTALL_DIR})
A qmake-based project that wished to use this would then do:
QT += KArchive
in their .pro file.
Since pre-1.0.0.
ECMGenerateQmlTypes
Generates plugins.qmltypes files for QML plugins.
ecm_generate_qmltypes(<org.kde.pluginname> 1.3
DESTINATION <${KDE_INSTALL_QMLDIR}/org/kde/pluginname>)
Makes it possible to generate plugins.qmltypes files for the QML plugins that our project
offers. These files offer introspection upon our plugin and are useful for integrating
with IDE language support of our plugin. It offers information about the objects its
methods and their argument types.
The developer will be in charge of making sure that these files are up to date. The
plugin.qmltypes file will sit in the source directory. This function will include the code
that installs the file in the right place and a small unit test named
qmltypes-pluginname-version that makes sure that it doesn’t need updating.
Since 5.33.0
ECMInstallIcons
Installs icons, sorting them into the correct directories according to the FreeDesktop.org
icon naming specification.
ecm_install_icons(ICONS <icon> [<icon> [...]]
DESTINATION <icon_install_dir>
[LANG <l10n_code>]
[THEME <theme>])
The given icons, whose names must match the pattern:
<size>-<group>-<name>.<ext>
will be installed to the appropriate subdirectory of DESTINATION according to the
FreeDesktop.org icon naming scheme. By default, they are installed to the “hicolor” theme,
but this can be changed using the THEME argument. If the icons are localized, the LANG
argument can be used to install them in a locale-specific directory.
<size> is a numeric pixel size (typically 16, 22, 32, 48, 64, 128 or 256) or sc for
scalable (SVG) files, <group> is one of the standard FreeDesktop.org icon groups (actions,
animations, apps, categories, devices, emblems, emotes, intl, mimetypes, places, status)
and <ext> is one of .png, .mng or .svgz.
The typical installation directory is share/icons.
ecm_install_icons(ICONS 22-actions-menu_new.png
DESTINATION share/icons)
The above code will install the file 22-actions-menu_new.png as
${CMAKE_INSTALL_PREFIX}/share/icons/<theme>/22x22/actions/menu_new.png
Users of the KDEInstallDirs module would normally use ${KDE_INSTALL_ICONDIR} as the
DESTINATION, while users of the GNUInstallDirs module should use
${CMAKE_INSTALL_DATAROOTDIR}/icons.
An old form of arguments will also be accepted:
ecm_install_icons(<icon_install_dir> [<l10n_code>])
This matches files named like:
<theme><size>-<group>-<name>.<ext>
where <theme> is one of * hi for hicolor * lo for locolor * cr for the Crystal icon theme
* ox for the Oxygen icon theme * br for the Breeze icon theme
With this syntax, the file hi22-actions-menu_new.png would be installed into
<icon_install_dir>/hicolor/22x22/actions/menu_new.png
Since pre-1.0.0.
ECMMarkAsTest
Marks a target as only being required for tests.
ecm_mark_as_test(<target1> [<target2> [...]])
This will cause the specified targets to not be built unless either BUILD_TESTING is set
to ON or the user invokes the buildtests target.
BUILD_TESTING is created as a cache variable by the CTest module and by the
KDECMakeSettings module.
Since pre-1.0.0.
ECMMarkNonGuiExecutable
Marks an executable target as not being a GUI application.
ecm_mark_nongui_executable(<target1> [<target2> [...]])
This will indicate to CMake that the specified targets should not be included in a
MACOSX_BUNDLE and should not be WIN32_EXECUTABLEs. On platforms other than MacOS X or
Windows, this will have no effect.
Since pre-1.0.0.
ECMOptionalAddSubdirectory
Make subdirectories optional.
ecm_optional_add_subdirectory(<dir>)
This behaves like add_subdirectory(), except that it does not complain if the directory
does not exist. Additionally, if the directory does exist, it creates an option to allow
the user to skip it. The option will be named BUILD_<dir>.
This is useful for “meta-projects” that combine several mostly-independent sub-projects.
If the CMake variable DISABLE_ALL_OPTIONAL_SUBDIRECTORIES is set to TRUE for the first
CMake run on the project, all optional subdirectories will be disabled by default (but can
of course be enabled via the respective options). For example, the following will disable
all optional subdirectories except the one named “foo”:
cmake -DDISABLE_ALL_OPTIONAL_SUBDIRECTORIES=TRUE -DBUILD_foo=TRUE myproject
Since pre-1.0.0.
ECMPackageConfigHelpers
Helper macros for generating CMake package config files.
write_basic_package_version_file() is the same as the one provided by the
CMakePackageConfigHelpers module in CMake; see that module’s documentation for more
information.
ecm_configure_package_config_file(<input> <output>
INSTALL_DESTINATION <path>
[PATH_VARS <var1> [<var2> [...]]
[NO_SET_AND_CHECK_MACRO]
[NO_CHECK_REQUIRED_COMPONENTS_MACRO])
This behaves in the same way as configure_package_config_file() from CMake 2.8.12, except
that it adds an extra helper macro: find_dependency(). It is highly recommended that you
read the documentation for CMakePackageConfigHelpers for more information, particularly
with regard to the PATH_VARS argument.
Note that there is no argument that will disable the find_dependency() macro; if you do
not require this macro, you should use configure_package_config_file from the
CMakePackageConfigHelpers module.
CMake 3.0 includes a CMakeFindDependencyMacro module that provides the find_dependency()
macro (which you can include() in your package config file), so this file is only useful
for projects wishing to provide config files that will work with CMake 2.8.12.
Additional Config File Macros
find_dependency(<dep> [<version> [EXACT]])
find_dependency() should be used instead of find_package() to find package dependencies.
It forwards the correct parameters for EXACT, QUIET and REQUIRED which were passed to the
original find_package() call. It also sets an informative diagnostic message if the
dependency could not be found.
Since pre-1.0.0.
ECMPoQmTools
This module provides the ecm_process_po_files_as_qm and ecm_install_po_files_as_qm
functions for generating QTranslator (.qm) catalogs from Gettext (.po) catalogs, and the
ecm_create_qm_loader function for generating the necessary code to load them in a Qt
application or library.
ecm_process_po_files_as_qm(<lang> [ALL]
[INSTALL_DESTINATION <install_destination>]
PO_FILES <pofile> [<pofile> [...]])
Compile .po files into .qm files for the given language.
If INSTALL_DESTINATION is given, the .qm files are installed in
<install_destination>/<lang>/LC_MESSAGES. Typically, <install_destination> is set to
share/locale.
ecm_process_po_files_as_qm creates a “translations” target. This target builds all .po
files into .qm files. If ALL is specified, these rules are added to the “all” target (and
so the .qm files will be built by default).
ecm_create_qm_loader(<source_files_var> <catalog_name>)
Generates C++ code which ensures translations are automatically loaded at startup. The
generated files are appended to <source_files_var>.
It assumes that the .qm file for the language code <lang> is installed as
<sharedir>/locale/<lang>/LC_MESSAGES/<catalog_name>.qm, where <sharedir> is one of the
directories given by the GenericDataLocation of QStandardPaths.
Typical usage is like:
set(mylib_SRCS foo.cpp bar.cpp)
ecm_create_qm_loader(mylib_SRCS mylib)
add_library(mylib ${mylib_SRCS})
ecm_install_po_files_as_qm(<podir>)
Searches for .po files and installs them to the standard location.
This is a convenience function which relies on all .po files being kept in
<podir>/<lang>/, where <lang> is the language the .po files are written in.
For example, given the following directory structure:
po/
fr/
mylib.po
ecm_install_po_files_as_qm(po) compiles mylib.po into mylib.qm and installs it in
<install_destination>/fr/LC_MESSAGES. <install_destination> defaults to
${LOCALE_INSTALL_DIR} if defined, otherwise it uses ${CMAKE_INSTALL_LOCALEDIR} if that is
defined, otherwise it uses share/locale.
Since pre-1.0.0.
ECMQMLModules
Find QML import modules through a find_qmlmodule() call. It uses the qmlplugindump
application to find the plugins and sets them up as runtime dependencies.
This is useful so that when we configure a project we are noified when some QML imports
are not present in the system, thus having the application compilable but fail at runtime.
ecm_find_qmlmodule(<module_name> <version>...)
Any further arguments passed will be forwarded into a find_package() call. See
find_package() documentation for more information.
Usage example:
ecm_find_qmlmodule(org.kde.kirigami 2.1)
Since 5.38.0.
ECMQtDeclareLoggingCategory
This module provides the ecm_qt_declare_logging_category function for generating
declarations for logging categories in Qt5, and the ecm_qt_install_logging_categories
function for generating and installing a file in KDebugSettings format with the info about
all those categories, as well as a file with info about any renamed categories if defined.
To include in that file any logging categories that are manually defined also a function
ecm_qt_export_logging_category is provided.
ecm_qt_declare_logging_category(<sources_var>
HEADER <filename>
IDENTIFIER <identifier>
CATEGORY_NAME <category_name>
[OLD_CATEGORY_NAMES <oldest_cat_name> [<second_oldest_cat_name> [...]]]
[DEFAULT_SEVERITY <Debug|Info|Warning|Critical|Fatal>]
[EXPORT <exportid>]
[DESCRIPTION <description>]
)
A header file, <filename>, will be generated along with a corresponding source file, which
will be added to <sources_var>. These will provide a QLoggingCategory category that can be
referred to from C++ code using <identifier>, and from the logging configuration using
<category_name>.
If <filename> is not absolute, it will be taken relative to the current binary directory.
If the code is compiled against Qt 5.4 or later, by default it will only log output that
is at least the severity specified by DEFAULT_SEVERITY, or “Info” level if
DEFAULT_SEVERITY is not given. Note that, due to a bug in Qt 5.5, “Info” may be treated as
more severe than “Fatal”.
<identifier> may include namespaces (eg: foo::bar::IDENT).
If EXPORT is passed, the category will be registered for the group id <exportid>. Info
about the categories of that group can then be generated in a file and installed by that
group id with the ecm_qt_install_logging_categories function. In that case also
DESCRIPTION will need to be passed, with <description> being a short single line text.
And OLD_CATEGORY_NAMES can be used to inform about any renamings of the category, so user
settings can be migrated. Since 5.68.0.
Since 5.14.0.
ecm_qt_export_logging_category(
IDENTIFIER <identifier>
CATEGORY_NAME <category_name>
[OLD_CATEGORY_NAMES <oldest_category_name> [<second_oldest_category_name> [...]]]
EXPORT <exportid>
DESCRIPTION <description>
[DEFAULT_SEVERITY <Debug|Info|Warning|Critical|Fatal>]
)
Registers a logging category for being included in the generated and installed
KDebugSettings files. To be used for categories who are declared by manual code or other
ways instead of code generated with ecm_qt_declare_logging_category.
<identifier> may include namespaces (eg: foo::bar::IDENT).
EXPORT specifies the group id with which the category will be registered. Info about the
categories of that group can then be generated in a file and installed by that group id
with the ecm_qt_install_logging_categories function.
DESCRIPTION specifies a short single line text describing the category.
OLD_CATEGORY_NAMES can be used to inform about any renamings of the category, so user
settings can be migrated.
Since 5.68.0.
ecm_qt_install_logging_categories(
EXPORT <exportid>
[FILE <filename>]
DESTINATION <install_path>
[SORT]
[COMPONENT <component>]
)
Generates and installs a file in KDebugSettings format with the info about all the
categories registered for the group <exportid>, as well as a file with info about any
renamed categories, if there are.
The method call needs to be after the last ecm_qt_declare_logging_category call which uses
the same <exportid>. This can be in the same directory, or any subdirectory or parent
directory.
EXPORT specifies the group id of categories whose informatipn should be stored in the file
generated and installed.
FILE specifies the name of the file generated and installed. It will default to
lower-cased <exportid>.categories.
DESTINATION specifies where the generated file will be installed.
IF SORT is set, entries will be sorted by identifiers.
COMPONENT specifies the installation component name with which the install rules for the
generated file are associated.
Example usage:
ecm_qt_declare_logging_category(
MYPROJECT_SRCS
HEADER "myproject_debug.h"
IDENTIFIER "MYPROJECT_DEBUG"
CATEGORY_NAME "myproject"
OLD_CATEGORY_NAMES "myprojectlog"
DESCRIPTION "My project"
EXPORT MyProject
)
ecm_qt_export_logging_category(
IDENTIFIER "MYPROJECT_SUBMODULE_DEBUG"
CATEGORY_NAME "myproject.submodule"
DESCRIPTION "My project - submodule"
EXPORT MyProject
)
ecm_qt_install_logging_categories(
EXPORT MyProject
FILE myproject.categories
DESTINATION "${KDE_INSTALL_LOGGINGCATEGORIESDIR}"
)
Since 5.68.0.
ECMSetupQtPluginMacroNames
Instruct CMake’s automoc about C++ preprocessor macros used to define Qt-style plugins.
ecm_setup_qtplugin_macro_names(
[JSON_NONE <macro_name> [<macro_name> [...]]]
[JSON_ARG1 <macro_name> [<macro_name> [...]]]
[JSON_ARG2 <macro_name> [<macro_name> [...]]]
[JSON_ARG3 <macro_name> [<macro_name> [...]]]
[CONFIG_CODE_VARIABLE <variable_name>] )
CMake’s automoc needs some support when parsing C++ source files to detect whether moc
should be run on those files and if there are also dependencies on other files, like those
with Qt plugin metadata in JSON format. Because automoc just greps overs the raw plain
text of the sources without any C++ preprocessor-like processing. CMake in newer versions
provides the variables CMAKE_AUTOMOC_DEPEND_FILTERS (CMake >= 3.9.0) and
CMAKE_AUTOMOC_MACRO_NAMES (CMake >= 3.10) to allow the developer to assist automoc.
This macro cares for the explicit setup needed for those variables for common cases of C++
preprocessor macros used for Qt-style plugins.
JSON_NONE lists the names of C++ preprocessor macros for Qt-style plugins which do not
refer to external files with the plugin metadata.
JSON_ARG1 lists the names of C++ preprocessor macros for Qt-style plugins where the first
argument to the macro is the name of the external file with the plugin metadata.
JSON_ARG2 is the same as JSON_ARG1 but with the file name being the second argument.
JSON_ARG3 is the same as JSON_ARG1 but with the file name being the third argument.
CONFIG_CODE_VARIABLE specifies the name of the variable which will get set as value some
generated CMake code for instructing automoc for the given macro names, as useful in an
installed CMake config file. The variable can then be used as usual in the template file
for such a CMake config file, by @<variable_name>@.
Example usage:
Given some plugin-oriented Qt-based software which defines a custom C++ preprocessor macro
EXPORT_MYPLUGIN for declaring the central plugin object:
#define EXPORT_MYPLUGIN_WITH_JSON(classname, jsonFile) \
class classname : public QObject \
{ \
Q_OBJECT \
Q_PLUGIN_METADATA(IID "myplugin" FILE jsonFile) \
explicit classname() {} \
};
In the CMake buildsystem of the library one calls
ecm_setup_qtplugin_macro_names(
JSON_ARG2
EXPORT_MYPLUGIN_WITH_JSON
)
to instruct automoc about the usage of that macro in the sources of the library itself.
Given the software installs a library including the header with the macro definition and a
CMake config file, so 3rd-party can create additional plugins by linking against the
library, one passes additionally the name of a variable which shall be set as value the
CMake code needed to instruct automoc about the usage of that macro.
ecm_setup_qtplugin_macro_names(
JSON_ARG2
EXPORT_MYPLUGIN_WITH_JSON
CONFIG_CODE_VARIABLE
PACKAGE_SETUP_AUTOMOC_VARIABLES
)
This variable then is used in the template file (e.g. MyProjectConfig.cmake.in) for the
libary’s installed CMake config file and that way will ensure that in the 3rd-party
plugin’s buildsystem automoc is instructed as well as needed:
@PACKAGE_SETUP_AUTOMOC_VARIABLES@
Since 5.45.0.
ECMSetupVersion
Handle library version information.
ecm_setup_version(<version>
VARIABLE_PREFIX <prefix>
[SOVERSION <soversion>]
[VERSION_HEADER <filename>]
[PACKAGE_VERSION_FILE <filename> [COMPATIBILITY <compat>]] )
This parses a version string and sets up a standard set of version variables. It can
optionally also create a C version header file and a CMake package version file to install
along with the library.
If the <version> argument is of the form <major>.<minor>.<patch> (or
<major>.<minor>.<patch>.<tweak>), The following CMake variables are set:
<prefix>_VERSION_MAJOR - <major>
<prefix>_VERSION_MINOR - <minor>
<prefix>_VERSION_PATCH - <patch>
<prefix>_VERSION - <version>
<prefix>_VERSION_STRING - <version> (for compatibility: use <prefix>_VERSION instead)
<prefix>_SOVERSION - <soversion>, or <major> if SOVERSION was not given
If CMake policy CMP0048 is not NEW, the following CMake variables will also be set:
PROJECT_VERSION_MAJOR - <major>
PROJECT_VERSION_MINOR - <minor>
PROJECT_VERSION_PATCH - <patch>
PROJECT_VERSION - <version>
PROJECT_VERSION_STRING - <version> (for compatibility: use PROJECT_VERSION instead)
If the VERSION_HEADER option is used, a simple C header is generated with the given
filename. If filename is a relative path, it is interpreted as relative to
CMAKE_CURRENT_BINARY_DIR. The generated header contains the following macros:
<prefix>_VERSION_MAJOR - <major> as an integer
<prefix>_VERSION_MINOR - <minor> as an integer
<prefix>_VERSION_PATCH - <patch> as an integer
<prefix>_VERSION_STRING - <version> as a C string
<prefix>_VERSION - the version as an integer
<prefix>_VERSION has <patch> in the bottom 8 bits, <minor> in the next 8 bits and <major>
in the remaining bits. Note that <patch> and <minor> must be less than 256.
If the PACKAGE_VERSION_FILE option is used, a simple CMake package version file is created
using the write_basic_package_version_file() macro provided by CMake. It should be
installed in the same location as the Config.cmake file of the library so that it can be
found by find_package(). If the filename is a relative path, it is interpreted as
relative to CMAKE_CURRENT_BINARY_DIR. The optional COMPATIBILITY option is forwarded to
write_basic_package_version_file(), and defaults to AnyNewerVersion.
If CMake policy CMP0048 is NEW, an alternative form of the command is available:
ecm_setup_version(PROJECT
[VARIABLE_PREFIX <prefix>]
[SOVERSION <soversion>]
[VERSION_HEADER <filename>]
[PACKAGE_VERSION_FILE <filename>] )
This will use the version information set by the project() command. VARIABLE_PREFIX
defaults to the project name. Note that PROJECT must be the first argument. In all other
respects, it behaves like the other form of the command.
Since pre-1.0.0.
COMPATIBILITY option available since 1.6.0.
ECMSourceVersionControl
Tries to determine whether the source is under version control (git clone, svn checkout,
etc).
ECM_SOURCE_UNDER_VERSION_CONTROL is set when indication is found that CMAKE_SOURCE_DIR is
under version control.
Since 5.63
ECMUninstallTarget
Add an uninstall target.
By including this module, an uninstall target will be added to your CMake project. This
will remove all files installed (or updated) by a previous invocation of the install
target. It will not remove files created or modified by an install(SCRIPT) or
install(CODE) command; you should create a custom uninstallation target for these and use
add_dependency to make the uninstall target depend on it:
include(ECMUninstallTarget)
install(SCRIPT install-foo.cmake)
add_custom_target(uninstall_foo COMMAND ${CMAKE_COMMAND} -P uninstall-foo.cmake)
add_dependency(uninstall uninstall_foo)
The target will fail if the install target has not yet been run (so it is not possible to
run CMake on the project and then immediately run the uninstall target).
WARNING:
CMake deliberately does not provide an uninstall target by default on the basis that
such a target has the potential to remove important files from a user’s computer. Use
with caution.
Since 1.7.0.
ECMUseFindModules
Selectively use some of the find modules provided by extra-cmake-modules.
This module is automatically available once extra-cmake-modules has been found, so it is
not necessary to include(ECMUseFindModules) explicitly.
ecm_use_find_modules(DIR <dir>
MODULES module1.cmake [module2.cmake [...]]
[NO_OVERRIDE])
This allows selective use of the find modules provided by ECM, including deferring to
CMake’s versions of those modules if it has them. Rather than adding
${ECM_FIND_MODULE_DIR} to CMAKE_MODULE_PATH, you use ecm_use_find_modules() to copy the
modules you want to a local (build) directory, and add that to CMAKE_MODULE_PATH.
The find modules given to MODULES will be copied to the directory given by DIR (which
should be located in ${CMAKE_BINARY_DIR} and added to CMAKE_MODULE_PATH). If NO_OVERRIDE
is given, only modules not also provided by CMake will be copied.
Example:
find_package(ECM REQUIRED)
ecm_use_find_modules(
DIR ${CMAKE_BINARY_DIR}/cmake
MODULES FindEGL.cmake
NO_OVERRIDE
)
set(CMAKE_MODULE_PATH ${CMAKE_BINARY_DIR}/cmake)
This example will make FindEGL.cmake available in your project, but only as long as it is
not yet part of CMake. Calls to find_package(EGL) will then make use of this copied module
(or the CMake module if it exists).
Another possible use for this macro is to take copies of find modules that can be
installed along with config files if they are required as a dependency (for example, if
targets provided by the find module are in the link interface of a library).
Since pre-1.0.0.
ECMWinResolveSymlinks
Resolve pseudo-symlinks created by git when cloning on Windows.
ecm_win_resolve_symlinks(<dir>)
When git checks out a repository with UNIX symlinks on Windows machine, it creates a text
file for each symlink, containing a relative path to the real file. This function would
recursively walk over specified directory and replace pseudo-symlinks with corresponding
real file’s contents. It would then run git update-index –assume-unchanged on them to
trick git.
This is useful for projects like “breeze-icons” that contain many identical icons
implemented as symlinks.
Since 5.28
SEE ALSO
ecm(7), ecm-find-modules(7), ecm-kde-modules(7)
COPYRIGHT
KDE Developers