Get Gentoo!
Development Guide
  1. Master index
  2. Eclass reference

cmake.eclass

Name

cmake.eclass -- common ebuild functions for cmake-based packages

Description

The cmake eclass makes creating ebuilds for cmake-based packages much easier. It provides all inherited features (DOCS, HTML_DOCS, PATCHES) along with out-of-source builds (default) and in-source builds.

Supported EAPIs

8

Transitively Provided Eclasses

  • ninja-utils

Exported Phases

  • src_compile

  • src_test

  • src_install

  • src_prepare

  • src_configure

Functions

cmake_run_in <working dir> <run command>

Set the desired working dir for a function or command.

cmake_comment_add_subdirectory [-f <filename or directory>] <subdirectory> [<subdirectories>]

Comment out one or more add_subdirectory calls with #DONOTBUILD in a) a given file path (error out on nonexisting path) b) a CMakeLists.txt file inside a given directory (ewarn if not found) c) CMakeLists.txt in current directory (do nothing if not found).

cmake_use_find_package <USE flag> <package name>

Based on use_enable. See ebuild(5).

cmake_use_find_package foo LibFoo echoes -DCMAKE_DISABLE_FIND_PACKAGE_LibFoo=OFF if foo is enabled and -DCMAKE_DISABLE_FIND_PACKAGE_LibFoo=ON if it is disabled. This can be used to make find_package optional.

cmake_prepare-per-cmakelists <path-to-current-CMakeLists.txt>

Override this to be provided with a hook into the cmake_src_prepare loop over all CMakeLists.txt below CMAKE_USE_DIR. Will be called from inside that loop with <path-to-current-CMakeLists.txt> as single argument. Used for recursive CMakeLists.txt detections and modifications.

cmake_prepare

Check existence of and sanitise CMake files, then make ${CMAKE_USE_DIR} read-only. MUST be run or cmake_src_configure will fail.

cmake_src_prepare

Apply ebuild and user patches via default_src_prepare. In case of conflict with another eclass' src_prepare phase, use cmake_prepare instead.

cmake_src_configure

General function for configuring with cmake. Default behaviour is to start an out-of-source build. Passes arguments to cmake by reading from an optionally pre-defined local mycmakeargs bash array.

src_configure() {
    local mycmakeargs=(
            $(cmake_use_find_package foo LibFoo)
    )
    cmake_src_configure
}
cmake_src_compile

General function for compiling with cmake. All arguments are passed to cmake_build.

cmake_build

Function for building the package. Automatically detects the build type. All arguments are passed to eninja (default) or emake depending on the value of CMAKE_MAKEFILE_GENERATOR.

cmake_src_test

Function for testing the package. Automatically detects the build type.

cmake_src_install

Function for installing the package. Automatically detects the build type.

Variables

BUILD_DIR

Build directory where all cmake processed files should be generated. For in-source build it's fixed to ${CMAKE_USE_DIR}. For out-of-source build it can be overridden, by default it uses ${CMAKE_USE_DIR}_build (set inside _cmake_check_build_dir).

CMAKE_BINARY

Eclass can use different cmake binary than the one provided in by system.

CMAKE_BUILD_TYPE

Set to override default CMAKE_BUILD_TYPE. Only useful for packages known to make use of "if (CMAKE_BUILD_TYPE MATCHES xxx)". If about to be set - needs to be set before invoking cmake_src_configure.

The default is RelWithDebInfo as that is least likely to append undesirable flags. However, you may still need to sed CMake files or choose a different build type to achieve desirable results.

CMAKE_IN_SOURCE_BUILD

Set to enable in-source build.

CMAKE_MAKEFILE_GENERATOR (SET BEFORE INHERIT)

Specify a makefile generator to be used by cmake. At this point only "emake" and "ninja" are supported. The default is set to "ninja".

CMAKE_REMOVE_MODULES_LIST (SET BEFORE INHERIT)

Array of .cmake modules to be removed in ${CMAKE_USE_DIR} during src_prepare, in order to force packages to use the system version. By default, contains "FindBLAS" and "FindLAPACK". Set to empty to disable removing modules entirely.

CMAKE_USE_DIR

Sets the directory where we are working with cmake, for example when application uses autotools and only one plugin needs to be done by cmake. By default it uses current working directory.

CMAKE_VERBOSE (USER VARIABLE)

Set to OFF to disable verbose messages during compilation

CMAKE_WARN_UNUSED_CLI

Warn about variables that are declared on the command line but not used. Might give false-positives. "no" to disable or anything else to enable. The default is set to "yes" (enabled).

CMAKE_ECM_MODE

Default value is "auto", which means _cmake_modify-cmakelists will make an effort to detect find_package(ECM) in CMakeLists.txt. If set to true, make extra checks and add common config settings related to ECM (KDE Extra CMake Modules). If set to false, do nothing.

CMAKE_EXTRA_CACHE_FILE (USER VARIABLE)

Specifies an extra cache file to pass to cmake. This is the analog of EXTRA_ECONF for econf and is needed to pass TRY_RUN results when cross-compiling. Should be set by user in a per-package basis in /etc/portage/package.env.

CMAKE_QA_COMPAT_SKIP

If set, skip detection of CMakeLists.txt unsupported in CMake 4 in case of false positives (e.g. unused outdated bundled libs).

_CMAKE_MINREQVER_CMAKE305 = ()

Internal array containing <file>:<version> tuples detected by _cmake_minreqver-get() for any CMake file with cmake_minimum_required version lower than 3.5.

_CMAKE_MINREQVER_CMAKE310 = ()

Internal array containing <file>:<version> tuples detected by _cmake_minreqver-get() for any CMake file with cmake_minimum_required version lower than 3.10 (causes CMake warnings as of 4.0) on top of those already added to _CMAKE_MINREQVER_CMAKE305.

_CMAKE_MINREQVER_CMAKE316 = ()

Internal array containing <file>:<version> tuples detected by _cmake_minreqver-get() for any CMake file with cmake_minimum_required version lower than 3.16 (causes ECM warnings since 5.100), on top of those already added to _CMAKE_MINREQVER_CMAKE305 and _CMAKE_MINREQVER_CMAKE310.

CMAKE_QA_SRC_DIR_READONLY (USER VARIABLE)

After running cmake_src_prepare, sets ${CMAKE_USE_DIR} to read-only. This is a user flag and should under _no circumstances_ be set in the ebuild. Helps in improving QA of build systems that write to source tree.

CMAKE_SKIP_TESTS

Array of tests that should be skipped when running CTest.

MYCMAKEARGS (USER VARIABLE)

User-controlled environment variable containing arguments to be passed to cmake in cmake_src_configure.

CTEST_JOBS (USER VARIABLE)

Maximum number of CTest jobs to run in parallel. If unset, the value will be determined from make options.

CTEST_LOADAVG (USER VARIABLE)

Maximum load, over which no new jobs will be started by CTest. Note that unlike make, CTest will not start any jobs if the load is exceeded. If unset, the value will be determined from make options.

Authors

Tomáš Chvátal <scarabeus@gentoo.org>

Maciej Mrozowski <reavertm@gentoo.org>

(undisclosed contributors)

Original author: Zephyrus (zephyrus@mirach.it)

Maintainers

kde@gentoo.org

base-system@gentoo.org

Reporting Bugs

Please report bugs via https://bugs.gentoo.org/