diff options
Diffstat (limited to 'Help/dev/experimental.rst')
| -rw-r--r-- | Help/dev/experimental.rst | 40 |
1 files changed, 31 insertions, 9 deletions
diff --git a/Help/dev/experimental.rst b/Help/dev/experimental.rst index 7638d22..03eb076 100644 --- a/Help/dev/experimental.rst +++ b/Help/dev/experimental.rst @@ -7,6 +7,23 @@ See documentation on `CMake Development`_ for more information. .. _`CMake Development`: README.rst +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. + +C++20 Module APIs +================= + +Variable: ``CMAKE_EXPERIMENTAL_CXX_MODULE_CMAKE_API`` +Value: ``3c375311-a3c9-4396-a187-3227ef642046`` + +In order to support C++20 modules, there are a number of behaviors that have +CMake APIs to provide the required features to build and export them from a +project. + C++20 Module Dependencies ========================= @@ -22,6 +39,11 @@ they can use it to develop and test their dependency scanning tool. The ``CMAKE_EXPERIMENTAL_CXX_SCANDEP_SOURCE`` variable must also be set to tell CMake how to invoke the C++20 module dependency scanning tool. +MSVC 19.34 (provided with Visual Studio 17.4) and above contains the support +that CMake needs and has these variables already set up as required and only +the UUID and the ``CMAKE_EXPERIMENTAL_CXX_MODULE_DYNDEP`` variables need to be +set. + For example, add code like the following to a test project: .. code-block:: cmake @@ -40,13 +62,8 @@ dependencies to the file specified by the ``<DYNDEP_FILE>`` placeholder. The ``CMAKE_EXPERIMENTAL_CXX_SCANDEP_DEPFILE_FORMAT`` file may be set to ``msvc`` for scandep rules which use ``msvc``-style dependency reporting. -For tools which need to know the file set the source belongs to, the -``CMAKE_EXPERIMENTAL_CXX_MODULE_SOURCE_TYPE_FLAG_<FILE_SET_TYPE>`` flag may -be provided so that different source types can be distinguished prior to -scanning. - The module dependencies should be written in the format described -by the `P1689r4`_ paper. +by the `P1689r5`_ paper. Compiler writers may try out their scanning functionality using the `cxx-modules-sandbox`_ test project, modified to set variables @@ -60,8 +77,9 @@ For compilers that generate module maps, tell CMake as follows: set(CMAKE_EXPERIMENTAL_CXX_MODULE_MAP_FLAG "${compiler_flags_for_module_map} -fmodule-mapper=<MODULE_MAP_FILE>") -Currently, the only supported format is ``gcc``. The format is described in -the GCC documentation, but the relevant section for the purposes of CMake is: +Currently, the only supported formats are ``gcc`` and ``msvc``. The ``gcc`` +format is described in the GCC documentation, but the relevant section for the +purposes of CMake is: A mapping file consisting of space-separated module-name, filename pairs, one per line. Only the mappings for the direct imports and any @@ -72,6 +90,10 @@ the GCC documentation, but the relevant section for the purposes of CMake is: -- GCC module mapper documentation +The ``msvc`` format is a response file containing flags required to compile +any module interfaces properly as well as find any required files to satisfy +``import`` statements as required for Microsoft's Visual Studio toolchains. + .. _`D1483r1`: https://mathstuf.fedorapeople.org/fortran-modules/fortran-modules.html -.. _`P1689r4`: http://www.open-std.org/jtc1/sc22/wg21/docs/papers/2021/p1689r4.html +.. _`P1689r5`: http://www.open-std.org/jtc1/sc22/wg21/docs/papers/2022/p1689r5.html .. _`cxx-modules-sandbox`: https://github.com/mathstuf/cxx-modules-sandbox |