Skip to content

experimental.rst

Latest commit

 

History

History
129 lines (89 loc) · 4.96 KB

experimental.rst

File metadata and controls

129 lines (89 loc) · 4.96 KB
Raw

CMake Experimental Features Guide

The following is a guide to CMake experimental features that are under development and not yet included in official documentation. See documentation on CMake Development for more information.

Features are gated behind CMAKE_EXPERIMENTAL_ variables which must be set to specific values in order to enable their gated behaviors. Note that the specific values will change over time to reinforce their experimental nature. When used, a warning will be generated to indicate that an experimental feature is in use and that the affected behavior in the project is not part of CMake's stability guarantees.

Export Package Dependencies

In order to activate support for this experimental feature, set

  • variable CMAKE_EXPERIMENTAL_EXPORT_PACKAGE_DEPENDENCIES to
  • value 1942b4fa-b2c5-4546-9385-83f254070067.

This UUID may change in future versions of CMake. Be sure to use the value documented here by the source tree of the version of CMake with which you are experimenting.

When activated, this experimental feature provides the following:

  • The install(EXPORT) and export(EXPORT) commands have experimental EXPORT_PACKAGE_DEPENDENCIES arguments to generate find_dependency calls automatically.
  • Details of the calls may be configured using the export(SETUP) command's PACKAGE_DEPENDENCY argument.
  • The package name associated with specific targets may be specified using the CMAKE_EXPORT_FIND_PACKAGE_NAME variable and/or EXPORT_FIND_PACKAGE_NAME target property.

Export Common Package Specification Package Information for install(EXPORT)

In order to activate support for this experimental feature, set

  • variable CMAKE_EXPERIMENTAL_MAPPED_PACKAGE_INFO to
  • value ababa1b5-7099-495f-a9cd-e22d38f274f2.

These UUIDs may change in future versions of CMake. Be sure to use the values documented here by the source tree of the version of CMake with which you are experimenting.

When activated, this experimental feature provides the following:

  • Setting CMAKE_INSTALL_EXPORTS_AS_PACKAGE_INFO enables generation of package information in the Common Package Specification format via the install(EXPORT) command.

Build database support

In order to activate support for exporting build databases, set

  • variable CMAKE_EXPERIMENTAL_EXPORT_BUILD_DATABASE to
  • value 70ef007e-b743-492d-9407-e35eeac03a40.

This UUID may change in future versions of CMake. Be sure to use the value documented here by the source tree of the version of CMake with which you are experimenting.

When activated, this experimental feature provides the following:

  • The :prop_tgt:`EXPORT_BUILD_DATABASE` target property and its initializing variable :variable:`CMAKE_EXPORT_BUILD_DATABASE` and environment variable :envvar:`CMAKE_EXPORT_BUILD_DATABASE`.
  • Targets with the property set to a true value will have their C++ build information exported to the build database.

Rust Support

In order to activate support for Rust, set

  • variable CMAKE_EXPERIMENTAL_RUST to
  • value b6fdddce-bf66-41a5-bc5f-077f6fa4d2a1.

This UUID may change in future versions of CMake. Be sure to use the value documented here by the source tree of the version of CMake with which you are experimenting.

SYCL Support

In order to activate support for SYCL, set

  • variable CMAKE_EXPERIMENTAL_SYCL to
  • value c0d1fb10-2ece-420e-9d29-7d7f2b300f25.

This UUID may change in future versions of CMake. Be sure to use the value documented here by the source tree of the version of CMake with which you are experimenting.

When activated, this experimental feature provides the following:

  • The experimental SYCL language, including enable_language(SYCL) and project(... LANGUAGES SYCL).
  • Target properties and variables for SYCL language standard selection.
  • The SYCL_EXTENSION_MODE target property, which controls whether SYCL sources use only SYCL language flags and feature requirements or prepend C++ language flags and combine C++ feature and standard requirements.
  • The SYCL and SYCL_HEADERS file set type aliases, which initialize the :prop_fs:`LANGUAGE` property. SYCL selects the language of a SOURCES file set, while SYCL_HEADERS marks a HEADERS file set as requiring SYCL for C++ sources that can reach it.

The SYCL language is supported by Makefile, Ninja, FASTBuild, and Visual Studio generators with AdaptiveCpp, SYCL-capable Clang, or IntelLLVM compiler drivers.

:prop_tgt:`SYCL_SEPARABLE_COMPILATION` controls separate compilation of device code. :prop_tgt:`SYCL_RESOLVE_DEVICE_SYMBOLS` controls device linking, including for static libraries used by C++-only consumers. See these properties for supported compiler and generator configurations.