• Home
  • Line#
  • Scopes#
  • Navigate#
  • Raw
  • Download
1=======
2Modules
3=======
4
5.. contents::
6   :local:
7
8Introduction
9============
10Most 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):
11
12.. code-block:: c
13
14  #include <SomeLib.h>
15
16The implementation is handled separately by linking against the appropriate library. For example, by passing ``-lSomeLib`` to the linker.
17
18Modules 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.
19
20Problems with the current model
21-------------------------------
22The ``#include`` mechanism provided by the C preprocessor is a very poor way to access the API of a library, for a number of reasons:
23
24* **Compile-time scalability**: Each time a header is included, the
25  compiler must preprocess and parse the text in that header and every
26  header it includes, transitively. This process must be repeated for
27  every translation unit in the application, which involves a huge
28  amount of redundant work. In a project with *N* translation units
29  and *M* headers included in each translation unit, the compiler is
30  performing *M x N* work even though most of the *M* headers are
31  shared among multiple translation units. C++ is particularly bad,
32  because the compilation model for templates forces a huge amount of
33  code into headers.
34
35* **Fragility**: ``#include`` directives are treated as textual
36  inclusion by the preprocessor, and are therefore subject to any
37  active macro definitions at the time of inclusion. If any of the
38  active macro definitions happens to collide with a name in the
39  library, it can break the library API or cause compilation failures
40  in the library header itself. For an extreme example,
41  ``#define std "The C++ Standard"`` and then include a standard
42  library header: the result is a horrific cascade of failures in the
43  C++ Standard Library's implementation. More subtle real-world
44  problems occur when the headers for two different libraries interact
45  due to macro collisions, and users are forced to reorder
46  ``#include`` directives or introduce ``#undef`` directives to break
47  the (unintended) dependency.
48
49* **Conventional workarounds**: C programmers have
50  adopted a number of conventions to work around the fragility of the
51  C preprocessor model. Include guards, for example, are required for
52  the vast majority of headers to ensure that multiple inclusion
53  doesn't break the compile. Macro names are written with
54  ``LONG_PREFIXED_UPPERCASE_IDENTIFIERS`` to avoid collisions, and some
55  library/framework developers even use ``__underscored`` names
56  in headers to avoid collisions with "normal" names that (by
57  convention) shouldn't even be macros. These conventions are a
58  barrier to entry for developers coming from non-C languages, are
59  boilerplate for more experienced developers, and make our headers
60  far uglier than they should be.
61
62* **Tool confusion**: In a C-based language, it is hard to build tools
63  that work well with software libraries, because the boundaries of
64  the libraries are not clear. Which headers belong to a particular
65  library, and in what order should those headers be included to
66  guarantee that they compile correctly? Are the headers C, C++,
67  Objective-C++, or one of the variants of these languages? What
68  declarations in those headers are actually meant to be part of the
69  API, and what declarations are present only because they had to be
70  written as part of the header file?
71
72Semantic import
73---------------
74Modules 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:
75
76.. code-block:: c
77
78  import std.io; // pseudo-code; see below for syntax discussion
79
80However, 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 [#]_
81This semantic import model addresses many of the problems of the preprocessor inclusion model:
82
83* **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.
84
85* **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.
86
87* **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.
88
89Problems modules do not solve
90-----------------------------
91Many 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:
92
93* **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.
94
95* **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.
96
97* **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.
98
99* **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.
100
101Using Modules
102=============
103To 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.
104
105Objective-C Import declaration
106------------------------------
107Objective-C provides syntax for importing a module via an *@import declaration*, which imports the named module:
108
109.. parsed-literal::
110
111  @import std;
112
113The ``@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.,
114
115.. parsed-literal::
116
117  @import std.io;
118
119Redundant 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.
120
121At present, there is no C or C++ syntax for import declarations. Clang
122will track the modules proposal in the C++ committee. See the section
123`Includes as imports`_ to see how modules get imported today.
124
125Includes as imports
126-------------------
127The 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
128
129.. code-block:: c
130
131  #include <stdio.h>
132
133will 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.
134
135.. note::
136
137  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.
138
139While building a module, ``#include_next`` is also supported, with one caveat.
140The usual behavior of ``#include_next`` is to search for the specified filename
141in the list of include paths, starting from the path *after* the one
142in which the current file was found.
143Because files listed in module maps are not found through include paths, a
144different strategy is used for ``#include_next`` directives in such files: the
145list of include paths is searched for the specified header name, to find the
146first include path that would refer to the current file. ``#include_next`` is
147interpreted as if the current file had been found in that path.
148If this search finds a file named by a module map, the ``#include_next``
149directive is translated into an import, just like for a ``#include``
150directive.``
151
152Module maps
153-----------
154The 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.
155
156Module 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.
157
158.. note::
159
160  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.
161
162One 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.
163
164Compilation model
165-----------------
166The 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.
167
168The 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.
169
170Modules 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.
171
172Command-line parameters
173-----------------------
174``-fmodules``
175  Enable the modules feature.
176
177``-fimplicit-module-maps``
178  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.
179
180``-fmodules-cache-path=<directory>``
181  Specify the path to the modules cache. If not provided, Clang will select a system-appropriate default.
182
183``-fno-autolink``
184  Disable automatic linking against the libraries associated with imported modules.
185
186``-fmodules-ignore-macro=macroname``
187  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.
188
189``-fmodules-prune-interval=seconds``
190  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.
191
192``-fmodules-prune-after=seconds``
193  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.
194
195``-module-file-info <module file name>``
196  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.
197
198``-fmodules-decluse``
199  Enable checking of module ``use`` declarations.
200
201``-fmodule-name=module-id``
202  Consider a source file as a part of the given module.
203
204``-fmodule-map-file=<file>``
205  Load the given module map file if a header from its directory or one of its subdirectories is loaded.
206
207``-fmodules-search-all``
208  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.
209
210``-fno-implicit-modules``
211  All modules used by the build must be specified with ``-fmodule-file``.
212
213``-fmodule-file=<file>``
214  Load the given precompiled module file.
215
216Module Semantics
217================
218
219Modules 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.
220
221.. note::
222
223  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.
224
225As 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.
226
227.. note::
228
229  Clang currently only performs minimal checking for violations of the One Definition Rule.
230
231If 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.
232
233Macros
234------
235
236The 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:
237
238* Each definition and undefinition of a macro is considered to be a distinct entity.
239* 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.
240* A ``#define X`` or ``#undef X`` directive *overrides* all definitions of ``X`` that are visible at the point of the directive.
241* A ``#define`` or ``#undef`` directive is *active* if it is visible and no visible directive overrides it.
242* 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).
243* 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.
244
245For example, suppose:
246
247* ``<stdio.h>`` defines a macro ``getc`` (and exports its ``#define``)
248* ``<cstdio>`` imports the ``<stdio.h>`` module and undefines the macro (and exports its ``#undef``)
249
250The ``#undef`` overrides the ``#define``, and a source file that imports both modules *in any order* will not see ``getc`` defined as a macro.
251
252Module Map Language
253===================
254
255.. warning::
256
257  The module map language is not currently guaranteed to be stable between major revisions of Clang.
258
259The module map language describes the mapping from header files to the
260logical structure of modules. To enable support for using a library as
261a module, one must write a ``module.modulemap`` file for that library. The
262``module.modulemap`` file is placed alongside the header files themselves,
263and is written in the module map language described below.
264
265.. note::
266    For compatibility with previous releases, if a module map file named
267    ``module.modulemap`` is not found, Clang will also search for a file named
268    ``module.map``. This behavior is deprecated and we plan to eventually
269    remove it.
270
271As an example, the module map file for the C standard library might look a bit like this:
272
273.. parsed-literal::
274
275  module std [system] [extern_c] {
276    module assert {
277      textual header "assert.h"
278      header "bits/assert-decls.h"
279      export *
280    }
281
282    module complex {
283      header "complex.h"
284      export *
285    }
286
287    module ctype {
288      header "ctype.h"
289      export *
290    }
291
292    module errno {
293      header "errno.h"
294      header "sys/errno.h"
295      export *
296    }
297
298    module fenv {
299      header "fenv.h"
300      export *
301    }
302
303    // ...more headers follow...
304  }
305
306Here, 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.
307
308Lexical structure
309-----------------
310Module 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.
311
312.. parsed-literal::
313
314  ``config_macros`` ``export``     ``private``
315  ``conflict``      ``framework``  ``requires``
316  ``exclude``       ``header``     ``textual``
317  ``explicit``      ``link``       ``umbrella``
318  ``extern``        ``module``     ``use``
319
320Module map file
321---------------
322A module map file consists of a series of module declarations:
323
324.. parsed-literal::
325
326  *module-map-file*:
327    *module-declaration**
328
329Within a module map file, modules are referred to by a *module-id*, which uses periods to separate each part of a module's name:
330
331.. parsed-literal::
332
333  *module-id*:
334    *identifier* ('.' *identifier*)*
335
336Module declaration
337------------------
338A module declaration describes a module, including the headers that contribute to that module, its submodules, and other aspects of the module.
339
340.. parsed-literal::
341
342  *module-declaration*:
343    ``explicit``:sub:`opt` ``framework``:sub:`opt` ``module`` *module-id* *attributes*:sub:`opt` '{' *module-member** '}'
344    ``extern`` ``module`` *module-id* *string-literal*
345
346The *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.
347
348The ``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.
349
350The ``framework`` qualifier specifies that this module corresponds to a Darwin-style framework. A Darwin-style framework (used primarily on Mac OS X 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:
351
352.. parsed-literal::
353
354  Name.framework/
355    Modules/module.modulemap  Module map for the framework
356    Headers/                  Subdirectory containing framework headers
357    Frameworks/               Subdirectory containing embedded frameworks
358    Resources/                Subdirectory containing additional resources
359    Name                      Symbolic link to the shared library for the framework
360
361The ``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.
362
363The ``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.
364
365Modules can have a number of different kinds of members, each of which is described below:
366
367.. parsed-literal::
368
369  *module-member*:
370    *requires-declaration*
371    *header-declaration*
372    *umbrella-dir-declaration*
373    *submodule-declaration*
374    *export-declaration*
375    *use-declaration*
376    *link-declaration*
377    *config-macros-declaration*
378    *conflict-declaration*
379
380An 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.
381
382Requires declaration
383~~~~~~~~~~~~~~~~~~~~
384A *requires-declaration* specifies the requirements that an importing translation unit must satisfy to use the module.
385
386.. parsed-literal::
387
388  *requires-declaration*:
389    ``requires`` *feature-list*
390
391  *feature-list*:
392    *feature* (',' *feature*)*
393
394  *feature*:
395    ``!``:sub:`opt` *identifier*
396
397The requirements clause allows specific modules or submodules to specify that they are only accessible with certain language dialects or on certain platforms. 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. The optional ``!`` indicates that a feature is incompatible with the module.
398
399The following features are defined:
400
401altivec
402  The target supports AltiVec.
403
404blocks
405  The "blocks" language feature is available.
406
407cplusplus
408  C++ support is available.
409
410cplusplus11
411  C++11 support is available.
412
413objc
414  Objective-C support is available.
415
416objc_arc
417  Objective-C Automatic Reference Counting (ARC) is available
418
419opencl
420  OpenCL is available
421
422tls
423  Thread local storage is available.
424
425*target feature*
426  A specific target feature (e.g., ``sse4``, ``avx``, ``neon``) is available.
427
428
429**Example:** The ``std`` module can be extended to also include C++ and C++11 headers using a *requires-declaration*:
430
431.. parsed-literal::
432
433 module std {
434    // C standard library...
435
436    module vector {
437      requires cplusplus
438      header "vector"
439    }
440
441    module type_traits {
442      requires cplusplus11
443      header "type_traits"
444    }
445  }
446
447Header declaration
448~~~~~~~~~~~~~~~~~~
449A header declaration specifies that a particular header is associated with the enclosing module.
450
451.. parsed-literal::
452
453  *header-declaration*:
454    ``private``:sub:`opt` ``textual``:sub:`opt` ``header`` *string-literal*
455    ``umbrella`` ``header`` *string-literal*
456    ``exclude`` ``header`` *string-literal*
457
458A 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.
459
460A 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.
461
462.. note::
463    Any headers not included by the umbrella header should have
464    explicit ``header`` declarations. Use the
465    ``-Wincomplete-umbrella`` warning option to ask Clang to complain
466    about headers not covered by the umbrella header or the module map.
467
468A header with the ``private`` specifier may not be included from outside the module itself.
469
470A header with the ``textual`` specifier will not be compiled when the module is
471built, and will be textually included if it is named by a ``#include``
472directive. However, it is considered to be part of the module for the purpose
473of checking *use-declaration*\s, and must still be a lexically-valid header
474file. In the future, we intend to pre-tokenize such headers and include the
475token sequence within the prebuilt module representation.
476
477A 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.
478
479**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.
480
481.. parsed-literal::
482
483  module std [system] {
484    textual header "assert.h"
485  }
486
487A given header shall not be referenced by more than one *header-declaration*.
488
489Umbrella directory declaration
490~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
491An umbrella directory declaration specifies that all of the headers in the specified directory should be included within the module.
492
493.. parsed-literal::
494
495  *umbrella-dir-declaration*:
496    ``umbrella`` *string-literal*
497
498The *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.
499
500An *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.
501
502.. note::
503
504    Umbrella directories are useful for libraries that have a large number of headers but do not have an umbrella header.
505
506
507Submodule declaration
508~~~~~~~~~~~~~~~~~~~~~
509Submodule declarations describe modules that are nested within their enclosing module.
510
511.. parsed-literal::
512
513  *submodule-declaration*:
514    *module-declaration*
515    *inferred-submodule-declaration*
516
517A *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.
518
519A *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*.
520
521.. parsed-literal::
522
523  *inferred-submodule-declaration*:
524    ``explicit``:sub:`opt` ``framework``:sub:`opt` ``module`` '*' *attributes*:sub:`opt` '{' *inferred-submodule-member** '}'
525
526  *inferred-submodule-member*:
527    ``export`` '*'
528
529A 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).
530
531For 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:
532
533* Have the same name as the header (without the file extension)
534* Have the ``explicit`` specifier, if the *inferred-submodule-declaration* has the ``explicit`` specifier
535* Have the ``framework`` specifier, if the
536  *inferred-submodule-declaration* has the ``framework`` specifier
537* Have the attributes specified by the \ *inferred-submodule-declaration*
538* Contain a single *header-declaration* naming that header
539* Contain a single *export-declaration* ``export *``, if the \ *inferred-submodule-declaration* contains the \ *inferred-submodule-member* ``export *``
540
541**Example:** If the subdirectory "MyLib" contains the headers ``A.h`` and ``B.h``, then the following module map:
542
543.. parsed-literal::
544
545  module MyLib {
546    umbrella "MyLib"
547    explicit module * {
548      export *
549    }
550  }
551
552is equivalent to the (more verbose) module map:
553
554.. parsed-literal::
555
556  module MyLib {
557    explicit module A {
558      header "A.h"
559      export *
560    }
561
562    explicit module B {
563      header "B.h"
564      export *
565    }
566  }
567
568Export declaration
569~~~~~~~~~~~~~~~~~~
570An *export-declaration* specifies which imported modules will automatically be re-exported as part of a given module's API.
571
572.. parsed-literal::
573
574  *export-declaration*:
575    ``export`` *wildcard-module-id*
576
577  *wildcard-module-id*:
578    *identifier*
579    '*'
580    *identifier* '.' *wildcard-module-id*
581
582The *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.
583
584**Example:** In the following example, importing ``MyLib.Derived`` also provides the API for ``MyLib.Base``:
585
586.. parsed-literal::
587
588  module MyLib {
589    module Base {
590      header "Base.h"
591    }
592
593    module Derived {
594      header "Derived.h"
595      export Base
596    }
597  }
598
599Note that, if ``Derived.h`` includes ``Base.h``, one can simply use a wildcard export to re-export everything ``Derived.h`` includes:
600
601.. parsed-literal::
602
603  module MyLib {
604    module Base {
605      header "Base.h"
606    }
607
608    module Derived {
609      header "Derived.h"
610      export *
611    }
612  }
613
614.. note::
615
616  The wildcard export syntax ``export *`` re-exports all of the
617  modules that were imported in the actual header file. Because
618  ``#include`` directives are automatically mapped to module imports,
619  ``export *`` provides the same transitive-inclusion behavior
620  provided by the C preprocessor, e.g., importing a given module
621  implicitly imports all of the modules on which it depends.
622  Therefore, liberal use of ``export *`` provides excellent backward
623  compatibility for programs that rely on transitive inclusion (i.e.,
624  all of them).
625
626Use declaration
627~~~~~~~~~~~~~~~
628A *use-declaration* specifies another module that the current top-level module
629intends to use. When the option *-fmodules-decluse* is specified, a module can
630only use other modules that are explicitly specified in this way.
631
632.. parsed-literal::
633
634  *use-declaration*:
635    ``use`` *module-id*
636
637**Example:** In the following example, use of A from C is not declared, so will trigger a warning.
638
639.. parsed-literal::
640
641  module A {
642    header "a.h"
643  }
644
645  module B {
646    header "b.h"
647  }
648
649  module C {
650    header "c.h"
651    use B
652  }
653
654When compiling a source file that implements a module, use the option
655``-fmodule-name=module-id`` to indicate that the source file is logically part
656of that module.
657
658The compiler at present only applies restrictions to the module directly being built.
659
660Link declaration
661~~~~~~~~~~~~~~~~
662A *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.
663
664.. parsed-literal::
665
666  *link-declaration*:
667    ``link`` ``framework``:sub:`opt` *string-literal*
668
669The *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.
670
671A *link-declaration* with the ``framework`` specifies that the linker should link against the named framework, e.g., with ``-framework MyFramework``.
672
673.. note::
674
675  Automatic linking with the ``link`` directive is not yet widely
676  implemented, because it requires support from both the object file
677  format and the linker. The notion is similar to Microsoft Visual
678  Studio's ``#pragma comment(lib...)``.
679
680Configuration macros declaration
681~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
682The *config-macros-declaration* specifies the set of configuration macros that have an effect on the API of the enclosing module.
683
684.. parsed-literal::
685
686  *config-macros-declaration*:
687    ``config_macros`` *attributes*:sub:`opt` *config-macro-list*:sub:`opt`
688
689  *config-macro-list*:
690    *identifier* (',' *identifier*)*
691
692Each *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.
693
694A *config-macros-declaration* shall only be present on a top-level module, i.e., a module that is not nested within an enclosing module.
695
696The ``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.
697
698.. note::
699
700  The ``exhaustive`` attribute implies that any macro definitions
701  for macros not listed as configuration macros should be ignored
702  completely when building the module. As an optimization, the
703  compiler could reduce the number of unique module variants by not
704  considering these non-configuration macros. This optimization is not
705  yet implemented in Clang.
706
707A translation unit shall not import the same module under different definitions of the configuration macros.
708
709.. note::
710
711  Clang implements a weak form of this requirement: the definitions
712  used for configuration macros are fixed based on the definitions
713  provided by the command line. If an import occurs and the definition
714  of any configuration macro has changed, the compiler will produce a
715  warning (under the control of ``-Wconfig-macros``).
716
717**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:
718
719.. parsed-literal::
720
721  module MyLogger {
722    umbrella header "MyLogger.h"
723    config_macros [exhaustive] NDEBUG
724  }
725
726Conflict declarations
727~~~~~~~~~~~~~~~~~~~~~
728A *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.
729
730.. parsed-literal::
731
732  *conflict-declaration*:
733    ``conflict`` *module-id* ',' *string-literal*
734
735The *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.
736
737The *string-literal* provides a message to be provided as part of the compiler diagnostic when two modules conflict.
738
739.. note::
740
741  Clang emits a warning (under the control of ``-Wmodule-conflict``)
742  when a module conflict is discovered.
743
744**Example:**
745
746.. parsed-literal::
747
748  module Conflicts {
749    explicit module A {
750      header "conflict_a.h"
751      conflict B, "we just don't like B"
752    }
753
754    module B {
755      header "conflict_b.h"
756    }
757  }
758
759
760Attributes
761----------
762Attributes are used in a number of places in the grammar to describe specific behavior of other declarations. The format of attributes is fairly simple.
763
764.. parsed-literal::
765
766  *attributes*:
767    *attribute* *attributes*:sub:`opt`
768
769  *attribute*:
770    '[' *identifier* ']'
771
772Any *identifier* can be used as an attribute, and each declaration specifies what attributes can be applied to it.
773
774Private Module Map Files
775------------------------
776Module map files are typically named ``module.modulemap`` and live
777either alongside the headers they describe or in a parent directory of
778the headers they describe. These module maps typically describe all of
779the API for the library.
780
781However, in some cases, the presence or absence of particular headers
782is used to distinguish between the "public" and "private" APIs of a
783particular library. For example, a library may contain the headers
784``Foo.h`` and ``Foo_Private.h``, providing public and private APIs,
785respectively. Additionally, ``Foo_Private.h`` may only be available on
786some versions of library, and absent in others. One cannot easily
787express this with a single module map file in the library:
788
789.. parsed-literal::
790
791  module Foo {
792    header "Foo.h"
793
794    explicit module Private {
795      header "Foo_Private.h"
796    }
797  }
798
799
800because the header ``Foo_Private.h`` won't always be available. The
801module map file could be customized based on whether
802``Foo_Private.h`` is available or not, but doing so requires custom
803build machinery.
804
805Private module map files, which are named ``module.private.modulemap``
806(or, for backward compatibility, ``module_private.map``), allow one to
807augment the primary module map file with an additional submodule. For
808example, we would split the module map file above into two module map
809files:
810
811.. code-block:: c
812
813  /* module.modulemap */
814  module Foo {
815    header "Foo.h"
816  }
817
818  /* module.private.modulemap */
819  explicit module Foo.Private {
820    header "Foo_Private.h"
821  }
822
823
824When a ``module.private.modulemap`` file is found alongside a
825``module.modulemap`` file, it is loaded after the ``module.modulemap``
826file. In our example library, the ``module.private.modulemap`` file
827would be available when ``Foo_Private.h`` is available, making it
828easier to split a library's public and private APIs along header
829boundaries.
830
831Modularizing a Platform
832=======================
833To 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).
834
835The 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.
836
837**Macro-guarded copy-and-pasted definitions**
838  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:
839
840  .. parsed-literal::
841
842    #ifndef _SIZE_T
843    #define _SIZE_T
844    typedef __SIZE_TYPE__ size_t;
845    #endif
846
847  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.
848
849**Conflicting definitions**
850  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).
851
852**Missing includes**
853  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.
854
855**Headers that vend multiple APIs at different times**
856  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.
857
858To 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.
859
860Future Directions
861=================
862Modules support is under active development, and there are many opportunities remaining to improve it. Here are a few ideas:
863
864**Detect unused module imports**
865  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.
866
867**Fix-Its for missing imports**
868  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.
869
870**Improve modularize**
871  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.
872
873Where To Learn More About Modules
874=================================
875The Clang source code provides additional information about modules:
876
877``clang/lib/Headers/module.modulemap``
878  Module map for Clang's compiler-specific header files.
879
880``clang/test/Modules/``
881  Tests specifically related to modules functionality.
882
883``clang/include/clang/Basic/Module.h``
884  The ``Module`` class in this header describes a module, and is used throughout the compiler to implement modules.
885
886``clang/include/clang/Lex/ModuleMap.h``
887  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).
888
889PCHInternals_
890  Information about the serialized AST format used for precompiled headers and modules. The actual implementation is in the ``clangSerialization`` library.
891
892.. [#] Automatic linking against the libraries of modules requires specific linker support, which is not widely available.
893
894.. [#] 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.
895
896.. [#] 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.
897
898.. [#] 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.
899
900.. _PCHInternals: PCHInternals.html
901
902