CMake package

Changed in version 2.6: releng-tool now populates CMAKE_FIND_ROOT_PATH.

A CMake package provides support for processing a CMake supported module.

LIBFOO_TYPE = 'cmake'

During the configuration stage of a CMake package, cmake will be invoked to generate build files for the module. For the build stage, cmake --build will invoke the generated build files. Similar approach for the installation stage where the build option is invoked again but with the install target invoked: cmake --build --target install. Each stage can be configured to manipulate environment variables and options used by the CMake executable.

The default configuration built for projects is RelWithDebInfo. A developer can override this option by explicitly adjusting the configuration option LIBFOO_CMAKE_BUILD_TYPE to, for example, Debug:

LIBFOO_CMAKE_BUILD_TYPE = 'Debug'

Packages can be configured with a toolchain using with the define CMAKE_TOOLCHAIN_FILE (via LIBFOO_CONF_DEFS) or using the command line option --toolchain (via LIBFOO_CONF_OPTS). releng-tool will provide required staging/target paths through the CMAKE_FIND_ROOT_PATH configuration. Ensure the toolchain configuration accepts CMAKE_FIND_ROOT_PATH hints. For example, using either:

list(APPEND CMAKE_FIND_ROOT_PATH "INTERNAL_SDK_PATH")

Or:

if(NOT DEFINED CMAKE_FIND_ROOT_PATH)
    set(CMAKE_FIND_ROOT_PATH "INTERNAL_SDK_PATH")
endif()

The following shows the default arguments used in stages and outlines configuration options that are available for an CMake package to set. See also the CMake package examples. All stages are invoked with a PKG_BUILD_DIR working directory.

Configuration

The configuration stage invokes cmake with the arguments:

cmake -C <RELENG-TOOL-CONFIG-CACHE> <PROJECT_DIR>

With the configuration cache that populates the options:

CMAKE_<LANG>_STANDARD_INCLUDE_DIRECTORIES=<INCLUDE_PATHS>
CMAKE_BUILD_TYPE=<BUILD_TYPE>
CMAKE_FIND_ROOT_PATH=<SYSROOT_PATHS>
CMAKE_FIND_ROOT_PATH_MODE_PROGRAM=NEVER
CMAKE_INCLUDE_PATH=<INCLUDE_PATHS>
CMAKE_INSTALL_LIBDIR="lib"
CMAKE_INSTALL_PREFIX=<PREFIX>
CMAKE_LIBRARY_PATH=<LIBRARY_PATHS>
CMAKE_MODULE_PATH=<MODULE_PATHS>
CMAKE_SKIP_INSTALL_ALL_DEPENDENCY=ON

The project directory is configured to PKG_BUILD_DIR.

The build type is configured by LIBFOO_CMAKE_BUILD_TYPE.

Paths may vary based on how the package's LIBFOO_INSTALL_TYPE is configured. System root paths provided will only include the staging directory if staging is configured. Both the staging and target directories are provided is the target is configured. Likewise with the host directory if host is configured.

The same concepts apply for defined include (<sysroot>[/<prefix>]/include), library (<sysroot>[/<prefix>]/lib) and module paths (<sysroot>[/<prefix>]/share/cmake/Modules).

Packages may override default defines using the LIBFOO_CONF_DEFS option.

A package may opt-out of configuring CMAKE_<LANG>_STANDARD_INCLUDE_DIRECTORIES variables using the releng.cmake.disable_direct_includes quirk.

Build

The build stage invokes cmake with the arguments:

cmake --build <BUILD_OUTPUT_DIR> --config <BUILD_TYPE>

With the following environment variables set:

CMAKE_BUILD_PARALLEL_LEVEL=<NJOBS>

The --build directory is configured to PKG_BUILD_OUTPUT_DIR.

The --config type is configured to the value defined for LIBFOO_CMAKE_BUILD_TYPE. Although, this option may not be applicable/used in all build environments.

The environment variable CMAKE_BUILD_PARALLEL_LEVEL is populated by either the --jobs argument or LIBFOO_FIXED_JOBS. Although, if the configuration results in a single job, the environment variable will not be set.

Install

The install stage invokes cmake with the arguments:

cmake \
    --build <BUILD_OUTPUT_DIR> \
    --config <BUILD_TYPE> \
    --target install

With the following environment variables set:

CMAKE_INSTALL_ALWAYS=1
DESTDIR=<TARGET_DIR>

The --build directory is configured to PKG_BUILD_OUTPUT_DIR.

The --config type is configured to the value defined for LIBFOO_CMAKE_BUILD_TYPE. Although, this option may not be applicable/used in all build environments.

The DESTDIR path will be set to the target sysroot the package should install into (see also LIBFOO_INSTALL_TYPE). cmake may be invoked multiple times for each target it needs to install into.

