extra-cmake-modules - Reference of available CMake custom modules.
The "cmake" executable is the CMake command-line interface. It may be used to configure projects in scripts. Project configuration settings may be specified on the command line with the -D option. The -i option will cause cmake to interactively prompt for such settings.
CMake is a cross-platform build system generator. Projects specify their build process with platform-independent CMake listfiles included in each directory of a source tree with the name CMakeLists.txt. Users build a project by using CMake to generate a build system for a native tool on their platform.
ECMDBusAddActivationServiceECMMarkAsTestECMMarkNonGuiExecutableECMOptionalAddSubdirectoryECMPrintVariablesECMQt4To5PortingECMQtFrameworkECMSetupVersionECMUseFindModulesECMWriteVersionHeaderFindBlueZFindKF5FindLibUSB1FindX11_XCBFindXCBKDECMakeSettingsKDECompilerSettingsKDEInstallDirsThe following modules are also available for CMake. They can be used with INCLUDE(ModuleName).
Custom CMake Modules - Additional Modules for CMake.
This is the documentation for additional modules and scripts for CMake. Using these modules you can check the computer system for installed software packages, features of the compiler and the existance of headers to name just a few.
ECMDBusAddActivationService: Install a DBus ".service" file, so that a program can be started via DBus activation.
ecm_dbus_add_activation_service(inputfile)
This macro will read the input file, generate a .service file from it, and install it into the right directory for the dbus server to find it.
Note that in the case of custom install prefixes, the user will have to add the prefix to XDG_DATA_DIRS before starting the DBus server.
Example:
ecm_dbus_add_activation_service(org.mydomain.myapp.service.in)
The file org.mydomain.myapp.service.in contains:
[D-BUS Service] Name=org.mydomain.myapp Exec=@CMAKE_INSTALL_PREFIX@/bin/myapp
This will create and install PREFIX/share/dbus-1/services/org.mydomain.myapp.service
See http://techbase.kde.org/Development/Tutorials/D-Bus/Autostart_Services for a more complete documentation.
Copyright 2012 David Faure <faure@kde.org>
Distributed under the OSI-approved BSD License (the "License"); see accompanying file Copyright.txt for details.
This software is distributed WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the License for more information.
ECMMarkAsTest: Function for marking targets as being only for testingThis module provides the function ECM_MARK_AS_TEST().
The ECM_MARK_AS_TEST function is used to indicate that a target should only be built if the BUILD_TESTING option (provided by CTest) is enabled.
ECM_MARK_AS_TEST( target1 target2 ... targetN )
If BUILD_TESTING is False, then targets marked as tests are exluded from the ALL target. They are all part of the 'buildtests' target though, so even if building with BUILD_TESTING set to False, it is possible to build all tests by invoking the 'buildtests' target.
ECMMarkNonGuiExecutable: Function for marking executables as being non-guiThis module provides the function ECM_MARK_NONGUI_EXECUTABLE().
The ECM_MARK_NONGUI_EXECUTABLE function is used to indicate that an executable target should not be part of a MACOSX_BUNDLE, and should not be a WIN32_EXECUTABLE.
ECM_MARK_NONGUI_EXECUTABLE( target1 target2 ... targetN )
ECMOptionalAddSubdirectory: ECM_OPTIONAL_ADD_SUBDIRECTORY() combines ADD_SUBDIRECTORY() with an OPTION()ECM_OPTIONAL_ADD_SUBDIRECTORY(<dir>)
If you use ECM_OPTIONAL_ADD_SUBDIRECTORY() instead of ADD_SUBDIRECTORY(), this will have two effects
1 - CMake will not complain if the directory doesn't exist
This makes sense if you want to distribute just one of the subdirs
in a source package, e.g. just one of the subdirs in kdeextragear.
2 - If the directory exists, it will offer an option to skip the
subdirectory.
This is useful if you want to compile only a subset of all
directories.
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). E.g. the following will disable all optional subdirectories except the one named "kcalc":
$ cmake -DDISABLE_ALL_OPTIONAL_SUBDIRECTORIES=TRUE -DBUILD_kcalc=TRUE <srcdir>
ECMPrintVariables: Convenience macro for printing the values of cmake variables, useful e.g. while debugging.ECM_PRINT_VARIABLES(var1 var2 .. varN)
This macro will print the name of each variable followed by its value. Example:
ecm_print_variables(CMAKE_C_COMPILER CMAKE_MAJOR_VERSION THIS_ONE_DOES_NOT_EXIST)
Gives:
-- CMAKE_C_COMPILER="/usr/bin/gcc" ; CMAKE_MAJOR_VERSION="2" ; THIS_ONE_DOES_NOT_EXIST=""
ECMQt4To5Porting: ============================================================================= Copyright 2005-2011 Kitware, Inc. All rights reserved.
Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met:
* Redistributions of source code must retain the above copyright
notice, this list of conditions and the following disclaimer.
* Redistributions in binary form must reproduce the above copyright
notice, this list of conditions and the following disclaimer in the
documentation and/or other materials provided with the distribution.
* Neither the name of Kitware, Inc. nor the names of its
contributors may be used to endorse or promote products derived
from this software without specific prior written permission.
THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. =============================================================================
ECMQtFramework: - Automatic configuration of a project as a Qt framework.
This module can be used to simplify creation of quality frameworks written in Qt. It sets compiler flags, Qt definitions and CMake options which make sense to use when creating A Qt based framework.
project(myspeciallib)
ecm_framework_version(5 0 0)
include(ECMQtFramework)
This will set myspeciallib to be a Qt framework, that is, the name of the project is relevant and used (see below). The version of the project is 5.0.0. It is important to include ECMQtFramework before finding Qt itself.
Specifically being an ECM Qt framework means:
1) The compiler is configured with export flags. With GCC and clang, this means enabling the -hidden-visibility flags. See the GenerateExportHeader module for more on generating and installing export headers.
2) A Coverage build type is created and made available in the cmake-gui. This means that running
cmake $SRCDIR -DCMAKE_BUILD_TYPE=Coverage
Will enable the use of the -fprofile-arcs -ftest-coverage flags on GCC. The Coverage type is also available through the cmake-gui program.
3) Sensible compiler warnings are enabled. These are the flags determined to be useful through a history in KDE buildsystem.
4) Qt build flags are defined. These include
* Disabling automatic ascii casts provided by Qt (so for example QLatin1String must be used). This is relevant to prevent encoding errors, and makes conversion to QString potentially faster or avoidable.
* Disabling Qt keywords such as signals and slots so that Q_SIGNALS and Q_SLOTS must be used instead. This is relevant if using the framework together with boost signals.
* Enabling the use of fast concatenation. This makes it possible to create strings from multiple pieces with one memory allocation.
5) CMake will use imported targets for Qt. This is relevant on windows because it is easier to build both debug and release versions of the framework.
6) CMake will include the current source and binary directories automatically while preprocessing. The source and binary directories of the current project will be used before others.
7) CMake will use built in automatic moc support.
8) A LIB_SUFFIX variable is made available. This is used to install libraries optionally to for example /lib64 instead of /lib
9) The ECM_TARGET_DEFAULT_ARGS variable is made available for use by targets in the framework. This is used in install(TARGETS) calls to install components of targets to the configured binary and library directories, to create an export target for the framework, and to put them in a component for use with CPack. The name of the component is the same as the argument to the project call (myspeciallib above).
10) The use of RPATH is enabled. (TODO RUNPATH?)
11) A CMake config file and config version are created and installed. The config file uses the project name so that:
* The file is called myspeciallibConfig.cmake. A companion file myspeciallibVersionConfig is also created.
* The variables myspeciallib_VERSION_MAJOR, myspeciallib_VERSION_MINOR, myspeciallib_VERSION_PATCH are defined as specified by the use of ecm_framework_version.
* Standard variables are set for linking to the library and including the directories of its headers.
12) The targets file is installed. This means that myspeciallib can be used as an imported target.
13) A version file is created called myspeciallib_version.h, which contains version information usable by the preprocessor. The version file must be installed by the user.
14) The FeatureSummary module is included.
15) The CMAKE_LINK_INTERFACE_LIBRARIES variable is set to empty. This means that the library targets created will have an empty link interface unless the LINK_INTERFACE_LIBRARIES or the LINK_PUBLIC keyword to target_link_libraries are used.
ECMSetupVersion: This file provides the function ecm_setup_version(). ECM_SETUP_VERSION() bundles three things which are usually done for versioned libraries:
- it sets a set of version variables
- optionally it creates a C version header file, which can then be installed along with the library
- optionally it creates a CMake package version file, which can then be installed along with a
CMake package Config.cmake file
ecm_setup_version(<major> <minor> <patch>
VARIABLE_PREFIX prefix
[SOVERSION <soversion>]
[VERSION_HEADER filename]
[PACKAGE_VERSION_FILE filename] )
ecm_setup_version() sets the following variables
<prefix>_VERSION_MAJOR = <major>
<prefix>_VERSION_MINOR = <minor>
<prefix>_VERSION_PATCH = <patch>
<prefix>_VERSION_STRING = <major>.<minor>.<patch>
<prefix>_SOVERSION is set to <major> if <soversion> has not been specified.
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
<prefix>_VERSION_MINOR
<prefix>_VERSION_PATCH
<prefix>_VERSION_STRING - containing the full version number as a C string
<prefix>_VERSION - containing the full version combined into one integer
If the PACKAGE_VERSION_FILE option is used, a simple CMake package version file is created using the write_basic_package_version_file() macro coming with CMake. It should be installed along the Config.cmake file of the library into the same directory where it can be found by find_package(). Also here, if the given filename is a relative path, it is interpreted as relative to CMAKE_CURRENT_BINARY_DIR.
ECMUseFindModules: Selectively use some of the Find-modules provided by extra-cmake-modules (ECM)ECM_USE_FIND_MODULES(DIR <dir> MODULES module1.cmake module2.cmake .. moduleN.cmake [NO_OVERRIDE] )
This macro is automatically available once extra-cmake-modules has been found, so it is not necessary to include(ECMUseFindModules) explictely.
Use this macro instead of simply adding ${ECM_FIND_MODULE_DIR} to CMAKE_MODULE_PATH if you want to use only a subset or some specific find-modules coming with extra-cmake-modules. The given find-modules will be copied to the given directory. This directory should then be added to CMAKE_MODULE_PATH. The given modules override modules of the same name coming with CMake, except if the NO_OVERRIDE option has been used.
DIR <dir> : the selected module files will be copied to that directory. The directory should be
located somewhere inside ${CMAKE_BINARY_DIR}. It should then be added to CMAKE_MODULE_PATH .
The directory is created if it does not exist yet.
MODULES : the list of find-modules to be used from extra-cmake-modules
NO_OVERRIDE: if used, the given modules will only be used if they do not exist in the currently used
CMake version
Example:
find_package(ECM 0.0.4 REQUIRED)
ecm_use_find_modules(DIR ${CMAKE_BINARY_DIR}/cmake/ Modules FindBlueZ.cmake NO_OVERRIDE )
set(CMAKE_MODULE_PATH ${CMAKE_BINARY_DIR}/cmake/ )
This example will make FindBlueZ.cmake available in your project, but only as long as it is not yet part of CMake. The file will be copied into ${CMAKE_BINARY_DIR}/cmake/, and then this directory is added to CMAKE_MODULE_PATH.
ECMWriteVersionHeader: Function for generating a version.h fileThe ECM_WRITE_VERSION_HEADER() function is used write a simple version header which contains macros for the major, minor and patch version numbers of the project. This version header then is usually installed. As version numbers the one set using ecm_version() is used.
FindBlueZ: Try to find BlueZ bluetooth library.Once done this will define
BLUEZ_FOUND - system has BlueZ
BLUEZ_INCLUDE_DIR - the BlueZ include directory
BLUEZ_LIBRARIES - Link these to use BlueZ
BLUEZ_DEFINITIONS - Compiler switches required for using BlueZ
Redistribution and use is allowed according to the terms of the BSD license. For details see the accompanying COPYING-CMAKE-SCRIPTS file.
FindKF5: hmm, any better ideas ?
FindLibUSB1: Try to find the libusb-1.0 libraryOnce done this defines
LIBUSB1_FOUND - system has libusb-1.0
LIBUSB1_INCLUDE_DIRS - the libusb-1.0 include directory
LIBUSB1_LIBRARIES - Link these to use libusb-1.0
FindX11_XCB: Try to find libX11-xcbOnce done this will define
X11_XCB_FOUND - system has libX11-xcb
X11_XCB_LIBRARIES - Link these to use libX11-xcb
X11_XCB_INCLUDE_DIR - the libX11-xcb include dir
X11_XCB_DEFINITIONS - compiler switches required for using libX11-xcb
FindXCB: Try to find XCB on a Unix system
This will define:
XCB_FOUND - True if xcb is available
XCB_LIBRARIES - Link these to use xcb
XCB_INCLUDE_DIR - Include directory for xcb
XCB_DEFINITIONS - Compiler flags for using xcb
In addition the following more fine grained variables will be defined:
XCB_XCB_FOUND XCB_XCB_INCLUDE_DIR XCB_XCB_LIBRARIES
XCB_UTIL_FOUND XCB_UTIL_INCLUDE_DIR XCB_UTIL_LIBRARIES
XCB_COMPOSITE_FOUND XCB_COMPOSITE_INCLUDE_DIR XCB_COMPOSITE_LIBRARIES
XCB_DAMAGE_FOUND XCB_DAMAGE_INCLUDE_DIR XCB_DAMAGE_LIBRARIES
XCB_XFIXES_FOUND XCB_XFIXES_INCLUDE_DIR XCB_XFIXES_LIBRARIES
XCB_RENDER_FOUND XCB_RENDER_INCLUDE_DIR XCB_RENDER_LIBRARIES
XCB_RANDR_FOUND XCB_RANDR_INCLUDE_DIR XCB_RANDR_LIBRARIES
XCB_SHAPE_FOUND XCB_SHAPE_INCLUDE_DIR XCB_SHAPE_LIBRARIES
XCB_DRI2_FOUND XCB_DRI2_INCLUDE_DIR XCB_DRI2_LIBRARIES
XCB_GLX_FOUND XCB_GLX_INCLUDE_DIR XCB_GLX_LIBRARIES
XCB_SHM_FOUND XCB_SHM_INCLUDE_DIR XCB_SHM_LIBRARIES
XCB_XV_FOUND XCB_XV_INCLUDE_DIR XCB_XV_LIBRARIES
XCB_SYNC_FOUND XCB_SYNC_INCLUDE_DIR XCB_SYNC_LIBRARIES
XCB_XTEST_FOUND XCB_XTEST_INCLUDE_DIR XCB_XTEST_LIBRARIES
XCB_ICCCM_FOUND XCB_ICCCM_INCLUDE_DIR XCB_ICCCM_LIBRARIES
XCB_EWMH_FOUND XCB_EWMH_INCLUDE_DIR XCB_EWMH_LIBRARIES
XCB_IMAGE_FOUND XCB_IMAGE_INCLUDE_DIR XCB_IMAGE_LIBRARIES
XCB_RENDERUTIL_FOUND XCB_RENDERUTIL_INCLUDE_DIR XCB_RENDERUTIL_LIBRARIES
Copyright (c) 2011 Fredrik Höglund <fredrik@kde.org>
Redistribution and use is allowed according to the terms of the BSD license. For details see the accompanying COPYING-CMAKE-SCRIPTS file.
KDECMakeSettings: The following variables can be set to TRUE to skip parts of the functionality:
KDE_SKIP_RPATH_SETTINGS
KDE_SKIP_BUILD_SETTINGS
KDE_SKIP_TEST_SETTINGS
KDECompilerSettings: This module provides the following options:
KDE4_ENABLE_FPIE - if enabled, the KDE4_CXX_FPIE_FLAGS and KDE4_PIE_LDFLAGS variables is set accordingly
This module provides the following variables:
KDE4_CXX_FPIE_FLAGS - the flag to be used for building PIE executables
KDE4_PIE_LDFLAGS - the flag to be used by linking PIE executables
KDE4_ENABLE_EXCEPTIONS - use this to enable exceptions
This module also sets up CMAKE_CXX_FLAGS for a set of predefined buildtypes as documented below.
A note on the possible values for CMAKE_BUILD_TYPE and how KDE handles
the flags for those buildtypes. FindKDE4Internal supports the values
Debug, Release, RelWithDebInfo, Profile and Debugfull:
Release
optimised for speed, qDebug/kDebug turned off, no debug symbols, no asserts
RelWithDebInfo (Release with debug info)
similar to Release, optimised for speed, but with debugging symbols on (-g)
Debug
optimised but debuggable, debugging on (-g)
(-fno-reorder-blocks -fno-schedule-insns -fno-inline)
DebugFull
no optimisation, full debugging on (-g3)
Profile
DebugFull + -ftest-coverage -fprofile-arcs
The default buildtype is RelWithDebInfo.
It is expected that the "Debug" build type be still debuggable with gdb
without going all over the place, but still produce better performance.
It's also important to note that gcc cannot detect all warning conditions
unless the optimiser is active.
KDEInstallDirs: This module defines also a bunch of variables used as locations for install directories for files of the package which is using this module. These variables don't say anything about the location of the installed KDE. They are all relative (to CMAKE_INSTALL_PREFIX).
BIN_INSTALL_DIR - the directory where executables will be installed (default is prefix/bin)
BUNDLE_INSTALL_DIR - Mac only: the directory where application bundles will be installed (default is /Applications/KDE5 )
SBIN_INSTALL_DIR - the directory where system executables will be installed (default is prefix/sbin)
LIB_INSTALL_DIR - the directory where libraries will be installed (default is prefix/lib)
CMAKECONFIG_INSTALL_PREFIX - the prefix under which packages will create their own subdirectory for their CMake configuration files
CONFIG_INSTALL_DIR - the directory where config files will be installed
DATA_INSTALL_DIR - the parent directory where applications can install their data
HTML_INSTALL_DIR - the directory where HTML documentation will be installed
ICON_INSTALL_DIR - the directory where the icons will be installed (default prefix/share/icons/)
INFO_INSTALL_DIR - the directory where info files will be installed (default prefix/info)
KCFG_INSTALL_DIR - the directory where kconfig files will be installed
LOCALE_INSTALL_DIR - the directory where translations will be installed
MAN_INSTALL_DIR - the directory where man pages will be installed (default prefix/man/)
QT_PLUGIN_INSTALL_DIR - the directory where Qt plugins will be installed (default is {LIB_INSTALL_DIR}/plugins)
PLUGIN_INSTALL_DIR - the directory where KDE plugins will be installed (default is ${QT_PLUGIN_INSTALL_DIR}/kf5)
IMPORTS_INSTALL_DIR - the directory where QML imports will be installed (default is ${QT_PLUGIN_INSTALL_DIR}/imports)
SERVICES_INSTALL_DIR - the directory where service (desktop, protocol, ...) files will be installed
SERVICETYPES_INSTALL_DIR - the directory where servicestypes desktop files will be installed
SOUND_INSTALL_DIR - the directory where sound files will be installed
TEMPLATES_INSTALL_DIR - the directory where templates (Create new file...) will be installed
WALLPAPER_INSTALL_DIR - the directory where wallpapers will be installed
AUTOSTART_INSTALL_DIR - the directory where autostart files will be installed
DEMO_INSTALL_DIR - the directory where demos will be installed
KCONF_UPDATE_INSTALL_DIR - the directory where kconf_update files will be installed
SYSCONF_INSTALL_DIR - the directory where sysconfig files will be installed (default /etc)
XDG_APPS_INSTALL_DIR - the XDG apps dir
XDG_DIRECTORY_INSTALL_DIR- the XDG directory
XDG_MIME_INSTALL_DIR - the XDG mimetypes install dir
DBUS_INTERFACES_INSTALL_DIR - the directory where dbus interfaces will be installed (default is prefix/share/dbus-1/interfaces)
DBUS_SERVICES_INSTALL_DIR - the directory where dbus services will be installed (default is prefix/share/dbus-1/services )
DBUS_SYSTEM_SERVICES_INSTALL_DIR - the directory where dbus system services will be installed (default is prefix/share/dbus-1/system-services )
The variable INSTALL_TARGETS_DEFAULT_ARGS can be used when installing libraries or executables into the default locations. The INSTALL_TARGETS_DEFAULT_ARGS variable should be used when libraries are installed. It should also be used when installing applications, since then on OS X application bundles will be installed to BUNDLE_INSTALL_DIR. The variable MUST NOT be used for installing plugins. It also MUST NOT be used for executables which are intended to go into sbin/ or libexec/.
Usage is like this:
install(TARGETS kdecore kdeui ${INSTALL_TARGETS_DEFAULT_ARGS} )
This will install libraries correctly under UNIX, OSX and Windows (i.e. dll's go into bin/.
.B ccmake(1), cpack(1), ctest(1), cmakecommands(1), cmakecompat(1), cmakemodules(1), cmakeprops(1), cmakevars(1)
The following resources are available to get help using CMake:
Home Page: http://www.cmake.orgThe primary starting point for learning about CMake.
Frequently Asked Questions: http://www.cmake.org/Wiki/CMake_FAQA Wiki is provided containing answers to frequently asked questions.
Online Documentation: http://www.cmake.org/HTML/Documentation.htmlLinks to available documentation may be found on this web page.
Mailing List: http://www.cmake.org/HTML/MailingLists.htmlFor help and discussion about using cmake, a mailing list is provided at cmake@cmake.org. The list is member-post-only but one may sign up on the CMake web page. Please first read the full documentation at http://www.cmake.org before posting questions to the list.