Help/dev/experimental.rst

   1 CMake Experimental Features Guide
   2 *********************************
   3
   4 The following is a guide to CMake experimental features that are
   5 under development and not yet included in official documentation.
   6 See documentation on `CMake Development`_ for more information.
   7
   8 .. _`CMake Development`: README.rst
   9
  10 Features are gated behind ``CMAKE_EXPERIMENTAL_`` variables which must be set
  11 to specific values in order to enable their gated behaviors. Note that the
  12 specific values will change over time to reinforce their experimental nature.
  13 When used, a warning will be generated to indicate that an experimental
  14 feature is in use and that the affected behavior in the project is not part of
  15 CMake's stability guarantees.
  16
  17 C++20 Module APIs
  18 =================
  19
  20 Variable: ``CMAKE_EXPERIMENTAL_CXX_MODULE_CMAKE_API``
  21 Value: ``3c375311-a3c9-4396-a187-3227ef642046``
  22
  23 In order to support C++20 modules, there are a number of behaviors that have
  24 CMake APIs to provide the required features to build and export them from a
  25 project.
  26
  27 C++20 Module Dependencies
  28 =========================
  29
  30 The Ninja generator has experimental infrastructure supporting C++20 module
  31 dependency scanning.  This is similar to the Fortran modules support, but
  32 relies on external tools to scan C++20 translation units for module
  33 dependencies.  The approach is described by Kitware's `D1483r1`_ paper.
  34
  35 The ``CMAKE_EXPERIMENTAL_CXX_MODULE_DYNDEP`` variable can be set to ``1``
  36 in order to activate this undocumented experimental infrastructure.  This
  37 is **intended to make the functionality available to compiler writers** so
  38 they can use it to develop and test their dependency scanning tool.
  39 The ``CMAKE_EXPERIMENTAL_CXX_SCANDEP_SOURCE`` variable must also be set
  40 to tell CMake how to invoke the C++20 module dependency scanning tool.
  41
  42 MSVC 19.34 (provided with Visual Studio 17.4) and above contains the support
  43 that CMake needs and has these variables already set up as required and only
  44 the UUID variable needs to be set.
  45
  46 For example, add code like the following to a test project:
  47
  48 .. code-block:: cmake
  49
  50   set(CMAKE_EXPERIMENTAL_CXX_MODULE_DYNDEP 1)
  51   string(CONCAT CMAKE_EXPERIMENTAL_CXX_SCANDEP_SOURCE
  52     "<CMAKE_CXX_COMPILER> <DEFINES> <INCLUDES> <FLAGS> <SOURCE>"
  53     " -MT <DYNDEP_FILE> -MD -MF <DEP_FILE>"
  54     " ${flags_to_scan_deps} -fdep-file=<DYNDEP_FILE> -fdep-output=<OBJECT>"
  55     )
  56
  57 The tool specified by ``CMAKE_EXPERIMENTAL_CXX_SCANDEP_SOURCE`` is
  58 expected to process the translation unit, write preprocessor dependencies
  59 to the file specified by the ``<DEP_FILE>`` placeholder, and write module
  60 dependencies to the file specified by the ``<DYNDEP_FILE>`` placeholder. The
  61 ``CMAKE_EXPERIMENTAL_CXX_SCANDEP_DEPFILE_FORMAT`` file may be set to ``msvc``
  62 for scandep rules which use ``msvc``-style dependency reporting.
  63
  64 The module dependencies should be written in the format described
  65 by the `P1689r5`_ paper.
  66
  67 Compiler writers may try out their scanning functionality using
  68 the `cxx-modules-sandbox`_ test project, modified to set variables
  69 as above for their compiler.
  70
  71 For compilers that generate module maps, tell CMake as follows:
  72
  73 .. code-block:: cmake
  74
  75   set(CMAKE_EXPERIMENTAL_CXX_MODULE_MAP_FORMAT "gcc")
  76   set(CMAKE_EXPERIMENTAL_CXX_MODULE_MAP_FLAG
  77     "${compiler_flags_for_module_map} -fmodule-mapper=<MODULE_MAP_FILE>")
  78
  79 Currently, the only supported format is ``gcc``.  The format is described in
  80 the GCC documentation, but the relevant section for the purposes of CMake is:
  81
  82     A mapping file consisting of space-separated module-name, filename
  83     pairs, one per line.  Only the mappings for the direct imports and any
  84     module export name need be provided.  If other mappings are provided,
  85     they override those stored in any imported CMI files.  A repository
  86     root may be specified in the mapping file by using ``$root`` as the
  87     module name in the first active line.
  88
  89     -- GCC module mapper documentation
  90
  91 .. _`D1483r1`: https://mathstuf.fedorapeople.org/fortran-modules/fortran-modules.html
  92 .. _`P1689r5`: http://www.open-std.org/jtc1/sc22/wg21/docs/papers/2022/p1689r5.html
  93 .. _`cxx-modules-sandbox`: https://github.com/mathstuf/cxx-modules-sandbox