C++20 Modules

For a long time, the #include directive has been the primary way we import functionality from C++ libraries and organize more significant projects. However, it is an excessively crude approach, effectively copying all the code from one source file and pasting it to another. As we covered previously, this has some issues:

• A source file can be included multiple times into the same destination, prompting us to always implement header guards like #pragma once
• An immense amount of code can be pasted into our files, causing them to take longer to compile than necessary. On larger projects, this forces us to do yet more manual workarounds to keep compilation times down, such as maintaining precompiled header files
• The crudeness of the preprocessor can cause subtle bugs that are difficult to track down, such as our program behaving differently depending on the order of our #include directives

It is an ongoing mission of the C++ community to reduce the dependency on the preprocessor. In the C++20 spec, an alternative to the #include directive was introduced. They are called modules.

Module import Statements

Previously, we imported iostream (and similar headers) using the #include directive as follows:

1#include <iostream>
2
3int main() {
4  std::cout << "Hello World!";
5}
6

To use the equivalent module, we update our code to use the import statement, as below:

1import <iostream>;
2
3int main() {
4  std::cout << "Hello World!";
5}
6

Note, import is a C++ statement rather than a preprocessor directive, so we end it with a semicolon ; like any other statement.

Creating a Module

To create our own module, we need to create a module interface file. This is just a typical file that will contain C++ code, similar to the .cpp or .h files we’ve been creating. There is no agreed convention on naming yet, but using the extension .cppm for a module interface file is becoming common.

On the first line of our module interface file, we use two new keywords, export, and module, followed by a name we want to give our module. The naming restrictions for modules broadly follow the same rules as naming variables.

Here, we define a module called Math:

1// Math.cppm
2export module Math;
3

Within this file, we can write C++ code as normal:

1// Math.cppm
2export module Math;
3import <iostream>;
4
5namespace Math {
6void SayHello() {
7  std::cout << "Hello!";
8};
9};
10
11constexpr float Pi{3.14};
12void SomeMathFunction(){};
13class SomeClass {};
14using Alias = SomeClass;
15

Unlike the traditional #include directive, modules support encapsulation natively. We can decide which parts of our module are private, and which parts are public.

By default, everything is private. So, the namespace, class and everything we defined in the previous example is private - it is not part of the module interface.

Module Exports

Our module can be selective with what it wants to make public. We do this by adding the export keyword before anything we want to be part of our public interface.

Pretty much anything with an identifier can be exported - variables, functions, using statements, classes, structs, namespaces, and more.

Below, we export our Pi variable and our Math namespace. When a namespace is exported, all of its members are automatically exported too:

1// Math.cppm
2export module Math;
3import <iostream>;
4
5// Public
6export namespace Math {
7void SayHello() {
8  std::cout << "Hello!";
9};
10};
11
12export constexpr float Pi{3.14};
13
14// Private
15void SomeMathFunction(){};
16class SomeClass {};
17using Alias = SomeClass;
18

In one of our other files, we can now import our module and use its exported features:

1// main.cpp
2import <iostream>;
3import Math;
4
5int main() {
6  std::cout << Pi;
7  Math::SayHello();
8
9  // Error - not exported
10  SomeMathFunction();
11}
12

Module Export Blocks

We can export multiple identifiers at once from our module using an export block:

1export module Math;
2import <iostream>;
3
4export {
5  namespace Math {
6  void SayHello() {
7    std::cout << "Hello!";
8  };
9  };
10
11  constexpr float Pi{3.14};
12}
13
14void SomeMathFunction(){};
15class SomeClass {};
16using Alias = SomeClass;
17
18export void Blah(){};
19

Module Transitive Dependencies

With the #include directive, we saw that the inclusion was recursively. A single #include directive can paste in a file that itself has yet more #include directives, and that continues any number of levels deep.

Below, our main.cpp is using iostream functions even though it is not including them. It is gaining indirect access to them by including a file that happens to include <iostream>:

1// Greetings.h
2#pragma once
3#include <iostream>
4
5void Greet() {
6  std::cout << "Hello!";
7}
8

1// main.cpp
2#include "Greetings.h";
3
4int main() {
5  Greet();
6  std::cout << "\nHello!";
7}
8

1Hello!
2Hello!
3

Our code having hidden dependencies like this is not a good thing. In complex projects, changes in unrelated files causing other files to stop compiling is a headache.

C++ modules do away with this. When we import a module, its sub-dependencies don’t magically become visible in the file we imported it to:

1// Greetings.cppm
2export module Greetings;
3import <iostream>;
4
5export void Greet() {
6  std::cout << "\nHello!";
7}
8

