.\" Man page generated from reStructuredText. . . .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 .. .TH "ECM-KDE-MODULES" "7" "Nov 08, 2024" "6.8" "Extra CMake Modules" .SH NAME ecm-kde-modules \- ECM KDE Modules Reference .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 \fI\%ecm\-modules(7)\fP, and ones that extend the functionality of the \fBfind_package\fP command, documented in \fI\%ecm\-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 .EX find_package(ECM REQUIRED NO_MODULE) set(CMAKE_MODULE_PATH ${ECM_MODULE_DIR}) .EE .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 \fBNO_POLICY_SCOPE\fP 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 \fBLIB_INSTALL_DIR\fP or, if the former is not set, \fBKDE_INSTALL_LIBDIR\fP), and also the linker search path. .sp \fBNOTE:\fP .INDENT 0.0 .INDENT 3.5 \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 \fI\%KDEInstallDirs\fP module. .UNINDENT .UNINDENT .sp This section can be disabled by setting \fBKDE_SKIP_RPATH_SETTINGS\fP to \fBTRUE\fP before including this module. .SS Testing .sp Testing is enabled by default, and an option \fBBUILD_TESTING\fP 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 \fBTRUE\fP 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 \fBfind_package(ECM 5.38)\fP 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 \fBkcoreaddons_add_plugin()\fP or set \fBLIBRARY_OUTPUT_DIRECTORY\fP as documented on \X'tty: link https://community.kde.org/Guidelines_and_HOWTOs/Making_apps_run_uninstalled'\fI\%https://community.kde.org/Guidelines_and_HOWTOs/Making_apps_run_uninstalled\fP\X'tty: link'). .sp This section can be disabled by setting \fBKDE_SKIP_BUILD_SETTINGS\fP to \fBTRUE\fP before including this module. .sp This section also provides an \fBuninstall\fP target that can be individually disabled by setting \fBKDE_SKIP_UNINSTALL_TARGET\fP to \fBTRUE\fP 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 (\fBOFF\fP 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 \X'tty: link https://commits.kde.org/clazy?path=README.md'\fI\%https://commits.kde.org/clazy?path=README.md\fP\X'tty: link' .sp Since 5.17.0 .INDENT 0.0 .IP \(bu 2 \fBuninstall\fP 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 \fBCMAKE_AUTORCC\fP enabled by default when supported by CMake (>= 3.0) since 5.62.0 .UNINDENT .SS Translations (deprecated) .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 (\fBOFF\fP by default) will indicate whether translations should be downloaded when building the project. .sp Since 5.34.0 .sp \fBKDE_L10N_SYNC_TRANSLATIONS\fP (\fBOFF\fP by default) will download the translations at configuration time instead of build time. .sp Since 5.50.0 .sp All \fBKDE_L10N_*\fP options have been deprecated since 5.102.0, as translations are meanwhile present inside the source code repositories. .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 .EX kde_clang_format() .EE .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. To format the files you have to invoke the target with \fBmake clang\-format\fP or \fBninja clang\-format\fP\&. Once the project is formatted it is recommended to enforce the formatting using a pre\-commit hook, this can be done using \fI\%KDEGitCommitHooks\fP\&. .sp The \fB\&.clang\-format\fP file from ECM will be copied to the source directory. This file should not be added to version control. It is recommended to add it to the \fB\&.gitignore\fP file: \fB/.clang\-format\fP\&. .sp Since 5.79: If the source folder already contains a .clang\-format file it is not overwritten. Since version 5.80 this function is called by default in \fI\%KDEFrameworkCompilerSettings\fP\&. If directories should be excluded from the formatting a .clang\-format file with \fBDisableFormat: true\fP and \fBSortIncludes: false\fP should be created. .sp Example usage: .INDENT 0.0 .INDENT 3.5 .sp .EX include(KDEClangFormat) file(GLOB_RECURSE ALL_CLANG_FORMAT_SOURCE_FILES *.cpp *.h *.hpp *.c) kde_clang_format(${ALL_CLANG_FORMAT_SOURCE_FILES}) .EE .UNINDENT .UNINDENT .sp To exclude directories from the formatting add a \fB\&.clang\-format\fP file in the directory with the following contents: .INDENT 0.0 .INDENT 3.5 .sp .EX DisableFormat: true SortIncludes: false .EE .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; \fBkde_target_enable_exceptions()\fP can be used to re\-enable them for a specific target. .sp \fBNOTE:\fP .INDENT 0.0 .INDENT 3.5 It is recommended to include this module with the \fBNO_POLICY_SCOPE\fP flag, otherwise you may get spurious warnings with some versions of CMake. .UNINDENT .UNINDENT .sp Since 5.85 newer settings are controlled by a variable \fBKDE_COMPILERSETTINGS_LEVEL\fP, taking an ECM version as value. That version can not be greater than the minimum required ECM version. The settings which are default at that version will then be used, but can be overridden by more fine\-grained controls (see respective settings). This variable needs to be set before including this module, otherwise defaults to the minimum required ECM version. .SS Modern code .sp The following CMake C standard default variables are set: .sp For \fBKDE_COMPILERSETTINGS_LEVEL\fP >= 5.85: .INDENT 0.0 .IP \(bu 2 \fBCMAKE_C_STANDARD\fP: \fB99\fP .IP \(bu 2 \fBCMAKE_C_STANDARD_REQUIRED\fP: \fBTRUE\fP .IP \(bu 2 \fBCMAKE_C_EXTENSIONS\fP: \fBOFF\fP .UNINDENT .sp Otherwise: .INDENT 0.0 .IP \(bu 2 \fBCMAKE_C_STANDARD\fP: \fB90\fP .IP \(bu 2 \fBCMAKE_C_STANDARD_REQUIRED\fP: not modified .IP \(bu 2 \fBCMAKE_C_EXTENSIONS\fP: not modified .UNINDENT .sp If the variable \fBCMAKE_C_STANDARD\fP is already set when including this module, none of the above variables will be modified. .sp The following CMake C++ standard default variables are set: .sp For \fBKDE_COMPILERSETTINGS_LEVEL\fP >= 5.85: .INDENT 0.0 .IP \(bu 2 \fBCMAKE_CXX_STANDARD\fP: \fB17\fP .IP \(bu 2 \fBCMAKE_CXX_STANDARD_REQUIRED\fP: \fBTRUE\fP .IP \(bu 2 \fBCMAKE_CXX_EXTENSIONS\fP: \fBOFF\fP .UNINDENT .sp Otherwise: .INDENT 0.0 .IP \(bu 2 \fBCMAKE_CXX_STANDARD\fP: \fB11\fP .IP \(bu 2 \fBCMAKE_CXX_STANDARD_REQUIRED\fP: \fBTRUE\fP .IP \(bu 2 \fBCMAKE_CXX_EXTENSIONS\fP: not modified. .UNINDENT .sp If the variable \fBCMAKE_CXX_STANDARD\fP is already set when including this module, none of the above variables will be modified. .sp The following C++ compiler flags are set: .INDENT 0.0 .IP \(bu 2 \fB\-pedantic\fP (GNU and Clang compilers, since 5.85) .sp Can be disabled by setting \fBKDE_SKIP_PEDANTIC_WARNINGS_SETTINGS\fP to \fBTRUE\fP before including this module (default is \fBFALSE\fP for \fBKDE_COMPILERSETTINGS_LEVEL\fP >= 5.85, \fBTRUE\fP otherwise). .IP \(bu 2 \fB\-Wmissing\-include\-dirs\fP (GNU compilers, since 5.85) .sp Can be disabled by setting \fBKDE_SKIP_MISSING_INCLUDE_DIRS_WARNINGS_SETTINGS\fP to \fBTRUE\fP before including this module (default is \fBFALSE\fP for \fBKDE_COMPILERSETTINGS_LEVEL\fP >= 5.85, \fBTRUE\fP otherwise). .IP \(bu 2 \fB\-Wzero\-as\-null\-pointer\-constant\fP (GNU and Clang compilers, since 5.85) .sp Can be disabled by setting \fBKDE_SKIP_NULLPTR_WARNINGS_SETTINGS\fP to \fBTRUE\fP before including this module (default is \fBFALSE\fP for \fBKDE_COMPILERSETTINGS_LEVEL\fP >= 5.85, \fBTRUE\fP otherwise). .IP \(bu 2 \fB\-Werror=undef\fP (GNU and Clang compilers, since 5.96.0) .IP \(bu 2 Qt related preprocessor definitions (since 5.85.0): .INDENT 2.0 .IP \(bu 2 \fB\-DQT_NO_CAST_TO_ASCII\fP .IP \(bu 2 \fB\-DQT_NO_CAST_FROM_ASCII\fP .IP \(bu 2 \fB\-DQT_NO_URL_CAST_FROM_STRING\fP .IP \(bu 2 \fB\-DQT_NO_CAST_FROM_BYTEARRAY\fP .IP \(bu 2 \fB\-DQT_USE_QSTRINGBUILDER\fP .IP \(bu 2 \fB\-DQT_NO_NARROWING_CONVERSIONS_IN_CONNECT\fP .IP \(bu 2 \fB\-DQT_NO_KEYWORDS\fP .IP \(bu 2 \fB\-DQT_NO_FOREACH\fP .IP \(bu 2 \fB\-DQT_STRICT_ITERATORS\fP .sp Strict iterators are not enabled on Windows, because they lead to a link error when application code iterates over a QVector for instance, unless Qt itself was also built with strict iterators. See example at \X'tty: link https://bugreports.qt.io/browse/AUTOSUITE-946'\fI\%https://bugreports.qt.io/browse/AUTOSUITE\-946\fP\X'tty: link' .UNINDENT .sp Can be controlled by setting \fBKDE_QT_MODERNCODE_DEFINITIONS_LEVEL\fP to the version of ECM where the wanted set of definitions has been added before including this module (default is \fBKDE_COMPILERSETTINGS_LEVEL\fP). To disable individual definitions instead use \fBremove_definitions()\fP directly after including this module. .UNINDENT .SS Functions .sp This module provides the following functions: .INDENT 0.0 .INDENT 3.5 .sp .EX kde_source_files_enable_exceptions([file1 [file2 [...]]]) .EE .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 .EX kde_target_enable_exceptions(target ) .EE .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 .EX kde_enable_exceptions() .EE .UNINDENT .UNINDENT .sp Enables exceptions for C++ source files compiled for the CMakeLists.txt file in the current directory and all subdirectories. .SS Variables .sp Inclusion of this module defines the following variables: .INDENT 0.0 .TP .B \fBENABLE_BSYMBOLICFUNCTIONS\fP indicates whether we make use of \fB\-Bsymbolic\-functions\fP for linking. It ensures libraries bind global function references locally rather than at runtime. This option only has an effect on ELF\-based systems. .sp The option is disabled by default except when using \fI\%KDEFrameworkCompilerSettings\fP where it’s enabled. Projects can enable it by calling \fBset(ENABLE_BSYMBOLICFUNCTIONS ON)\fP or passing \fB\-DENABLE BSYMBOLICFUNCTIONS=ON\fP when configuring the build directory. .sp Since 5.85 .UNINDENT .sp Example usages: .INDENT 0.0 .INDENT 3.5 .sp .EX # needing some macro/feature only available with ECM 5.80.0 find_package(ECM 5.80.0 NO_MODULE) # requiring ECM 5.80.0 above will default KDE_COMPILERSETTINGS_LEVEL also to 5.80.0, # thus not activate any newer settings include(KDECompilerSettings NO_POLICY_SCOPE) .EE .UNINDENT .UNINDENT .INDENT 0.0 .INDENT 3.5 .sp .EX # needing some macro/feature only available with ECM 5.87.0 find_package(ECM 5.87.0 NO_MODULE) # project uses settings default as of KDECompilerSettings in ECM 5.85.0 set(KDE_COMPILERSETTINGS_LEVEL 5.85.0) include(KDECompilerSettings NO_POLICY_SCOPE) .EE .UNINDENT .UNINDENT .INDENT 0.0 .INDENT 3.5 .sp .EX # needing some macro/feature only available with ECM 5.87.0 find_package(ECM 5.87.0 NO_MODULE) # project mainly uses settings default as of KDECompilerSettings in ECM 5.85.0 # with some small twisting set(KDE_COMPILERSETTINGS_LEVEL 5.85.0) # not ready yet for pedantic compilers set(KDE_SKIP_PEDANTIC_WARNINGS_SETTINGS TRUE) # avoid any Qt definitions set(KDE_QT_MODERNCODE_DEFINITIONS_LEVEL 5.84.0) include(KDECompilerSettings NO_POLICY_SCOPE) .EE .UNINDENT .UNINDENT .INDENT 0.0 .INDENT 3.5 .sp .EX # needing some macro/feature only available with ECM 5.85.0 find_package(ECM 5.85.0 NO_MODULE) # requiring ECM 5.85.0 above will default KDE_COMPILERSETTINGS_LEVEL also to 5.85.0, # which again defaults KDE_QT_MODERNCODE_DEFINITIONS_LEVEL also to 5.85.0 include(KDECompilerSettings NO_POLICY_SCOPE) # project is fine with almost all added Qt definitions as of 5.85.0, but not these ones: remove_definitions( \-DQT_NO_KEYWORDS \-DQT_NO_FOREACH ) .EE .UNINDENT .UNINDENT .sp Since pre\-1.0.0. .SS KDEFrameworkCompilerSettings .sp Set stricter compile and link flags for KDE Frameworks modules. .sp \fBWARNING:\fP .INDENT 0.0 .INDENT 3.5 Do not use this module for software which is not part of KDE\-Frameworks. There is no guarantee for backward\-compatibility in newer versions. .UNINDENT .UNINDENT .sp The \fI\%KDECompilerSettings\fP module is included and, in addition, various defines that affect the Qt libraries are set to enforce certain conventions. .sp For example, constructions like \fBQString(\(dqfoo\(dq)\fP are prohibited, instead forcing the use of QLatin1String or QStringLiteral, and some Qt\-defined keywords like signals and slots will not be defined. .sp \fBNOTE:\fP .INDENT 0.0 .INDENT 3.5 It is recommended to include this module with the NO_POLICY_SCOPE flag, otherwise you may get spurious warnings with some versions of CMake. .UNINDENT .UNINDENT .sp Since pre\-1.0.0. .SS KDEGitCommitHooks .sp This module provides a functionality to enforce formatting or in the future other QS checks. .sp This module provides the following function: .INDENT 0.0 .INDENT 3.5 .sp .EX kde_configure_git_pre_commit_hook( CHECKS [ [...] [CUSTOM_SCRIPTS [