10 Modules [module]

10.1 Module units and purviews [module.unit]

1
#
A module unit is a translation unit that contains a module-declaration.
A named module is the collection of module units with the same module-name.
The identifiers module and import shall not appear as identifiers in a module-name or module-partition.
All module-names either beginning with an identifier consisting of std followed by zero or more digits or containing a reserved identifier ([lex.name]) are reserved and shall not be specified in a module-declaration; no diagnostic is required.
If any identifier in a reserved module-name is a reserved identifier, the module name is reserved for use by C++ implementations; otherwise it is reserved for future standardization.
The optional attribute-specifier-seq appertains to the module-declaration.
2
#
A module interface unit is a module unit whose module-declaration starts with export-keyword; any other module unit is a module implementation unit.
A named module shall contain exactly one module interface unit with no module-partition, known as the primary module interface unit of the module; no diagnostic is required.
3
#
A module partition is a module unit whose module-declaration contains a module-partition.
A named module shall not contain multiple module partitions with the same module-partition.
All module partitions of a module that are module interface units shall be directly or indirectly exported by the primary module interface unit ([module.import]).
No diagnostic is required for a violation of these rules.
[Note 1: 
Module partitions can be imported only by other module units in the same module.
The division of a module into module units is not visible outside the module.
— end note]
4
#
[Example 1: 

Translation unit #1:export module A; export import :Foo; export int baz();

Translation unit #2:export module A:Foo; import :Internals; export int foo() { return 2 * (bar() + 1); }

Translation unit #3:module A:Internals; int bar();

Translation unit #4:module A; import :Internals; int bar() { return baz() - 10; } int baz() { return 30; }

Module A contains four translation units:
  • (4.1)
    a primary module interface unit,
  • (4.2)
    a module partition A:Foo, which is a module interface unit forming part of the interface of module A,
  • (4.3)
    a module partition A:Internals, which does not contribute to the external interface of module A, and
  • (4.4)
    a module implementation unit providing a definition of bar and baz, which cannot be imported because it does not have a partition name.
— end example]
5
#
A module unit purview is the sequence of tokens starting at the module-declaration and extending to the end of the translation unit.
The purview of a named module M is the set of module unit purviews of M's module units.
6
#
The global module is the collection of all global-module-fragments and all translation units that are not module units.
Declarations appearing in such a context are said to be in the purview of the global module.
[Note 2: 
The global module has no name, no module interface unit, and is not introduced by any module-declaration.
— end note]
7
#
A module is either a named module or the global module.
A declaration is attached to a module as follows:
8
#
A module-declaration that contains neither an export-keyword nor a module-partition implicitly imports the primary module interface unit of the module as if by a module-import-declaration.
[Example 2: 

Translation unit #1:module B:Y; // does not implicitly import B int y();

Translation unit #2:export module B; import :Y; // OK, does not create interface dependency cycle int n = y();

Translation unit #3:module B:X1; // does not implicitly import B int &a = n; // error: n not visible here

Translation unit #4:module B:X2; // does not implicitly import B import B; int &b = n; // OK

Translation unit #5:module B; // implicitly imports B int &c = n; // OK — end example]

10.2 Export declaration [module.interface]

1
#
An export-declaration shall inhabit a namespace scope and appear in the purview of a module interface unit.
An export-declaration shall not appear directly or indirectly within an unnamed namespace or a private-module-fragment.
An export-declaration has the declarative effects of its name-declaration, declaration-seq (if any), or module-import-declaration.
The name-declaration of an export-declaration shall not declare a partial specialization ([temp.decls.general]).
[Note 1: 
An export-declaration does not establish a scope.
— end note]
2
#
A declaration is exported if it is declared within an export-declaration and inhabits a namespace scope or it is
3
#
If an exported declaration is not within a header unit, it shall not declare a name with internal linkage.
4
#
[Example 1: 

Source file "a.h":export int x;

Translation unit #1:module; #include "a.h" // error: declaration of x is not in the // purview of a module interface unit export module M; export namespace {} // error: namespace has internal linkage namespace { export int a2; // error: export of name with internal linkage } export static int b; // error: b explicitly declared static export int f(); // OK export namespace N { } // OK export using namespace N; // OK — end example]

5
#
If an exported declaration is a using-declaration ([namespace.udecl]) and is not within a header unit, all entities to which all of the using-declarators ultimately refer (if any) shall have been introduced with a name having external linkage.
[Example 2: 

Source file "b.h":int f();

Importable header "c.h":int g();

Translation unit #1:export module X; export int h();

Translation unit #2:module; #include "b.h" export module M; import "c.h"; import X; export using ::f, ::g, ::h; // OK struct S; export using ::S; // error: S has module linkage namespace N { export int h(); static int h(int); // #1 } export using N::h; // error: #1 has internal linkage — end example]

[Note 2: 
These constraints do not apply to type names introduced by typedef declarations and alias-declarations.
[Example 3: export module M; struct S; export using T = S; // OK, exports name T denoting type S — end example]
— end note]
6
#
A redeclaration of an entity X is implicitly exported if X was introduced by an exported declaration; otherwise it shall not be exported.
[Example 4: export module M; struct S { int n; }; typedef S S; export typedef S S; // OK, does not redeclare an entity export struct S; // error: exported declaration follows non-exported declaration — end example]
7
#
[Note 3: 
Names introduced by exported declarations have either external linkage or no linkage; see [basic.link].
Namespace-scope declarations exported by a module can be found by name lookup in any translation unit importing that module ([basic.lookup]).
Class and enumeration member names can be found by name lookup in any context in which a definition of the type is reachable.
— end note]
[Example 5: 

Interface unit of M:export module M; export struct X { static void f(); struct Y { }; }; namespace { struct S { }; } export void f(S); // OK struct T { }; export T id(T); // OK export struct A; // A exported as incomplete export auto rootFinder(double a) { return [=](double x) { return (x + a/x)/2; }; } export const int n = 5; // OK, n has external linkage

Implementation unit of M:module M; struct A { int value; };

Main program:import M; int main() { X::f(); // OK, X is exported and definition of X is reachable X::Y y; // OK, X​::​Y is exported as a complete type auto f = rootFinder(2); // OK return A{45}.value; // error: A is incomplete } — end example]

8
#
[Note 4: 
Declarations in an exported namespace-definition or in an exported linkage-specification ([dcl.link]) are exported and subject to the rules of exported declarations.
[Example 6: export module M; int g; export namespace N { int x; // OK using ::g; // error: ​::​g has module linkage } — end example]
— end note]

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]).

10.4 Global module fragment [module.global.frag]

1
#
[Note 1: 
Prior to phase 4 of translation, only preprocessing directives can appear in the declaration-seq ([cpp.pre]).
— end note]
2
#
A global-module-fragment specifies the contents of the global module fragment for a module unit.
The global module fragment can be used to provide declarations that are attached to the global module and usable within the module unit.
3
#
A declaration D is decl-reachable from a declaration S in the same translation unit if:
  • (3.1)
    D does not declare a function or function template and S contains an id-expression, namespace-name, type-name, template-name, or concept-name naming D, or
  • (3.2)
    D declares a function or function template that is named by an expression ([basic.def.odr]) appearing in S, or
  • (3.3)
    S contains a dependent call E ([temp.dep]) and D is found by any name lookup performed for an expression synthesized from E by replacing each type-dependent argument or operand with a value of a placeholder type with no associated namespaces or entities, or
    [Note 2: 
    This includes the lookup for operator== performed when considering rewriting an != expression, the lookup for operator<=> performed when considering rewriting a relational comparison, and the lookup for operator!= when considering whether an operator== is a rewrite target.
    — end note]
  • (3.4)
    S contains an expression that takes the address of an overload set ([over.over]) that contains D and for which the target type is dependent, or
  • (3.5)
    there exists a declaration M that is not a namespace-definition for which M is decl-reachable from S and either
    • (3.5.1)
      D is decl-reachable from M, or
    • (3.5.2)
      D and M declare the same entity, and D neither is a friend declaration nor inhabits a block scope, or
    • (3.5.3)
      D declares a namespace N and M is a member of N, or
    • (3.5.4)
      one of D and M declares a class or class template C and the other declares a member or friend of C, or
    • (3.5.5)
      one of D and M declares an enumeration E and the other declares an enumerator of E, or
    • (3.5.6)
      D declares a function or variable and M is declared in D,90 or
    • (3.5.7)
      one of D and M declares a template and the other declares a partial or explicit specialization or an implicit or explicit instantiation of that template, or
    • (3.5.8)
      M declares a class template and D is a deduction guide for that template, or
    • (3.5.9)
      one of D and M declares a class or enumeration type and the other introduces a typedef name for linkage purposes for that type.
In this determination, it is unspecified
4
#
A declaration D in a global module fragment of a module unit is discarded if D is not decl-reachable from any declaration in the declaration-seq of the translation-unit.
[Note 3: 
A discarded declaration is neither reachable nor visible to name lookup outside the module unit, nor in template instantiations whose points of instantiation ([temp.point]) are outside the module unit, even when the instantiation context ([module.context]) includes the module unit.
— end note]
5
#
[Example 1: const int size = 2; int ary1[size]; // unspecified whether size is decl-reachable from ary1 constexpr int identity(int x) { return x; } int ary2[identity(2)]; // unspecified whether identity is decl-reachable from ary2 template<typename> struct S; template<typename, int> struct S2; constexpr int g(int); template<typename T, int N> S<S2<T, g(N)>> f(); // S, S2, g, and ​::​ are decl-reachable from f template<int N> void h() noexcept(g(N) == N); // g and ​::​ are decl-reachable from h — end example]
6
#
[Example 2: 

Source file "foo.h":namespace N { struct X {}; int d(); int e(); inline int f(X, int = d()) { return e(); } int g(X); int h(X); }

Module M interface:module; #include "foo.h" export module M; template<typename T> int use_f() { N::X x; // N​::​X, N, and ​::​ are decl-reachable from use_f return f(x, 123); // N​::​f is decl-reachable from use_f, // N​::​e is indirectly decl-reachable from use_f // because it is decl-reachable from N​::​f, and // N​::​d is decl-reachable from use_f // because it is decl-reachable from N​::​f // even though it is not used in this call } template<typename T> int use_g() { N::X x; // N​::​X, N, and ​::​ are decl-reachable from use_g return g((T(), x)); // N​::​g is not decl-reachable from use_g } template<typename T> int use_h() { N::X x; // N​::​X, N, and ​::​ are decl-reachable from use_h return h((T(), x)); // N​::​h is not decl-reachable from use_h, but // N​::​h is decl-reachable from use_h<int> } int k = use_h<int>(); // use_h<int> is decl-reachable from k, so // N​::​h is decl-reachable from k

Module M implementation:module M; int a = use_f<int>(); // OK int b = use_g<int>(); // error: no viable function for call to g; // g is not decl-reachable from purview of // module M's interface, so is discarded int c = use_h<int>(); // OK — end example]

90)90)
A declaration can appear within a lambda-expression in the initializer of a variable.

10.5 Private module fragment [module.private.frag]

private-module-fragment:
module-keyword : private ; declaration-seq
1
#
A private-module-fragment shall appear only in a primary module interface unit ([module.unit]).
A module unit with a private-module-fragment shall be the only module unit of its module; no diagnostic is required.
2
#
[Note 1: 
A private-module-fragment ends the portion of the module interface unit that can affect the behavior of other translation units.
A private-module-fragment allows a module to be represented as a single translation unit without making all of the contents of the module reachable to importers.
The presence of a private-module-fragment affects:
— end note]
3
#
[Example 1: export module A; export inline void fn_e(); // error: exported inline function fn_e not defined // before private module fragment inline void fn_m(); // error: non-exported inline function fn_m not defined static void fn_s(); export struct X; export void g(X *x) { fn_s(); // OK, call to static function in same translation unit } export X *factory(); // OK module :private; struct X {}; // definition not reachable from importers of A X *factory() { return new X (); } void fn_e() {} void fn_m() {} void fn_s() {} — end example]

10.6 Instantiation context [module.context]

1
#
The instantiation context is a set of points within the program that determines which declarations are found by argument-dependent name lookup ([basic.lookup.argdep]) and which are reachable ([module.reach]) in the context of a particular declaration or template instantiation.
2
#
During the implicit definition of a defaulted function ([special], [class.compare.default]), the instantiation context is the union of the instantiation context from the definition of the class and the instantiation context of the program construct that resulted in the implicit definition of the defaulted function.
3
#
During the implicit instantiation of a template whose point of instantiation is specified as that of an enclosing specialization ([temp.point]), the instantiation context is the union of the instantiation context of the enclosing specialization and, if the template is defined in a module interface unit of a module M and the point of instantiation is not in a module interface unit of M, the point at the end of the declaration-seq of the primary module interface unit of M (prior to the private-module-fragment, if any).
4
#
During the implicit instantiation of a template that is implicitly instantiated because it is referenced from within the implicit definition of a defaulted function, the instantiation context is the instantiation context of the defaulted function.
5
#
During the instantiation of any other template specialization, the instantiation context comprises the point of instantiation of the template.
6
#
In any other case, the instantiation context at a point within the program comprises that point.
7
#
[Example 1: 

Translation unit #1:export module stuff; export template<typename T, typename U> void foo(T, U u) { auto v = u; } export template<typename T, typename U> void bar(T, U u) { auto v = *u; }

Translation unit #2:export module M1; import "defn.h"; // provides struct X {}; import stuff; export template<typename T> void f(T t) { X x; foo(t, x); }

Translation unit #3:export module M2; import "decl.h"; // provides struct X; (not a definition) import stuff; export template<typename T> void g(T t) { X *x; bar(t, x); }

Translation unit #4:import M1; import M2; void test() { f(0); g(0); }

The call to f(0) is valid; the instantiation context of foo<int, X> comprises
  • (7.1)
    the point at the end of translation unit #1,
  • (7.2)
    the point at the end of translation unit #2, and
  • (7.3)
    the point of the call to f(0),
so the definition of X is reachable ([module.reach]).
It is unspecified whether the call to g(0) is valid: the instantiation context of bar<int, X> comprises
  • (7.4)
    the point at the end of translation unit #1,
  • (7.5)
    the point at the end of translation unit #3, and
  • (7.6)
    the point of the call to g(0),
so the definition of X need not be reachable, as described in [module.reach].
— end example]

10.7 Reachability [module.reach]

1
#
A translation unit U is necessarily reachable from a point P if U is a module interface unit on which the translation unit containing P has an interface dependency, or the translation unit containing P imports U, in either case prior to P ([module.import]).
[Note 1: 
While module interface units are reachable even when they are only transitively imported via a non-exported import declaration, namespace-scope names from such module interface units are not found by name lookup ([basic.lookup]).
— end note]
2
#
All translation units that are necessarily reachable are reachable.
Additional translation units on which the point within the program has an interface dependency may be considered reachable, but it is unspecified which are and under what circumstances.91
[Note 2: 
It is advisable to avoid depending on the reachability of any additional translation units in programs intending to be portable.
— end note]
3
#
A declaration D is reachable from a point P if
A declaration is reachable if it is reachable from any point in the instantiation context ([module.context]).
[Note 3: 
Whether a declaration is exported has no bearing on whether it is reachable.
— end note]
4
#
The accumulated properties of all reachable declarations of an entity within a context determine the behavior of the entity within that context.
[Note 4: 
These reachable semantic properties include type completeness, type definitions, initializers, default arguments of functions or template declarations, attributes, names bound, etc.
Since default arguments are evaluated in the context of the call expression, the reachable semantic properties of the corresponding parameter types apply in that context.
[Example 1: 

Translation unit #1:export module M:A; export struct B;

Translation unit #2:module M:B; struct B { operator int(); };

Translation unit #3:module M:C; import :A; B b1; // error: no reachable definition of struct B

Translation unit #4:export module M; export import :A; import :B; B b2; export void f(B b = B());

Translation unit #5:import M; B b3; // error: no reachable definition of struct B void g() { f(); } // error: no reachable definition of struct B — end example]

— end note]
5
#
[Note 5: 
Declarations of an entity can be reachable even where they cannot be found by name lookup.
— end note]
[Example 2: 

Translation unit #1:export module A; struct X {}; export using Y = X;

Translation unit #2:import A; Y y; // OK, definition of X is reachable X x; // error: X not visible to unqualified lookup — end example]

91)91)
Implementations are therefore not required to prevent the semantic effects of additional translation units involved in the compilation from being observed.