C++ Modules

A module system is coming to C++20, this page describes the GCC implementation state.

A module system will provide several benefits:

Implementation State

The modules branch has been merged to trunk, please use the usual trunk build procedure and report bugs in Bugzilla.

The implementation has a few known missing features:

Of course there are bugs in it :)

Invoking the Compiler

There are several new options for modules:

More complete documentation is in the GCC manual under 'C++ Modules'.

CMI Location

Compiling a module interface TU generates a Compiled Module Interface. This CMI is read in by the module's implementation TUs and each importer of the module. There's clearly a dependency between these things, which is different from header files because we have to invoke the compiler to generate the CMI.

To resolve this dependency, a module mapper is queried whenever a CMI name is needed. Communication is via a text-based protocol, which provides mechanism without policy. As such the compiler itself is completely agnostic about where CMIs are or how they are named. Build systems may provide a build-specific mapper. If no module mapper has been specified, a default is provided. It is expected that the behaviour of the default mapper will mature.

The -fmodule-mapper value may be one of:

The first four may specify an ident to provide to the remote mapper, by affixing a trailing ?ident to the first component of the argument. For instance =/tmp/mybuild?shibboleth7, or |build-mapper?shibboleth8 bob. If no ident is specified, the name of the main source file is used in its place. Parallel builds could use the ident to distinguish connections from different compiler instances. The protocol does not provide a general purpose compilation mechanism, is not to be exposed beyond one's local security zone, & is not cryptographically hard.

The protocol is documented in the GCC manual. And published in p1184 (https://wg21.link/p1184). It will have matured since p1184, the GCC manual is the canonical specification (but may be buggy).

The CMI is not a distributable artifact. Think of it as a cache, that can be recreated as needed.

Design

There are three main pieces of work, (a) streaming to disk, (b) name lookup (c) cross-module references.

The original plan was to try and reuse LTO's streaming technology for the former. But that turned out to be impractical as there is not much overlap. LTO streams GIMPLE and language-agnostic type information. Modules need AST representation and FE type information. So I went the hand-written auto-numbering streaming route.

Name lookup started by abusing inline namespaces, but that too proved impractical. We'd need the ability to turn these namespaces on and off, and to do that requires changes to name-lookup. Once you're making that kind of change, one may as well do it properly. As a benefit, name-lookup has gotten a lot cleaner.

Cross-module references originally relied on name-lookup and the specialization table. This became impractical as the specification changed, and some C++ features (I'm looking at you, implicit member functions), broke the invariants that relied upon. These are now done via an indexing table, independent of name-lookup. The last 3 months of 2019 were spent morphing the compiler to that scheme.

ATOM

The ATOM proposal deviated from the TS in a few ways. Now (October 2018) ATOM is no longer a separate flag, having been merged in p1103r2 (https://wg21.link/p1103). The 4 distinguishing features of ATOM are:

Mangling

Name mangling needs to be adjusted to deal with module-linkage. This is a compiler-interoperability and toolchain issue, as we want objects from different compilers to be link-compatible, and the debugger able to understand module symbols.

Current thoughts are described in module-abi-2017-09-01.pdf.

Module Linkage

I am not presuming any new linker technology. Module ownership is a new concept, and at least for module-linkage entities, must be reflected in the name mangling. Exported names need not reflect this ownership.

I am working with the Clang developers to define interoperable changes here. To facilitate migration of code, mangling of exported entities does not change from what they would have outside of a module.

Compiled Module Interface Files

As mentioned above, a CMI is generated during the compilation of a module interface unit. For GCC I'm generating it as an on-the-side entity, but it could be stashed as a special section in the output assembly file, or even be a new stage of compilation. (Clang is taking this last approach.) The data is encapsulated in an ELF-like file. You can use 'readelf -S' to get at the sections it contains, and 'readelf -p .gnu.c++.README' to get at its human-readable section. (ELF is used even on non-elf systems, we do not rely on ELF tools being present.) There are several specially-named sections, which generate the set of namespace-scope bindings. The actual binding values are held in sections named by a decl within them. We support lazy loading via cooperation with the name-lookup machinery. If it finds a lazy binding, it invokes the loader to load that binding. This loading may recurse, but we take care to make sure loops do not occur (this is non-trivial with C++).

Recompiling a TU with exactly the same options will produce a CMI that is equivalent, which is what you want with a cache. It does contain CRCs, which are used to detect corruption. I've not made corruption detection cryptographically strong or anything, I do not presume an adversarial attacker. If we detect corruption, you should get an error and then compilation terminates with a fatal error -- the likelihood of any further diagnostics being meaningful is negligible.

The README sections of the CMI are not read by the compiler, nor contribute to an consistency checks. Thus they can change without invalidating the rest of the CMI. Mutable build information is stored here (build time, host name etc). I may add an option to provide bit-identical CMIs.

CMIs are relocatable within the file system, or copyable to another machine, which you might want with a distributed build. They refer to their own imports by reference, naming both the import module, and the (relative) location of the CMI that was loaded. If you copy a CMI you must recursively copy all its imports and recreate the same file structure (these can be found by examining the README section). If you give the compiler an absolute path (for instance your include-path), that absolute path will end up in the CMI. I may add an option expunge, prefix or relocate file-system-absolute paths.

Example

Put the following in hello.cc: 

module;
#include <iostream>
#include <string_view>
export module hello;
export void greeter (std::string_view const &name)
{
  std::cout << "Hello " << name << "!\n";
}

and put the following in main.cc: 

import hello;
int main (void)
{
  greeter ("world");
  return 0;
}

Now compile with: 

g++ -fmodules-ts hello.cc main.cc

You can run the a.out: 

bester:7>./a.out
Hello world!

Notice that main.cc did not #include <string_view> — it doesn't need to, because it never names that type. The type itself becomes known about due to the exported declaration greeter.

Global Module

The Global Module exists to allow legacy C++ headers to be used in a module. The Global Module's contents derive from two sources:

Header Units are traditional header files that are (separately) compiled with the -fmodule-header flag. They each produce a BMI, and are imported into user code with an import declaration naming a header unit: 

import <iostream>;
import "otherheader.h";

The Global Module Fragment's contents are header files that are included before a module declaration: 

module;
#include <iostream>
#include "otherheader.h"
export module Quux;
...

Header Units can be imported into both module and non-module code. The Global Module Fragment is only relevant to modules themselves. Regular non-module code is also in the Global Module. One aspect of the Global Module is that entities can be declared, or even defined, in multiple places -- because that's how header files work. The compiler has to merge these declarations, but can rely on the ODR to presume they are 'the same'.

Another thing is that Header Units export macros. That's unavoidable if one wants to treat a header file as a header unit.

Timeline

Random Cleanups

I've been making some random cleanups to the code base:

Documentation

I wrote some papers:

I also presented work at:

None: cxx-modules (last edited 2021-01-18 16:30:20 by NathanSidwell)