You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
description: Modules in C++20 provide a modern alternative to header files.
6
6
---
7
7
# Overview of modules in C++
8
8
9
-
C++20 introduces *modules*, a modern solution for componentization of C++ libraries and programs. A module is a set of source code files that are compiled independently of the [translation units](https://wikipedia.org/wiki/Translation_unit_(programming)) that import them. Modules eliminate or reduce many of the problems associated with the use of header files. They often reduce compilation times. Macros, preprocessor directives, and non-exported names declared in a module aren't visible outside the module. They have no effect on the compilation of the translation unit that imports the module. You can import modules in any order without concern for macro redefinitions. Declarations in the importing translation unit don't participate in overload resolution or name lookup in the imported module. After a module is compiled once, the results are stored in a binary file that describes all the exported types, functions, and templates. That file can be processed much faster than a header file. And, the compiler can reuse it every place where the module is imported in a project.
9
+
C++20 introduces *modules*, a modern solution that turns C++ libraries and programs into components. A *module* is a set of source code files that are compiled independently of the [translation units](https://wikipedia.org/wiki/Translation_unit_(programming)) that import them. Modules eliminate or reduce many of the problems associated with the use of header files. They often reduce compilation times. Macros, preprocessor directives, and non-exported names declared in a module aren't visible outside the module. They have no effect on the compilation of the translation unit that imports the module. You can import modules in any order without concern for macro redefinitions. Declarations in the importing translation unit don't participate in overload resolution or name lookup in the imported module. After a module is compiled once, the results are stored in a binary file that describes all the exported types, functions, and templates. The compiler can process that file much faster than a header file. And, the compiler can reuse it every place where the module is imported in a project.
10
10
11
-
Modules can be used side by side with header files. A C++ source file can import modules and also #include header files. In some cases, a header file can be imported as a module rather than textually #included by the preprocessor. We recommend you use modules in new projects rather than header files as much as possible. For larger existing projects under active development, experiment with converting legacy headers to modules. Base adoption on whether you get a meaningful reduction in compilation times.
11
+
You can use modules side by side with header files. A C++ source file can `import` modules and also `#include` header files. In some cases, you can import a header file as a module rather than include it textually by using `#include` in the preprocessor. We recommend you use modules in new projects rather than header files as much as possible. For larger existing projects under active development, experiment with converting legacy headers to modules. Base your adoption on whether you get a meaningful reduction in compilation times.
12
12
13
13
## Enable modules in the Microsoft C++ compiler
14
14
@@ -18,7 +18,7 @@ A module and the code that consumes it must be compiled with the same compiler o
18
18
19
19
## Consume the C++ Standard Library as modules
20
20
21
-
Although not specified by the C++20 standard, Microsoft enables its implementation of the C++ Standard Library to be imported as modules. By importing the C++ Standard Library as modules rather than #including it through header files, you can potentially speed up compilation times depending on the size of your project. The library is componentized into the following modules:
21
+
Although not specified by the C++20 standard, Microsoft makes its implementation of the C++ Standard Library importable as modules. By importing the C++ Standard Library as modules rather than including it through header files, you can potentially speed up compilation times depending on the size of your project. The library is split into the following named modules:
22
22
23
23
-`std.regex` provides the content of header `<regex>`
24
24
-`std.filesystem` provides the content of header `<filesystem>`
@@ -33,13 +33,14 @@ import std.core;
33
33
import std.regex;
34
34
```
35
35
36
-
To consume the Microsoft Standard Library module, compile your program with [`/EHsc`](../build/reference/eh-exception-handling-model.md) and [`/MD`](../build/reference/md-mt-ld-use-run-time-library.md) options.
36
+
To consume the Microsoft Standard Library modules, compile your program with [`/EHsc`](../build/reference/eh-exception-handling-model.md) and [`/MD`](../build/reference/md-mt-ld-use-run-time-library.md) options.
37
37
38
38
## Basic example
39
39
40
-
The following example shows a simple module definition in a source file called *`Example.ixx`*. The *`.ixx`* extension is required for module interface files in Visual Studio. In this example, the interface file contains both the function definition and the declaration. However, the definitions can be also placed in one or more separate files (as shown in a later example). The `export module Example;` statement indicates that this file is the primary interface for a module called `Example`. The **`export`** modifier on `f()` indicates that this function is visible when `Example` is imported by another program or module. The module references a namespace `Example_NS`.
40
+
The following example shows a simple module definition in a source file called *`Example.ixx`*. The *`.ixx`* extension is required for module interface files in Visual Studio. In this example, the interface file contains both the function definition and the declaration. However, you can also place the definitions in one or more separate module implementation files, as shown in a later example. The `export module Example;` statement indicates that this file is the primary interface for a module called `Example`. The **`export`** modifier on `f()` indicates that this function is visible when `Example` is imported by another program or module. The module references a namespace `Example_NS`.
41
41
42
42
```cpp
43
+
// Example.ixx
43
44
exportmodule Example;
44
45
45
46
#defineANSWER 42
@@ -59,7 +60,7 @@ namespace Example_NS
59
60
The file *`MyProgram.cpp`* uses the **`import`** declaration to access the name that is exported by `Example`. The name `Example_NS` is visible here, but not all of its members. Also, the macro `ANSWER` isn't visible.
60
61
61
62
```cpp
62
-
63
+
// MyProgram.cpp
63
64
import Example;
64
65
import std.core;
65
66
@@ -71,16 +72,50 @@ int main()
71
72
// int i = Example_NS::f_internal(); // C2039
72
73
// int j = ANSWER; //C2065
73
74
}
74
-
75
75
```
76
76
77
77
The `import` declaration can appear only at global scope.
You can create a module with a single interface file (*`.ixx`*) that exports names and includes implementations of all functions and types. You can also put the implementations in one or more separate implementation files, similar to how .h and .cpp files are used. The **`export`** keyword is used in the interface file only. An implementation file can **`import`** another module, but can't **`export`** any names. Implementation files may be named with any extension. An interface file and the backing set of implementation files are treated as a special variation of a translation unit called a *module unit*. A name that's declared in any implementation file is automatically visible in all other files within the same module unit.
102
+
A *module interface* exports the module name and all the namespaces, types, functions and so on that make up the public interface of the module. A *module implementation* defines the things exported by the module. In its simplest form, a module can consist of a single file that combines the module interface and implementation. You can also put the implementations in one or more separate module implementation files, similar to how *`.h`* and *`.cpp`* files are used.
103
+
104
+
For larger modules, you can split parts of the module into submodules called *partitions*. Each partition consists of a module interface file that exports a module partition name. A partition may also have one or more partition implementation files. The module as a whole has one *primary module interface*, the public interface of the module that may also import and export the partition interfaces.
105
+
106
+
A module consists of one or more *module units*. A module unit is a translation unit (a source file) that contains a module declaration. There are several types of module units:
107
+
108
+
- A *module interface unit* is a module unit that exports a module name or module partition name. A module interface unit has `export module` in its module declaration.
109
+
110
+
- A *module implementation unit* is a module unit that doesn't export a module name or module partition name. As the name implies, it's used to implement a module.
111
+
112
+
- A *primary module interface unit* is a module interface unit that exports the module name. There must be one and only one primary module interface unit in a module.
113
+
114
+
- A *module partition interface unit* is a module interface unit that exports a module partition name.
115
+
116
+
- A *module partition implementation unit* is a module implementation unit that has a module partition name in its module declaration, but no `export` keyword.
82
117
83
-
For larger modules, you can split the module into multiple module units called *partitions*. Each partition consists of an interface file backed by one or more implementation files.
118
+
The **`export`** keyword is used in interface files only. An implementation file can **`import`** another module, but can't **`export`** any names. Implementation files can have any extension.
84
119
85
120
## Modules, namespaces, and argument-dependent lookup
86
121
@@ -90,7 +125,7 @@ When it does argument-dependent lookup for overload resolutions in the importing
90
125
91
126
### Module partitions
92
127
93
-
A module can be componentized into *partitions*, each consisting of an interface file and zero or more implementation files. A module partition is similar to a module, except it shares ownership of all declarations in the entire module. All names exported by partition interface files are imported and re-exported by the primary interface file. A partition's name must begin with the module name followed by a colon. Declarations in any of the partitions are visible within the entire module. No special precautions are needed to avoid one-definition-rule (ODR) errors. You can declare a name (function, class, and so on) in one partition and define it in another. A partition implementation file begins like this:
128
+
A module partition is similar to a module, except it shares ownership of all declarations in the entire module. All names exported by partition interface files are imported and re-exported by the primary interface file. A partition's name must begin with the module name followed by a colon. Declarations in any of the partitions are visible within the entire module. No special precautions are needed to avoid one-definition-rule (ODR) errors. You can declare a name (function, class, and so on) in one partition and define it in another. A partition implementation file begins like this:
94
129
95
130
```cpp
96
131
module Example:part1;
@@ -147,7 +182,7 @@ import std.filesystem;
147
182
148
183
### Imported header files
149
184
150
-
Some headers are sufficiently self-contained that they can be brought in using the **`import`** keyword. The main difference between an imported header and an imported module is that any preprocessor definitions in the header are visible in the importing program immediately after the `import` statement. However, preprocessor definitions in any files included by that header aren't visible.
185
+
Some headers are sufficiently self-contained that they can be brought in using the **`import`** keyword. The main difference between an imported header and an imported module is that any preprocessor definitions in the header are visible in the importing program immediately after the `import` statement.
0 commit comments