.\" Man page generated from reStructuredText. . .TH "ECM-KDE-MODULES" "7" "Jan 22, 2021" "5.78" "Extra CMake Modules" .SH NAME ecm-kde-modules \- ECM KDE Modules Reference . .nr rst2man-indent-level 0 . .de1 rstReportMargin \\$1 \\n[an-margin] level \\n[rst2man-indent-level] level margin: \\n[rst2man-indent\\n[rst2man-indent-level]] - \\n[rst2man-indent0] \\n[rst2man-indent1] \\n[rst2man-indent2] .. .de1 INDENT .\" .rstReportMargin pre: . RS \\$1 . nr rst2man-indent\\n[rst2man-indent-level] \\n[an-margin] . nr rst2man-indent-level +1 .\" .rstReportMargin post: .. .de UNINDENT . RE .\" indent \\n[an-margin] .\" old: \\n[rst2man-indent\\n[rst2man-indent-level]] .nr rst2man-indent-level -1 .\" new: \\n[rst2man-indent\\n[rst2man-indent-level]] .in \\n[rst2man-indent\\n[rst2man-indent-level]]u .. .SH INTRODUCTION .sp Extra CMake Modules (ECM) provides several modules that provide default settings (like installation directories, compiler flags and other CMake options) aimed at software produced by the KDE modules; these are documented here. ECM also provides modules with more general functionality, documented in \fBecm\-modules(7)\fP, and ones that extend the functionality of the \fBfind_package\fP command, documented in \fBecm\-find\-modules(7)\fP\&. .sp To use these modules, you need to tell CMake to find the ECM package, and then add either \fB${ECM_MODULE_PATH}\fP or \fB${ECM_KDE_MODULE_DIR}\fP to the \fBCMAKE_MODULE_PATH\fP variable: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C find_package(ECM REQUIRED NO_MODULE) set(CMAKE_MODULE_PATH ${ECM_MODULE_DIR}) .ft P .fi .UNINDENT .UNINDENT .sp Using \fB${ECM_MODULE_PATH}\fP will also make the other types of modules available. .SH ALL KDE MODULES .SS KDECMakeSettings .sp Changes various CMake settings to what the KDE community views as more sensible defaults. .sp It is recommended to include this module with the NO_POLICY_SCOPE flag, otherwise you may get spurious warnings with some versions of CMake. .sp It is split into three parts, which can be independently disabled if desired. .SS Runtime Paths .sp The default runtime path (used on Unix systems to search for dynamically\-linked libraries) is set to include the location that libraries will be installed to (as set in LIB_INSTALL_DIR or, if the former is not set, KDE_INSTALL_LIBDIR), and also the linker search path. .sp Note that \fBLIB_INSTALL_DIR\fP or alternatively \fBKDE_INSTALL_LIBDIR\fP needs to be set before including this module. Typically, this is done by including the \fBKDEInstallDirs\fP module. .sp This section can be disabled by setting \fBKDE_SKIP_RPATH_SETTINGS\fP to TRUE before including this module. .SS Testing .sp Testing is enabled by default, and an option (BUILD_TESTING) is provided for users to control this. See the CTest module documentation in the CMake manual for more details. .sp This section can be disabled by setting \fBKDE_SKIP_TEST_SETTINGS\fP to TRUE before including this module. .SS Build Settings .sp Various CMake build defaults are altered, such as searching source and build directories for includes first, enabling automoc by default. .sp When find_package(ECM 5.38) or higher is called, this also selects a layout for the build dir that helps running executables without installing: all executables are built into a toplevel “bin” dir, making it possible to find helper binaries, and to find uninstalled plugins (provided that you use kcoreaddons_add_plugin or set LIBRARY_OUTPUT_DIRECTORY as documented on \fI\%https://community.kde.org/Guidelines_and_HOWTOs/Making_apps_run_uninstalled\fP). .sp This section can be disabled by setting \fBKDE_SKIP_BUILD_SETTINGS\fP to TRUE before including this module. .sp This section also provides an “uninstall” target that can be individually disabled by setting \fBKDE_SKIP_UNINSTALL_TARGET\fP to TRUE before including this module. .sp By default on OS X, X11 and XCB related detections are disabled. However if the need would arise to use these technologies, the detection can be enabled by setting \fBAPPLE_FORCE_X11\fP to \fBON\fP\&. .sp A warning is printed for the developer to know that the detection is disabled on OS X. This message can be turned off by setting \fBAPPLE_SUPPRESS_X11_WARNING\fP to \fBON\fP\&. .sp Since pre\-1.0.0. .sp \fBENABLE_CLAZY\fP option is added (OFF by default) when clang is being used. Turning this option on will force clang to load the clazy plugins for richer warnings on Qt\-related code. .sp If clang is not being used, this won’t have an effect. See \fI\%https://commits.kde.org/clazy?path=README.md\fP .sp Since 5.17.0 .INDENT 0.0 .IP \(bu 2 Uninstall target functionality since 1.7.0. .IP \(bu 2 \fBAPPLE_FORCE_X11\fP option since 5.14.0 (detecting X11 was previously the default behavior) .IP \(bu 2 \fBAPPLE_SUPPRESS_X11_WARNING\fP option since 5.14.0 .IP \(bu 2 CMAKE_AUTORCC enabled by default when supported by cmake (>= 3.0) since 5.62.0 .UNINDENT .SS Translations .sp A fetch\-translations target will be set up that will download translations for projects using l10n.kde.org. .sp \fBKDE_L10N_BRANCH\fP will be responsible for choosing which l10n branch to use for the translations. .sp \fBKDE_L10N_AUTO_TRANSLATIONS\fP (OFF by default) will indicate whether translations should be downloaded when building the project. .sp Since 5.34.0 .sp \fBKDE_L10N_SYNC_TRANSLATIONS\fP (OFF by default) will download the translations at configuration time instead of build time. .sp Since 5.50.0 .SS KDEClangFormat .sp This module provides a functionality to format the source code of your repository according to a predefined KDE clang\-format file. .sp This module provides the following function: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C kde_clang_format() .ft P .fi .UNINDENT .UNINDENT .sp Using this function will create a clang\-format target that will format all \fB\fP passed to the function with the predefined KDE clang\-format style. .sp Example usage: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C include(KDEClangFormat) file(GLOB_RECURSE ALL_CLANG_FORMAT_SOURCE_FILES src/*.cpp src/*.h) kde_clang_format(${ALL_CLANG_FORMAT_SOURCE_FILES}) .ft P .fi .UNINDENT .UNINDENT .sp Since 5.64 .SS KDECompilerSettings .sp Set useful compile and link flags for C++ (and C) code. .sp Enables many more warnings than the default, and sets stricter modes for some compiler features. By default, exceptions are disabled; kde_target_enable_exceptions() can be used to re\-enable them for a specific target. .sp NB: it is recommended to include this module with the NO_POLICY_SCOPE flag, otherwise you may get spurious warnings with some versions of CMake. .sp This module provides the following functions: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C kde_source_files_enable_exceptions([file1 [file2 [...]]]) .ft P .fi .UNINDENT .UNINDENT .sp Enables exceptions for specific source files. This should not be used on source files in a language other than C++. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C kde_target_enable_exceptions(target ) .ft P .fi .UNINDENT .UNINDENT .sp Enables exceptions for a specific target. This should not be used on a target that has source files in a language other than C++. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C kde_enable_exceptions() .ft P .fi .UNINDENT .UNINDENT .sp Enables exceptions for C++ source files compiled for the CMakeLists.txt file in the current directory and all subdirectories. .sp Since pre\-1.0.0. .SS KDEFrameworkCompilerSettings .sp Set stricter compile and link flags for KDE Frameworks modules. .sp The KDECompilerSettings module is included and, in addition, various defines that affect the Qt libraries are set to enforce certain conventions. .sp For example, constructions like QString(“foo”) are prohibited, instead forcing the use of QLatin1String or QStringLiteral, and some Qt\-defined keywords like signals and slots will not be defined. .sp NB: it is recommended to include this module with the NO_POLICY_SCOPE flag, otherwise you may get spurious warnings with some versions of CMake. .sp Since pre\-1.0.0. .SS KDEInstallDirs .sp Define KDE standard installation directories. .sp Note that none of the variables defined by this module provide any information about the location of already\-installed KDE software. .sp Also sets \fBCMAKE_INSTALL_PREFIX\fP to the installation prefix of ECM, unless that variable has been already explicitly set by something else (since 5.61 and with CMake >= 3.7). .sp Inclusion of this module defines the following variables: .INDENT 0.0 .TP .B \fBKDE_INSTALL_\fP destination for files of a given type .TP .B \fBKDE_INSTALL_FULL_\fP corresponding absolute path .UNINDENT .sp where \fB\fP is one of (default values in parentheses and alternative, deprecated variable name in square brackets): .INDENT 0.0 .TP .B \fBBUNDLEDIR\fP application bundles (\fB/Applications/KDE\fP) [\fBBUNDLE_INSTALL_DIR\fP] .TP .B \fBEXECROOTDIR\fP executables and libraries (\fB\fP) [\fBEXEC_INSTALL_PREFIX\fP] .TP .B \fBBINDIR\fP user executables (\fBEXECROOTDIR/bin\fP) [\fBBIN_INSTALL_DIR\fP] .TP .B \fBSBINDIR\fP system admin executables (\fBEXECROOTDIR/sbin\fP) [\fBSBIN_INSTALL_DIR\fP] .TP .B \fBLIBDIR\fP object code libraries (\fBEXECROOTDIR/lib\fP, \fBEXECROOTDIR/lib64\fP or \fBEXECROOTDIR/lib/\fP variables (or their \fBCMAKE_INSTALL_\fP or deprecated counterparts) may be passed to the DESTINATION options of \fBinstall()\fP commands for the corresponding file type. They are set in the CMake cache, and so the defaults above can be overridden by users. .sp Note that the \fBKDE_INSTALL_\fP, \fBCMAKE_INSTALL_\fP or deprecated form of the variable can be changed using CMake command line variable definitions; in either case, all forms of the variable will be affected. The effect of passing multiple forms of the same variable on the command line (such as \fBKDE_INSTALL_BINDIR\fP and \fBCMAKE_INSTALL_BINDIR\fP is undefined. .sp The variable \fBKDE_INSTALL_TARGETS_DEFAULT_ARGS\fP is also defined (along with the deprecated form \fBINSTALL_TARGETS_DEFAULT_ARGS\fP). This should be used when libraries or user\-executable applications are installed, in the following manner: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C install(TARGETS mylib myapp ${KDE_INSTALL_TARGETS_DEFAULT_ARGS}) .ft P .fi .UNINDENT .UNINDENT .sp It MUST NOT be used for installing plugins, system admin executables or executables only intended for use internally by other code. Those should use \fBKDE_INSTALL_PLUGINDIR\fP, \fBKDE_INSTALL_SBINDIR\fP or \fBKDE_INSTALL_LIBEXECDIR\fP respectively. .sp Additionally, \fBCMAKE_INSTALL_DEFAULT_COMPONENT_NAME\fP will be set to \fB${PROJECT_NAME}\fP to provide a sensible default for this CMake option. .sp Note that mixing absolute and relative paths, particularly for \fBBINDIR\fP, \fBLIBDIR\fP and \fBINCLUDEDIR\fP, can cause issues with exported targets. Given that the default values for these are relative paths, relative paths should be used on the command line when possible (eg: use \fB\-DKDE_INSTALL_LIBDIR=lib64\fP instead of \fB\-DKDE_INSTALL_LIBDIR=/usr/lib/lib64\fP to override the library directory). .sp Since pre\-1.0.0. .sp NB: The variables starting \fBKDE_INSTALL_\fP are available since 1.6.0, unless otherwise noted with the variable. .sp The \fBKDE_INSTALL_PREFIX_SCRIPT\fP option will install a ${CMAKE_INSTALL_PREFIX}/prefix.sh file that allows to easily incorporate the necessary environment variables for the prefix into a process. .SS KDETemplateGenerator .sp Packages KApptemplate/KDevelop compatible application templates .sp This module provides a functionality to package in a tarball and install project templates compatible with the format used by KApptemplate and KDevelop. Useful for providing minimal examples for the usage of the KDE Frameworks. .sp This module provides the following function: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C kde_package_app_templates(TEMPLATES