1e5dd7070Spatrick======= 2e5dd7070SpatrickModules 3e5dd7070Spatrick======= 4e5dd7070Spatrick 5e5dd7070Spatrick.. contents:: 6e5dd7070Spatrick :local: 7e5dd7070Spatrick 8e5dd7070SpatrickIntroduction 9e5dd7070Spatrick============ 10e5dd7070SpatrickMost software is built using a number of software libraries, including libraries supplied by the platform, internal libraries built as part of the software itself to provide structure, and third-party libraries. For each library, one needs to access both its interface (API) and its implementation. In the C family of languages, the interface to a library is accessed by including the appropriate header files(s): 11e5dd7070Spatrick 12e5dd7070Spatrick.. code-block:: c 13e5dd7070Spatrick 14e5dd7070Spatrick #include <SomeLib.h> 15e5dd7070Spatrick 16e5dd7070SpatrickThe implementation is handled separately by linking against the appropriate library. For example, by passing ``-lSomeLib`` to the linker. 17e5dd7070Spatrick 18e5dd7070SpatrickModules provide an alternative, simpler way to use software libraries that provides better compile-time scalability and eliminates many of the problems inherent to using the C preprocessor to access the API of a library. 19e5dd7070Spatrick 20e5dd7070SpatrickProblems with the current model 21e5dd7070Spatrick------------------------------- 22e5dd7070SpatrickThe ``#include`` mechanism provided by the C preprocessor is a very poor way to access the API of a library, for a number of reasons: 23e5dd7070Spatrick 24e5dd7070Spatrick* **Compile-time scalability**: Each time a header is included, the 25e5dd7070Spatrick compiler must preprocess and parse the text in that header and every 26e5dd7070Spatrick header it includes, transitively. This process must be repeated for 27e5dd7070Spatrick every translation unit in the application, which involves a huge 28e5dd7070Spatrick amount of redundant work. In a project with *N* translation units 29e5dd7070Spatrick and *M* headers included in each translation unit, the compiler is 30e5dd7070Spatrick performing *M x N* work even though most of the *M* headers are 31e5dd7070Spatrick shared among multiple translation units. C++ is particularly bad, 32e5dd7070Spatrick because the compilation model for templates forces a huge amount of 33e5dd7070Spatrick code into headers. 34e5dd7070Spatrick 35e5dd7070Spatrick* **Fragility**: ``#include`` directives are treated as textual 36e5dd7070Spatrick inclusion by the preprocessor, and are therefore subject to any 37e5dd7070Spatrick active macro definitions at the time of inclusion. If any of the 38e5dd7070Spatrick active macro definitions happens to collide with a name in the 39e5dd7070Spatrick library, it can break the library API or cause compilation failures 40e5dd7070Spatrick in the library header itself. For an extreme example, 41e5dd7070Spatrick ``#define std "The C++ Standard"`` and then include a standard 42e5dd7070Spatrick library header: the result is a horrific cascade of failures in the 43e5dd7070Spatrick C++ Standard Library's implementation. More subtle real-world 44e5dd7070Spatrick problems occur when the headers for two different libraries interact 45e5dd7070Spatrick due to macro collisions, and users are forced to reorder 46e5dd7070Spatrick ``#include`` directives or introduce ``#undef`` directives to break 47e5dd7070Spatrick the (unintended) dependency. 48e5dd7070Spatrick 49e5dd7070Spatrick* **Conventional workarounds**: C programmers have 50e5dd7070Spatrick adopted a number of conventions to work around the fragility of the 51e5dd7070Spatrick C preprocessor model. Include guards, for example, are required for 52e5dd7070Spatrick the vast majority of headers to ensure that multiple inclusion 53e5dd7070Spatrick doesn't break the compile. Macro names are written with 54e5dd7070Spatrick ``LONG_PREFIXED_UPPERCASE_IDENTIFIERS`` to avoid collisions, and some 55e5dd7070Spatrick library/framework developers even use ``__underscored`` names 56e5dd7070Spatrick in headers to avoid collisions with "normal" names that (by 57e5dd7070Spatrick convention) shouldn't even be macros. These conventions are a 58e5dd7070Spatrick barrier to entry for developers coming from non-C languages, are 59e5dd7070Spatrick boilerplate for more experienced developers, and make our headers 60e5dd7070Spatrick far uglier than they should be. 61e5dd7070Spatrick 62e5dd7070Spatrick* **Tool confusion**: In a C-based language, it is hard to build tools 63e5dd7070Spatrick that work well with software libraries, because the boundaries of 64e5dd7070Spatrick the libraries are not clear. Which headers belong to a particular 65e5dd7070Spatrick library, and in what order should those headers be included to 66e5dd7070Spatrick guarantee that they compile correctly? Are the headers C, C++, 67e5dd7070Spatrick Objective-C++, or one of the variants of these languages? What 68e5dd7070Spatrick declarations in those headers are actually meant to be part of the 69e5dd7070Spatrick API, and what declarations are present only because they had to be 70e5dd7070Spatrick written as part of the header file? 71e5dd7070Spatrick 72e5dd7070SpatrickSemantic import 73e5dd7070Spatrick--------------- 74e5dd7070SpatrickModules improve access to the API of software libraries by replacing the textual preprocessor inclusion model with a more robust, more efficient semantic model. From the user's perspective, the code looks only slightly different, because one uses an ``import`` declaration rather than a ``#include`` preprocessor directive: 75e5dd7070Spatrick 76e5dd7070Spatrick.. code-block:: c 77e5dd7070Spatrick 78e5dd7070Spatrick import std.io; // pseudo-code; see below for syntax discussion 79e5dd7070Spatrick 80e5dd7070SpatrickHowever, this module import behaves quite differently from the corresponding ``#include <stdio.h>``: when the compiler sees the module import above, it loads a binary representation of the ``std.io`` module and makes its API available to the application directly. Preprocessor definitions that precede the import declaration have no impact on the API provided by ``std.io``, because the module itself was compiled as a separate, standalone module. Additionally, any linker flags required to use the ``std.io`` module will automatically be provided when the module is imported [#]_ 81e5dd7070SpatrickThis semantic import model addresses many of the problems of the preprocessor inclusion model: 82e5dd7070Spatrick 83e5dd7070Spatrick* **Compile-time scalability**: The ``std.io`` module is only compiled once, and importing the module into a translation unit is a constant-time operation (independent of module system). Thus, the API of each software library is only parsed once, reducing the *M x N* compilation problem to an *M + N* problem. 84e5dd7070Spatrick 85e5dd7070Spatrick* **Fragility**: Each module is parsed as a standalone entity, so it has a consistent preprocessor environment. This completely eliminates the need for ``__underscored`` names and similarly defensive tricks. Moreover, the current preprocessor definitions when an import declaration is encountered are ignored, so one software library can not affect how another software library is compiled, eliminating include-order dependencies. 86e5dd7070Spatrick 87e5dd7070Spatrick* **Tool confusion**: Modules describe the API of software libraries, and tools can reason about and present a module as a representation of that API. Because modules can only be built standalone, tools can rely on the module definition to ensure that they get the complete API for the library. Moreover, modules can specify which languages they work with, so, e.g., one can not accidentally attempt to load a C++ module into a C program. 88e5dd7070Spatrick 89e5dd7070SpatrickProblems modules do not solve 90e5dd7070Spatrick----------------------------- 91e5dd7070SpatrickMany programming languages have a module or package system, and because of the variety of features provided by these languages it is important to define what modules do *not* do. In particular, all of the following are considered out-of-scope for modules: 92e5dd7070Spatrick 93e5dd7070Spatrick* **Rewrite the world's code**: It is not realistic to require applications or software libraries to make drastic or non-backward-compatible changes, nor is it feasible to completely eliminate headers. Modules must interoperate with existing software libraries and allow a gradual transition. 94e5dd7070Spatrick 95e5dd7070Spatrick* **Versioning**: Modules have no notion of version information. Programmers must still rely on the existing versioning mechanisms of the underlying language (if any exist) to version software libraries. 96e5dd7070Spatrick 97e5dd7070Spatrick* **Namespaces**: Unlike in some languages, modules do not imply any notion of namespaces. Thus, a struct declared in one module will still conflict with a struct of the same name declared in a different module, just as they would if declared in two different headers. This aspect is important for backward compatibility, because (for example) the mangled names of entities in software libraries must not change when introducing modules. 98e5dd7070Spatrick 99e5dd7070Spatrick* **Binary distribution of modules**: Headers (particularly C++ headers) expose the full complexity of the language. Maintaining a stable binary module format across architectures, compiler versions, and compiler vendors is technically infeasible. 100e5dd7070Spatrick 101e5dd7070SpatrickUsing Modules 102e5dd7070Spatrick============= 103e5dd7070SpatrickTo enable modules, pass the command-line flag ``-fmodules``. This will make any modules-enabled software libraries available as modules as well as introducing any modules-specific syntax. Additional `command-line parameters`_ are described in a separate section later. 104e5dd7070Spatrick 105*12c85518SrobertStandard C++ Modules 106*12c85518Srobert-------------------- 107*12c85518Srobert.. note:: 108*12c85518Srobert Modules are adopted into C++20 Standard. And its semantic and command line interface are very different from the Clang C++ modules. See `StandardCPlusPlusModules <StandardCPlusPlusModules.html>`_ for details. 109*12c85518Srobert 110e5dd7070SpatrickObjective-C Import declaration 111e5dd7070Spatrick------------------------------ 112e5dd7070SpatrickObjective-C provides syntax for importing a module via an *@import declaration*, which imports the named module: 113e5dd7070Spatrick 114e5dd7070Spatrick.. parsed-literal:: 115e5dd7070Spatrick 116e5dd7070Spatrick @import std; 117e5dd7070Spatrick 118e5dd7070SpatrickThe ``@import`` declaration above imports the entire contents of the ``std`` module (which would contain, e.g., the entire C or C++ standard library) and make its API available within the current translation unit. To import only part of a module, one may use dot syntax to specific a particular submodule, e.g., 119e5dd7070Spatrick 120e5dd7070Spatrick.. parsed-literal:: 121e5dd7070Spatrick 122e5dd7070Spatrick @import std.io; 123e5dd7070Spatrick 124e5dd7070SpatrickRedundant import declarations are ignored, and one is free to import modules at any point within the translation unit, so long as the import declaration is at global scope. 125e5dd7070Spatrick 126e5dd7070SpatrickAt present, there is no C or C++ syntax for import declarations. Clang 127e5dd7070Spatrickwill track the modules proposal in the C++ committee. See the section 128e5dd7070Spatrick`Includes as imports`_ to see how modules get imported today. 129e5dd7070Spatrick 130e5dd7070SpatrickIncludes as imports 131e5dd7070Spatrick------------------- 132e5dd7070SpatrickThe primary user-level feature of modules is the import operation, which provides access to the API of software libraries. However, today's programs make extensive use of ``#include``, and it is unrealistic to assume that all of this code will change overnight. Instead, modules automatically translate ``#include`` directives into the corresponding module import. For example, the include directive 133e5dd7070Spatrick 134e5dd7070Spatrick.. code-block:: c 135e5dd7070Spatrick 136e5dd7070Spatrick #include <stdio.h> 137e5dd7070Spatrick 138e5dd7070Spatrickwill be automatically mapped to an import of the module ``std.io``. Even with specific ``import`` syntax in the language, this particular feature is important for both adoption and backward compatibility: automatic translation of ``#include`` to ``import`` allows an application to get the benefits of modules (for all modules-enabled libraries) without any changes to the application itself. Thus, users can easily use modules with one compiler while falling back to the preprocessor-inclusion mechanism with other compilers. 139e5dd7070Spatrick 140e5dd7070Spatrick.. note:: 141e5dd7070Spatrick 142e5dd7070Spatrick The automatic mapping of ``#include`` to ``import`` also solves an implementation problem: importing a module with a definition of some entity (say, a ``struct Point``) and then parsing a header containing another definition of ``struct Point`` would cause a redefinition error, even if it is the same ``struct Point``. By mapping ``#include`` to ``import``, the compiler can guarantee that it always sees just the already-parsed definition from the module. 143e5dd7070Spatrick 144e5dd7070SpatrickWhile building a module, ``#include_next`` is also supported, with one caveat. 145e5dd7070SpatrickThe usual behavior of ``#include_next`` is to search for the specified filename 146e5dd7070Spatrickin the list of include paths, starting from the path *after* the one 147e5dd7070Spatrickin which the current file was found. 148e5dd7070SpatrickBecause files listed in module maps are not found through include paths, a 149e5dd7070Spatrickdifferent strategy is used for ``#include_next`` directives in such files: the 150e5dd7070Spatricklist of include paths is searched for the specified header name, to find the 151e5dd7070Spatrickfirst include path that would refer to the current file. ``#include_next`` is 152e5dd7070Spatrickinterpreted as if the current file had been found in that path. 153e5dd7070SpatrickIf this search finds a file named by a module map, the ``#include_next`` 154e5dd7070Spatrickdirective is translated into an import, just like for a ``#include`` 155e5dd7070Spatrickdirective.`` 156e5dd7070Spatrick 157e5dd7070SpatrickModule maps 158e5dd7070Spatrick----------- 159e5dd7070SpatrickThe crucial link between modules and headers is described by a *module map*, which describes how a collection of existing headers maps on to the (logical) structure of a module. For example, one could imagine a module ``std`` covering the C standard library. Each of the C standard library headers (``<stdio.h>``, ``<stdlib.h>``, ``<math.h>``, etc.) would contribute to the ``std`` module, by placing their respective APIs into the corresponding submodule (``std.io``, ``std.lib``, ``std.math``, etc.). Having a list of the headers that are part of the ``std`` module allows the compiler to build the ``std`` module as a standalone entity, and having the mapping from header names to (sub)modules allows the automatic translation of ``#include`` directives to module imports. 160e5dd7070Spatrick 161e5dd7070SpatrickModule maps are specified as separate files (each named ``module.modulemap``) alongside the headers they describe, which allows them to be added to existing software libraries without having to change the library headers themselves (in most cases [#]_). The actual `Module map language`_ is described in a later section. 162e5dd7070Spatrick 163e5dd7070Spatrick.. note:: 164e5dd7070Spatrick 165e5dd7070Spatrick To actually see any benefits from modules, one first has to introduce module maps for the underlying C standard library and the libraries and headers on which it depends. The section `Modularizing a Platform`_ describes the steps one must take to write these module maps. 166e5dd7070Spatrick 167e5dd7070SpatrickOne can use module maps without modules to check the integrity of the use of header files. To do this, use the ``-fimplicit-module-maps`` option instead of the ``-fmodules`` option, or use ``-fmodule-map-file=`` option to explicitly specify the module map files to load. 168e5dd7070Spatrick 169e5dd7070SpatrickCompilation model 170e5dd7070Spatrick----------------- 171e5dd7070SpatrickThe binary representation of modules is automatically generated by the compiler on an as-needed basis. When a module is imported (e.g., by an ``#include`` of one of the module's headers), the compiler will spawn a second instance of itself [#]_, with a fresh preprocessing context [#]_, to parse just the headers in that module. The resulting Abstract Syntax Tree (AST) is then persisted into the binary representation of the module that is then loaded into translation unit where the module import was encountered. 172e5dd7070Spatrick 173e5dd7070SpatrickThe binary representation of modules is persisted in the *module cache*. Imports of a module will first query the module cache and, if a binary representation of the required module is already available, will load that representation directly. Thus, a module's headers will only be parsed once per language configuration, rather than once per translation unit that uses the module. 174e5dd7070Spatrick 175e5dd7070SpatrickModules maintain references to each of the headers that were part of the module build. If any of those headers changes, or if any of the modules on which a module depends change, then the module will be (automatically) recompiled. The process should never require any user intervention. 176e5dd7070Spatrick 177e5dd7070SpatrickCommand-line parameters 178e5dd7070Spatrick----------------------- 179e5dd7070Spatrick``-fmodules`` 180e5dd7070Spatrick Enable the modules feature. 181e5dd7070Spatrick 182e5dd7070Spatrick``-fbuiltin-module-map`` 183e5dd7070Spatrick Load the Clang builtins module map file. (Equivalent to ``-fmodule-map-file=<resource dir>/include/module.modulemap``) 184e5dd7070Spatrick 185e5dd7070Spatrick``-fimplicit-module-maps`` 186e5dd7070Spatrick Enable implicit search for module map files named ``module.modulemap`` and similar. This option is implied by ``-fmodules``. If this is disabled with ``-fno-implicit-module-maps``, module map files will only be loaded if they are explicitly specified via ``-fmodule-map-file`` or transitively used by another module map file. 187e5dd7070Spatrick 188e5dd7070Spatrick``-fmodules-cache-path=<directory>`` 189e5dd7070Spatrick Specify the path to the modules cache. If not provided, Clang will select a system-appropriate default. 190e5dd7070Spatrick 191e5dd7070Spatrick``-fno-autolink`` 192e5dd7070Spatrick Disable automatic linking against the libraries associated with imported modules. 193e5dd7070Spatrick 194e5dd7070Spatrick``-fmodules-ignore-macro=macroname`` 195e5dd7070Spatrick Instruct modules to ignore the named macro when selecting an appropriate module variant. Use this for macros defined on the command line that don't affect how modules are built, to improve sharing of compiled module files. 196e5dd7070Spatrick 197e5dd7070Spatrick``-fmodules-prune-interval=seconds`` 198e5dd7070Spatrick Specify the minimum delay (in seconds) between attempts to prune the module cache. Module cache pruning attempts to clear out old, unused module files so that the module cache itself does not grow without bound. The default delay is large (604,800 seconds, or 7 days) because this is an expensive operation. Set this value to 0 to turn off pruning. 199e5dd7070Spatrick 200e5dd7070Spatrick``-fmodules-prune-after=seconds`` 201e5dd7070Spatrick Specify the minimum time (in seconds) for which a file in the module cache must be unused (according to access time) before module pruning will remove it. The default delay is large (2,678,400 seconds, or 31 days) to avoid excessive module rebuilding. 202e5dd7070Spatrick 203e5dd7070Spatrick``-module-file-info <module file name>`` 204e5dd7070Spatrick Debugging aid that prints information about a given module file (with a ``.pcm`` extension), including the language and preprocessor options that particular module variant was built with. 205e5dd7070Spatrick 206e5dd7070Spatrick``-fmodules-decluse`` 207e5dd7070Spatrick Enable checking of module ``use`` declarations. 208e5dd7070Spatrick 209e5dd7070Spatrick``-fmodule-name=module-id`` 210e5dd7070Spatrick Consider a source file as a part of the given module. 211e5dd7070Spatrick 212e5dd7070Spatrick``-fmodule-map-file=<file>`` 213e5dd7070Spatrick Load the given module map file if a header from its directory or one of its subdirectories is loaded. 214e5dd7070Spatrick 215e5dd7070Spatrick``-fmodules-search-all`` 216e5dd7070Spatrick If a symbol is not found, search modules referenced in the current module maps but not imported for symbols, so the error message can reference the module by name. Note that if the global module index has not been built before, this might take some time as it needs to build all the modules. Note that this option doesn't apply in module builds, to avoid the recursion. 217e5dd7070Spatrick 218e5dd7070Spatrick``-fno-implicit-modules`` 219e5dd7070Spatrick All modules used by the build must be specified with ``-fmodule-file``. 220e5dd7070Spatrick 221e5dd7070Spatrick``-fmodule-file=[<name>=]<file>`` 222e5dd7070Spatrick Specify the mapping of module names to precompiled module files. If the 223e5dd7070Spatrick name is omitted, then the module file is loaded whether actually required 224e5dd7070Spatrick or not. If the name is specified, then the mapping is treated as another 225e5dd7070Spatrick prebuilt module search mechanism (in addition to ``-fprebuilt-module-path``) 226e5dd7070Spatrick and the module is only loaded if required. Note that in this case the 227e5dd7070Spatrick specified file also overrides this module's paths that might be embedded 228e5dd7070Spatrick in other precompiled module files. 229e5dd7070Spatrick 230e5dd7070Spatrick``-fprebuilt-module-path=<directory>`` 231e5dd7070Spatrick Specify the path to the prebuilt modules. If specified, we will look for modules in this directory for a given top-level module name. We don't need a module map for loading prebuilt modules in this directory and the compiler will not try to rebuild these modules. This can be specified multiple times. 232e5dd7070Spatrick 233a9ac8606Spatrick``-fprebuilt-implicit-modules`` 234a9ac8606Spatrick Enable prebuilt implicit modules. If a prebuilt module is not found in the 235a9ac8606Spatrick prebuilt modules paths (specified via ``-fprebuilt-module-path``), we will 236a9ac8606Spatrick look for a matching implicit module in the prebuilt modules paths. 237a9ac8606Spatrick 238e5dd7070Spatrick-cc1 Options 239e5dd7070Spatrick~~~~~~~~~~~~ 240e5dd7070Spatrick 241e5dd7070Spatrick``-fmodules-strict-context-hash`` 242e5dd7070Spatrick Enables hashing of all compiler options that could impact the semantics of a 243e5dd7070Spatrick module in an implicit build. This includes things such as header search paths 244e5dd7070Spatrick and diagnostics. Using this option may lead to an excessive number of modules 245e5dd7070Spatrick being built if the command line arguments are not homogeneous across your 246e5dd7070Spatrick build. 247e5dd7070Spatrick 248a9ac8606SpatrickUsing Prebuilt Modules 249a9ac8606Spatrick---------------------- 250a9ac8606Spatrick 251a9ac8606SpatrickBelow are a few examples illustrating uses of prebuilt modules via the different options. 252a9ac8606Spatrick 253a9ac8606SpatrickFirst, let's set up files for our examples. 254a9ac8606Spatrick 255a9ac8606Spatrick.. code-block:: c 256a9ac8606Spatrick 257a9ac8606Spatrick /* A.h */ 258a9ac8606Spatrick #ifdef ENABLE_A 259a9ac8606Spatrick void a() {} 260a9ac8606Spatrick #endif 261a9ac8606Spatrick 262a9ac8606Spatrick.. code-block:: c 263a9ac8606Spatrick 264a9ac8606Spatrick /* B.h */ 265a9ac8606Spatrick #include "A.h" 266a9ac8606Spatrick 267a9ac8606Spatrick.. code-block:: c 268a9ac8606Spatrick 269a9ac8606Spatrick /* use.c */ 270a9ac8606Spatrick #include "B.h" 271a9ac8606Spatrick void use() { 272a9ac8606Spatrick #ifdef ENABLE_A 273a9ac8606Spatrick a(); 274a9ac8606Spatrick #endif 275a9ac8606Spatrick } 276a9ac8606Spatrick 277a9ac8606Spatrick.. code-block:: c 278a9ac8606Spatrick 279a9ac8606Spatrick /* module.modulemap */ 280a9ac8606Spatrick module A { 281a9ac8606Spatrick header "A.h" 282a9ac8606Spatrick } 283a9ac8606Spatrick module B { 284a9ac8606Spatrick header "B.h" 285a9ac8606Spatrick export * 286a9ac8606Spatrick } 287a9ac8606Spatrick 288a9ac8606SpatrickIn the examples below, the compilation of ``use.c`` can be done without ``-cc1``, but the commands used to prebuild the modules would need to be updated to take into account the default options passed to ``clang -cc1``. (See ``clang use.c -v``) 289a9ac8606SpatrickNote also that, since we use ``-cc1``, we specify the ``-fmodule-map-file=`` or ``-fimplicit-module-maps`` options explicitly. When using the clang driver, ``-fimplicit-module-maps`` is implied by ``-fmodules``. 290a9ac8606Spatrick 291a9ac8606SpatrickFirst let us use an explicit mapping from modules to files. 292a9ac8606Spatrick 293a9ac8606Spatrick.. code-block:: sh 294a9ac8606Spatrick 295a9ac8606Spatrick rm -rf prebuilt ; mkdir prebuilt 296a9ac8606Spatrick clang -cc1 -emit-module -o prebuilt/A.pcm -fmodules module.modulemap -fmodule-name=A 297a9ac8606Spatrick clang -cc1 -emit-module -o prebuilt/B.pcm -fmodules module.modulemap -fmodule-name=B -fmodule-file=A=prebuilt/A.pcm 298a9ac8606Spatrick clang -cc1 -emit-obj use.c -fmodules -fmodule-map-file=module.modulemap -fmodule-file=A=prebuilt/A.pcm -fmodule-file=B=prebuilt/B.pcm 299a9ac8606Spatrick 300a9ac8606SpatrickInstead of of specifying the mappings manually, it can be convenient to use the ``-fprebuilt-module-path`` option. Let's also use ``-fimplicit-module-maps`` instead of manually pointing to our module map. 301a9ac8606Spatrick 302a9ac8606Spatrick.. code-block:: sh 303a9ac8606Spatrick 304a9ac8606Spatrick rm -rf prebuilt; mkdir prebuilt 305a9ac8606Spatrick clang -cc1 -emit-module -o prebuilt/A.pcm -fmodules module.modulemap -fmodule-name=A 306a9ac8606Spatrick clang -cc1 -emit-module -o prebuilt/B.pcm -fmodules module.modulemap -fmodule-name=B -fprebuilt-module-path=prebuilt 307a9ac8606Spatrick clang -cc1 -emit-obj use.c -fmodules -fimplicit-module-maps -fprebuilt-module-path=prebuilt 308a9ac8606Spatrick 309a9ac8606SpatrickA trick to prebuild all modules required for our source file in one command is to generate implicit modules while using the ``-fdisable-module-hash`` option. 310a9ac8606Spatrick 311a9ac8606Spatrick.. code-block:: sh 312a9ac8606Spatrick 313a9ac8606Spatrick rm -rf prebuilt ; mkdir prebuilt 314a9ac8606Spatrick clang -cc1 -emit-obj use.c -fmodules -fimplicit-module-maps -fmodules-cache-path=prebuilt -fdisable-module-hash 315a9ac8606Spatrick ls prebuilt/*.pcm 316a9ac8606Spatrick # prebuilt/A.pcm prebuilt/B.pcm 317a9ac8606Spatrick 318a9ac8606SpatrickNote that with explicit or prebuilt modules, we are responsible for, and should be particularly careful about the compatibility of our modules. 319a9ac8606SpatrickUsing mismatching compilation options and modules may lead to issues. 320a9ac8606Spatrick 321a9ac8606Spatrick.. code-block:: sh 322a9ac8606Spatrick 323a9ac8606Spatrick clang -cc1 -emit-obj use.c -fmodules -fimplicit-module-maps -fprebuilt-module-path=prebuilt -DENABLE_A 324a9ac8606Spatrick # use.c:4:10: warning: implicit declaration of function 'a' is invalid in C99 [-Wimplicit-function-declaration] 325a9ac8606Spatrick # return a(x); 326a9ac8606Spatrick # ^ 327a9ac8606Spatrick # 1 warning generated. 328a9ac8606Spatrick 329a9ac8606SpatrickSo we need to maintain multiple versions of prebuilt modules. We can do so using a manual module mapping, or pointing to a different prebuilt module cache path. For example: 330a9ac8606Spatrick 331a9ac8606Spatrick.. code-block:: sh 332a9ac8606Spatrick 333a9ac8606Spatrick rm -rf prebuilt ; mkdir prebuilt ; rm -rf prebuilt_a ; mkdir prebuilt_a 334a9ac8606Spatrick clang -cc1 -emit-obj use.c -fmodules -fimplicit-module-maps -fmodules-cache-path=prebuilt -fdisable-module-hash 335a9ac8606Spatrick clang -cc1 -emit-obj use.c -fmodules -fimplicit-module-maps -fmodules-cache-path=prebuilt_a -fdisable-module-hash -DENABLE_A 336a9ac8606Spatrick clang -cc1 -emit-obj use.c -fmodules -fimplicit-module-maps -fprebuilt-module-path=prebuilt 337a9ac8606Spatrick clang -cc1 -emit-obj use.c -fmodules -fimplicit-module-maps -fprebuilt-module-path=prebuilt_a -DENABLE_A 338a9ac8606Spatrick 339a9ac8606Spatrick 340a9ac8606SpatrickInstead of managing the different module versions manually, we can build implicit modules in a given cache path (using ``-fmodules-cache-path``), and reuse them as prebuilt implicit modules by passing ``-fprebuilt-module-path`` and ``-fprebuilt-implicit-modules``. 341a9ac8606Spatrick 342a9ac8606Spatrick.. code-block:: sh 343a9ac8606Spatrick 344a9ac8606Spatrick rm -rf prebuilt; mkdir prebuilt 345a9ac8606Spatrick clang -cc1 -emit-obj -o use.o use.c -fmodules -fimplicit-module-maps -fmodules-cache-path=prebuilt 346a9ac8606Spatrick clang -cc1 -emit-obj -o use.o use.c -fmodules -fimplicit-module-maps -fmodules-cache-path=prebuilt -DENABLE_A 347a9ac8606Spatrick find prebuilt -name "*.pcm" 348a9ac8606Spatrick # prebuilt/1AYBIGPM8R2GA/A-3L1K4LUA6O31.pcm 349a9ac8606Spatrick # prebuilt/1AYBIGPM8R2GA/B-3L1K4LUA6O31.pcm 350a9ac8606Spatrick # prebuilt/VH0YZMF1OIRK/A-3L1K4LUA6O31.pcm 351a9ac8606Spatrick # prebuilt/VH0YZMF1OIRK/B-3L1K4LUA6O31.pcm 352a9ac8606Spatrick clang -cc1 -emit-obj -o use.o use.c -fmodules -fimplicit-module-maps -fprebuilt-module-path=prebuilt -fprebuilt-implicit-modules 353a9ac8606Spatrick clang -cc1 -emit-obj -o use.o use.c -fmodules -fimplicit-module-maps -fprebuilt-module-path=prebuilt -fprebuilt-implicit-modules -DENABLE_A 354a9ac8606Spatrick 355a9ac8606SpatrickFinally we want to allow implicit modules for configurations that were not prebuilt. When using the clang driver a module cache path is implicitly selected. Using ``-cc1``, we simply add use the ``-fmodules-cache-path`` option. 356a9ac8606Spatrick 357a9ac8606Spatrick.. code-block:: sh 358a9ac8606Spatrick 359a9ac8606Spatrick clang -cc1 -emit-obj -o use.o use.c -fmodules -fimplicit-module-maps -fprebuilt-module-path=prebuilt -fprebuilt-implicit-modules -fmodules-cache-path=cache 360a9ac8606Spatrick clang -cc1 -emit-obj -o use.o use.c -fmodules -fimplicit-module-maps -fprebuilt-module-path=prebuilt -fprebuilt-implicit-modules -fmodules-cache-path=cache -DENABLE_A 361a9ac8606Spatrick clang -cc1 -emit-obj -o use.o use.c -fmodules -fimplicit-module-maps -fprebuilt-module-path=prebuilt -fprebuilt-implicit-modules -fmodules-cache-path=cache -DENABLE_A -DOTHER_OPTIONS 362a9ac8606Spatrick 363a9ac8606SpatrickThis way, a single directory containing multiple variants of modules can be prepared and reused. The options configuring the module cache are independent of other options. 364a9ac8606Spatrick 365e5dd7070SpatrickModule Semantics 366e5dd7070Spatrick================ 367e5dd7070Spatrick 368e5dd7070SpatrickModules are modeled as if each submodule were a separate translation unit, and a module import makes names from the other translation unit visible. Each submodule starts with a new preprocessor state and an empty translation unit. 369e5dd7070Spatrick 370e5dd7070Spatrick.. note:: 371e5dd7070Spatrick 372e5dd7070Spatrick This behavior is currently only approximated when building a module with submodules. Entities within a submodule that has already been built are visible when building later submodules in that module. This can lead to fragile modules that depend on the build order used for the submodules of the module, and should not be relied upon. This behavior is subject to change. 373e5dd7070Spatrick 374e5dd7070SpatrickAs an example, in C, this implies that if two structs are defined in different submodules with the same name, those two types are distinct types (but may be *compatible* types if their definitions match). In C++, two structs defined with the same name in different submodules are the *same* type, and must be equivalent under C++'s One Definition Rule. 375e5dd7070Spatrick 376e5dd7070Spatrick.. note:: 377e5dd7070Spatrick 378e5dd7070Spatrick Clang currently only performs minimal checking for violations of the One Definition Rule. 379e5dd7070Spatrick 380e5dd7070SpatrickIf any submodule of a module is imported into any part of a program, the entire top-level module is considered to be part of the program. As a consequence of this, Clang may diagnose conflicts between an entity declared in an unimported submodule and an entity declared in the current translation unit, and Clang may inline or devirtualize based on knowledge from unimported submodules. 381e5dd7070Spatrick 382e5dd7070SpatrickMacros 383e5dd7070Spatrick------ 384e5dd7070Spatrick 385e5dd7070SpatrickThe C and C++ preprocessor assumes that the input text is a single linear buffer, but with modules this is not the case. It is possible to import two modules that have conflicting definitions for a macro (or where one ``#define``\s a macro and the other ``#undef``\ines it). The rules for handling macro definitions in the presence of modules are as follows: 386e5dd7070Spatrick 387e5dd7070Spatrick* Each definition and undefinition of a macro is considered to be a distinct entity. 388e5dd7070Spatrick* Such entities are *visible* if they are from the current submodule or translation unit, or if they were exported from a submodule that has been imported. 389e5dd7070Spatrick* A ``#define X`` or ``#undef X`` directive *overrides* all definitions of ``X`` that are visible at the point of the directive. 390e5dd7070Spatrick* A ``#define`` or ``#undef`` directive is *active* if it is visible and no visible directive overrides it. 391e5dd7070Spatrick* A set of macro directives is *consistent* if it consists of only ``#undef`` directives, or if all ``#define`` directives in the set define the macro name to the same sequence of tokens (following the usual rules for macro redefinitions). 392e5dd7070Spatrick* If a macro name is used and the set of active directives is not consistent, the program is ill-formed. Otherwise, the (unique) meaning of the macro name is used. 393e5dd7070Spatrick 394e5dd7070SpatrickFor example, suppose: 395e5dd7070Spatrick 396e5dd7070Spatrick* ``<stdio.h>`` defines a macro ``getc`` (and exports its ``#define``) 397e5dd7070Spatrick* ``<cstdio>`` imports the ``<stdio.h>`` module and undefines the macro (and exports its ``#undef``) 398e5dd7070Spatrick 399e5dd7070SpatrickThe ``#undef`` overrides the ``#define``, and a source file that imports both modules *in any order* will not see ``getc`` defined as a macro. 400e5dd7070Spatrick 401e5dd7070SpatrickModule Map Language 402e5dd7070Spatrick=================== 403e5dd7070Spatrick 404e5dd7070Spatrick.. warning:: 405e5dd7070Spatrick 406e5dd7070Spatrick The module map language is not currently guaranteed to be stable between major revisions of Clang. 407e5dd7070Spatrick 408e5dd7070SpatrickThe module map language describes the mapping from header files to the 409e5dd7070Spatricklogical structure of modules. To enable support for using a library as 410e5dd7070Spatricka module, one must write a ``module.modulemap`` file for that library. The 411e5dd7070Spatrick``module.modulemap`` file is placed alongside the header files themselves, 412e5dd7070Spatrickand is written in the module map language described below. 413e5dd7070Spatrick 414e5dd7070Spatrick.. note:: 415e5dd7070Spatrick For compatibility with previous releases, if a module map file named 416e5dd7070Spatrick ``module.modulemap`` is not found, Clang will also search for a file named 417e5dd7070Spatrick ``module.map``. This behavior is deprecated and we plan to eventually 418e5dd7070Spatrick remove it. 419e5dd7070Spatrick 420e5dd7070SpatrickAs an example, the module map file for the C standard library might look a bit like this: 421e5dd7070Spatrick 422e5dd7070Spatrick.. parsed-literal:: 423e5dd7070Spatrick 424e5dd7070Spatrick module std [system] [extern_c] { 425e5dd7070Spatrick module assert { 426e5dd7070Spatrick textual header "assert.h" 427e5dd7070Spatrick header "bits/assert-decls.h" 428e5dd7070Spatrick export * 429e5dd7070Spatrick } 430e5dd7070Spatrick 431e5dd7070Spatrick module complex { 432e5dd7070Spatrick header "complex.h" 433e5dd7070Spatrick export * 434e5dd7070Spatrick } 435e5dd7070Spatrick 436e5dd7070Spatrick module ctype { 437e5dd7070Spatrick header "ctype.h" 438e5dd7070Spatrick export * 439e5dd7070Spatrick } 440e5dd7070Spatrick 441e5dd7070Spatrick module errno { 442e5dd7070Spatrick header "errno.h" 443e5dd7070Spatrick header "sys/errno.h" 444e5dd7070Spatrick export * 445e5dd7070Spatrick } 446e5dd7070Spatrick 447e5dd7070Spatrick module fenv { 448e5dd7070Spatrick header "fenv.h" 449e5dd7070Spatrick export * 450e5dd7070Spatrick } 451e5dd7070Spatrick 452e5dd7070Spatrick // ...more headers follow... 453e5dd7070Spatrick } 454e5dd7070Spatrick 455e5dd7070SpatrickHere, the top-level module ``std`` encompasses the whole C standard library. It has a number of submodules containing different parts of the standard library: ``complex`` for complex numbers, ``ctype`` for character types, etc. Each submodule lists one of more headers that provide the contents for that submodule. Finally, the ``export *`` command specifies that anything included by that submodule will be automatically re-exported. 456e5dd7070Spatrick 457e5dd7070SpatrickLexical structure 458e5dd7070Spatrick----------------- 459e5dd7070SpatrickModule map files use a simplified form of the C99 lexer, with the same rules for identifiers, tokens, string literals, ``/* */`` and ``//`` comments. The module map language has the following reserved words; all other C identifiers are valid identifiers. 460e5dd7070Spatrick 461e5dd7070Spatrick.. parsed-literal:: 462e5dd7070Spatrick 463e5dd7070Spatrick ``config_macros`` ``export_as`` ``private`` 464e5dd7070Spatrick ``conflict`` ``framework`` ``requires`` 465e5dd7070Spatrick ``exclude`` ``header`` ``textual`` 466e5dd7070Spatrick ``explicit`` ``link`` ``umbrella`` 467e5dd7070Spatrick ``extern`` ``module`` ``use`` 468e5dd7070Spatrick ``export`` 469e5dd7070Spatrick 470e5dd7070SpatrickModule map file 471e5dd7070Spatrick--------------- 472e5dd7070SpatrickA module map file consists of a series of module declarations: 473e5dd7070Spatrick 474e5dd7070Spatrick.. parsed-literal:: 475e5dd7070Spatrick 476e5dd7070Spatrick *module-map-file*: 477e5dd7070Spatrick *module-declaration** 478e5dd7070Spatrick 479e5dd7070SpatrickWithin a module map file, modules are referred to by a *module-id*, which uses periods to separate each part of a module's name: 480e5dd7070Spatrick 481e5dd7070Spatrick.. parsed-literal:: 482e5dd7070Spatrick 483e5dd7070Spatrick *module-id*: 484e5dd7070Spatrick *identifier* ('.' *identifier*)* 485e5dd7070Spatrick 486e5dd7070SpatrickModule declaration 487e5dd7070Spatrick------------------ 488e5dd7070SpatrickA module declaration describes a module, including the headers that contribute to that module, its submodules, and other aspects of the module. 489e5dd7070Spatrick 490e5dd7070Spatrick.. parsed-literal:: 491e5dd7070Spatrick 492e5dd7070Spatrick *module-declaration*: 493e5dd7070Spatrick ``explicit``:sub:`opt` ``framework``:sub:`opt` ``module`` *module-id* *attributes*:sub:`opt` '{' *module-member** '}' 494e5dd7070Spatrick ``extern`` ``module`` *module-id* *string-literal* 495e5dd7070Spatrick 496e5dd7070SpatrickThe *module-id* should consist of only a single *identifier*, which provides the name of the module being defined. Each module shall have a single definition. 497e5dd7070Spatrick 498e5dd7070SpatrickThe ``explicit`` qualifier can only be applied to a submodule, i.e., a module that is nested within another module. The contents of explicit submodules are only made available when the submodule itself was explicitly named in an import declaration or was re-exported from an imported module. 499e5dd7070Spatrick 500e5dd7070SpatrickThe ``framework`` qualifier specifies that this module corresponds to a Darwin-style framework. A Darwin-style framework (used primarily on macOS and iOS) is contained entirely in directory ``Name.framework``, where ``Name`` is the name of the framework (and, therefore, the name of the module). That directory has the following layout: 501e5dd7070Spatrick 502e5dd7070Spatrick.. parsed-literal:: 503e5dd7070Spatrick 504e5dd7070Spatrick Name.framework/ 505e5dd7070Spatrick Modules/module.modulemap Module map for the framework 506e5dd7070Spatrick Headers/ Subdirectory containing framework headers 507e5dd7070Spatrick PrivateHeaders/ Subdirectory containing framework private headers 508e5dd7070Spatrick Frameworks/ Subdirectory containing embedded frameworks 509e5dd7070Spatrick Resources/ Subdirectory containing additional resources 510e5dd7070Spatrick Name Symbolic link to the shared library for the framework 511e5dd7070Spatrick 512e5dd7070SpatrickThe ``system`` attribute specifies that the module is a system module. When a system module is rebuilt, all of the module's headers will be considered system headers, which suppresses warnings. This is equivalent to placing ``#pragma GCC system_header`` in each of the module's headers. The form of attributes is described in the section Attributes_, below. 513e5dd7070Spatrick 514e5dd7070SpatrickThe ``extern_c`` attribute specifies that the module contains C code that can be used from within C++. When such a module is built for use in C++ code, all of the module's headers will be treated as if they were contained within an implicit ``extern "C"`` block. An import for a module with this attribute can appear within an ``extern "C"`` block. No other restrictions are lifted, however: the module currently cannot be imported within an ``extern "C"`` block in a namespace. 515e5dd7070Spatrick 516e5dd7070SpatrickThe ``no_undeclared_includes`` attribute specifies that the module can only reach non-modular headers and headers from used modules. Since some headers could be present in more than one search path and map to different modules in each path, this mechanism helps clang to find the right header, i.e., prefer the one for the current module or in a submodule instead of the first usual match in the search paths. 517e5dd7070Spatrick 518e5dd7070SpatrickModules can have a number of different kinds of members, each of which is described below: 519e5dd7070Spatrick 520e5dd7070Spatrick.. parsed-literal:: 521e5dd7070Spatrick 522e5dd7070Spatrick *module-member*: 523e5dd7070Spatrick *requires-declaration* 524e5dd7070Spatrick *header-declaration* 525e5dd7070Spatrick *umbrella-dir-declaration* 526e5dd7070Spatrick *submodule-declaration* 527e5dd7070Spatrick *export-declaration* 528e5dd7070Spatrick *export-as-declaration* 529e5dd7070Spatrick *use-declaration* 530e5dd7070Spatrick *link-declaration* 531e5dd7070Spatrick *config-macros-declaration* 532e5dd7070Spatrick *conflict-declaration* 533e5dd7070Spatrick 534e5dd7070SpatrickAn extern module references a module defined by the *module-id* in a file given by the *string-literal*. The file can be referenced either by an absolute path or by a path relative to the current map file. 535e5dd7070Spatrick 536e5dd7070SpatrickRequires declaration 537e5dd7070Spatrick~~~~~~~~~~~~~~~~~~~~ 538e5dd7070SpatrickA *requires-declaration* specifies the requirements that an importing translation unit must satisfy to use the module. 539e5dd7070Spatrick 540e5dd7070Spatrick.. parsed-literal:: 541e5dd7070Spatrick 542e5dd7070Spatrick *requires-declaration*: 543e5dd7070Spatrick ``requires`` *feature-list* 544e5dd7070Spatrick 545e5dd7070Spatrick *feature-list*: 546e5dd7070Spatrick *feature* (',' *feature*)* 547e5dd7070Spatrick 548e5dd7070Spatrick *feature*: 549e5dd7070Spatrick ``!``:sub:`opt` *identifier* 550e5dd7070Spatrick 551e5dd7070SpatrickThe requirements clause allows specific modules or submodules to specify that they are only accessible with certain language dialects, platforms, environments and target specific features. The feature list is a set of identifiers, defined below. If any of the features is not available in a given translation unit, that translation unit shall not import the module. When building a module for use by a compilation, submodules requiring unavailable features are ignored. The optional ``!`` indicates that a feature is incompatible with the module. 552e5dd7070Spatrick 553e5dd7070SpatrickThe following features are defined: 554e5dd7070Spatrick 555e5dd7070Spatrickaltivec 556e5dd7070Spatrick The target supports AltiVec. 557e5dd7070Spatrick 558e5dd7070Spatrickblocks 559e5dd7070Spatrick The "blocks" language feature is available. 560e5dd7070Spatrick 561e5dd7070Spatrickcoroutines 562e5dd7070Spatrick Support for the coroutines TS is available. 563e5dd7070Spatrick 564e5dd7070Spatrickcplusplus 565e5dd7070Spatrick C++ support is available. 566e5dd7070Spatrick 567e5dd7070Spatrickcplusplus11 568e5dd7070Spatrick C++11 support is available. 569e5dd7070Spatrick 570e5dd7070Spatrickcplusplus14 571e5dd7070Spatrick C++14 support is available. 572e5dd7070Spatrick 573e5dd7070Spatrickcplusplus17 574e5dd7070Spatrick C++17 support is available. 575e5dd7070Spatrick 576e5dd7070Spatrickc99 577e5dd7070Spatrick C99 support is available. 578e5dd7070Spatrick 579e5dd7070Spatrickc11 580e5dd7070Spatrick C11 support is available. 581e5dd7070Spatrick 582e5dd7070Spatrickc17 583e5dd7070Spatrick C17 support is available. 584e5dd7070Spatrick 585e5dd7070Spatrickfreestanding 586e5dd7070Spatrick A freestanding environment is available. 587e5dd7070Spatrick 588e5dd7070Spatrickgnuinlineasm 589e5dd7070Spatrick GNU inline ASM is available. 590e5dd7070Spatrick 591e5dd7070Spatrickobjc 592e5dd7070Spatrick Objective-C support is available. 593e5dd7070Spatrick 594e5dd7070Spatrickobjc_arc 595e5dd7070Spatrick Objective-C Automatic Reference Counting (ARC) is available 596e5dd7070Spatrick 597e5dd7070Spatrickopencl 598e5dd7070Spatrick OpenCL is available 599e5dd7070Spatrick 600e5dd7070Spatricktls 601e5dd7070Spatrick Thread local storage is available. 602e5dd7070Spatrick 603e5dd7070Spatrick*target feature* 604e5dd7070Spatrick A specific target feature (e.g., ``sse4``, ``avx``, ``neon``) is available. 605e5dd7070Spatrick 606e5dd7070Spatrick*platform/os* 607e5dd7070Spatrick A os/platform variant (e.g. ``freebsd``, ``win32``, ``windows``, ``linux``, ``ios``, ``macos``, ``iossimulator``) is available. 608e5dd7070Spatrick 609e5dd7070Spatrick*environment* 610e5dd7070Spatrick A environment variant (e.g. ``gnu``, ``gnueabi``, ``android``, ``msvc``) is available. 611e5dd7070Spatrick 612e5dd7070Spatrick**Example:** The ``std`` module can be extended to also include C++ and C++11 headers using a *requires-declaration*: 613e5dd7070Spatrick 614e5dd7070Spatrick.. parsed-literal:: 615e5dd7070Spatrick 616e5dd7070Spatrick module std { 617e5dd7070Spatrick // C standard library... 618e5dd7070Spatrick 619e5dd7070Spatrick module vector { 620e5dd7070Spatrick requires cplusplus 621e5dd7070Spatrick header "vector" 622e5dd7070Spatrick } 623e5dd7070Spatrick 624e5dd7070Spatrick module type_traits { 625e5dd7070Spatrick requires cplusplus11 626e5dd7070Spatrick header "type_traits" 627e5dd7070Spatrick } 628e5dd7070Spatrick } 629e5dd7070Spatrick 630e5dd7070SpatrickHeader declaration 631e5dd7070Spatrick~~~~~~~~~~~~~~~~~~ 632e5dd7070SpatrickA header declaration specifies that a particular header is associated with the enclosing module. 633e5dd7070Spatrick 634e5dd7070Spatrick.. parsed-literal:: 635e5dd7070Spatrick 636e5dd7070Spatrick *header-declaration*: 637e5dd7070Spatrick ``private``:sub:`opt` ``textual``:sub:`opt` ``header`` *string-literal* *header-attrs*:sub:`opt` 638e5dd7070Spatrick ``umbrella`` ``header`` *string-literal* *header-attrs*:sub:`opt` 639e5dd7070Spatrick ``exclude`` ``header`` *string-literal* *header-attrs*:sub:`opt` 640e5dd7070Spatrick 641e5dd7070Spatrick *header-attrs*: 642e5dd7070Spatrick '{' *header-attr** '}' 643e5dd7070Spatrick 644e5dd7070Spatrick *header-attr*: 645e5dd7070Spatrick ``size`` *integer-literal* 646e5dd7070Spatrick ``mtime`` *integer-literal* 647e5dd7070Spatrick 648e5dd7070SpatrickA header declaration that does not contain ``exclude`` nor ``textual`` specifies a header that contributes to the enclosing module. Specifically, when the module is built, the named header will be parsed and its declarations will be (logically) placed into the enclosing submodule. 649e5dd7070Spatrick 650e5dd7070SpatrickA header with the ``umbrella`` specifier is called an umbrella header. An umbrella header includes all of the headers within its directory (and any subdirectories), and is typically used (in the ``#include`` world) to easily access the full API provided by a particular library. With modules, an umbrella header is a convenient shortcut that eliminates the need to write out ``header`` declarations for every library header. A given directory can only contain a single umbrella header. 651e5dd7070Spatrick 652e5dd7070Spatrick.. note:: 653e5dd7070Spatrick Any headers not included by the umbrella header should have 654e5dd7070Spatrick explicit ``header`` declarations. Use the 655e5dd7070Spatrick ``-Wincomplete-umbrella`` warning option to ask Clang to complain 656e5dd7070Spatrick about headers not covered by the umbrella header or the module map. 657e5dd7070Spatrick 658e5dd7070SpatrickA header with the ``private`` specifier may not be included from outside the module itself. 659e5dd7070Spatrick 660e5dd7070SpatrickA header with the ``textual`` specifier will not be compiled when the module is 661e5dd7070Spatrickbuilt, and will be textually included if it is named by a ``#include`` 662e5dd7070Spatrickdirective. However, it is considered to be part of the module for the purpose 663e5dd7070Spatrickof checking *use-declaration*\s, and must still be a lexically-valid header 664e5dd7070Spatrickfile. In the future, we intend to pre-tokenize such headers and include the 665e5dd7070Spatricktoken sequence within the prebuilt module representation. 666e5dd7070Spatrick 667e5dd7070SpatrickA header with the ``exclude`` specifier is excluded from the module. It will not be included when the module is built, nor will it be considered to be part of the module, even if an ``umbrella`` header or directory would otherwise make it part of the module. 668e5dd7070Spatrick 669e5dd7070Spatrick**Example:** The C header ``assert.h`` is an excellent candidate for a textual header, because it is meant to be included multiple times (possibly with different ``NDEBUG`` settings). However, declarations within it should typically be split into a separate modular header. 670e5dd7070Spatrick 671e5dd7070Spatrick.. parsed-literal:: 672e5dd7070Spatrick 673e5dd7070Spatrick module std [system] { 674e5dd7070Spatrick textual header "assert.h" 675e5dd7070Spatrick } 676e5dd7070Spatrick 677e5dd7070SpatrickA given header shall not be referenced by more than one *header-declaration*. 678e5dd7070Spatrick 679e5dd7070SpatrickTwo *header-declaration*\s, or a *header-declaration* and a ``#include``, are 680e5dd7070Spatrickconsidered to refer to the same file if the paths resolve to the same file 681e5dd7070Spatrickand the specified *header-attr*\s (if any) match the attributes of that file, 682e5dd7070Spatrickeven if the file is named differently (for instance, by a relative path or 683e5dd7070Spatrickvia symlinks). 684e5dd7070Spatrick 685e5dd7070Spatrick.. note:: 686e5dd7070Spatrick The use of *header-attr*\s avoids the need for Clang to speculatively 687e5dd7070Spatrick ``stat`` every header referenced by a module map. It is recommended that 688e5dd7070Spatrick *header-attr*\s only be used in machine-generated module maps, to avoid 689e5dd7070Spatrick mismatches between attribute values and the corresponding files. 690e5dd7070Spatrick 691e5dd7070SpatrickUmbrella directory declaration 692e5dd7070Spatrick~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 693e5dd7070SpatrickAn umbrella directory declaration specifies that all of the headers in the specified directory should be included within the module. 694e5dd7070Spatrick 695e5dd7070Spatrick.. parsed-literal:: 696e5dd7070Spatrick 697e5dd7070Spatrick *umbrella-dir-declaration*: 698e5dd7070Spatrick ``umbrella`` *string-literal* 699e5dd7070Spatrick 700e5dd7070SpatrickThe *string-literal* refers to a directory. When the module is built, all of the header files in that directory (and its subdirectories) are included in the module. 701e5dd7070Spatrick 702e5dd7070SpatrickAn *umbrella-dir-declaration* shall not refer to the same directory as the location of an umbrella *header-declaration*. In other words, only a single kind of umbrella can be specified for a given directory. 703e5dd7070Spatrick 704e5dd7070Spatrick.. note:: 705e5dd7070Spatrick 706e5dd7070Spatrick Umbrella directories are useful for libraries that have a large number of headers but do not have an umbrella header. 707e5dd7070Spatrick 708e5dd7070Spatrick 709e5dd7070SpatrickSubmodule declaration 710e5dd7070Spatrick~~~~~~~~~~~~~~~~~~~~~ 711e5dd7070SpatrickSubmodule declarations describe modules that are nested within their enclosing module. 712e5dd7070Spatrick 713e5dd7070Spatrick.. parsed-literal:: 714e5dd7070Spatrick 715e5dd7070Spatrick *submodule-declaration*: 716e5dd7070Spatrick *module-declaration* 717e5dd7070Spatrick *inferred-submodule-declaration* 718e5dd7070Spatrick 719e5dd7070SpatrickA *submodule-declaration* that is a *module-declaration* is a nested module. If the *module-declaration* has a ``framework`` specifier, the enclosing module shall have a ``framework`` specifier; the submodule's contents shall be contained within the subdirectory ``Frameworks/SubName.framework``, where ``SubName`` is the name of the submodule. 720e5dd7070Spatrick 721e5dd7070SpatrickA *submodule-declaration* that is an *inferred-submodule-declaration* describes a set of submodules that correspond to any headers that are part of the module but are not explicitly described by a *header-declaration*. 722e5dd7070Spatrick 723e5dd7070Spatrick.. parsed-literal:: 724e5dd7070Spatrick 725e5dd7070Spatrick *inferred-submodule-declaration*: 726e5dd7070Spatrick ``explicit``:sub:`opt` ``framework``:sub:`opt` ``module`` '*' *attributes*:sub:`opt` '{' *inferred-submodule-member** '}' 727e5dd7070Spatrick 728e5dd7070Spatrick *inferred-submodule-member*: 729e5dd7070Spatrick ``export`` '*' 730e5dd7070Spatrick 731e5dd7070SpatrickA module containing an *inferred-submodule-declaration* shall have either an umbrella header or an umbrella directory. The headers to which the *inferred-submodule-declaration* applies are exactly those headers included by the umbrella header (transitively) or included in the module because they reside within the umbrella directory (or its subdirectories). 732e5dd7070Spatrick 733e5dd7070SpatrickFor each header included by the umbrella header or in the umbrella directory that is not named by a *header-declaration*, a module declaration is implicitly generated from the *inferred-submodule-declaration*. The module will: 734e5dd7070Spatrick 735e5dd7070Spatrick* Have the same name as the header (without the file extension) 736e5dd7070Spatrick* Have the ``explicit`` specifier, if the *inferred-submodule-declaration* has the ``explicit`` specifier 737e5dd7070Spatrick* Have the ``framework`` specifier, if the 738e5dd7070Spatrick *inferred-submodule-declaration* has the ``framework`` specifier 739e5dd7070Spatrick* Have the attributes specified by the \ *inferred-submodule-declaration* 740e5dd7070Spatrick* Contain a single *header-declaration* naming that header 741e5dd7070Spatrick* Contain a single *export-declaration* ``export *``, if the \ *inferred-submodule-declaration* contains the \ *inferred-submodule-member* ``export *`` 742e5dd7070Spatrick 743e5dd7070Spatrick**Example:** If the subdirectory "MyLib" contains the headers ``A.h`` and ``B.h``, then the following module map: 744e5dd7070Spatrick 745e5dd7070Spatrick.. parsed-literal:: 746e5dd7070Spatrick 747e5dd7070Spatrick module MyLib { 748e5dd7070Spatrick umbrella "MyLib" 749e5dd7070Spatrick explicit module * { 750e5dd7070Spatrick export * 751e5dd7070Spatrick } 752e5dd7070Spatrick } 753e5dd7070Spatrick 754e5dd7070Spatrickis equivalent to the (more verbose) module map: 755e5dd7070Spatrick 756e5dd7070Spatrick.. parsed-literal:: 757e5dd7070Spatrick 758e5dd7070Spatrick module MyLib { 759e5dd7070Spatrick explicit module A { 760e5dd7070Spatrick header "A.h" 761e5dd7070Spatrick export * 762e5dd7070Spatrick } 763e5dd7070Spatrick 764e5dd7070Spatrick explicit module B { 765e5dd7070Spatrick header "B.h" 766e5dd7070Spatrick export * 767e5dd7070Spatrick } 768e5dd7070Spatrick } 769e5dd7070Spatrick 770e5dd7070SpatrickExport declaration 771e5dd7070Spatrick~~~~~~~~~~~~~~~~~~ 772e5dd7070SpatrickAn *export-declaration* specifies which imported modules will automatically be re-exported as part of a given module's API. 773e5dd7070Spatrick 774e5dd7070Spatrick.. parsed-literal:: 775e5dd7070Spatrick 776e5dd7070Spatrick *export-declaration*: 777e5dd7070Spatrick ``export`` *wildcard-module-id* 778e5dd7070Spatrick 779e5dd7070Spatrick *wildcard-module-id*: 780e5dd7070Spatrick *identifier* 781e5dd7070Spatrick '*' 782e5dd7070Spatrick *identifier* '.' *wildcard-module-id* 783e5dd7070Spatrick 784e5dd7070SpatrickThe *export-declaration* names a module or a set of modules that will be re-exported to any translation unit that imports the enclosing module. Each imported module that matches the *wildcard-module-id* up to, but not including, the first ``*`` will be re-exported. 785e5dd7070Spatrick 786e5dd7070Spatrick**Example:** In the following example, importing ``MyLib.Derived`` also provides the API for ``MyLib.Base``: 787e5dd7070Spatrick 788e5dd7070Spatrick.. parsed-literal:: 789e5dd7070Spatrick 790e5dd7070Spatrick module MyLib { 791e5dd7070Spatrick module Base { 792e5dd7070Spatrick header "Base.h" 793e5dd7070Spatrick } 794e5dd7070Spatrick 795e5dd7070Spatrick module Derived { 796e5dd7070Spatrick header "Derived.h" 797e5dd7070Spatrick export Base 798e5dd7070Spatrick } 799e5dd7070Spatrick } 800e5dd7070Spatrick 801e5dd7070SpatrickNote that, if ``Derived.h`` includes ``Base.h``, one can simply use a wildcard export to re-export everything ``Derived.h`` includes: 802e5dd7070Spatrick 803e5dd7070Spatrick.. parsed-literal:: 804e5dd7070Spatrick 805e5dd7070Spatrick module MyLib { 806e5dd7070Spatrick module Base { 807e5dd7070Spatrick header "Base.h" 808e5dd7070Spatrick } 809e5dd7070Spatrick 810e5dd7070Spatrick module Derived { 811e5dd7070Spatrick header "Derived.h" 812e5dd7070Spatrick export * 813e5dd7070Spatrick } 814e5dd7070Spatrick } 815e5dd7070Spatrick 816e5dd7070Spatrick.. note:: 817e5dd7070Spatrick 818e5dd7070Spatrick The wildcard export syntax ``export *`` re-exports all of the 819e5dd7070Spatrick modules that were imported in the actual header file. Because 820e5dd7070Spatrick ``#include`` directives are automatically mapped to module imports, 821e5dd7070Spatrick ``export *`` provides the same transitive-inclusion behavior 822e5dd7070Spatrick provided by the C preprocessor, e.g., importing a given module 823e5dd7070Spatrick implicitly imports all of the modules on which it depends. 824e5dd7070Spatrick Therefore, liberal use of ``export *`` provides excellent backward 825e5dd7070Spatrick compatibility for programs that rely on transitive inclusion (i.e., 826e5dd7070Spatrick all of them). 827e5dd7070Spatrick 828e5dd7070SpatrickRe-export Declaration 829e5dd7070Spatrick~~~~~~~~~~~~~~~~~~~~~ 830e5dd7070SpatrickAn *export-as-declaration* specifies that the current module will have 831e5dd7070Spatrickits interface re-exported by the named module. 832e5dd7070Spatrick 833e5dd7070Spatrick.. parsed-literal:: 834e5dd7070Spatrick 835e5dd7070Spatrick *export-as-declaration*: 836e5dd7070Spatrick ``export_as`` *identifier* 837e5dd7070Spatrick 838e5dd7070SpatrickThe *export-as-declaration* names the module that the current 839e5dd7070Spatrickmodule will be re-exported through. Only top-level modules 840e5dd7070Spatrickcan be re-exported, and any given module may only be re-exported 841e5dd7070Spatrickthrough a single module. 842e5dd7070Spatrick 843e5dd7070Spatrick**Example:** In the following example, the module ``MyFrameworkCore`` 844e5dd7070Spatrickwill be re-exported via the module ``MyFramework``: 845e5dd7070Spatrick 846e5dd7070Spatrick.. parsed-literal:: 847e5dd7070Spatrick 848e5dd7070Spatrick module MyFrameworkCore { 849e5dd7070Spatrick export_as MyFramework 850e5dd7070Spatrick } 851e5dd7070Spatrick 852e5dd7070SpatrickUse declaration 853e5dd7070Spatrick~~~~~~~~~~~~~~~ 854e5dd7070SpatrickA *use-declaration* specifies another module that the current top-level module 855e5dd7070Spatrickintends to use. When the option *-fmodules-decluse* is specified, a module can 856e5dd7070Spatrickonly use other modules that are explicitly specified in this way. 857e5dd7070Spatrick 858e5dd7070Spatrick.. parsed-literal:: 859e5dd7070Spatrick 860e5dd7070Spatrick *use-declaration*: 861e5dd7070Spatrick ``use`` *module-id* 862e5dd7070Spatrick 863e5dd7070Spatrick**Example:** In the following example, use of A from C is not declared, so will trigger a warning. 864e5dd7070Spatrick 865e5dd7070Spatrick.. parsed-literal:: 866e5dd7070Spatrick 867e5dd7070Spatrick module A { 868e5dd7070Spatrick header "a.h" 869e5dd7070Spatrick } 870e5dd7070Spatrick 871e5dd7070Spatrick module B { 872e5dd7070Spatrick header "b.h" 873e5dd7070Spatrick } 874e5dd7070Spatrick 875e5dd7070Spatrick module C { 876e5dd7070Spatrick header "c.h" 877e5dd7070Spatrick use B 878e5dd7070Spatrick } 879e5dd7070Spatrick 880e5dd7070SpatrickWhen compiling a source file that implements a module, use the option 881e5dd7070Spatrick``-fmodule-name=module-id`` to indicate that the source file is logically part 882e5dd7070Spatrickof that module. 883e5dd7070Spatrick 884e5dd7070SpatrickThe compiler at present only applies restrictions to the module directly being built. 885e5dd7070Spatrick 886e5dd7070SpatrickLink declaration 887e5dd7070Spatrick~~~~~~~~~~~~~~~~ 888e5dd7070SpatrickA *link-declaration* specifies a library or framework against which a program should be linked if the enclosing module is imported in any translation unit in that program. 889e5dd7070Spatrick 890e5dd7070Spatrick.. parsed-literal:: 891e5dd7070Spatrick 892e5dd7070Spatrick *link-declaration*: 893e5dd7070Spatrick ``link`` ``framework``:sub:`opt` *string-literal* 894e5dd7070Spatrick 895e5dd7070SpatrickThe *string-literal* specifies the name of the library or framework against which the program should be linked. For example, specifying "clangBasic" would instruct the linker to link with ``-lclangBasic`` for a Unix-style linker. 896e5dd7070Spatrick 897e5dd7070SpatrickA *link-declaration* with the ``framework`` specifies that the linker should link against the named framework, e.g., with ``-framework MyFramework``. 898e5dd7070Spatrick 899e5dd7070Spatrick.. note:: 900e5dd7070Spatrick 901e5dd7070Spatrick Automatic linking with the ``link`` directive is not yet widely 902e5dd7070Spatrick implemented, because it requires support from both the object file 903e5dd7070Spatrick format and the linker. The notion is similar to Microsoft Visual 904e5dd7070Spatrick Studio's ``#pragma comment(lib...)``. 905e5dd7070Spatrick 906e5dd7070SpatrickConfiguration macros declaration 907e5dd7070Spatrick~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 908e5dd7070SpatrickThe *config-macros-declaration* specifies the set of configuration macros that have an effect on the API of the enclosing module. 909e5dd7070Spatrick 910e5dd7070Spatrick.. parsed-literal:: 911e5dd7070Spatrick 912e5dd7070Spatrick *config-macros-declaration*: 913e5dd7070Spatrick ``config_macros`` *attributes*:sub:`opt` *config-macro-list*:sub:`opt` 914e5dd7070Spatrick 915e5dd7070Spatrick *config-macro-list*: 916e5dd7070Spatrick *identifier* (',' *identifier*)* 917e5dd7070Spatrick 918e5dd7070SpatrickEach *identifier* in the *config-macro-list* specifies the name of a macro. The compiler is required to maintain different variants of the given module for differing definitions of any of the named macros. 919e5dd7070Spatrick 920e5dd7070SpatrickA *config-macros-declaration* shall only be present on a top-level module, i.e., a module that is not nested within an enclosing module. 921e5dd7070Spatrick 922e5dd7070SpatrickThe ``exhaustive`` attribute specifies that the list of macros in the *config-macros-declaration* is exhaustive, meaning that no other macro definition is intended to have an effect on the API of that module. 923e5dd7070Spatrick 924e5dd7070Spatrick.. note:: 925e5dd7070Spatrick 926e5dd7070Spatrick The ``exhaustive`` attribute implies that any macro definitions 927e5dd7070Spatrick for macros not listed as configuration macros should be ignored 928e5dd7070Spatrick completely when building the module. As an optimization, the 929e5dd7070Spatrick compiler could reduce the number of unique module variants by not 930e5dd7070Spatrick considering these non-configuration macros. This optimization is not 931e5dd7070Spatrick yet implemented in Clang. 932e5dd7070Spatrick 933e5dd7070SpatrickA translation unit shall not import the same module under different definitions of the configuration macros. 934e5dd7070Spatrick 935e5dd7070Spatrick.. note:: 936e5dd7070Spatrick 937e5dd7070Spatrick Clang implements a weak form of this requirement: the definitions 938e5dd7070Spatrick used for configuration macros are fixed based on the definitions 939e5dd7070Spatrick provided by the command line. If an import occurs and the definition 940e5dd7070Spatrick of any configuration macro has changed, the compiler will produce a 941e5dd7070Spatrick warning (under the control of ``-Wconfig-macros``). 942e5dd7070Spatrick 943e5dd7070Spatrick**Example:** A logging library might provide different API (e.g., in the form of different definitions for a logging macro) based on the ``NDEBUG`` macro setting: 944e5dd7070Spatrick 945e5dd7070Spatrick.. parsed-literal:: 946e5dd7070Spatrick 947e5dd7070Spatrick module MyLogger { 948e5dd7070Spatrick umbrella header "MyLogger.h" 949e5dd7070Spatrick config_macros [exhaustive] NDEBUG 950e5dd7070Spatrick } 951e5dd7070Spatrick 952e5dd7070SpatrickConflict declarations 953e5dd7070Spatrick~~~~~~~~~~~~~~~~~~~~~ 954e5dd7070SpatrickA *conflict-declaration* describes a case where the presence of two different modules in the same translation unit is likely to cause a problem. For example, two modules may provide similar-but-incompatible functionality. 955e5dd7070Spatrick 956e5dd7070Spatrick.. parsed-literal:: 957e5dd7070Spatrick 958e5dd7070Spatrick *conflict-declaration*: 959e5dd7070Spatrick ``conflict`` *module-id* ',' *string-literal* 960e5dd7070Spatrick 961e5dd7070SpatrickThe *module-id* of the *conflict-declaration* specifies the module with which the enclosing module conflicts. The specified module shall not have been imported in the translation unit when the enclosing module is imported. 962e5dd7070Spatrick 963e5dd7070SpatrickThe *string-literal* provides a message to be provided as part of the compiler diagnostic when two modules conflict. 964e5dd7070Spatrick 965e5dd7070Spatrick.. note:: 966e5dd7070Spatrick 967e5dd7070Spatrick Clang emits a warning (under the control of ``-Wmodule-conflict``) 968e5dd7070Spatrick when a module conflict is discovered. 969e5dd7070Spatrick 970e5dd7070Spatrick**Example:** 971e5dd7070Spatrick 972e5dd7070Spatrick.. parsed-literal:: 973e5dd7070Spatrick 974e5dd7070Spatrick module Conflicts { 975e5dd7070Spatrick explicit module A { 976e5dd7070Spatrick header "conflict_a.h" 977e5dd7070Spatrick conflict B, "we just don't like B" 978e5dd7070Spatrick } 979e5dd7070Spatrick 980e5dd7070Spatrick module B { 981e5dd7070Spatrick header "conflict_b.h" 982e5dd7070Spatrick } 983e5dd7070Spatrick } 984e5dd7070Spatrick 985e5dd7070Spatrick 986e5dd7070SpatrickAttributes 987e5dd7070Spatrick---------- 988e5dd7070SpatrickAttributes are used in a number of places in the grammar to describe specific behavior of other declarations. The format of attributes is fairly simple. 989e5dd7070Spatrick 990e5dd7070Spatrick.. parsed-literal:: 991e5dd7070Spatrick 992e5dd7070Spatrick *attributes*: 993e5dd7070Spatrick *attribute* *attributes*:sub:`opt` 994e5dd7070Spatrick 995e5dd7070Spatrick *attribute*: 996e5dd7070Spatrick '[' *identifier* ']' 997e5dd7070Spatrick 998e5dd7070SpatrickAny *identifier* can be used as an attribute, and each declaration specifies what attributes can be applied to it. 999e5dd7070Spatrick 1000e5dd7070SpatrickPrivate Module Map Files 1001e5dd7070Spatrick------------------------ 1002e5dd7070SpatrickModule map files are typically named ``module.modulemap`` and live 1003e5dd7070Spatrickeither alongside the headers they describe or in a parent directory of 1004e5dd7070Spatrickthe headers they describe. These module maps typically describe all of 1005e5dd7070Spatrickthe API for the library. 1006e5dd7070Spatrick 1007e5dd7070SpatrickHowever, in some cases, the presence or absence of particular headers 1008e5dd7070Spatrickis used to distinguish between the "public" and "private" APIs of a 1009e5dd7070Spatrickparticular library. For example, a library may contain the headers 1010e5dd7070Spatrick``Foo.h`` and ``Foo_Private.h``, providing public and private APIs, 1011e5dd7070Spatrickrespectively. Additionally, ``Foo_Private.h`` may only be available on 1012e5dd7070Spatricksome versions of library, and absent in others. One cannot easily 1013e5dd7070Spatrickexpress this with a single module map file in the library: 1014e5dd7070Spatrick 1015e5dd7070Spatrick.. parsed-literal:: 1016e5dd7070Spatrick 1017e5dd7070Spatrick module Foo { 1018e5dd7070Spatrick header "Foo.h" 1019e5dd7070Spatrick ... 1020e5dd7070Spatrick } 1021e5dd7070Spatrick 1022e5dd7070Spatrick module Foo_Private { 1023e5dd7070Spatrick header "Foo_Private.h" 1024e5dd7070Spatrick ... 1025e5dd7070Spatrick } 1026e5dd7070Spatrick 1027e5dd7070Spatrick 1028e5dd7070Spatrickbecause the header ``Foo_Private.h`` won't always be available. The 1029e5dd7070Spatrickmodule map file could be customized based on whether 1030e5dd7070Spatrick``Foo_Private.h`` is available or not, but doing so requires custom 1031e5dd7070Spatrickbuild machinery. 1032e5dd7070Spatrick 1033e5dd7070SpatrickPrivate module map files, which are named ``module.private.modulemap`` 1034e5dd7070Spatrick(or, for backward compatibility, ``module_private.map``), allow one to 1035e5dd7070Spatrickaugment the primary module map file with an additional modules. For 1036e5dd7070Spatrickexample, we would split the module map file above into two module map 1037e5dd7070Spatrickfiles: 1038e5dd7070Spatrick 1039e5dd7070Spatrick.. code-block:: c 1040e5dd7070Spatrick 1041e5dd7070Spatrick /* module.modulemap */ 1042e5dd7070Spatrick module Foo { 1043e5dd7070Spatrick header "Foo.h" 1044e5dd7070Spatrick } 1045e5dd7070Spatrick 1046e5dd7070Spatrick /* module.private.modulemap */ 1047e5dd7070Spatrick module Foo_Private { 1048e5dd7070Spatrick header "Foo_Private.h" 1049e5dd7070Spatrick } 1050e5dd7070Spatrick 1051e5dd7070Spatrick 1052e5dd7070SpatrickWhen a ``module.private.modulemap`` file is found alongside a 1053e5dd7070Spatrick``module.modulemap`` file, it is loaded after the ``module.modulemap`` 1054e5dd7070Spatrickfile. In our example library, the ``module.private.modulemap`` file 1055e5dd7070Spatrickwould be available when ``Foo_Private.h`` is available, making it 1056e5dd7070Spatrickeasier to split a library's public and private APIs along header 1057e5dd7070Spatrickboundaries. 1058e5dd7070Spatrick 1059e5dd7070SpatrickWhen writing a private module as part of a *framework*, it's recommended that: 1060e5dd7070Spatrick 1061e5dd7070Spatrick* Headers for this module are present in the ``PrivateHeaders`` framework 1062e5dd7070Spatrick subdirectory. 1063e5dd7070Spatrick* The private module is defined as a *top level module* with the name of the 1064e5dd7070Spatrick public framework prefixed, like ``Foo_Private`` above. Clang has extra logic 1065e5dd7070Spatrick to work with this naming, using ``FooPrivate`` or ``Foo.Private`` (submodule) 1066e5dd7070Spatrick trigger warnings and might not work as expected. 1067e5dd7070Spatrick 1068e5dd7070SpatrickModularizing a Platform 1069e5dd7070Spatrick======================= 1070e5dd7070SpatrickTo get any benefit out of modules, one needs to introduce module maps for software libraries starting at the bottom of the stack. This typically means introducing a module map covering the operating system's headers and the C standard library headers (in ``/usr/include``, for a Unix system). 1071e5dd7070Spatrick 1072e5dd7070SpatrickThe module maps will be written using the `module map language`_, which provides the tools necessary to describe the mapping between headers and modules. Because the set of headers differs from one system to the next, the module map will likely have to be somewhat customized for, e.g., a particular distribution and version of the operating system. Moreover, the system headers themselves may require some modification, if they exhibit any anti-patterns that break modules. Such common patterns are described below. 1073e5dd7070Spatrick 1074e5dd7070Spatrick**Macro-guarded copy-and-pasted definitions** 1075e5dd7070Spatrick System headers vend core types such as ``size_t`` for users. These types are often needed in a number of system headers, and are almost trivial to write. Hence, it is fairly common to see a definition such as the following copy-and-pasted throughout the headers: 1076e5dd7070Spatrick 1077e5dd7070Spatrick .. parsed-literal:: 1078e5dd7070Spatrick 1079e5dd7070Spatrick #ifndef _SIZE_T 1080e5dd7070Spatrick #define _SIZE_T 1081e5dd7070Spatrick typedef __SIZE_TYPE__ size_t; 1082e5dd7070Spatrick #endif 1083e5dd7070Spatrick 1084e5dd7070Spatrick Unfortunately, when modules compiles all of the C library headers together into a single module, only the first actual type definition of ``size_t`` will be visible, and then only in the submodule corresponding to the lucky first header. Any other headers that have copy-and-pasted versions of this pattern will *not* have a definition of ``size_t``. Importing the submodule corresponding to one of those headers will therefore not yield ``size_t`` as part of the API, because it wasn't there when the header was parsed. The fix for this problem is either to pull the copied declarations into a common header that gets included everywhere ``size_t`` is part of the API, or to eliminate the ``#ifndef`` and redefine the ``size_t`` type. The latter works for C++ headers and C11, but will cause an error for non-modules C90/C99, where redefinition of ``typedefs`` is not permitted. 1085e5dd7070Spatrick 1086e5dd7070Spatrick**Conflicting definitions** 1087e5dd7070Spatrick Different system headers may provide conflicting definitions for various macros, functions, or types. These conflicting definitions don't tend to cause problems in a pre-modules world unless someone happens to include both headers in one translation unit. Since the fix is often simply "don't do that", such problems persist. Modules requires that the conflicting definitions be eliminated or that they be placed in separate modules (the former is generally the better answer). 1088e5dd7070Spatrick 1089e5dd7070Spatrick**Missing includes** 1090e5dd7070Spatrick Headers are often missing ``#include`` directives for headers that they actually depend on. As with the problem of conflicting definitions, this only affects unlucky users who don't happen to include headers in the right order. With modules, the headers of a particular module will be parsed in isolation, so the module may fail to build if there are missing includes. 1091e5dd7070Spatrick 1092e5dd7070Spatrick**Headers that vend multiple APIs at different times** 1093e5dd7070Spatrick Some systems have headers that contain a number of different kinds of API definitions, only some of which are made available with a given include. For example, the header may vend ``size_t`` only when the macro ``__need_size_t`` is defined before that header is included, and also vend ``wchar_t`` only when the macro ``__need_wchar_t`` is defined. Such headers are often included many times in a single translation unit, and will have no include guards. There is no sane way to map this header to a submodule. One can either eliminate the header (e.g., by splitting it into separate headers, one per actual API) or simply ``exclude`` it in the module map. 1094e5dd7070Spatrick 1095e5dd7070SpatrickTo detect and help address some of these problems, the ``clang-tools-extra`` repository contains a ``modularize`` tool that parses a set of given headers and attempts to detect these problems and produce a report. See the tool's in-source documentation for information on how to check your system or library headers. 1096e5dd7070Spatrick 1097e5dd7070SpatrickFuture Directions 1098e5dd7070Spatrick================= 1099e5dd7070SpatrickModules support is under active development, and there are many opportunities remaining to improve it. Here are a few ideas: 1100e5dd7070Spatrick 1101e5dd7070Spatrick**Detect unused module imports** 1102e5dd7070Spatrick Unlike with ``#include`` directives, it should be fairly simple to track whether a directly-imported module has ever been used. By doing so, Clang can emit ``unused import`` or ``unused #include`` diagnostics, including Fix-Its to remove the useless imports/includes. 1103e5dd7070Spatrick 1104e5dd7070Spatrick**Fix-Its for missing imports** 1105e5dd7070Spatrick It's fairly common for one to make use of some API while writing code, only to get a compiler error about "unknown type" or "no function named" because the corresponding header has not been included. Clang can detect such cases and auto-import the required module, but should provide a Fix-It to add the import. 1106e5dd7070Spatrick 1107e5dd7070Spatrick**Improve modularize** 1108e5dd7070Spatrick The modularize tool is both extremely important (for deployment) and extremely crude. It needs better UI, better detection of problems (especially for C++), and perhaps an assistant mode to help write module maps for you. 1109e5dd7070Spatrick 1110e5dd7070SpatrickWhere To Learn More About Modules 1111e5dd7070Spatrick================================= 1112e5dd7070SpatrickThe Clang source code provides additional information about modules: 1113e5dd7070Spatrick 1114e5dd7070Spatrick``clang/lib/Headers/module.modulemap`` 1115e5dd7070Spatrick Module map for Clang's compiler-specific header files. 1116e5dd7070Spatrick 1117e5dd7070Spatrick``clang/test/Modules/`` 1118e5dd7070Spatrick Tests specifically related to modules functionality. 1119e5dd7070Spatrick 1120e5dd7070Spatrick``clang/include/clang/Basic/Module.h`` 1121e5dd7070Spatrick The ``Module`` class in this header describes a module, and is used throughout the compiler to implement modules. 1122e5dd7070Spatrick 1123e5dd7070Spatrick``clang/include/clang/Lex/ModuleMap.h`` 1124e5dd7070Spatrick The ``ModuleMap`` class in this header describes the full module map, consisting of all of the module map files that have been parsed, and providing facilities for looking up module maps and mapping between modules and headers (in both directions). 1125e5dd7070Spatrick 1126e5dd7070SpatrickPCHInternals_ 1127e5dd7070Spatrick Information about the serialized AST format used for precompiled headers and modules. The actual implementation is in the ``clangSerialization`` library. 1128e5dd7070Spatrick 1129e5dd7070Spatrick.. [#] Automatic linking against the libraries of modules requires specific linker support, which is not widely available. 1130e5dd7070Spatrick 1131e5dd7070Spatrick.. [#] There are certain anti-patterns that occur in headers, particularly system headers, that cause problems for modules. The section `Modularizing a Platform`_ describes some of them. 1132e5dd7070Spatrick 1133e5dd7070Spatrick.. [#] The second instance is actually a new thread within the current process, not a separate process. However, the original compiler instance is blocked on the execution of this thread. 1134e5dd7070Spatrick 1135e5dd7070Spatrick.. [#] The preprocessing context in which the modules are parsed is actually dependent on the command-line options provided to the compiler, including the language dialect and any ``-D`` options. However, the compiled modules for different command-line options are kept distinct, and any preprocessor directives that occur within the translation unit are ignored. See the section on the `Configuration macros declaration`_ for more information. 1136e5dd7070Spatrick 1137e5dd7070Spatrick.. _PCHInternals: PCHInternals.html 1138