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 C++20 Module Dependencies
  11 =========================
  12
  13 The Ninja generator has experimental infrastructure supporting C++20 module
  14 dependency scanning.  This is similar to the Fortran modules support, but
  15 relies on external tools to scan C++20 translation units for module
  16 dependencies.  The approach is described by Kitware's `D1483r1`_ paper.
  17
  18 The ``CMAKE_EXPERIMENTAL_CXX_MODULE_DYNDEP`` variable can be set to ``1``
  19 in order to activate this undocumented experimental infrastructure.  This
  20 is **intended to make the functionality available to compiler writers** so
  21 they can use it to develop and test their dependency scanning tool.
  22 The ``CMAKE_EXPERIMENTAL_CXX_SCANDEP_SOURCE`` variable must also be set
  23 to tell CMake how to invoke the C++20 module dependency scanning tool.
  24
  25 For example, add code like the following to a test project:
  26
  27 .. code-block:: cmake
  28
  29   set(CMAKE_EXPERIMENTAL_CXX_MODULE_DYNDEP 1)
  30   string(CONCAT CMAKE_EXPERIMENTAL_CXX_SCANDEP_SOURCE
  31     "<CMAKE_CXX_COMPILER> <DEFINES> <INCLUDES> <FLAGS> <SOURCE>"
  32     " -MT <DYNDEP_FILE> -MD -MF <DEP_FILE>"
  33     " ${flags_to_scan_deps} -fdep-file=<DYNDEP_FILE> -fdep-output=<OBJECT>"
  34     )
  35
  36 The tool specified by ``CMAKE_EXPERIMENTAL_CXX_SCANDEP_SOURCE`` is
  37 expected to process the translation unit, write preprocessor dependencies
  38 to the file specified by the ``<DEP_FILE>`` placeholder, and write module
  39 dependencies to the file specified by the ``<DYNDEP_FILE>`` placeholder. The
  40 ``CMAKE_EXPERIMENTAL_CXX_SCANDEP_DEPFILE_FORMAT`` file may be set to ``msvc``
  41 for scandep rules which use ``msvc``-style dependency reporting.
  42
  43 For tools which need to know the file set the source belongs to, the
  44 ``CMAKE_EXPERIMENTAL_CXX_MODULE_SOURCE_TYPE_FLAG_<FILE_SET_TYPE>`` flag may
  45 be provided so that different source types can be distinguished prior to
  46 scanning.
  47
  48 The module dependencies should be written in the format described
  49 by the `P1689r4`_ paper.
  50
  51 Compiler writers may try out their scanning functionality using
  52 the `cxx-modules-sandbox`_ test project, modified to set variables
  53 as above for their compiler.
  54
  55 For compilers that generate module maps, tell CMake as follows:
  56
  57 .. code-block:: cmake
  58
  59   set(CMAKE_EXPERIMENTAL_CXX_MODULE_MAP_FORMAT "gcc")
  60   set(CMAKE_EXPERIMENTAL_CXX_MODULE_MAP_FLAG
  61     "${compiler_flags_for_module_map} -fmodule-mapper=<MODULE_MAP_FILE>")
  62
  63 Currently, the only supported format is ``gcc``.  The format is described in
  64 the GCC documentation, but the relevant section for the purposes of CMake is:
  65
  66     A mapping file consisting of space-separated module-name, filename
  67     pairs, one per line.  Only the mappings for the direct imports and any
  68     module export name need be provided.  If other mappings are provided,
  69     they override those stored in any imported CMI files.  A repository
  70     root may be specified in the mapping file by using ``$root`` as the
  71     module name in the first active line.
  72
  73     -- GCC module mapper documentation
  74
  75 .. _`D1483r1`: https://mathstuf.fedorapeople.org/fortran-modules/fortran-modules.html
  76 .. _`P1689r4`: http://www.open-std.org/jtc1/sc22/wg21/docs/papers/2021/p1689r4.html
  77 .. _`cxx-modules-sandbox`: https://github.com/mathstuf/cxx-modules-sandbox