The installation stage can be skipped by configuring LIBFOO_CMAKE_NOINSTALL.

LIBFOO_BUILD_DEFS

Changed in version 2.2: Support added for path-like values.

Provides a means to pass definitions into the build process. This option can is defined as a dictionary of string pairs. This field is optional.

LIBFOO_BUILD_DEFS = {
    # adds "-Doption=value" to the command
    'option': 'value',
}

LIBFOO_BUILD_ENV

Changed in version 2.2: Support added for path-like values.

Provides a means to pass environment variables into the build process. This option is defined as a dictionary with key-value pairs where the key is the environment name and the value is the environment variable's value. This field is optional.

LIBFOO_BUILD_ENV = {
    'OPTION': 'VALUE',
}

LIBFOO_BUILD_OPTS

Changed in version 2.2: Support added for path-like values.

Provides a means to pass command line options into the build process. This option can be defined as a dictionary of string pairs or a list with strings -- either way defined will generate argument values to include in the build event. This field is optional.

LIBFOO_BUILD_OPTS = {
    # adds "--option value" to the command
    '--option': 'value',
}

# (or)

LIBFOO_BUILD_OPTS = [
    # adds "--some-option" to the command
    '--some-option',
]

LIBFOO_CMAKE_BUILD_TYPE

Added in version 0.17.

Specifies the build type used for the CMake package. A package may use a common build type (Debug, Release, RelWithDebInfo or MinSizeRel), or may have a custom build type defined. A developer needing to use a specific build type can configure this option with the name of the configuration. By default, the RelWithDebInfo build type is used for all CMake packages.

LIBFOO_CMAKE_BUILD_TYPE = 'Debug'

LIBFOO_CMAKE_NOINSTALL

Added in version 0.10.

Specifies whether the CMake package should skip an attempt to invoke the install command. Ideally, projects will have an install rule configured to define how a project will install files into a target (or staging) environment. Not all CMake projects may have this rule defined, which can cause the installation stage for a package to fail. A developer can specify this no-install flag to skip a CMake-driven install request and manage installation actions through other means (such as post-processing). By default, the installation stage is invoked with a value of False.

LIBFOO_CMAKE_NOINSTALL = True

LIBFOO_CONF_DEFS

Changed in version 2.2: Support added for path-like values.

Provides a means to pass definitions into the configuration process. This option can is defined as a dictionary of string pairs. This field is optional.

LIBFOO_CONF_DEFS = {
    # adds "-Doption=value" to the command
    'option': 'value',
}

LIBFOO_CONF_ENV

Changed in version 2.2: Support added for path-like values.

Provides a means to pass environment variables into the configuration process. This option is defined as a dictionary with key-value pairs where the key is the environment name and the value is the environment variable's value. This field is optional.

LIBFOO_CONF_ENV = {
    'OPTION': 'VALUE',
}

LIBFOO_CONF_OPTS

Changed in version 2.2: Support added for path-like values.

Provides a means to pass command line options into the configuration process. This option can be defined as a dictionary of string pairs or a list with strings -- either way defined will generate argument values to include in the configuration event. This field is optional.

LIBFOO_CONF_OPTS = {
    # adds "--option value" to the command
    '--option': 'value',
}

# (or)

LIBFOO_CONF_OPTS = [
    # adds "--some-option" to the command
    '--some-option',
]

LIBFOO_ENV

Added in version 0.17.

Changed in version 2.2: Support added for path-like values.

Provides a means to pass environment variables into all stages for a package. This option is defined as a dictionary with key-value pairs where the key is the environment name and the value is the environment variable's value. This field is optional.

LIBFOO_ENV = {
    'OPTION': 'VALUE',
}

LIBFOO_INSTALL_DEFS

Changed in version 2.2: Support added for path-like values.

Provides a means to pass definitions into the installation process. This option can is defined as a dictionary of string pairs. This field is optional.

LIBFOO_INSTALL_DEFS = {
    # adds "-Doption=value" to the command
    'option': 'value',
}

LIBFOO_INSTALL_ENV

Changed in version 2.2: Support added for path-like values.

Provides a means to pass environment variables into the installation process. This option is defined as a dictionary with key-value pairs where the key is the environment name and the value is the environment variable's value. This field is optional.

LIBFOO_INSTALL_ENV = {
    'OPTION': 'VALUE',
}

LIBFOO_INSTALL_OPTS

Changed in version 2.2: Support added for path-like values.

Provides a means to pass command line options into the installation process. This option can be defined as a dictionary of string pairs or a list with strings -- either way defined will generate argument values to include in the installation event. This field is optional.

LIBFOO_INSTALL_OPTS = {
    # adds "--option value" to the command
    '--option': 'value',
}

# (or)

LIBFOO_INSTALL_OPTS = [
    # adds "--some-option" to the command
    '--some-option',
]