# Standard C++ Modules

```{contents}
:local:
```

## Introduction

The term `module` is ambiguous, as it is used to mean multiple things in
Clang. For Clang users, a module may refer to an `Objective-C Module`,
{doc}`Clang Module <Modules>` (also called a `Clang Header Module`) or a
`C++20 Module` (or a `Standard C++ Module`). The implementation of all
these kinds of modules in Clang shares a lot of code, but from the perspective
of users their semantics and command line interfaces are very different. This
document is an introduction to the use of C++20 modules in Clang. In the
remainder of this document, the term `module` will refer to Standard C++20
modules and the term `Clang module` will refer to the Clang Modules
extension.

In terms of the C++ Standard, modules consist of two components: "Named
Modules" or "Header Units". This document covers both.

## Standard C++ Named modules

In order to better understand the compiler's behavior, it is helpful to
understand some terms and definitions for readers who are not familiar with the
C++ feature. This document is not a tutorial on C++; it only introduces
necessary concepts to better understand use of modules in a project. Other
resources at [Wikipedia](<https://en.wikipedia.org/wiki/Modules_(C++)>) and
[cppreference](https://en.cppreference.com/w/cpp/language/modules.html) can
provide more background information about modules if needed.

### Background and terminology

#### Module and module unit

A module consists of one or more module units. A module unit is a special kind
of translation unit. A module unit should almost always start with a module
declaration. The syntax of the module declaration is:

```c++
[export] module module_name[:partition_name];
```

Terms enclosed in `[]` are optional. `module_name` and `partition_name`
follow the rules for a C++ identifier, except that they may contain one or more
period (`.`) characters. Note that a `.` in the name has no semantic
meaning and does not imply any hierarchy.

In this document, module units are classified as:

- Primary module interface unit
- Module implementation unit
- Module partition interface unit
- Internal module partition unit

A primary module interface unit is a module unit whose module declaration is
`export module module_name;` where `module_name` denotes the name of the
module. A module should have one and only one primary module interface unit.

A module implementation unit is a module unit whose module declaration is
`module module_name;`. Multiple module implementation units can be declared
in the same module.

A module partition interface unit is a module unit whose module declaration is
`export module module_name:partition_name;`. The `partition_name` should be
unique within any given module.

An internal module partition unit is a module unit whose module
declaration is `module module_name:partition_name;`. The `partition_name`
should be unique within any given module.

In this document, we use the following terms:

- A `module interface unit` refers to either a `primary module interface unit`
  or a `module partition interface unit`.
- An `importable module unit` refers to either a `module interface unit` or
  an `internal module partition unit`.
- A `module partition unit` refers to either a `module partition interface unit`
  or an `internal module partition unit`.

#### Built Module Interface

A `Built Module Interface` (or `BMI`) is the precompiled result of an
importable module unit.

#### Global module fragment

The `global module fragment` (or `GMF`) is the code between the `module;`
and the module declaration within a module unit.

### How to build projects using modules

#### Quick Start

Let's see a "hello world" example that uses modules.

```c++
// Hello.cppm
module;
#include <iostream>
export module Hello;
export void hello() {
  std::cout << "Hello World!\n";
}

// use.cpp
import Hello;
int main() {
  hello();
  return 0;
}
```

Then, on the command line, invoke Clang like:

```console
$ clang++ -std=c++20 Hello.cppm --precompile -o Hello.pcm
$ clang++ -std=c++20 use.cpp -fmodule-file=Hello=Hello.pcm Hello.pcm -o Hello.out
$ ./Hello.out
Hello World!
```

In this example, we make and use a simple module `Hello` which contains only a
primary module interface unit named `Hello.cppm`.

A more complex "hello world" example which uses the 4 kinds of module units is:

```c++
// M.cppm
export module M;
export import :interface_part;
import :impl_part;
export void Hello();

// interface_part.cppm
export module M:interface_part;
export void World();

// impl_part.cppm
module;
#include <iostream>
#include <string>
module M:impl_part;
import :interface_part;

std::string W = "World.";
void World() {
  std::cout << W << std::endl;
}

// Impl.cpp
module;
#include <iostream>
module M;
void Hello() {
  std::cout << "Hello ";
}

// User.cpp
import M;
int main() {
  Hello();
  World();
  return 0;
}
```

Then, back on the command line, invoke Clang with:

```console
# Precompiling the module
$ clang++ -std=c++20 interface_part.cppm --precompile -o M-interface_part.pcm
$ clang++ -std=c++20 impl_part.cppm --precompile -fprebuilt-module-path=. -o M-impl_part.pcm
$ clang++ -std=c++20 M.cppm --precompile -fprebuilt-module-path=. -o M.pcm
$ clang++ -std=c++20 Impl.cpp -fprebuilt-module-path=. -c -o Impl.o

# Compiling the user
$ clang++ -std=c++20 User.cpp -fprebuilt-module-path=. -c -o User.o

# Compiling the module and linking it together
$ clang++ -std=c++20 M-interface_part.pcm -fprebuilt-module-path=. -c -o M-interface_part.o
$ clang++ -std=c++20 M-impl_part.pcm -fprebuilt-module-path=. -c -o M-impl_part.o
$ clang++ -std=c++20 M.pcm -fprebuilt-module-path=. -c -o M.o
$ clang++ User.o M-interface_part.o  M-impl_part.o M.o Impl.o -o a.out
```

We explain the options in the following sections.

#### How to enable standard C++ modules

Standard C++ modules are enabled automatically when the language standard mode
is `-std=c++20` or newer.

#### How to produce a BMI

To generate a BMI for an importable module unit, use either the `--precompile`,
`--precompile-reduced-bmi`, or `-fmodule-output` command line options.

The `--precompile` option generates the BMI as the output of the compilation
with the output path specified using the `-o` option.

The `--precompile-reduced-bmi` option generates a Reduced BMI (See the
following section for the definition of Reduced BMI) as the output of
the compilation with the output path specified using the `-o` option.

The `-fmodule-output` option generates the BMI as a by-product of the
compilation. If `-fmodule-output=` is specified, the BMI will be emitted to
the specified location. If `-fmodule-output` and `-c` are specified, the
BMI will be emitted in the directory of the output file with the name of the
input file with the extension `.pcm`. Otherwise, the BMI will be emitted in
the working directory with the name of the input file with the extension
`.pcm`.

Generating BMIs with `--precompile` is referred to as two-phase compilation
because it takes two steps to compile a source file to an object file.
Generating BMIs with `-fmodule-output` is called one-phase compilation. The
one-phase compilation model is simpler for build systems to implement while the
two-phase compilation has the potential to compile faster due to higher
parallelism. As an example, if there are two module units `A` and `B`, and
`B` depends on `A`, the one-phase compilation model needs to compile them
serially, whereas the two-phase compilation model can be compiled as
soon as `A.pcm` is available, and thus can be compiled simultaneously with the
`A.pcm` to `A.o` compilation step.

#### File name requirements

By convention, `importable module unit` files should use `.cppm` (or
`.ccm`, `.cxxm`, or `.c++m`) as a file extension.
`Module implementation unit` files should use `.cpp` (or `.cc`, `.cxx`,
or `.c++`) as a file extension.

A BMI should use `.pcm` as a file extension. The file name of the BMI for a
`primary module interface unit` should be `module_name.pcm`. The file name
of a BMI for a `module partition unit` should be
`module_name-partition_name.pcm`.

Clang may fail to build the module if different extensions are used. For
example, if the filename of an `importable module unit` ends with `.cpp`
instead of `.cppm`, then Clang cannot generate a BMI for the
`importable module unit` with the `--precompile` option because the
`--precompile` option would only run the preprocessor (`-E`). If using a
different extension than the conventional one for an `importable module unit`
you can specify `-x c++-module` before the file. For example,

```c++
// Hello.cpp
module;
#include <iostream>
export module Hello;
export void hello() {
  std::cout << "Hello World!\n";
}

// use.cpp
import Hello;
int main() {
  hello();
  return 0;
}
```

In this example, the extension used by the `module interface` is `.cpp`
instead of `.cppm`, so it cannot be compiled like the previous example, but
it can be compiled with:

```console
$ clang++ -std=c++20 -x c++-module Hello.cpp --precompile -o Hello.pcm
$ clang++ -std=c++20 use.cpp -fprebuilt-module-path=. Hello.pcm -o Hello.out
$ ./Hello.out
Hello World!
```

#### Module name requirements

%

> [module.unit]p1:
>
> 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.

Therefore, none of the following names are valid by default:

```text
std
std1
std.foo
__test
// and so on ...
```

Using a reserved module name is strongly discouraged, but
`-Wno-reserved-module-identifier` can be used to suppress the warning.

#### Specifying BMI dependencies

There are 3 ways to specify a BMI dependency:

1. `-fprebuilt-module-path=<path/to/directory>`.
2. `-fmodule-file=<path/to/BMI>` (Deprecated).
3. `-fmodule-file=<module-name>=<path/to/BMI>`.

The `-fprebuilt-module-path` option specifies the path to search for
BMI dependencies. Multiple paths may be specified, similar to using `-I` to
specify a search path for header files. When importing a module `M`, the
compiler looks for `M.pcm` in the directories specified by
`-fprebuilt-module-path`. Similarly, when importing a partition module unit
`M:P`, the compiler looks for `M-P.pcm` in the directories specified by
`-fprebuilt-module-path`.

The `-fmodule-file=<path/to/BMI>` option causes the compiler to load the
specified BMI directly. The `-fmodule-file=<module-name>=<path/to/BMI>`
option causes the compiler to load the specified BMI for the module specified
by `<module-name>` when necessary. The main difference is that
`-fmodule-file=<path/to/BMI>` will load the BMI eagerly, whereas
`-fmodule-file=<module-name>=<path/to/BMI>` will only load the BMI lazily,
as will `-fprebuilt-module-path`. The `-fmodule-file=<path/to/BMI>` option
for named modules is deprecated and will be removed in a future version of
Clang.

When these options are specified in the same invocation of the compiler, the
`-fmodule-file=<path/to/BMI>` option takes precedence over
`-fmodule-file=<module-name>=<path/to/BMI>`, which takes precedence over
`-fprebuilt-module-path=<path/to/directory>`.

Note: all BMI dependencies must be specified explicitly, either directly or
indirectly. See <https://github.com/llvm/llvm-project/issues/62707> for details.

When compiling a `module implementation unit`, the BMI of the corresponding
`primary module interface unit` must be specified because a module
implementation unit implicitly imports the primary module interface unit.

> [module.unit]p8
>
> 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.

The `-fprebuilt-module-path=<path/to/directory>`, `-fmodule-file=<path/to/BMI>`,
and `-fmodule-file=<module-name>=<path/to/BMI>` options may be specified
multiple times. For example, the command line to compile `M.cppm` in
the previous example could be rewritten as:

```console
$ clang++ -std=c++20 M.cppm --precompile -fmodule-file=M:interface_part=M-interface_part.pcm -fmodule-file=M:impl_part=M-impl_part.pcm -o M.pcm
```

When there are multiple `-fmodule-file=<module-name>=` options for the same
`<module-name>`, the last `-fmodule-file=<module-name>=` overrides the
previous `-fmodule-file=<module-name>=` option.

#### Remember that module units still have an object counterpart to the BMI

While module interfaces resemble traditional header files, they still require
compilation. Module units are translation units, and need to be compiled to
object files, which then need to be linked together as the following examples
show.

For example, the traditional compilation processes for headers are like:

```text
src1.cpp -+> clang++ src1.cpp --> src1.o ---,
hdr1.h  --'                                 +-> clang++ src1.o src2.o ->  executable
hdr2.h  --,                                 |
src2.cpp -+> clang++ src2.cpp --> src2.o ---'
```

And the compilation processes for module units are like:

```text
              src1.cpp ----------------------------------------+> clang++ src1.cpp -------> src1.o -,
(header unit) hdr1.h    -> clang++ hdr1.h ...    -> hdr1.pcm --'                                    +-> clang++ src1.o mod1.o src2.o ->  executable
              mod1.cppm -> clang++ mod1.cppm ... -> mod1.pcm --,--> clang++ mod1.pcm ... -> mod1.o -+
              src2.cpp ----------------------------------------+> clang++ src2.cpp -------> src2.o -'
```

As the diagrams show, we need to compile the BMI from module units to object
files and then link the object files. (However, this cannot be done for the BMI
from header units. See the section on {ref}`header units <header-units>` for
more details.)

BMIs cannot be shipped in an archive to create a module library. Instead, the
BMIs(`*.pcm`) are compiled into object files(`*.o`) and those object files
are added to the archive instead.

#### clang-cl

`clang-cl` supports the same options as `clang++` for modules as detailed above;
there is no need to prefix these options with `/clang:`. Note that `cl.exe`
[options to emit/consume IFC files](https://devblogs.microsoft.com/cppblog/using-cpp-modules-in-msvc-from-the-command-line-part-1/) are *not* supported.
The resulting precompiled modules are also not compatible for use with `cl.exe`.

We recommend that build system authors use the above-mentioned `clang++` options with `clang-cl` to build modules.

#### Consistency Requirements

Modules can be viewed as a kind of cache to speed up compilation. Thus, like
other caching techniques, it is important to maintain cache consistency, which
is why Clang does very strict checking for consistency.

##### Options consistency

Compiler options related to the language dialect for a module unit and its
non-module-unit uses need to be consistent. Consider the following example:

```c++
// M.cppm
export module M;

// Use.cpp
import M;
```

```console
$ clang++ -std=c++20 M.cppm --precompile -o M.pcm
$ clang++ -std=c++23 Use.cpp -fprebuilt-module-path=.
```

Clang rejects the example due to the inconsistent language standard modes. Not
all compiler options are language-dialect options, though. For example:

```console
$ clang++ -std=c++20 M.cppm --precompile -o M.pcm
# Inconsistent optimization level.
$ clang++ -std=c++20 -O3 Use.cpp -fprebuilt-module-path=.
# Inconsistent debugging level.
$ clang++ -std=c++20 -g Use.cpp -fprebuilt-module-path=.
```

Although the optimization and debugging levels are inconsistent, these
compilations are accepted because the compiler options do not impact the
language dialect.

Note that the compiler **currently** doesn't reject inconsistent macro
definitions (this may change in the future). For example:

```console
$ clang++ -std=c++20 M.cppm --precompile -o M.pcm
# Inconsistent optimization level.
$ clang++ -std=c++20 -O3 -DNDEBUG Use.cpp -fprebuilt-module-path=.
```

Currently, Clang accepts the above example, though it may produce surprising
results if the debugging code depends on consistent use of `NDEBUG` in other
translation units.

##### Source Files Consistency

Clang may open the input files [^footnote-1] of a BMI during the compilation. This implies that
when Clang consumes a BMI, all the input files need to be present in the original path
and with the original contents.

To overcome these requirements and simplify cases like distributed builds and sandboxed
builds, users can use the `-fmodules-embed-all-files` flag to embed all input files
into the BMI so that Clang does not need to open the corresponding file on disk.

When the `-fmodules-embed-all-files` flag is enabled, Clang explicitly emits the source
code into the BMI file; the BMI file contains a sufficiently verbose
representation to reproduce the original source file.

[^footnote-1]: Input files: The source files which took part in the compilation of the BMI.
    For example:

    ```c++
    // M.cppm
    module;
    #include "foo.h"
    export module M;

    // foo.h
    #pragma once
    #include "bar.h"
    ```

    The `M.cppm`, `foo.h` and `bar.h` are input files for the BMI of `M.cppm`.

##### Object definition consistency

The C++ language requires that declarations of the same entity in different
translation units have the same definition, which is known as the One
Definition Rule (ODR). Without modules, the compiler cannot perform strong ODR
violation checking because it only sees one translation unit at a time. With
the use of modules, the compiler can perform checks for ODR violations across
translation units.

However, the current ODR checking mechanisms are not perfect. There are a
significant number of false positive ODR violation diagnostics, where the
compiler incorrectly diagnoses two identical declarations as having different
definitions. Further, true positive ODR violations are not always reported.

To give a better user experience, improve compilation performance, and for
consistency with MSVC, ODR checking of declarations in the global module
fragment is disabled by default. These checks can be enabled by specifying
`-Xclang -fno-skip-odr-check-in-gmf` when compiling. If the check is enabled
and you encounter incorrect or missing diagnostics, please report them via the
[community issue tracker](https://github.com/llvm/llvm-project/issues/).

### Privacy Issue

BMIs are not and should not be treated as an information hiding mechanism.
They should always be assumed to contain all the information that was used to
create them, in a recoverable form.

### ABI Impacts

This section describes the new ABI changes brought by modules. Only changes to
the Itanium C++ ABI are covered.

#### Name Mangling

The declarations in a module unit which are not in the global module fragment
have new linkage names.

For example,

```c++
export module M;
namespace NS {
  export int foo();
}
```

The linkage name of `NS::foo()` is `_ZN2NSW1M3fooEv`. This couldn't be
demangled by previous versions of the debugger or demangler. As of LLVM 15.x,
`llvm-cxxfilt` can be used to demangle this:

```console
$ llvm-cxxfilt _ZN2NSW1M3fooEv
  NS::foo@M()
```

The result should be read as `NS::foo()` in module `M`.

The ABI implies that something cannot be declared in a module unit and defined
in a non-module unit (or vice-versa), as this would result in linking errors.

Despite this, it is possible to implement declarations with a compatible ABI in
a module unit by using a language linkage specifier because the declarations in
the language linkage specifier are attached to the global module fragment. For
example:

```c++
export module M;
namespace NS {
  export extern "C++" int foo();
}
```

Now the linkage name of `NS::foo()` will be `_ZN2NS3fooEv`.

#### Module Initializers

All importable module units are required to emit an initializer function to
handle the dynamic initialization of non-inline variables in the module unit.
The importable module unit has to emit the initializer even if there is no
dynamic initialization; otherwise, the importer may call a nonexistent
function. The initializer function emits calls to imported modules first
followed by calls to all of the dynamic initializers in the current module
unit.

Translation units that explicitly or implicitly import a named module must call
the initializer functions of the imported named module within the sequence of
the dynamic initializers in the translation unit. Initializations of entities
at namespace scope are appearance-ordered. This (recursively) extends to
imported modules at the point of appearance of the import declaration.

If the imported module is known to be empty, the call to its initializer may be
omitted. Additionally, if the imported module is known to have already been
imported, the call to its initializer may be omitted.

### Reduced BMI

To support the two-phase compilation model, Clang puts everything needed to
produce an object into the BMI. However, other consumers of the BMI generally
don't need that information. This makes the BMI larger and may introduce
unnecessary dependencies for the BMI. To mitigate the problem, Clang has a
compiler option to reduce the information contained in the BMI. These two
formats are known as Full BMI and Reduced BMI, respectively.

Users can use the `-fmodules-reduced-bmi` or `--precompile-reduced-bmi`
option to produce a Reduced BMI.

The `--precompile-reduced-bmi` option will produce the reduced BMI
to the location specified by `-o`.

Note that `--precompile` will always generate the full BMI. So that build
system which may generate the BMI only should take care of this.

For the one-phase compilation model (CMake implements this model), with
`-fmodules-reduced-bmi`, the generated BMI will be a Reduced
BMI automatically. (The output path of the BMI is specified by
`-fmodule-output=` as usual with the one-phase compilation model).

It is also possible to produce a Reduced BMI with the two-phase compilation
model. When `-fmodules-reduced-bmi`, `--precompile`, and
`-fmodule-output=` are specified, the generated BMI specified by `-o` will
be a full BMI and the BMI specified by `-fmodule-output=` will be a Reduced
BMI. The dependency graph in this case would look like:

```none
module-unit.cppm --> module-unit.full.pcm -> module-unit.o
                  |
                  -> module-unit.reduced.pcm -> consumer1.cpp
                                             -> consumer2.cpp
                                             -> ...
                                             -> consumer_n.cpp
```

Clang does not emit diagnostics when `-fmodules-reduced-bmi` is
used with a non-module unit. This design permits users of the one-phase
compilation model to try using reduced BMIs without needing to modify the build
system. The two-phase compilation module requires build system support.

In a Reduced BMI, Clang does not emit unreachable entities from the global
module fragment, or definitions of non-inline functions and non-inline
variables. This may not be a transparent change.

Consider the following example:

```c++
// foo.h
namespace N {
  struct X {};
  int d();
  int e();
  inline int f(X, int = d()) { return e(); }
  int g(X);
  int h(X);
}

// M.cppm
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

// M-impl.cpp
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
```

In the above example, the function definition of `N::g` is elided from the
Reduced BMI of `M.cppm`. Then the use of `use_g<int>` in `M-impl.cpp`
fails to instantiate. For such issues, users can add references to `N::g` in
the [module purview](https://eel.is/c++draft/module.unit#5) of `M.cppm` to
ensure it is reachable, e.g. `using N::g;`.

As of Clang 22.x, the Reduced BMI is enabled by default. You may still want to
use Full BMI with `-fno-modules-reduced-bmi` in the following case:
1\. Your build system uses two-phase compilation, but it hasn't adjusted the
implementation for reduced BMI.
2\. You encounter a regression with Reduced BMI that you cannot work around. Please
report an issue for this case.

### Experimental Non-Cascading Changes

This section is primarily for build system vendors. For end compiler users,
if you don't want to read it all, this is helpful to reduce recompilations.
We encourage build system vendors and end users to try this out and bring feedback.

Before Clang 19, a change in BMI of any (transitive) dependency would cause the
outputs of the BMI to change. Starting with Clang 19, changes to non-direct
dependencies should not directly affect the output BMI, unless they affect the
results of the compilations. We expect that there are many more opportunities
for this optimization than we currently have realized and would appreciate
feedback about missed optimization opportunities. For example,

```c++
// m-partA.cppm
export module m:partA;

// m-partB.cppm
export module m:partB;
export int getB() { return 44; }

// m.cppm
export module m;
export import :partA;
export import :partB;

// useBOnly.cppm
export module useBOnly;
import m;
export int B() {
  return getB();
}

// Use.cc
import useBOnly;
int get() {
  return B();
}
```

To compile the project (for brevity, some commands are omitted.):

```console
$ clang++ -std=c++20 m-partA.cppm --precompile -o m-partA.pcm
$ clang++ -std=c++20 m-partB.cppm --precompile -o m-partB.pcm
$ clang++ -std=c++20 m.cppm --precompile -o m.pcm -fprebuilt-module-path=.
$ clang++ -std=c++20 useBOnly.cppm --precompile -o useBOnly.pcm -fprebuilt-module-path=.
$ md5sum useBOnly.pcm
07656bf4a6908626795729295f9608da  useBOnly.pcm
```

If the interface of `m-partA.cppm` is changed to:

```c++
// m-partA.v1.cppm
export module m:partA;
export int getA() { return 43; }
```

and the BMI for `useBOnly` is recompiled as in:

```console
$ clang++ -std=c++20 m-partA.cppm --precompile -o m-partA.pcm
$ clang++ -std=c++20 m-partB.cppm --precompile -o m-partB.pcm
$ clang++ -std=c++20 m.cppm --precompile -o m.pcm -fprebuilt-module-path=.
$ clang++ -std=c++20 useBOnly.cppm --precompile -o useBOnly.pcm -fprebuilt-module-path=.
$ md5sum useBOnly.pcm
07656bf4a6908626795729295f9608da  useBOnly.pcm
```

then the contents of `useBOnly.pcm` remain unchanged.
Consequently, if the build system only bases recompilation decisions on directly imported modules,
it becomes possible to skip the recompilation of `Use.cc`.
It should be fine because the altered interfaces do not affect `Use.cc` in any way;
the changes do not cascade.

When `Clang` generates a BMI, it records the hash values of all potentially contributory BMIs
for the BMI being produced. This ensures that build systems are not required to consider
transitively imported modules when deciding whether to recompile.

What is considered to be a potential contributory BMIs is currently unspecified.
However, it is a severe bug for a BMI to remain unchanged following an
observable change in the module source files that affects the module consumers.

Build systems may utilize this optimization by doing an update-if-changed operation to the BMI
that is consumed from the BMI that is output by the compiler.

We encourage build systems to add an experimental mode that
reuses the cached BMI when **direct** dependencies did not change,
even if **transitive** dependencies did change.

Given that there are potential compiler bugs, we recommend that build systems
support this feature as a configurable option so that users
can go back to the transitive change mode safely at any time.

#### Interactions with Reduced BMI

With reduced BMI, non-cascading changes can be more powerful. For example,

```c++
// A.cppm
export module A;
export int a() { return 44; }

// B.cppm
export module B;
import A;
export int b() { return a(); }
```

```console
$ clang++ -std=c++20 A.cppm -c -fmodule-output=A.pcm  -fmodules-reduced-bmi -o A.o
$ clang++ -std=c++20 B.cppm -c -fmodule-output=B.pcm  -fmodules-reduced-bmi -o B.o -fmodule-file=A=A.pcm
$ md5sum B.pcm
6c2bd452ca32ab418bf35cd141b060b9  B.pcm
```

And let's change the implementation for `A.cppm` to:

```c++
export module A;
int a_impl() { return 99; }
export int a() { return a_impl(); }
```

and recompile the example:

```console
$ clang++ -std=c++20 A.cppm -c -fmodule-output=A.pcm  -fmodules-reduced-bmi -o A.o
$ clang++ -std=c++20 B.cppm -c -fmodule-output=B.pcm  -fmodules-reduced-bmi -o B.o -fmodule-file=A=A.pcm
$ md5sum B.pcm
6c2bd452ca32ab418bf35cd141b060b9  B.pcm
```

We should find the contents of `B.pcm` remain the same. In this case, the build system is
allowed to skip recompilations of TUs which solely and directly depend on module `B`.

This only happens with a reduced BMI. With reduced BMIs, we won't record the function body
of `int b()` in the BMI for `B` so that the module `A` doesn't contribute to the BMI of `B`
and we have less dependencies.

### Performance Tips

#### Reduce duplications

While it is valid to have duplicated declarations in the global module fragments
of different module units, it is not free for Clang to deal with the duplicated
declarations. A translation unit will compile more slowly if there are a lot of
duplicated declarations between the translation unit and modules it imports.
For example:

```c++
// M-partA.cppm
module;
#include "big.header.h"
export module M:partA;
...

// M-partB.cppm
module;
#include "big.header.h"
export module M:partB;
...

// other partitions
...

// M-partZ.cppm
module;
#include "big.header.h"
export module M:partZ;
...

// M.cppm
export module M;
export import :partA;
export import :partB;
...
export import :partZ;

// use.cpp
import M;
... // use declarations from module M.
```

When `big.header.h` is big enough and there are a lot of partitions, the
compilation of `use.cpp` may be significantly slower than the following
approach:

```c++
module;
#include "big.header.h"
export module m:big.header.wrapper;
export ... // export the needed declarations

// M-partA.cppm
export module M:partA;
import :big.header.wrapper;
...

// M-partB.cppm
export module M:partB;
import :big.header.wrapper;
...

// other partitions
...

// M-partZ.cppm
export module M:partZ;
import :big.header.wrapper;
...

// M.cppm
export module M;
export import :partA;
export import :partB;
...
export import :partZ;

// use.cpp
import M;
... // use declarations from module M.
```

Reducing the duplication from textual includes is what improves compile-time
performance.

To help users to identify such issues, we add a warning `-Wdecls-in-multiple-modules`.
This warning is disabled by default and it needs to be explicitly enabled or by `-Weverything`.

### Transitioning to modules

It is best for new code and libraries to use modules from the start if
possible. However, it may be a breaking change for existing code or libraries
to switch to modules. As a result, many existing libraries need to provide
both headers and module interfaces for a while to not break existing users.

This section provides some suggestions on how to ease the transition process
for existing libraries. **Note that this information is only intended as
guidance, rather than as requirements to use modules in Clang.** It presumes
the project is starting with no module-based dependencies.

#### ABI non-breaking styles

##### export-using style

```c++
module;
#include "header_1.h"
#include "header_2.h"
...
#include "header_n.h"
export module your_library;
export namespace your_namespace {
  using decl_1;
  using decl_2;
  ...
  using decl_n;
}
```

This example shows how to include all the headers containing declarations which
need to be exported, and uses `using` declarations in an `export` block to
produce the module interface.

##### export extern-C++ style

```c++
module;
#include "third_party/A/headers.h"
#include "third_party/B/headers.h"
...
#include "third_party/Z/headers.h"
export module your_library;
#define IN_MODULE_INTERFACE
extern "C++" {
  #include "header_1.h"
  #include "header_2.h"
  ...
  #include "header_n.h"
}
```

Headers (from `header_1.h` to `header_n.h`) need to define the macro:

```c++
#ifdef IN_MODULE_INTERFACE
#define EXPORT export
#else
#define EXPORT
#endif
```

and put `EXPORT` on the declarations you want to export.

Also, it is recommended to refactor headers to include third-party headers
conditionally:

```c++
#ifndef IN_MODULE_INTERFACE
#include "third_party/A/headers.h"
#endif

#include "header_x.h"

...
```

This can be helpful because it gives better diagnostic messages if the module
interface unit is not properly updated when modifying code.

This approach works because the declarations with language linkage are attached
to the global module. Thus, the ABI of the modular form of the library does not
change.

While this style is more involved than the export-using style, it makes it
easier to further refactor the library to other styles.

#### ABI breaking style

The term `ABI breaking` may sound like a bad approach. However, this style
forces consumers of the library use it in a consistent way. e.g., either always
include headers for the library or always import modules. The style prevents
the ability to mix includes and imports for the library.

The pattern for ABI breaking style is similar to the export extern-C++ style.

```c++
module;
#include "third_party/A/headers.h"
#include "third_party/B/headers.h"
...
#include "third_party/Z/headers.h"
export module your_library;
#define IN_MODULE_INTERFACE
#include "header_1.h"
#include "header_2.h"
...
#include "header_n.h"

#if the number of .cpp files in your project are small
module :private;
#include "source_1.cpp"
#include "source_2.cpp"
...
#include "source_n.cpp"
#else // the number of .cpp files in your project are a lot
// Using all the declarations from third-party libraries which are
// used in the .cpp files.
namespace third_party_namespace {
  using third_party_decl_used_in_cpp_1;
  using third_party_decl_used_in_cpp_2;
  ...
  using third_party_decl_used_in_cpp_n;
}
#endif
```

(And add `EXPORT` and conditional include to the headers as suggested in the
export extern-C++ style section.)

The ABI with modules is different and thus we need to compile the source files
into the new ABI. This is done by an additional part of the interface unit:

```c++
#if the number of .cpp files in your project are small
module :private;
#include "source_1.cpp"
#include "source_2.cpp"
...
#include "source_n.cpp"
#else // the number of .cpp files in your project are a lot
// Using all the declarations from third-party libraries which are
// used in the .cpp files.
namespace third_party_namespace {
  using third_party_decl_used_in_cpp_1;
  using third_party_decl_used_in_cpp_2;
  ...
  using third_party_decl_used_in_cpp_n;
}
#endif
```

If the number of source files is small, everything can be put in the private
module fragment directly (it is recommended to add conditional includes to the
source files as well). However, compile time performance will be bad if there
are a lot of source files to compile.

**Note that the private module fragment can only be in the primary module
interface unit and the primary module interface unit containing the private
module fragment should be the only module unit of the corresponding module.**

In this case, source files (.cpp files) must be converted to module
implementation units:

```c++
#ifndef IN_MODULE_INTERFACE
// List all the includes here.
#include "third_party/A/headers.h"
...
#include "header.h"
#endif

module your_library;

// Following off should be unchanged.
...
```

The module implementation unit will import the primary module implicitly. Do
not include any headers in the module implementation units as it avoids
duplicated declarations between translation units. This is why non-exported
using declarations should be added from third-party libraries in the primary
module interface unit.

If the library is provided as `libyour_library.so`, a modular library (e.g.,
`libyour_library_modules.so`) may also need to be provided for ABI
compatibility.

##### What if there are headers only included by the source files

The above practice may be problematic if there are headers only included by the
source files. When using a private module fragment, this issue may be solved by
including those headers in the private module fragment. While it is OK to solve
it by including the implementation headers in the module purview when using
implementation module units, it may be suboptimal because the primary module
interface units now contain entities that do not belong to the interface.

This can potentially be improved by introducing a module partition
implementation unit. An internal module partition unit is an importable
module unit which is internal to the module itself.

##### The ABI of your library

You can skip this section your library doesn't ship ABI.

With the ABI breaking style, for every ABI you shipped in your library,
you should provide a corresponding ABI within the modules version.

For example, if this your library before provding modules,

```c++
// header.h
#pragma once

#include <cstdint>

namespace example {
class C {
public:
    std::size_t inline_get() { return 42; }
    std::size_t get();
};
}

// src.cpp
#include "header.h"

std::size_t example::C::get() {
    return 43 + inline_get();
}
```

Then you will ship ABI may be like:

```text
$nm -ACD libexample.so
libexample.so:0000000000001130 W example::C::inline_get()
libexample.so:0000000000001110 T example::C::get()
```

Then with ABI breaking style, your code may look like:

```c++
// example.cppm
export module example;
import std;
// and other third-party modules, if any
#define IN_MODULE_WRAPPER
#include "header.h" // omit changing of header.h for brevity

// src.module.cpp
module example;
#define IN_MODULE_IMPL
#include "src.cpp" // omit changing of src.cpp for brevity
```

And your ABI should look like:

```text
$llvm-nm -ACD libexample.so
libexample.so: 0000000000001060 T initializer for module example
libexample.so: 0000000000001150 W example::C::inline_get()
libexample.so: 0000000000001130 T example::C::get()
libexample.so: 0000000000001180 T example::C@example::inline_get()
libexample.so: 0000000000001160 T example::C@example::get()
```

Here `example::C@example::inline_get()` and `example::C@example::get()` is
the corresponding version for `example::C::inline_get()` and `example::C::get()`
in modules version.

##### Which part of the ABI will be broken?

While your library keeps ABI compatible by providing both ABI versions.
The users's ABI may be breaking if they used the ABI of modules' version.

This is similar with
[the famous ABI break in GCC 5's libstdc++ for C++11](https://gcc.gnu.org/onlinedocs/libstdc++/manual/using_dual_abi.html).

Although your library remains compatible with both ABIs, for your library's users,
choosing the module-based ABI will also break their ABI. For example, if your user's
code contains:

```c++
#include "header.h"

namespace user {
    void user_def(example::C& c) {

    }
}
```

then, (if your user will ship ABI too), their shipped ABI may look like:

```c++
$ llvm-nm -ACD libuser.so
libuser.so: 0000000000001100 T user::user_def(example::C&)
```

But when your user switches to your ABI-breaking style module:

```c++
import example;

namespace user {
    void user_def(example::C& c) {

    }
}
```

The corresponding ABI may look like:

```text
$ llvm-nm -ACD libuser.so
libuser.so: 0000000000001100 T user::user_def(example::C@example&)
```

Here we can find the ABI break from `user::user_def(example::C&)` to
`user::user_def(example::C@example&)`.

##### Less duplicated generated code

Another benefit of ABI breaking style is, it is more likely to modules native
style. So that compiler can generate the previously implicitly inline entities
(e.g., virtual tables, variables and functions)
to the module unit instead of generating them in every translation unit used.

e.g, for the above example, in header version, the definition of
`example::C::inline_get()` will be generated in every translation unit used.
But in modules version, `example::C::inline_get()` will only be generated once
in the module unit.

This is helpful for the whole build process to generate less duplicated code,
which will results in smaller binary size and faster compilation speed.

Note that for compatibility, the explicitly inline entities will still be inline
in modules. So that if you have explicitly inline entities and you're using
ABI breaking style, it is suggestted to use a macro to control inliness of the entity.

e.g.,

```c++
// your_header.h
#include <cstdint>

inline void your_interface() {}
```

within ABI breaking style, we suggest,

```c++
// your_header.h
#ifndef IN_MODULE_WRAPPER
#include <cstdint>
#endif

#ifdef IN_MODULE_WRAPPER
#define MY_EXPORT export
#else
#define MY_EXPORT
#endif

#ifdef IN_MODULE_WRAPPER
#define MY_INLINE
#else
#define MY_INLINE inline
#endif

MY_EXPORT MY_INLINE void your_interface() {}

// your_module_interface.cppm
export module your_library;
import std;
#define IN_MODULE_WRAPPER
#include "your_header.h"
```

So that `your_interface()` will not be inline in modules version.

#### Providing a header to skip parsing redundant headers

Many redeclarations shared between translation units cause Clang to have
slower compile-time performance. Further, there are known issues with
[include after import](https://github.com/llvm/llvm-project/issues/61465).
Even when that issue is resolved, users may still get slower compilation speed
and larger BMIs. For these reasons, it is recommended to not include headers
after importing the corresponding module. However, it is not always easy if the
library is included by other dependencies, as in:

```c++
#include "third_party/A.h" // #include "your_library/a_header.h"
import your_library;
```

or

```c++
import your_library;
#include "third_party/A.h" // #include "your_library/a_header.h"
```

For such cases, it is best if the library providing both module and header
interfaces also provides a header which skips parsing so that the library can
be imported with the following approach that skips redundant redeclarations:

```c++
import your_library;
#include "your_library_imported.h"
#include "third_party/A.h" // #include "your_library/a_header.h" but got skipped
```

The implementation of `your_library_imported.h` can be a set of controlling
macros or an overall controlling macro if using `#pragma once`. Then headers
can be refactored to:

```c++
#pragma once
#ifndef YOUR_LIBRARY_IMPORTED
...
#endif
```

If the modules imported by the library provide such headers, remember to add
them to `your_library_imported.h` too.

#### Importing modules

When there are library dependencies providing modules, the module dependencies
should be imported in your module as well. Many existing libraries will fall
into this category once the `std` module is more widely available.

##### All library dependencies providing modules

Of course, most of the complexity disappears if all the library dependencies
provide modules.

Headers need to be converted to include third-party headers conditionally. Then,
for the export-using style:

```c++
module;
import modules_from_third_party;
#define IN_MODULE_INTERFACE
#include "header_1.h"
#include "header_2.h"
...
#include "header_n.h"
export module your_library;
export namespace your_namespace {
  using decl_1;
  using decl_2;
  ...
  using decl_n;
}
```

or, for the export extern-C++ style:

```c++
export module your_library;
import modules_from_third_party;
#define IN_MODULE_INTERFACE
extern "C++" {
  #include "header_1.h"
  #include "header_2.h"
  ...
  #include "header_n.h"
}
```

or, for the ABI-breaking style,

```c++
export module your_library;
import modules_from_third_party;
#define IN_MODULE_INTERFACE
#include "header_1.h"
#include "header_2.h"
...
#include "header_n.h"

#if the number of .cpp files in your project are small
module :private;
#include "source_1.cpp"
#include "source_2.cpp"
...
#include "source_n.cpp"
#endif
```

Non-exported `using` declarations are unnecessary if using implementation
module units. Instead, third-party modules can be imported directly in
implementation module units.

##### Partial library dependencies providing modules

If the library has to mix the use of `include` and `import` in its module,
the primary goal is still the removal of duplicated declarations in translation
units as much as possible. If the imported modules provide headers to skip
parsing their headers, those should be included after the import. If the
imported modules don't provide such a header, one can be made manually for
improved compile time performance.

### Reachability of internal partition units

The internal partition units are sometimes called implementation partition units in other documentation.
However, the name may be confusing since implementation partition units are not implementation
units.

According to [[module.reach]p1](https://eel.is/c++draft/module.reach#1) and
[[module.reach]p2](https://eel.is/c++draft/module.reach#2) (from N4986):

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

For example,

```c++
// a.cpp
import B;
int main()
{
    g<void>();
}

// b.cppm
export module B;
import :C;
export template <typename T> inline void g() noexcept
{
    return f<T>();
}

// c.cppm
module B:C;
template<typename> inline void f() noexcept {}
```

The internal partition unit `c.cppm` is not necessarily reachable by
`a.cpp` because `c.cppm` is not a module interface unit and `a.cpp`
doesn't import `c.cppm`. This leaves it up to the compiler to decide if
`c.cppm` is reachable by `a.cpp` or not. Clang's behavior is that
indirectly imported internal partition units are not reachable.

The suggested approach for using an internal partition unit in Clang is
to only import them in the implementation unit.

### Using Clang Module Map to Avoid mixing #include and import problems

:::{note}
Discussion in this section is experimental.
:::

#### Problems Background

As discussed before, the redeclaration in different TU is one of the major problems
of using modules from the perspective of the compiler. The redeclaration pattern
is a major trigger of compiler bugs. And even if the compiler accepts the redeclaration
pattern as expected, the compilation performance will be affected too.

e.g,

```c++
// a.h
#pragma once
class A { ... };

// a.cppm
module;
#include "a.h"
export module a;
export using ::A;

// a.cc
import a;
#include "a.h"
A a;
```

Here in `a.cc`, we have redeclaration for `A`, one from `a.cppm` and one from `a.cc`
itself.

To avoid the redeclaration pattern, in previous section, we suggested users to comment
out thirdparty headers manually.

And here we will introduce another approach to avoid such redeclaration pattern by using
clang module map.

#### Clang Module Map Background

Clang Module Map is a feature of Clang Header Modules. See {doc}`Clang Module <Modules>`
for full introduction of Clang Header Modules. Here we would only introduce Clang Header
Modules to make this document self contained.

##### Clang Implicit Header Modules

In Clang Implicit Header Module mode, Clang will read the module map and compile the
header in the module map into a module file and use the module file automatically.
This sounds very nice. But due to the complexity, this is not so wonderful in practice.
Clang has to compile the same header in different preprocessor context into
different module file for correctness conservatively. Then this may trigger the
redeclaration in different TU problems. So that the user of implicit header modules
has to design a module system bottom up carefully. And clang implicit header module
[has many issues with soundness and performance due to tradeoffs made for module
reuse and filesystem contention](https://discourse.llvm.org/t/clang-modules-build-daemon-build-system-agnostic-support-for-explicitly-built-modules).

##### Clang Explicit Header Modules

Clang explicit header modules offloads the job of creating and managing module files
to the build system. Given the C++20 modules and clang header modules actually share the
same underlying implementation, it is actually possible to reuse the interface of clang module
map for C++20 named modules.

Technically, Clang Explicit Header Modules may be able to solve the redeclaration problem.
For the above example,

e.g,

```c++
// a.h
#pragma once
class A { ... };

// a.cppm
module;
#include "a.h"
export module a;
export using ::A;

// a.cc
import a;
#include "a.h"
A a;
```

The build system can build the header into a module file and use it in both `a.cppm` and `a.cc`.
Then there is no redeclaration in the example. All the declaration of `class A` come from the
synthesized TU `a.h`.

But there are problems: (1) the build system needs to support clang explicit module.
(2) The interaction between clang named modules and clang header modules are theoriticall fine but
not verified in practice. And also the document itself is about standard C++ modules, so we won't
expand here.

#### Examples

To use Clang Module Map for C++20 Named Modules, end users have to wait for the support
from build systems. Here we ignore the build systems to help users to understand the
mechanism.

Here is an example of using clang module map to replace a header to an import of a module.

```c++
// a.h
#pragma once
static_assert(false, "don't include a.h");

// main.cpp
#include "a.h"
int main() {
    return 0;
}

// a.cppm
module;
#include <iostream>
export module a;
struct Init {
    Init() {
        std::cout << "Module 'a' got imported" << std::endl;
    }
};
Init a;

// a.cppm.modulemap
module a {
  header "a.h"
}
```

Then invoke Clang with:

```console
$ clang++ -std=c++20 a.cppm -c -fmodule-output=a.pcm -o a.o
$ clang++ -std=c++20 main.cpp -fmodule-map-file=a.cppm.modulemap -fmodule-file=a=a.pcm a.o -o main
$ ./main
Module 'a' got imported
```

We can find that the header file `a.h` is not included actually (otherwise the compilation should fail due to the static assert).
And it imports the module `a` and then the varaible in module `a` got initialized.

The secret comes from the flag `-fmodule-map-file=a.cppm.modulemap`, the content of `a.cppm.modulemap` says:
map the #include of `a.h` to the import to module `a`. Then when the compiler sees `#include "a.h"`, the compiler
won't include `a.h` actually but tries to import the module `a`. And the from the command line `-fmodule-file=a=a.pcm`,
the compiler get the module file of module `a`, then module file of module `a` get imported and the inclusion of `a.h`
is skipped.

Then we can try to use the mechanism to avoid redeclaration pattern for header wrapping modules.

```c++
// a.h
#pragma once
class A { ... };

// a.cppm
module;
#include "a.h"
export module a;
export using ::A;

// a.cc
import a;
#include "a.h"
A a;

// a.cppm.modulemap
module a {
  header "a.h"
}
```

Similarly, when we compile `a.cc`, if we add the flag `-fmodule-map-file=a.cppm.modulemap`, the compiler
will map the inclusion of `a.h` to the import of module `a`. And the module `a` is already imported.
So we avoid the redeclaration of class `A` in `a.cc`.

An imaginable problem with this approach maybe the hidden inclusion. e.g,

```c++
// b.h
#pragma once
struct B {};

// a.h
#pragma once
#include "b.h"
struct A { B b; };

// b.cppm
export module b;
export extern "C++" struct B { };

// a.cppm
export module a;
import b;
export extern "C++" struct A { B b; };

// test.cc
import a;
#include "a.h"
A a;
B b;

// a.cppm.modulemap
module a {
  header "a.h"
}

// b.cppm.modulemap
module b {
  header "b.h"
}
```

The example is valid if we don't use the module map:

```console
$ clang++ -std=c++20 b.cppm -c -fmodule-output=b.pcm -o b.o
$ clang++ -std=c++20 a.cppm -c -fmodule-output=a.pcm -fmodule-file=b=b.pcm -o a.o
$ clang++ -std=c++20 test.cc -fmodule-file=a=a.pcm  -fmodule-file=b=b.pcm  -fsyntax-only
```

But if we enable the module map, the example is invalid:

```console
$ clang++ -std=c++20 test.cc -fmodule-map-file=a.cppm.modulemap -fmodule-file=a=a.pcm -fmodule-map-file=b.cppm.modulemap -fmodule-file=b=b.pcm -fsyntax-only
test.cc:4:1: error: declaration of 'B' must be imported from module 'b' before it is required
    4 | B b;
      | ^
b.cppm:2:28: note: declaration here is not visible
    2 | export extern "C++" struct B { };
      |                            ^
1 error generated.
```

#### A suggested convention for end users and build systems

As said, the build system is a vital role in this strategy.
However, for build systems, it is not easy to support clang explicit header modules or
support the module map with C++20 named modules generally. The complexity for build system
won't be less than supporting C++20 named modules.

So here we suggest a convention between end users and build systems to ease the implementation
burden of build systems and help end users to avoid the redeclaration problem from mixing #include
and import.

For end users who is the author of header based library offering named module wrappers, The header's interface
should be a subset of the module interface excluding user-facing macros.

- Extract all user facing headers into a single header file. Since C++20 named modules
- For each named module interface, provide a module map file to map the interface headers to the named module. The name of the module map should be the name of the module interface unit plus `.modulemap`.

The number of the module map may not be a lot sicne this is still a
header based library.

For build systems,

- For each Translation Units, if the unit doesn't import any named modules, stop. This is not what we want.
- If the TU imports named module, for all imported named module unit, look up for the module map file in the same path of the imported module unit with the name of the module unit plus `.modulemap`. e.g., if the name of the module unit is `a.cppm`, we should lookup for `a.cppm.modulemap`.
- For the found module map, pass `-fmodule-map-file=<module_map_file_path>` to the clang compiler.

The point of the approach is, the build system can reuse the result of C++20 named modules to manage depencies. So that
the implementation burden of build systems is largely reduced.

### Known Issues

The following describes issues in the current implementation of modules. Please
see
[the issues list for modules](https://github.com/llvm/llvm-project/labels/clang%3Amodules)
for a list of issues or to file a new issue if you don't find an existing one.
When creating a new issue for standard C++ modules, please start the title with
`[C++20] [Modules]` (or `[C++23] [Modules]`, etc) and add the label
`clang:modules` if possible.

A high-level overview of support for standards features, including modules, can
be found on the [C++ Feature Status](https://clang.llvm.org/cxx_status.html)
page.

#### Including headers after import is not well-supported

The following example is accepted:

```c++
#include <iostream>
import foo; // assume module 'foo' contain the declarations from `<iostream>`

int main(int argc, char *argv[])
{
    std::cout << "Test\n";
    return 0;
}
```

but if the order of `#include <iostream>` and `import foo;` is reversed,
then the code is currently rejected:

```c++
import foo; // assume module 'foo' contain the declarations from `<iostream>`
#include <iostream>

int main(int argc, char *argv[])
{
    std::cout << "Test\n";
    return 0;
}
```

Both of the above examples should be accepted.

This is a limitation of the implementation. In the first example, the compiler
will see and parse `<iostream>` first then it will see the `import`. In
this case, ODR checking and declaration merging will happen in the
deserializer. In the second example, the compiler will see the `import` first
and the `#include` second which results in ODR checking and declarations
merging happening in the semantic analyzer. This is due to a divergence in the
implementation path. This is tracked by
[#61465](https://github.com/llvm/llvm-project/issues/61465).

#### Ignored `preferred_name` Attribute

When Clang writes BMIs, it will ignore the `preferred_name` attribute on
declarations which use it. Thus, the preferred name will not be displayed in
the debugger as expected. This is tracked by
[#56490](https://github.com/llvm/llvm-project/issues/56490).

#### Inconsistent filename suffix requirement for importable module units

Currently, Clang requires the file name of an `importable module unit` to
have `.cppm` (or `.ccm`, `.cxxm`, `.c++m`) as the file extension.
However, the behavior is inconsistent with other compilers. This is tracked by
[#57416](https://github.com/llvm/llvm-project/issues/57416).

#### Incorrect ODR violation diagnostics

ODR violations are a common issue when using modules. Clang sometimes produces
false-positive diagnostics or fails to produce true-positive diagnostics of the
One Definition Rule. One often-reported example is:

```c++
// part.cc
module;
typedef long T;
namespace ns {
inline void fun() {
    (void)(T)0;
}
}
export module repro:part;

// repro.cc
module;
typedef long T;
namespace ns {
    using ::T;
}
namespace ns {
inline void fun() {
    (void)(T)0;
}
}
export module repro;
export import :part;
```

Currently the compiler incorrectly diagnoses the inconsistent definition of
`fun()` in two module units. Because both definitions of `fun()` have the
same spelling and `T` refers to the same type entity, there is no ODR
violation. This is tracked by
[#78850](https://github.com/llvm/llvm-project/issues/78850).

#### Using TU-local entity in other units

Module units are translation units, so the entities which should be local to
the module unit itself should never be used by other units.

The C++ standard defines the concept of `TU-local` and `exposure` in
[basic.link/p14](https://eel.is/c++draft/basic.link#14),
[basic.link/p15](https://eel.is/c++draft/basic.link#15),
[basic.link/p16](https://eel.is/c++draft/basic.link#16),
[basic.link/p17](https://eel.is/c++draft/basic.link#17), and
[basic.link/p18](https://eel.is/c++draft/basic.link#18).

However, Clang doesn't formally support these two concepts. This results in
unclear or confusing diagnostic messages. Further, Clang may import
`TU-local` entities to other units without any diagnostics. This is tracked
by [#78173](https://github.com/llvm/llvm-project/issues/78173).

(header-units)=

## Header Units

### How to build projects using header units

:::{warning}
The support for header units, including related command line options, is
experimental. There are still many unanswered questions about how tools
should interact with header units. The details described here may change in
the future.
:::

#### Quick Start

The following example:

```c++
import <iostream>;
int main() {
  std::cout << "Hello World.\n";
}
```

could be compiled with:

```console
$ clang++ -std=c++20 -xc++-system-header --precompile iostream -o iostream.pcm
$ clang++ -std=c++20 -fmodule-file=iostream.pcm main.cpp
```

#### How to produce BMIs

Similar to named modules, `--precompile` can be used to produce a BMI.
However, that requires specifying that the input file is a header by using
`-xc++-system-header` or `-xc++-user-header`.

The `-fmodule-header={user,system}` option can also be used to produce a BMI
for header units which have a file extension like `.h` or `.hh`. The argument to
`-fmodule-header` specifies either the user search path or the system search
path. The default value for `-fmodule-header` is `user`. For example:

```c++
// foo.h
#include <iostream>
void Hello() {
  std::cout << "Hello World.\n";
}

// use.cpp
import "foo.h";
int main() {
  Hello();
}
```

could be compiled with:

```console
$ clang++ -std=c++20 -fmodule-header foo.h -o foo.pcm
$ clang++ -std=c++20 -fmodule-file=foo.pcm use.cpp
```

For headers which do not have a file extension, `-xc++-header` (or
`-xc++-system-header`, `-xc++-user-header`) must be used to specify the
file as a header. For example:

```c++
// use.cpp
import "foo.h";
int main() {
  Hello();
}
```

```console
$ clang++ -std=c++20 -fmodule-header=system -xc++-header iostream -o iostream.pcm
$ clang++ -std=c++20 -fmodule-file=iostream.pcm use.cpp
```

#### How to specify BMI dependencies

`-fmodule-file` can be used to specify a BMI dependency (or multiple times for
more than one BMI dependency).

With the existing implementation, `-fprebuilt-module-path` cannot be used for
header units (because they are nominally anonymous). For header units, use
`-fmodule-file` to include the relevant PCM file for each header unit.

This is expected to be solved in a future version of Clang either by the compiler
finding and specifying `-fmodule-file` automatically, or by the use of a
module-mapper that understands how to map the header name to their PCMs.

#### Compiling a header unit to an object file

A header unit cannot be compiled to an object file due to the semantics of
header units. For example:

```console
$ clang++ -std=c++20 -xc++-system-header --precompile iostream -o iostream.pcm
# This is not allowed!
$ clang++ iostream.pcm -c -o iostream.o
```

#### Include translation

The C++ standard allows vendors to convert `#include header-name` to
`import header-name;` when possible. Currently, Clang does this translation
for the `#include` in the global module fragment. For example, the following
example:

```c++
module;
import <iostream>;
export module M;
export void Hello() {
  std::cout << "Hello.\n";
}
```

is the same as this example:

```c++
module;
#include <iostream>
export module M;
export void Hello() {
    std::cout << "Hello.\n";
}
```

```console
$ clang++ -std=c++20 -xc++-system-header --precompile iostream -o iostream.pcm
$ clang++ -std=c++20 -fmodule-file=iostream.pcm --precompile M.cppm -o M.cpp
```

In the latter example, Clang can find the BMI for `<iostream>` and so it
tries to replace the `#include <iostream>` with `import <iostream>;`
automatically.

### Differences between Clang modules and header units

Header units have similar semantics to Clang modules. The semantics of both are
like headers. Therefore, header units can be mimicked by Clang modules as in
the following example:

```c++
module "iostream" {
  export *
  header "/path/to/libstdcxx/iostream"
}
```

```console
$ clang++ -std=c++20 -fimplicit-modules -fmodule-map-file=.modulemap main.cpp
```

This example is simplified when using libc++:

```console
$ clang++ -std=c++20 main.cpp -fimplicit-modules -fimplicit-module-maps
```

because libc++ already supplies a
[module map](https://github.com/llvm/llvm-project/blob/main/libcxx/include/module.modulemap.in).

This raises the question: why are header units not implemented through Clang
modules?

This is primarily because Clang modules have more hierarchical semantics when
wrapping multiple headers together as one module, which is not supported by
Standard C++ Header units. We want to avoid the impression that these
additional semantics get interpreted as Standard C++ behavior.

Another reason is that there are proposals to introduce module mappers to the
C++ standard (for example, <https://wg21.link/p1184r2>). Reusing Clang's
`modulemap` may be more difficult if we need to introduce another module
mapper.

## Discovering Dependencies

Without use of modules, all the translation units in a project can be compiled
in parallel. However, the presence of module units requires compiling the
translation units in a topological order.

The `clang-scan-deps` tool can extract dependency information and produce a
JSON file conforming to the specification described in
[P1689](https://www.open-std.org/jtc1/sc22/wg21/docs/papers/2022/p1689r5.html).
Only named modules are supported currently.

A compilation database is needed when using `clang-scan-deps`. See
{doc}`JSON Compilation Database Format Specification <JSONCompilationDatabase>`
for more information about compilation databases. Note that the `output`
JSON attribute is necessary for `clang-scan-deps` to scan using the P1689
format. For example:

```c++
//--- M.cppm
export module M;
export import :interface_part;
import :impl_part;
export int Hello();

//--- interface_part.cppm
export module M:interface_part;
export void World();

//--- Impl.cpp
module;
#include <iostream>
module M;
void Hello() {
    std::cout << "Hello ";
}

//--- impl_part.cppm
module;
#include <string>
#include <iostream>
module M:impl_part;
import :interface_part;

std::string W = "World.";
void World() {
    std::cout << W << std::endl;
}

//--- User.cpp
import M;
import third_party_module;
int main() {
  Hello();
  World();
  return 0;
}
```

And here is the compilation database:

```text
[
{
    "directory": ".",
    "command": "<path-to-compiler-executable>/clang++ -std=c++20 M.cppm -c -o M.o",
    "file": "M.cppm",
    "output": "M.o"
},
{
    "directory": ".",
    "command": "<path-to-compiler-executable>/clang++ -std=c++20 Impl.cpp -c -o Impl.o",
    "file": "Impl.cpp",
    "output": "Impl.o"
},
{
    "directory": ".",
    "command": "<path-to-compiler-executable>/clang++ -std=c++20 impl_part.cppm -c -o impl_part.o",
    "file": "impl_part.cppm",
    "output": "impl_part.o"
},
{
    "directory": ".",
    "command": "<path-to-compiler-executable>/clang++ -std=c++20 interface_part.cppm -c -o interface_part.o",
    "file": "interface_part.cppm",
    "output": "interface_part.o"
},
{
    "directory": ".",
    "command": "<path-to-compiler-executable>/clang++ -std=c++20 User.cpp -c -o User.o",
    "file": "User.cpp",
    "output": "User.o"
}
]
```

To get the dependency information in P1689 format, use:

```console
$ clang-scan-deps -format=p1689 -compilation-database P1689.json
```

to get:

```text
{
  "revision": 0,
  "rules": [
    {
      "primary-output": "Impl.o",
      "requires": [
        {
          "logical-name": "M",
          "source-path": "M.cppm"
        }
      ]
    },
    {
      "primary-output": "M.o",
      "provides": [
        {
          "is-interface": true,
          "logical-name": "M",
          "source-path": "M.cppm"
        }
      ],
      "requires": [
        {
          "logical-name": "M:interface_part",
          "source-path": "interface_part.cppm"
        },
        {
          "logical-name": "M:impl_part",
          "source-path": "impl_part.cppm"
        }
      ]
    },
    {
      "primary-output": "User.o",
      "requires": [
        {
          "logical-name": "M",
          "source-path": "M.cppm"
        },
        {
          "logical-name": "third_party_module"
        }
      ]
    },
    {
      "primary-output": "impl_part.o",
      "provides": [
        {
          "is-interface": false,
          "logical-name": "M:impl_part",
          "source-path": "impl_part.cppm"
        }
      ],
      "requires": [
        {
          "logical-name": "M:interface_part",
          "source-path": "interface_part.cppm"
        }
      ]
    },
    {
      "primary-output": "interface_part.o",
      "provides": [
        {
          "is-interface": true,
          "logical-name": "M:interface_part",
          "source-path": "interface_part.cppm"
        }
      ]
    }
  ],
  "version": 1
}
```

See the P1689 paper for the meaning of the fields.

Getting dependency information per file with finer-grained control (such as
scanning generated source files) is possible. For example:

```console
$ clang-scan-deps -format=p1689 -- <path-to-compiler-executable>/clang++ -std=c++20 impl_part.cppm -c -o impl_part.o
```

will produce:

```text
{
  "revision": 0,
  "rules": [
    {
      "primary-output": "impl_part.o",
      "provides": [
        {
          "is-interface": false,
          "logical-name": "M:impl_part",
          "source-path": "impl_part.cppm"
        }
      ],
      "requires": [
        {
          "logical-name": "M:interface_part"
        }
      ]
    }
  ],
  "version": 1
}
```

Individual command line options can be specified after `--`.
`clang-scan-deps` will extract the necessary information from the specified
options. Note that the path to the compiler executable needs to be specified
explicitly instead of using `clang++` directly.

Users may want the scanner to get the transitive dependency information for
headers. Otherwise, the project has to be scanned twice, once for headers and
once for modules. To address this, `clang-scan-deps` will recognize the
specified preprocessor options in the given command line and generate the
corresponding dependency information. For example:

```console
$ clang-scan-deps -format=p1689 -- ../bin/clang++ -std=c++20 impl_part.cppm -c -o impl_part.o -MD -MT impl_part.ddi -MF impl_part.dep
$ cat impl_part.dep
```

will produce:

```text
impl_part.ddi: \
  /usr/include/bits/wchar.h /usr/include/bits/types/wint_t.h \
  /usr/include/bits/types/mbstate_t.h \
  /usr/include/bits/types/__mbstate_t.h /usr/include/bits/types/__FILE.h \
  /usr/include/bits/types/FILE.h /usr/include/bits/types/locale_t.h \
  /usr/include/bits/types/__locale_t.h \
  ...
```

When `clang-scan-deps` detects the `-MF` option, it will try to write the
dependency information for headers to the file specified by `-MF`.

### Possible Issues: Failed to find system headers

If encountering an error like `fatal error: 'stddef.h' file not found`,
the specified `<path-to-compiler-executable>/clang++` probably refers to a
symlink instead of a real binary. There are four potential solutions to the
problem:

1. Point the specified compiler executable to the real binary instead of the
   symlink.

2. Invoke `<path-to-compiler-executable>/clang++ -print-resource-dir` to get
   the corresponding resource directory for your compiler and add that
   directory to the include search paths manually in the build scripts.

3. For build systems that use a compilation database as the input for
   `clang-scan-deps`, the build system can add the
   `--resource-dir-recipe invoke-compiler` option when executing
   `clang-scan-deps` to calculate the resource directory dynamically.
   The calculation happens only once for a unique `<path-to-compiler-executable>/clang++`.

4. For build systems that invoke `clang-scan-deps` per file, repeatedly
   calculating the resource directory may be inefficient. In such cases, the
   build system can cache the resource directory and specify
   `-resource-dir <resource-dir>` explicitly, as in:

   ```console
   $ clang-scan-deps -format=p1689 -- <path-to-compiler-executable>/clang++ -std=c++20 -resource-dir <resource-dir> mod.cppm -c -o mod.o
   ```

## Import modules with clang-repl

`clang-repl` supports importing C++20 named modules. For example:

```c++
// M.cppm
export module M;
export const char* Hello() {
    return "Hello Interpreter for Modules!";
}
```

The named module still needs to be compiled ahead of time.

```console
$ clang++ -std=c++20 M.cppm --precompile -o M.pcm
$ clang++ M.pcm -c -o M.o
$ clang++ -shared M.o -o libM.so
```

Note that the module unit needs to be compiled as a dynamic library so that
`clang-repl` can load the object files of the module units. Then it is
possible to import module `M` in clang-repl.

```console
$ clang-repl -Xcc=-std=c++20 -Xcc=-fprebuilt-module-path=.
# We need to load the dynamic library first before importing the modules.
clang-repl> %lib libM.so
clang-repl> import M;
clang-repl> extern "C" int printf(const char *, ...);
clang-repl> printf("%s\n", Hello());
Hello Interpreter for Modules!
clang-repl> %quit
```

## Possible Questions

### How modules speed up compilation

A classic theory for the reason why modules speed up the compilation is: if
there are `n` headers and `m` source files and each header is included by
each source file, then the complexity of the compilation is `O(n*m)`.
However, if there are `n` module interfaces and `m` source files, the
complexity of the compilation is `O(n+m)`. Therefore, using modules would be
a significant improvement at scale. More simply, use of modules causes many of
the redundant compilations to no longer be necessary.

While this is accurate at a high level, this depends greatly on the
optimization level, as illustrated below.

First is `-O0`. The compilation process is described in the following graph.

```none
├-------------frontend----------┼-------------middle end----------------┼----backend----┤
│                               │                                       │               │
└---parsing----sema----codegen--┴----- transformations ---- codegen ----┴---- codegen --┘

├---------------------------------------------------------------------------------------┐
|                                                                                       │
|                                     source file                                       │
|                                                                                       │
└---------------------------------------------------------------------------------------┘

            ├--------┐
            │        │
            │imported│
            │        │
            │  code  │
            │        │
            └--------┘
```

In this case, the source file (which could be a non-module unit or a module
unit) would get processed by the entire pipeline. However, the imported code
would only get involved in semantic analysis, which, for the most part, is name
lookup, overload resolution, and template instantiation. All of these processes
are fast relative to the whole compilation process. More importantly, the
imported code only needs to be processed once during frontend code generation,
as well as the whole middle end and backend. So we could get a big win for the
compilation time in `-O0`.

But with optimizations, things are different (the `code generation` part for
each end is omitted due to limited space):

```none
├-------- frontend ---------┼--------------- middle end --------------------┼------ backend ----┤
│                           │                                               │                   │
└--- parsing ---- sema -----┴--- optimizations --- IPO ---- optimizations---┴--- optimizations -┘

├-----------------------------------------------------------------------------------------------┐
│                                                                                               │
│                                         source file                                           │
│                                                                                               │
└-----------------------------------------------------------------------------------------------┘
              ├---------------------------------------┐
              │                                       │
              │                                       │
              │            imported code              │
              │                                       │
              │                                       │
              └---------------------------------------┘
```

It would be very unfortunate if we end up with worse performance when using
modules. The main concern is that when a source file is compiled, the compiler
needs to see the body of imported module units so that it can perform IPO
(InterProcedural Optimization, primarily inlining in practice) to optimize
functions in the current source file with the help of the information provided
by the imported module units. In other words, the imported code would be
processed again and again in importee units by optimizations (including IPO
itself). The optimizations before IPO and IPO itself are the most time-consuming
part in whole compilation process. So from this perspective, it might not be
possible to get the compile time improvements described, but there could be
time savings for optimizations after IPO and the whole backend.

Overall, at `-O0` the implementations of functions defined in a module will
not impact module users, but at higher optimization levels the definitions of
such functions are provided to user compilations for the purposes of
optimization (but definitions of these functions are still not included in the
use's object file). This means the build speedup at higher optimization levels
may be lower than expected given `-O0` experience, but does provide more
optimization opportunities.

### Interoperability with Clang Modules

We **wish** to support Clang modules and standard C++ modules at the same time,
but the mixing them together is not well used/tested yet. Please file new
GitHub issues as you find interoperability problems.
