cpp/language/modules

Most C++ projects use multiple translation units, and so they need to share and  across those units. The usage of headers is prominent for this purpose, an example being the standard library whose declarations can be provided by including the corresponding header.

Modules are a language feature to share declarations and definitions across translation units. They are an alternative to some use cases of headers.

Modules are orthogonal to.

Syntax
@1@ Module declaration. Declares that the current translation unit is a module unit. @2,3@ Export declaration. Export all namespace-scope declarations in or. @4,5,6@ Import declaration. Import a module unit/module partition/header unit. @7@ Starts a global module fragment. @8@ Starts a private module fragment.

Module declarations
A translation unit may have a module declaration, in which case it is considered a module unit. The module declaration, if provided, must be the first declaration of the translation unit (excepted the global module fragment, which is covered later on). Each module unit is associated to a module name (and optionally a partition), provided in the module declaration.

The module name consists of one or more identifiers separated by dots (for example:, , ...). Dots have no intrinsic meaning, however they are used informally to represent hierarchy.

A named module is the collection of module units with the same module name.

Module units whose declaration has the keyword are termed module interface units; all other module units are termed module implementation units.

For every named module, there must be exactly one module interface unit that specifies no module partition; this module unit is termed the primary module interface unit. Its exported content will be available when importing the corresponding named module.

Exporting declarations and definitions
Module interface units can export declarations (including definitions), which can be imported by other translation units. To export a declaration, either prefix it with the keyword, or else place it inside an  block.

Importing modules and headers
Modules are imported via an import declaration:

All declarations and definitions exported in the module interface units of the given named module will be available in the translation unit using the import declaration.

Import declarations can be exported in a module interface unit. That is, if module A export-imports B, then importing A will also make visible all exports from B.

In module units, all import declarations (including export-imports) must be grouped after the module declaration and before all other declarations.

should not be used in a module unit (outside the global module fragment), because all included declarations and definitions would be considered part of the module. Instead, headers can also be imported with an import declaration:

Importing a header will make accessible all its definitions and declarations. Preprocessor macros are also accessible (because import declarations are recognized by the preprocessor). However, contrary to, preprocessing macros defined in the translation unit will not affect the processing of the header. This may be inconvenient in some cases (some headers use preprocessing macros as a form of configuration), in which case the usage of global module fragment is needed.

Global module fragment
Module units can be prefixed by a global module fragment, which can be used to include headers when importing the headers is not possible (notably when the header uses preprocessing macros as configuration).

If a module-unit has a global module fragment, then its first declaration must be. Then, only preprocessing directives can appear in the global module fragment. Then, a standard module declaration marks the end of the global module fragment and the start of the module content.

Private module fragment
Primary module interface unit can be suffixed by a private module fragment, which allows a module to be represented as a single translation unit without making all of the contents of the module reachable to importers.

Private module fragment ends the portion of the module interface unit that can affect the behavior of other translation units. If a module unit contains a private module fragment, it will be the only module unit of its module.

Module partitions
A module can have module partition units. They are module units whose module declarations include a module partition, which starts with a colon and is placed after the module name.

A module partition represents exactly one module unit (two module units cannot designate the same module partition). They are visible only from inside the named module (translation units outside the named module cannot import a module partition directly).

A module partition can be imported by module units of the same named module.

All definitions and declarations in a module partition are visible by the importing module unit, whether exported or not.

Module partitions can be module interface units (when their module declarations have ). They must be export-imported by the primary module interface unit, and their exported statements will be visible when the module is imported.

Module ownership
In general, if a declaration appears after the module declaration in a module unit, it is attached to that module.

If a declaration of an entity is attached to a named module, that entity can only be defined in that module. All declarations of such an entity must be attached to the same module.

If a declaration is attached to a named module, and it is not exported, the declared name has.

If two matching declarations are attached to different modules, and they both declare names with external linkage, the program is ill-formed; no diagnostic is required if neither is reachable from the other. In practice, there are two models:


 * In the weak module ownership model, such declarations are considered to declare the same entity.
 * In the strong module ownership model, they are considered to declare different entities.

The following declarations are not attached to any named module (and thus the declared entity can be defined outside the module):


 * definitions with external linkage;
 * declarations within a specification.

Keywords
,, ,