10 Modules [module]

10.3 Import declaration [module.import]

module-import-declaration:
	import-keyword module-name attribute-specifier-seq ;
	import-keyword module-partition attribute-specifier-seq ;
	import-keyword header-name attribute-specifier-seq ;
1
#
A module-import-declaration shall only appear at global namespace scope.
In a module unit, all module-import-declarations and export-declarations exporting module-import-declarations shall precede 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
:
Namespace-scope names exported by the imported translation units become visible ([basic.scope.namespace]) 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
:
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
    : It is therefore possible that multiple copies exist of entities declared with internal linkage in an importable header. — end note
     ]
[ Note
: 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]. — 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
:
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.98
These rules may in turn lead to the importation of yet more translation units.
8
#
A module implementation unit shall not be exported.
[ Example
:

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
: 
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
:

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
— end example
 ]
98)
This is consistent with the rules for visibility of imported names ([basic.scope.namespace]).
⮥