Provided by: extra-cmake-modules_5.44.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> [...]])
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.
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.
• The tool png2ico is required. See FindPng2Ico.
• Supported sizes: 16, 32, 48, 64, 128.
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. 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.
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>]
[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.
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. http://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
documenation 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.
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 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.
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
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.
ECMGenerateHeaders
Generate C/C++ CamelCase forwarding headers.
ecm_generate_headers(<camelcase_forwarding_headers_var>
HEADER_NAMES <CamelCaseName> [<CamelCaseName> [...]]
[ORIGINAL <CAMELCASE|LOWERCASE>]
[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 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.
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>]
[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.
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. DESCRIPTION available since 5.1.41
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.
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.
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.
ECMQtDeclareLoggingCategory
Generate declarations for logging categories in Qt5.
ecm_qt_declare_logging_category(<sources_var>
HEADER <filename>
IDENTIFIER <identifier>
CATEGORY_NAME <category_name>
[DEFAULT_SEVERITY
<Debug|Info|Warning|
Critical|Fatal>])
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).
Since 5.14.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.
COMPATIBLITY option available since 1.6.0.
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.
SEE ALSO
ecm(7), ecm-find-modules(7), ecm-kde-modules(7)
COPYRIGHT
KDE Developers
5.44 Mar 12, 2018 ECM-MODULES(7)