10 Modules [module]

10.3 Import declaration [module.import]

1
#
A module-import-declaration shall inhabit the global namespace scope.
In a module unit, all module-import-declarations and export-declarations exporting module-import-declarations shall appear before all other declarations in the declaration-seq of the translation-unit and of the private-module-fragment (if any).
2
#
A module-import-declaration imports a set of translation units determined as described below.
[Note 1: 
Namespace-scope declarations exported by the imported translation units can be found by name lookup ([basic.lookup]) in the importing translation unit and declarations within the imported translation units become reachable ([module.reach]) in the importing translation unit after the import declaration.
— end note]
3
#
A module-import-declaration that specifies a module-name M imports all module interface units of M.
4
#
A module-import-declaration that specifies a module-partition shall only appear after the module-declaration in a module unit of some module M.
Such a declaration imports the so-named module partition of M.
5
#
A module-import-declaration that specifies a header-name H imports a synthesized header unit, which is a translation unit formed by applying phases 1 to 7 of translation ([lex.phases]) to the source file or header nominated by H, which shall not contain a module-declaration.
[Note 2: 
A header unit is a separate translation unit with an independent set of defined macros.
All declarations within a header unit are implicitly exported ([module.interface]), and are attached to the global module ([module.unit]).
— end note]
An importable header is a member of an implementation-defined set of headers that includes all importable C++ library headers ([headers]).
H shall identify an importable header.
Given two such module-import-declarations:
  • (5.1)
    if their header-names identify different headers or source files ([cpp.include]), they import distinct header units;
  • (5.2)
    otherwise, if they appear in the same translation unit, they import the same header unit;
  • (5.3)
    otherwise, it is unspecified whether they import the same header unit.
    [Note 3: 
    It is therefore possible that multiple copies exist of entities declared with internal linkage in an importable header.
    — end note]
[Note 4: 
A module-import-declaration nominating a header-name is also recognized by the preprocessor, and results in macros defined at the end of phase 4 of translation of the header unit being made visible as described in [cpp.import].
Any other module-import-declaration does not make macros visible.
— end note]
6
#
A declaration of a name with internal linkage is permitted within a header unit despite all declarations being implicitly exported ([module.interface]).
[Note 5: 
A definition that appears in multiple translation units cannot in general refer to such names ([basic.def.odr]).
— end note]
A header unit shall not contain a definition of a non-inline function or variable whose name has external linkage.
7
#
When a module-import-declaration imports a translation unit T, it also imports all translation units imported by exported module-import-declarations in T; such translation units are said to be exported by T.
Additionally, when a module-import-declaration in a module unit of some module M imports another module unit U of M, it also imports all translation units imported by non-exported module-import-declarations in the module unit purview of U.89
These rules can in turn lead to the importation of yet more translation units.
[Note 6: 
Such indirect importation does not make macros available, because a translation unit is a sequence of tokens in translation phase 7 ([lex.phases]).
Macros can be made available by directly importing header units as described in [cpp.import].
— end note]
8
#
A module implementation unit shall not be exported.
[Example 1: 

Translation unit #1:module M:Part;

Translation unit #2:export module M; export import :Part; // error: exported partition :Part is an implementation unit — end example]

9
#
A module implementation unit of a module M that is not a module partition shall not contain a module-import-declaration nominating M.
[Example 2: module M; import M; // error: cannot import M in its own unit — end example]
10
#
A translation unit has an interface dependency on a translation unit U if it contains a declaration (possibly a module-declaration) that imports U or if it has an interface dependency on a translation unit that has an interface dependency on U.
A translation unit shall not have an interface dependency on itself.
[Example 3: 

Interface unit of M1:export module M1; import M2;

Interface unit of M2:export module M2; import M3;

Interface unit of M3:export module M3; import M1; // error: cyclic interface dependency M3 →M1 →M2 →M3 — end example]

89)89)
This is consistent with the lookup rules for imported names ([basic.lookup]).