10 Modules [module]

10.1 Module units and purviews [module.unit]

module-declaration:
	export module module-name module-partition attribute-specifier-seq ;
module-name:
	module-name-qualifier identifier
module-partition:
	: module-name-qualifier identifier
module-name-qualifier:
	identifier .
	module-name-qualifier identifier .
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.
The optional attribute-specifier-seq appertains to the module-declaration.
A module interface unit is a module unit whose module-declaration contains the 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.
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
:
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
]
[Example
:

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:
  • a primary module interface unit,
  • a module partition A:Foo, which is a module interface unit forming part of the interface of module A,
  • a module partition A:Internals, which does not contribute to the external interface of module A, and
  • 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
]
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.
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
:
The global module has no name, no module interface unit, and is not introduced by any module-declaration.
end note
]
A module is either a named module or the global module.
A declaration is attached to a module as follows:
A module-declaration that contains neither export nor a module-partition implicitly imports the primary module interface unit of the module as if by a module-import-declaration.
[Example
:

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]

export-declaration:
	export declaration
	export { declaration-seq }
An export-declaration shall appear only at namespace scope and only 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 declaration or its declaration-seq (if any).
An export-declaration does not establish a scope and its declaration or declaration-seq shall not contain an export-declaration.
A declaration is exported if it is
The interface of a module M is the set of all exported declarations within its purview.
[Example
:
export module M;
namespace A {                   // exported
  export int f();               // exported
  int g();                      // not exported
}
The interface of M comprises A and A::f.
end example
]
An exported declaration shall declare at least one name.
If the declaration is not within a header unit, it shall not declare a name with internal linkage.
[Example
:

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: does not introduce any names
export namespace {
  int a1;                       // error: export of name with 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;       // error: does not declare a name
end example
]
If the 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
:

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
:
These constraints do not apply to type names introduced by typedef declarations and alias-declarations.
[Example
:
export module M;
struct S;
export using T = S;             // OK, exports name T denoting type S
end example
]
end note
]
A redeclaration of an exported declaration of an entity is implicitly exported.
An exported redeclaration of a non-exported declaration of an entity is ill-formed.
[Example
:
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
]
A name is exported by a module if it is introduced or redeclared by an exported declaration in the purview of that module.
[Note
:
Exported names have either external linkage or no linkage; see [basic.link].
Namespace-scope names exported by a module are visible to name lookup in any translation unit importing that module; see [basic.scope.namespace].
Class and enumeration member names are visible to name lookup in any context in which a definition of the type is reachable.
end note
]
[Example
:

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
]
[Note
:
Redeclaring a name in an export-declaration cannot change the linkage of the name ([basic.link]).
[Example
:

Interface unit of M:

export module M;
static int f();                 // #1
export int f();                 // error: #1 gives internal linkage
struct S;                       // #2
export struct S;                // error: #2 gives module linkage
namespace {
  namespace N {
    extern int x;               // #3
  }
}
export int N::x;                // error: #3 gives internal linkage
end example
]
end note
]
[Note
:
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
:
export module M;
export namespace N {
  int x;                        // OK
  static_assert(1 == 1);        // error: does not declare a name
}
end example
]
end note
]

10.3 Import declaration [module.import]

module-import-declaration:
	export import module-name attribute-specifier-seq ;
	export import module-partition attribute-specifier-seq ;
	export import header-name attribute-specifier-seq ;
In a module unit, all module-import-declarations shall precede all other top-level-declarations in the top-level-declaration-seq of the translation-unit and of the private-module-fragment (if any).
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
]
A module-import-declaration that specifies a module-name M imports all module interface units of M.
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.
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.
H shall identify an importable header.
Two module-import-declarations import the same header unit if and only if their header-names identify the same header or source file ([cpp.include]).
[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.module].
end note
]
A declaration of a name with internal linkage is permitted within a header unit despite all declarations being implicitly exported ([module.interface]).
If such a declaration declares an entity that is odr-used outside the header unit, or by a template instantiation whose point of instantiation is outside the header unit, the program is ill-formed.
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.
When a module-import-declaration in a module unit imports another module unit of the same module, it also imports all translation units imported by all module-import-declarations in that module unit.
These rules may in turn lead to the importation of yet more translation units.
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
]
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
]
A translation unit has an interface dependency on a module unit U if it contains a module-declaration or module-import-declaration that imports U or if it has an interface dependency on a module 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
]

10.4 Global module fragment [module.global]