1// main.cpp
2import Greetings;
3
4int main() {
5  Greet();
6  std::cout << "Hello!";
7}
8

In this example, we have not imported <iostream> into main.cpp, so the use of std::cout is problematic.

The phrases commonly used to describe this distinction are reachable vs visible. Within main.cpp in this example, std::cout is reachable, so line 4 works. But, it is not visible, so line 5 is not valid.

For std::cout to be visible, the file where it is defined needs to be imported explicitly:

1// main.cpp
2import Greetings;
3import <iostream>;
4
5int main() {
6  Greet();
7  std::cout << "\nHello!";
8}
9

1Hello!
2Hello!
3

Exporting Module Macros

Preprocessor macros are usable within modules, but cannot normally be exported from a module. There is an exception, which we’ll cover later in this lesson, but under normal circumstances, #define directives are restricted to just the file module file where they’re used:

1// Greetings.cppm
2export module Greetings;
3import <iostream>;
4
5#define SayHello
6
7export void Greet() {
8#ifdef SayHello
9  std::cout << "Hello from the Module!";
10#endif
11}
12

1// main.cpp
2import Greetings;
3import <iostream>;
4
5int main() {
6  Greet();
7#ifdef SayHello
8  std::cout << "Hello from main!";
9#endif
10}
11

1Hello from the Module!
2

For projects that require importing macros, and also want to use modules, the recommended approach is to move the macros into dedicated files and #include them where they’re needed in the traditional way.

Module Partitions

When we want to break up a large module into smaller chunks, we have two options.

• Module partitions allow us to break our module across multiple files. But, this is effectively invisible to consumers - from the perspective of any other file, they just import our module as normal
• Submodules allow us to break larger modules into a hierarchy of any number of child modules. Consumers can choose to import the module as a whole, or just import specific submodules

A module partition file is implemented in the same way as a regular module. The only difference is that a partition has a semicolon in the name.

A partition name has three parts:

1. The name of the module for which it is a partition of
2. A semicolon, :
3. A name for the partition.

For example, if our Math module had a partition called Geometry, we would call the partition Math:Geometry.

In the following example, we create a Math module with two partitions: Math:Geometry and Math:Algebra

It would look like this:

1// MathAlgebra.cppm
2export module Math:Algebra;
3
4export float MilesToKM(float Miles) {
5  return Miles * 1.61;
6}
7

1// MathGeometry.cppm
2export module Math:Geometry;
3
4export constexpr float Pi{3.14};
5

We then create the main module interface file for the Math module, which exports the module, as well as imports and re-exports all of the partitions. The syntax looks like this - note for our partitions we omit the part of the name that comes before the semicolon:

1// Math.cppm
2export module Math;
3
4export import :Algebra;
5export import :Geometry;
6

The partitions are not accessible to consumers. They simply use our module as normal, as if it was not partitioned:

1// main.cpp
2import Math;
3import <iostream>;
4
5int main() {
6  std::cout << "Result: " << MilesToKM(100);
7}
8

1Result: 161
2

Submodules

The notion of a submodule is not an official part of the C++ language, but it is something that is adopted by the community. Module names can include . characters, and we use this to organize multiple modules into a hierarchy. For example, we can have a module called Math, with “child” modules called Math.Geometry and Math.Algebra.

Whilst partitions must use a strict naming pattern, containing the parent module and a semicolon, submodules can have any name. The naming convention of ParentModule.ChildModule is just a common convention.

Unlike partitions, consumers can see this hierarchy of a submodule hierarchy, and interact with it. For example, they can choose to import just Math.Geometry rather than the whole Math module.

To set this up, we create submodules in the normal way, including a . in their name:

1// MathAlgebra.cppm
2export module Math.Algebra;
3
4export float MilesToKM(float Miles) {
5  return Miles * 1.61;
6}
7

1// MathGeometry.cppm
2export module Math.Geometry;
3
4export constexpr float Pi{3.14};
5

We then create the parent module, which “rolls up” all the submodules, by both importing and re-exporting them. Note, with partitions, we omitted the part of the name before the : but with the submodule pattern, we must include the full module name in each of our export import statements:

1// Math.cppm
2export module Math;
3
4export import Math.Algebra;
5export import Math.Geometry;
6

Now, within any other file, our consumers can choose to import just a submodule, or import the parent and get everything:

1// main.cpp
2import Math.Algebra;
3import <iostream>;
4
5int main() {
6  std::cout << "Result: " << MilesToKM(100);
7}
8

1Result: 161
2

We're not restricted to one level of hierarchy - we can nest modules as deep as we want. For example, we can have a Math.Geometry.Circles module.

Splitting Interface and Implementation

When working with large projects and the #include directive, it became important to separate code into header files and implementation files to keep compile times down.

