ECM-MODULES(7) Extra CMake Modules ECM-MODULES(7)
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 mod-
ules that can be used from CMake scripts: those that extend the func-
tionality 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 mod-
ules 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
CheckAtomic
Check if the compiler supports std:atomic out of the box or if li-
batomic is needed for atomic support. If it is needed libatomicis added
to CMAKE_REQUIRED_LIBRARIES. So after running CheckAtomic you can use
std:atomic.
Since 5.75.0.
ECMAddAppIcon
Add icons to executable files and packages.
ecm_add_app_icon(<sources_var_name(|target (since 5.83))>
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 as platform-specific application icons to the variable
named <sources_var_name> or, if the first argument is a target (since
5.83), to the SOURCES property of <target>. Any target must be created
with add_executable() and not be an alias.
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.
The platforms currently supported are Windows and Mac OS X, on all oth-
ers the call has no effect and is ignored.
<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 gener-
ated 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_name>.<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.
• 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 success-
fully 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 stan-
dard-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. If an SVG icon is provided, ksvg2icns
will be used internally to automatically generate all appro-
priate sizes, including the high-resolution ones.
• 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 docu-
mentation files in the QCH format, and the ecm_install_qch_export func-
tion for generating and installing exported CMake targets for such gen-
erated 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 corre-
sponding doxygen tag file, which enables creating links from other doc-
umentation 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_NAME-
SPACE, 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 ex-
isting, 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 documenta-
tion 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 rela-
tive 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_TEM-
PLATE 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 in-
cluded 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 in-
cluded 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 in-
stall rules for the generated QCH file and tag file are associated.
NAMESPACE can be used to set a custom namespace <namespace> of the gen-
erated QCH file. The namepspace is used as the unique id by QHelpEngine
(cmp. https://doc.qt.io/qt-5/qthelpproject.html#namespace). The de-
fault 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 li-
braries. For each target <qch> in the list these target properties are
expected to be defined: DOXYGEN_TAGFILE, QHP_NAMESPACE and QHP_VIRTUAL-
FOLDER. 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 han-
dled 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 ig-
nored 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_DOXY-
GEN_QHELPGENERATOR_EXECUTABLE - ECM_QCH_DOXYGEN_FILEPATH, ECM_QCH_DOXY-
GEN_TAGFILE The following CMake variables can be used: - ECM_QCH_DOXY-
GEN_PROJECTNAME - ECM_QCH_DOXYGEN_PROJECTVERSION - ECM_QCH_DOXYGEN_VIR-
TUALFOLDER - ECM_QCH_DOXYGEN_FULLNAMESPACE - ECM_QCH_DOXYGEN_TAGFILES -
ECM_QCH_DOXYGEN_WARN_LOGFILE - ECM_QCH_DOXYGEN_QUIET There is no guar-
antue that the other CMake variables currently used in the default con-
fig file template will also be present with the same semantics in fu-
ture 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_DOXY-
GEN when run (since v5.67.0). For backward-compatibility also the defi-
nition 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 in-
stall 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 generat-
ing 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 de-
fault 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 wid-
gets 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 ini-
tializing 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 cre-
ating widgets.
COMPONENT specifies the installation component name with which the in-
stall 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 name-
spaces. 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 de-
fault 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. De-
faults 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(QWid-
get* parent). The default is “return new <impl_class_name><construc-
tor_args_code>;”.
INITIALIZE_CODE_FROM_VARIABLE specifies the variable to get from the
C++ code to use with the override of QDesignerCustomWidgetInter-
face::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 QDesignerCustomWidgetInter-
face::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_LI-
BRARIES. 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 (regard-
less 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 tests will be build with -DQT_FORCE_ASSERTS to enable assertions in
the test executable even for release builds.
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.
ECMCheckOutboundLicense
Assert that source file licenses are compatible with a desired outbound
license of a compiled binary artifact (e.g., library, plugin or appli-
cation).
This module provides the ecm_check_outbound_license function that gen-
erates unit tests for checking the compatibility of license statements.
The license statements in all tested files are required to be added by
using the SPDX marker SPDX-License-Identifier.
During the CMake configuration of the project, a temporary license bill
of materials (BOM) in SPDX format is generated by calling the REUSE
tool (see <https://reuse.software>). That BOM is parsed and license
computations based on an internal compatibility matrix are performed.
Preconditions for using this module:
• All tested input source files must contain the SPDX-Li-
cense-Identifier tag.
• Python3 must be available.
• The REUSE tool must be available, which generates the
bill-of-materials by running reuse spdx on the tested direc-
tory.
When this module is included, a SKIP_LICENSE_TESTS option is added (de-
fault OFF). Turning this option on skips the generation of license
tests, which might be convenient if licenses shall not be tested in all
build configurations.
ecm_check_outbound_license(LICENSES <outbound-licenses>
FILES <source-files>
[TEST_NAME <name>]
[WILL_FAIL])
This method adds a custom unit test to ensure the specified outbound
license to be compatible with the specified license headers. Note that
a convenient way is to use the CMake GLOB argument of the FILE func-
tion.
LICENSES
List of one or multiple outbound license regarding which the
compatibility of the source code files shall be tested..INDENT
7.0
Currently, the following values are supported (values are SPDX registry
identifiers):
• MIT
• BSD-2-Clause
• BSD-3-Clause
• LGPL-2.0-only
• LGPL-2.1-only
• LGPL-3.0-only
• GPL-2.0-only
• GPL-3.0-only
FILES: List of source files that contain valid SPDX-License-Identifier
markers. The paths can be relative to the CMake file that gen-
erates the test case or be absolute paths.
TEST_NAME
Optional parameter that defines the name of the generated test
case. If no name is defined, the relative path to the test di-
rectory with appended license name is used. Every test has li-
censecheck_ as prefix.
WILL_FAIL
Optional parameter that inverts the test result. This parameter
is usually only used for tests of the module.
Since 5.75.0
ECMConfiguredInstall
Takes a list of files, runs configure_file on each and installs the re-
sultant configured files in the given location.
Any suffix of “.in” in the passed file names will be stripped from the
file name at the installed location.
ecm_install_configured_files(
INPUT <file> [<file2> [...]]
DESTINATION <INSTALL_DIRECTORY>
[COPYONLY]
[ESCAPE_QUOTES]
[@ONLY]
[COMPONENT <component>])
Example usage:
ecm_install_configured_files(INPUT foo.txt.in DESTINATION ${KDE_INSTALL_DATADIR} @ONLY)
This will install the file as foo.txt with any cmake variable replace-
ments made into the data directory.
Since 5.73.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:
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_MES-
SAGES, 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, oth-
erwise 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 in-
stalled 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 tar-
get 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 ap-
pended 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.
ECMDeprecationSettings
This module provides the ecm_set_disabled_deprecation_versions function
setting the excluding deprecated API for Qt and KF projects.
This method expects pairs of the identifier and deprecation version.
For the identifier QT this functions adds the definition QT_DIS-
ABLE_DEPRECATED_BEFORE with the given version in a hexadecimal format.
Otherwise the name for the definition is generated using ${IDENTI-
FIER}_DISABLE_DEPRECATED_BEFORE_AND_AT, following the naming of the
generated code in ECMGenerateExportHeader. The version for the defini-
tion can be overwritten, by passing definition name and the deprecation
version as a CMake definition. This allows one to exclude deprecations
without having to edit the CMakeLists.txt file.
This module provides the following function:
ecm_set_disabled_deprecation_versions(
[DISABLE_NEWER_WARNINGS] # since 5.96
[<identifier> <deprecation_version>]
[<identifier2> <deprecation_version2>]
)
DISABLE_NEWER_WARNINGS disables additionally the compiler warnings for
API deprecated in newer versions of the same major version.
Example usage:
set(QT_MIN_VERSION "5.15.2")
set(KF5_MIN_VERSION "5.90")
ecm_set_disabled_deprecation_versions(
QT ${QT_MIN_VERSION}
KF ${KF5_MIN_VERSION}
KCOREADDONS 5.89.0 # In case we depend on deprecated KCoreAddons API
)
Since 5.91
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 sup-
ports 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 sani-
tizers, 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_li-
brary_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 compo-
nents. 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 li-
brary, 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>_<compo-
nent>_pkg_config will be searched for and used to help locate the li-
brary and header file. It will also be used to set <name>_<compo-
nent>_VERSION.
Note that if version information is found via pkg-config, <name>_<com-
ponent>_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>_<compo-
nent>_component_deps. <component>_FOUND will also be set to FALSE if
any of the components in <name>_<component>_component_deps are not
found. This requires the components in <name>_<component>_compo-
nent_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:
These variables are never cleared, so if ecm_find_package_handle_li-
brary_components() is called multiple times with different compo-
nents (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.
ECMFindQmlModule
Find QML import modules through a find_qmlmodule() call. It uses the
qmlplugindump application to find the plugins and sets them up as run-
time dependencies.
This is useful so that when we configure a project we are notified when
some QML imports are not present in the system, thus having the appli-
cation 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.
ECMGenerateDBusServiceFile
This module provides the ecm_generate_dbus_service_file function for
generating and installing a D-Bus service file.
ecm_generate_dbus_service_file(
NAME <service name>
EXECUTABLE <executable>
[SYSTEMD_SERVICE <systemd service>]
DESTINATION <install_path>
[RENAME <dbus service filename>] # Since 5.75
)
A D-Bus service file <service name>.service will be generated and in-
stalled in the relevant D-Bus config location. This filename can be
customized with RENAME.
<executable> must be an absolute path to the installed service exe-
cutable. When using it with KDEInstallDirs it needs to be the _FULL_
variant of the path variable.
NOTE:
On Windows, the macro will only use the file name part of <exe-
cutable> since D-Bus service executables are to be installed in the
same directory as the D-Bus daemon.
Optionally, a <systemd service> can be specified to launch the corre-
sponding systemd service instead of the <executable> if the D-Bus dae-
mon is started by systemd.
Example usage:
ecm_generate_dbus_service_file(
NAME org.kde.kded5
EXECUTABLE ${KDE_INSTALL_FULL_BINDIR}/kded5
DESTINATION ${KDE_INSTALL_DBUSSERVICEDIR}
)
ecm_generate_dbus_service_file(
NAME org.kde.kded5
EXECUTABLE ${KDE_INSTALL_FULL_BINDIR}/kded5
SYSTEMD_SERVICE plasma-kded.service
DESTINATION ${KDE_INSTALL_DBUSSERVICEDIR}
RENAME org.kde.daemon.service
)
Since 5.73.0.
ECMGenerateExportHeader
This module provides the ecm_generate_export_header function for gener-
ating export macros for libraries with version-based control over visi-
bility 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 “<ma-
jor>.<minor>.<patchlevel>”.
GROUP_BASE_NAME specifies the name to use for the macros defining li-
brary group default values. If set, this will generate code supporting
<group_base_name>_NO_DEPRECATED_WARNINGS, <group_base_name>_DIS-
ABLE_DEPRECATED_BEFORE_AND_AT, <group_base_name>_DEPRECATED_WARN-
INGS_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. Possible values are “0”, “CURRENT”
(which resolves to <version>) and a version string in the format “<ma-
jor>.<minor>.<patchlevel>”. The default is the value of “<exclude_dep-
recated_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)
or <prefix_name><base_name>_DEPRECATED_VERSION_BELATED(major, minor,
textmajor, textminor, 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 com-
pletely. Possible values are “0” (default), “CURRENT” (which resolves
to <version>) and a version string in the format “<major>.<mi-
nor>.<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_BE-
FORE_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><upper-
case_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_BE-
FORE_AND_AT, so e.g. test and examples part of the project automati-
cally build against the full API included in the build and without any
deprecation warnings for it.
CUSTOM_CONTENT_FROM_VARIABLE specifies the name of a variable whose
content will be appended at the end of the generated file, before any
final inclusion guard closing. Note that before 5.98 this was broken
and would only append the string passed as argument value.
The function ecm_generate_export_header defines C++ preprocessor macros
in the generated export header, some for use in the sources of the li-
brary 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><upper-
case_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>_DEPRECATED_VERSION_BELATED(major,
minor, textmajor, textminor, text)
to use to conditionally set a <prefix_name><upper-
case_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), with major & mi-
nor applied for the logic and textmajor & textminor for the
warnings message. Useful for retroactive tagging of API for the
compiler without injecting the API into the compiler warning
conditions of already released versions. Since 5.71.
<prefix_name><uppercase_base_name>_ENUMERATOR_DEPRECATED_VERSION(major,
minor, text)
to use to conditionally set a <prefix_name><upper-
case_base_name>_DEPRECATED macro for an enumerator, depending on
the warnings macro flags set (see below). In builds using C++14
standard or earlier, where enumerator attributes are not yet
supported, the macro will always yield an empty string. With
MSVC it is also always an empty string for now. Since 5.82.
<prefix_name><uppercase_base_name>_ENUMERATOR_DEPRECATED_VERSION_BE-
LATED(major, minor, textmajor, textminor, text)
to use to conditionally set a <prefix_name><upper-
case_base_name>_DEPRECATED macro for an enumerator, depending on
the warnings macro flags set (see below), with major & minor ap-
plied for the logic and textmajor & textminor for the warnings
message. In builds using C++14 standard or earlier, where enu-
merator attributes are not yet supported, the macro will always
yield an empty string. Useful for retroactive tagging of API
for the compiler without injecting the API into the compiler
warning conditions of already released versions. With MSVC it
is also always an empty string for now. Since 5.82.
<prefix_name><uppercase_base_name>_ENABLE_DEPRECATED_SINCE(major, mi-
nor)
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 visi-
bility requested.
<prefix_name><uppercase_base_name>_BUILD_DEPRECATED_SINCE(major, minor)
evaluates to TRUE or FALSE depending on the value of EX-
CLUDE_DEPRECATED_BEFORE_AND_AT. To be used mainly with #if/#en-
dif 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 nota-
tion (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_DEPRE-
CATED_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 nota-
tion (0x<major><minor><patchlevel>). Warnings will be only acti-
vated for API deprecated up to and including the version. If
<prefix_name><uppercase_base_name>_DISABLE_DEPRECATED_BE-
FORE_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>_DEPRE-
CATED_WARNINGS_SINCE to “0”. If both are set, this flag over-
rules.
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.
WARNING:
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 enu-
merator series used as index into tables
In such cases the API can be only “hidden” at build time of the li-
brary, itself, by generated hard coded macro settings, using <pre-
fix_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_EXPORT
FOO_DEPRECATED_VERSION(5, 0, "Use doFoo2()")
void doFoo();
#endif
#if FOO_ENABLE_DEPRECATED_SINCE(5, 12)
/**
* @deprecated Since 5.12
*/
FOO_EXPORT
FOO_DEPRECATED_VERSION(5, 12, "Use doBar2()")
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 defini-
tion 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 FOO_ENUMERATOR_DEPRECATED_VERSION(5, 0, "Use Three"), // macro available since 5.82
#endif
Three,
};
#if FOO_ENABLE_DEPRECATED_SINCE(5, 0)
/**
* @deprecated Since 5.0
*/
FOO_EXPORT
FOO_DEPRECATED_VERSION(5, 0, "Use doFoo2()")
void doFoo();
#endif
#if FOO_ENABLE_DEPRECATED_SINCE(5, 12)
/**
* @deprecated Since 5.12
*/
FOO_EXPORT
FOO_DEPRECATED_VERSION(5, 12, "Use doBar2()")
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 enu-
merator Two as well as the methods ::doFoo() and Foo::doWhat() will be
not available to library consumers. The methods will not have been com-
piled 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 bet-
ter explicitly sets FOO_DISABLE_DEPRECATED_BEFORE_AND_AT for those tar-
gets to the version before and at which all deprecated API has been ex-
cluded 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_ex-
port_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 redi-
rects 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: low-
ercased 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, gen-
erate 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 re-
quired 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 [PRIVATE|PUBLIC] <dep> [[PRIVATE|PUBLIC] <dep> [...]]]
[FILENAME_VAR <filename_variable>]
[INCLUDE_INSTALL_DIR <dir>]
[LIB_INSTALL_DIR <dir>]
[DEFINES -D<variable=value>...]
[DESCRIPTION <library description>] # since 5.41.0
[URL <url>] # since 5.89.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 unde-
fined, 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.
DEPS is the list of libraries required by this library. Libraries that
are not exposed to applications should be marked with PRIVATE. The de-
fault is PUBLIC, but note that according to the Guide to pkg-config
marking dependencies as private is usually preferred. The PUBLIC and
PRIVATE keywords are supported since 5.89.0.
FILENAME_VAR is specified with a variable name. This variable will re-
ceive 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_IN-
STALL_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.
URL An URL where people can get more information about and download the
package. Defaults to “https://www.kde.org/”. Since 5.89.0.
INSTALL will cause the module to be installed to the pkgconfig subdi-
rectory of LIB_INSTALL_DIR, unless the ECM_PKGCONFIG_INSTALL_DIR cache
variable is set to something different.
NOTE:
The first call to ecm_generate_pkgconfig_file() with the INSTALL ar-
gument 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 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 ei-
ther 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>
[VERSION <version>] # since 5.83
[DEPS "<dep> [<dep> [...]]"]
[FILENAME_VAR <filename_variable>]
[INCLUDE_INSTALL_DIRS <dir> [<dir> [...]]] # since 5.92
[INCLUDE_INSTALL_DIR <dir>] # deprecated since 5.92
[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.
VERSION specifies the version of the library the .pri file describes.
If not set, the value is taken from the context variable PROJECT_VER-
SION. This variable is usually set by the project(... VERSION ...)
command or, if CMake policy CMP0048 is not NEW, by ECMSetupVersion.
For backward-compatibility with older ECM versions the PROJECT_VER-
SION_STRING variable as set by ECMSetupVersion will be preferred over
PROJECT_VERSION if set, unless the minimum required version of ECM is
5.83 and newer. Since 5.83.
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 ac-
tual 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_DIRS are the paths (relative to CMAKE_INSTALL_PREFIX)
that include files will be installed to. It defaults to ${INCLUDE_IN-
STALL_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 oper-
ates similarly for the installation location for libraries; it defaults
to ${LIB_INSTALL_DIR}, ${CMAKE_INSTALL_LIBDIR} or lib, in that order.
INCLUDE_INSTALL_DIR is the old variant of INCLUDE_INSTALL_DIRS, taking
only one directory.
Example usage:
ecm_generate_pri_file(
BASE_NAME KArchive
LIB_NAME KF5KArchive
DEPS "core"
FILENAME_VAR pri_filename
VERSION 4.2.0
)
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 plug-
ins 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 ac-
cording 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, de-
vices, 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_IN-
STALL_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-indepen-
dent sub-projects.
If the CMake variable DISABLE_ALL_OPTIONAL_SUBDIRECTORIES is set to
TRUE for the first CMake run on the project, all optional subdirecto-
ries will be disabled by default (but can of course be enabled via the
respective options). For example, the following will disable all op-
tional 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 docu-
mentation 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_depen-
dency(). It is highly recommended that you read the documentation for
CMakePackageConfigHelpers for more information, particularly with re-
gard 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_pack-
age_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 con-
fig 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_in-
stall_po_files_as_qm functions for generating QTranslator (.qm) cata-
logs 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 <in-
stall_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(<sources_var_name(|target (since 5.83))> <catalog_name>)
Generates C++ code which ensures translations are automatically loaded
at startup. The generated files are appended to the variable named
<sources_var_name> or, if the first argument is a target (since 5.83),
to the SOURCES property of <target>. Any target must be created with
add_executable() or add_library() and not be an alias.
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 mycatalog)
add_library(mylib ${mylib_SRCS})
# Or, since 5.83:
add_library(mylib foo.cpp bar.cpp)
ecm_create_qm_loader(mylib mycatalog)
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 in-
stalls it in <install_destination>/fr/LC_MESSAGES. <install_destina-
tion> 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.
ECMQmlModule
This file contains helper functions to make it easier to create QML
modules. It takes care of a number of things that often need to be re-
peated. It also takes care of special handling of QML modules between
shared and static builds. When building a static version of a QML mod-
ule, the relevant QML source files are bundled into the static library.
When using a shared build, the QML plugin and relevant QML files are
copied to the target’s RUNTIME_OUTPUT_DIRECTORY to make it easier to
run things directly from the build directory.
Example usage:
ecm_add_qml_module(ExampleModule URI "org.example.Example" VERSION 1.4)
target_sources(ExampleModule PRIVATE ExamplePlugin.cpp)
target_link_libraries(ExampleModule PRIVATE Qt::Quick)
ecm_target_qml_sources(ExampleModule SOURCES ExampleItem.qml)
ecm_target_qml_sources(ExampleModule SOURCES AnotherExampleItem.qml VERSION 1.5)
ecm_finalize_qml_module(ExampleModule DESTINATION ${KDE_INSTALL_QMLDIR})
ecm_add_qml_module(<target name> URI <module uri> [VERSION <module version>] [NO_PLUGIN] [CLASSNAME <class name>])
This will declare a new CMake target called <target name>. The URI ar-
gument is required and should be a proper QML module URI. The URI is
used, among others, to generate a subdirectory where the module will be
installed to.
If the VERSION argument is specified, it is used to initialize the de-
fault version that is used by ecm_target_qml_sources when adding QML
files. If it is not specified, a default of 1.0 is used. Additionally,
if a version greater than or equal to 2.0 is specified, the major ver-
sion is appended to the installation path of the module.
If the option NO_PLUGIN is set, a target is declared that is not ex-
pected to contain any C++ QML plugin.
If the optional CLASSNAME argument is supplied, it will be used as
class name in the generated QMLDIR file. If it is not specified, the
target name will be used instead.
You can add C++ and QML source files to the target using target_sources
and ecm_target_qml_sources, respectively.
Since 5.91.0
ecm_add_qml_module_dependencies(<target> DEPENDS <module string> [<module string> ...])
Add the list of dependencies specified by the DEPENDS argument to be
listed as dependencies in the generated QMLDIR file of <target>.
Since 5.91.0
ecm_target_qml_sources(<target> SOURCES <source.qml> [<source.qml> ...] [VERSION <version>] [PATH <path>] [PRIVATE])
Add the list of QML files specified by the SOURCES argument as source
files to the QML module target <target>.
If the optional VERSION argument is specified, all QML files will be
added with the specified version. If it is not specified, they will use
the version of the QML module target.
If the optional PRIVATE argument is specified, the QML files will be
included in the target but not in the generated qmldir file. Any ver-
sion argument will be ignored.
The optional PATH argument declares a subdirectory of the module where
the files should be copied to. By default, files will be copied to the
module root.
This function will fail if <target> is not a QML module target or any
of the specified files do not exist.
Since 5.91.0
ecm_finalize_qml_module(<target> DESTINATION <QML install destination>)
Finalize the specified QML module target. This must be called after all
other setup (like adding sources) on the target has been done. It will
perform a number of tasks:
• It will generate a qmldir file from the QML files added to the tar-
get. If the module has a C++ plugin, this will also be included in
the qmldir file.
• If BUILD_SHARED_LIBS is off, a QRC file is generated from the QML
files added to the target. This QRC file will be included when com-
piling the C++ QML module. The built static library will be installed
in a subdirection of DESTINATION based on the QML module’s uri. Note
that if NO_PLUGIN is set, a C++ QML plugin will be generated to in-
clude the QRC files.
• If BUILD_SHARED_LIBS in on, all generated files, QML sources and the
C++ plugin will be installed in a subdirectory of DESTINATION based
upon the QML module’s uri. In addition, these files will also be
copied to the target’s RUNTIME_OUTPUT_DIRECTORY in a similar subdi-
rectory.
This function will fail if <target> is not a QML module target.
Since 5.91.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 in-
stalling 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 manu-
ally defined also a function ecm_qt_export_logging_category is pro-
vided.
ecm_qt_declare_logging_category(<sources_var_name(|target (since 5.80))>
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. These will provide a QLoggingCategory category that can be
referred to from C++ code using <identifier>, and from the logging con-
figuration using <category_name>.
The generated source file will be added to the variable with the name
<sources_var_name>. If the given argument is a target though, instead
both the generated header file and the generated source file will be
added to the target as private sources (since 5.80). The target must
not be an alias.
If <filename> is not absolute, it will be taken relative to the current
binary directory.
<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 gener-
ated in a file and installed by that group id with the ecm_qt_in-
stall_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 de-
clared 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 regis-
tered. 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_log-
ging_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_cate-
gory call which uses the same <exportid>. This can be in the same di-
rectory, or any subdirectory or parent directory.
EXPORT specifies the group id of categories whose information 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 in-
stall rules for the generated file are associated.
Since 5.85.0 this is a no-op when building for Android, as KDebugSet-
tings is not available on that platform and the logging category files
therefore just bloat the APK.
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.
ECMQueryQt
This module can be used to query the installation paths used by Qt.
For Qt5 this uses qmake, and for Qt6 this used qtpaths (the latter has
built-in support to query the paths of a target platform when
cross-compiling).
This module defines the following function:
ecm_query_qt(<result_variable> <qt_variable> [TRY])
Passing TRY will result in the method not making the build fail if the
executable used for querying has not been found, but instead simply
print a warning message and return an empty string.
Example usage:
include(ECMQueryQt)
ecm_query_qt(bin_dir QT_INSTALL_BINS)
If the call succeeds ${bin_dir} will be set to <prefix>/path/to/bin/dir
(e.g. /usr/lib64/qt/bin/).
Since: 5.93
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 de-
tect whether moc should be run on those files and if there are also de-
pendencies 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 de-
veloper 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 plug-
ins which do not refer to external files with the plugin metadata.
JSON_ARG1 lists the names of C++ preprocessor macros for Qt-style plug-
ins 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 ob-
ject:
#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 addi-
tional 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. MyProjectCon-
fig.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 in-
structed 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>_SOVERSION - <soversion>, or <major> if SOVERSION was not given
For backward-compatibility also this variable is set (only if the mini-
mum required version of ECM is < 5.83):
<prefix>_VERSION_STRING - <version> (use <prefix>_VERSION instead)
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>
For backward-compatibility, if CMake policy CMP0048 is not NEW, also
this variable is set (only if the minimum required version of ECM is <
5.83):
PROJECT_VERSION_STRING - <version> (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 inter-
preted 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 <mi-
nor> must be less than 256.
If the PACKAGE_VERSION_FILE option is used, a simple CMake package ver-
sion 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_pack-
age(). If the filename is a relative path, it is interpreted as rela-
tive 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_de-
pendency 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 impor-
tant 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-mod-
ules.
This module is automatically available once extra-cmake-modules has
been found, so it is not necessary to include(ECMUseFindModules) ex-
plicitly.
ecm_use_find_modules(DIR <dir>
MODULES module1.cmake [module2.cmake [...]]
[NO_OVERRIDE])
This allows selective use of the find modules provided by ECM, includ-
ing 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 ex-
ists).
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 di-
rectory and replace pseudo-symlinks with corresponding real file’s con-
tents. 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 iden-
tical icons implemented as symlinks.
Since 5.28
QtVersionOption
Adds a build option to select the major Qt version if necessary, that
is, if the major Qt version has not yet been determined otherwise (e.g.
by a corresponding find_package() call). This module is typically in-
cluded by other modules requiring knowledge about the major Qt version.
QT_MAJOR_VERSION is defined to either be “5” or “6”.
Since 5.82.0.
SEE ALSO
ecm(7), ecm-find-modules(7), ecm-kde-modules(7)
COPYRIGHT
KDE Developers
5.103 Feb 12, 2023 ECM-MODULES(7)
Generated by dwww version 1.15 on Sat Jun 29 02:29:24 CEST 2024.