global-module-fragment:
	module ; top-level-declaration-seq
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.
[Note
:
Prior to phase 4 of translation, only preprocessing directives can appear in the global module fragment ([cpp.glob.frag]).
end note
]
A declaration D is decl-reachable from a declaration S in the same translation unit if:
  • 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
  • D declares a function or function template that is named by an expression ([basic.def.odr]) appearing in S, or
  • S contains an expression E of the form
    postfix-expression ( expression-list )
    
    whose postfix-expression denotes a dependent name, or for an operator expression whose operator denotes a dependent name, and D is found by name lookup for the corresponding name in 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
  • S contains an expression that takes the address of an overloaded function ([over.over]) whose set of overloads contains D and for which the target type is dependent, or
  • there exists a declaration M that is not a namespace-definition for which M is decl-reachable from S and either
    • D is decl-reachable from M, or
    • D redeclares the entity declared by M or M redeclares the entity declared by D, and D is neither a friend declaration nor a block-scope declaration, or
    • D declares a namespace N and M is a member of N, or
    • one of M and D declares a class or class template C and the other declares a member or friend of C, or
    • one of D and M declares an enumeration E and the other declares an enumerator of E, or
    • D declares a function or variable and M is declared in D,103 or
    • one of M and D declares a template and the other declares a partial or explicit specialization or an implicit or explicit instantiation of that template, or
    • one of M and D 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
  • whether a reference to an alias-declaration, typedef declaration, using-declaration, or namespace-alias-declaration is replaced by the declarations they name prior to this determination,
  • whether a simple-template-id that does not denote a dependent type and whose template-name names an alias template is replaced by its denoted type prior to this determination,
  • whether a decltype-specifier that does not denote a dependent type is replaced by its denoted type prior to this determination, and
  • whether a non-value-dependent constant expression is replaced by the result of constant evaluation prior to this determination.
A declaration D in a global module fragment of a module unit is discarded if D is not decl-reachable from any top-level-declaration in the top-level-declaration-seq of the translation unit.
[Note
:
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
]
[Example
:
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
]
[Example
:

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_­f
  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
]
A declaration can appear within a lambda-expression in the initializer of a variable.

10.5 Instantiation context [module.context]

The instantiation context is a set of points within the program that determines which names are visible to argument-dependent name lookup ([basic.lookup.argdep]) and which declarations are reachable ([module.reach]) in the context of a particular declaration or template instantiation.
During the implicit definition of a defaulted special member function ([special]), 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 special member function.
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 top-level-declaration-seq of the primary module interface unit of M (prior to the private-module-fragment, if any).
During the implicit instantiation of a template that is implicitly instantiated because it is referenced from within the implicit definition of a defaulted special member function, the instantiation context is the instantiation context of the defaulted special member function.
During the instantiation of any other template specialization, the instantiation context comprises the point of instantiation of the template.
In any other case, the instantiation context at a point within the program comprises that point.
[Example
:

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
  • the point at the end of translation unit #1,
  • the point at the end of translation unit #2, and
  • 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
  • the point at the end of translation unit #1,
  • the point at the end of translation unit #3, and
  • the point of the call to g(0),
so the definition of X is not necessarily reachable, as described in [module.reach].
end example
]

10.6 Reachability [module.reach]

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
:
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 visible to name lookup ([basic.scope.namespace]).
end note
]
All translation units that are necessarily reachable are reachable.
It is unspecified whether additional translation units on which the point within the program has an interface dependency are considered reachable, and under what circumstances.104
[Note
:
It is advisable to avoid depending on the reachability of any additional translation units in programs intending to be portable.
end note
]
A declaration D is reachable or necessarily reachable, respectively, if, for any point P in the instantiation context ([module.context]),
[Note
:
Whether a declaration is exported has no bearing on whether it is reachable.
end note
]
The accumulated properties of all reachable declarations of an entity within a context determine the behavior of the entity within that context.
[Note
:
These reachable semantic properties include type completeness, type definitions, initializers, default arguments of functions or template declarations, attributes, visibility of class or enumeration member names to ordinary lookup, 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
:

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:

module X;
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
]
[Note
:
An entity can have reachable declarations even if it is not visible to name lookup.
end note
]
[Example
:
export module A;
struct X {};
export using Y = X;

module B;
import A;
Y y;                // OK, definition of X is reachable
X x;                // ill-formed: X not visible to unqualified lookup
end example
]
Implementations are therefore not required to prevent the semantic effects of additional translation units involved in the compilation from being observed.