With modules, that is no longer a factor. However, many will still want to implement this separation for code organization reasons.

Below, we show two approaches to this. First, we move the interface to the top of the file, with implementations at the bottom:

1// Character.cppm
2export module Character;
3import <string>;
4import <iostream>;
5
6// Definition
7export class Character {
8 public:
9  Character(std::string Name);
10  void SayHello();
11  std::string GetName();
12
13 private:
14  std::string Name;
15};
16
17// Implementation
18Character::Character(std::string Name)
19    : Name{Name} {}
20
21void Character::SayHello() {
22  std::cout << "Hello there!  The name is "
23            << Name;
24}
25
26std::string Character::GetName() {
27  return Name;
28}
29

We can also split our module into an interface file, and one (or more) implementation files.

In our implementation file(s), we use the module declaration at the top, without the export statement. For example:

1module Character;
2
3// Character implementation here
4

This has the effect of importing the Character module and its dependencies from our interface file, and also declaring that the subsequent code is providing implementations for that module. We then provide implementions in the normal way.

Below is an example of splitting our previous Character module into an interface and implementation file:

1// Character.cppm
2export module Character;
3import <string>;
4import <iostream>;
5
6// Definition
7export class Character {
8 public:
9  Character(std::string Name);
10  void SayHello();
11  std::string GetName();
12
13 private:
14  std::string Name;
15};
16

1// Character.cpp
2module Character;
3
4Character::Character(std::string Name)
5    : Name{Name} {}
6
7void Character::SayHello() {
8  std::cout << "Hello there!  The name is "
9            << Name;
10}
11
12std::string Character::GetName() {
13  return Name;
14}
15

Internal Partitions / Implementation Partitions

When we split a complex module across many partitions, we’ll often come across scenarios where we want some segments of code to be shared across multiple files.

An internal partition (sometimes called an implementation partition) can help us here. This is a partition that is a repository for shared code to be used across our module, but not exported as part of the public interface.

A minimal internal partition for a Math module would look something like this:

1module Math:Helpers;
2
3constexpr float Pi{3.14};
4

Once we’ve set up our internal partition, we can import and use it in any of our other module files:

1export module Math;
2import :Helpers;
3
4export class Circle {
5 public:
6  float Circumference(float Radius) {
7    return Radius * 2 * Pi;
8  }
9};
10

Header Units: Using Traditional Header Files as Modules

It’s still very early in the lifespan of modules. If we want to use them now, we’re going to be mixing them with third-party libraries and other code that is still using traditional header files.

Assuming we can’t convert those files to proper modules, there are two workarounds. The first is we just use the import statement, and provide a path to the header file within quotes. This creates what is known as a Header Unit:

1// Character.h
2#pragma once
3#include <iostream>
4
5class Character {
6 public:
7  void SayHello() { std::cout << "Hello!"; };
8};
9

1// main.cpp
2import "Character.h";
3
4int main() {
5  Character Greeter;
6  Greeter.SayHello();
7}
8

1Hello!
2

Header units are a stop-gap measure implemented by compilers. In essence, they convert a header file to a module, and everything in that header file (including preprocessor macros) is exported. The exact implementation here varies from compiler to compiler, and it doesn’t always work.

The other option we have for mixing traditional code with modules is to just #include the older files within our module files. However, we need to be careful there, as we explain in the next section.

Using the #include directive within modules

Inevitably, we’ll be tempted to place an #include directive within the purview of our module:

1// Character.cppm
2export module Character;
3#include <SomeLibrary>
4
5// ...
6

This may not work, but even if it does, it’s not something we should do. Given #include is simply a crude copy-and-paste, dropping one below our module declaration is going to cause some issues.

When this code gets preprocessed and sent for compilation, the compiler is just going to see the entire contents of whatever we included as part of our Character module. That’s almost never what we intend so, in most compilers, we should at least receive a warning:

1'#include <SomeLibrary>' in the purview
2of module 'Character' appears erroneous
3

But, if we still need to #include the library, what do we do?

In the world of C++ modules, all code must be attached to a module. Anything that is not explicitly attached to a module (such as the main function) is part of the global module.

This is also where we want the output of our #include directives to go. When we need to #include a file within a module, we can specify it as being part of that global module, using a global module fragment. It looks like this:

1module;  // Global module fragment
2#include <SomeLibrary>  // Legacy include
3
4export module Character;  // Named module begins
5import <iostream>;
6
7export class Character {
8 public:
9  void SayHello() { std::cout << "Hello!"; };
10};
11

The only use case for global module fragments is to solve these preprocessor-related problems. As such, we can't put any other type of code there - only preprocessor directives are allowed within the global module fragment.