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
The `header-units.json` file lists which header files can be built into header units. This file must be in the same directory as the header files being included. This file is only used when [`/translateInclude`](translateinclude.md) is specified along with either [`/scanDependencies`](scandependencies.md) or [`/sourceDependencies:directives`]((sourcedependencies-directives.md).
13
+
The `header-units.json` file lists which header files can be built into header units. This file must be in the same directory as the included header files. This file is only used when [`/translateInclude`](translateinclude.md) is specified along with either [`/scanDependencies`](scandependencies.md) or [`/sourceDependencies:directives`]((sourcedependencies-directives.md).
14
14
15
15
## Rationale
16
16
17
-
Some header files can't be compiled into header units. For example, given `a.h`, `b.h` and `macros.h` which are all in the same directory:
17
+
Some header files can't be safely translated to header units. Header files that use macros that aren't defined on the command line, or aren't defined in the header files included by this header, can't be built as header units.
18
+
19
+
If a header defines macros which affect whether other headers are included, it cannot be safely translated. For example, given `a.h`, `b.h` and `macros.h`, which are all in the same directory:
18
20
19
21
```cpp
20
22
// a.h
@@ -38,9 +40,9 @@ The `header-units.json` in this directory can contain `a.h` and `b.h`, but not `
38
40
}
39
41
```
40
42
41
-
The reason `macros.h` can't be listed in this `header-units.json` file is that during the scan phase, the header unit (`.ifc`) may not be compiled yet for `macros.h`. So `MACRO`may not be defined when `a.h` is compiled. That means `b.h` will be missing from the list of dependencies for `a.h`. Because it isn't in the list of dependencies, the build system won't build a header unit for `b.h` despite it being listed in the `header-units.json` file.
43
+
The reason `macros.h` can't be listed in this `header-units.json` file is that during the scan phase, the header unit (`.ifc`) might not be compiled yet for `macros.h`. In that case, `MACRO`won't be defined when `a.h` is compiled. That means `b.h` will be missing from the list of dependencies for `a.h`. Because it isn't in the list of dependencies, the build system won't build a header unit for `b.h` despite it being listed in the `header-units.json` file.
42
44
43
-
To avoid this problem when there is a dependency on a macro in another header file, the header file defining the macro is excluded from the list of those that can be compiled into a header unit.
45
+
To avoid this problem when there is a dependency on a macro in another header file, the header file that defines the macro is excluded from the list of those that can be compiled into a header unit. This way the header file that defines the macro is treated as an `#include` and `MACRO` will be visible so that `b.h` is included and listed as one of the dependencies.
44
46
45
47
## Schema
46
48
@@ -74,7 +76,7 @@ The schema also supports comments, as shown here:
74
76
75
77
## Search rules
76
78
77
-
The build system looks for this file in the same directory as the header file being processed. If your library is organized into subdirectories, each subdirectory needs its own `header-units.json` file.
79
+
The compiler looks for this file in the same directory as the header file being processed. If your library is organized into subdirectories, each subdirectory needs its own `header-units.json` file.
Copy file name to clipboardExpand all lines: docs/build/reference/headerunit.md
+3-3Lines changed: 3 additions & 3 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -29,7 +29,7 @@ The name of a file that contains compiled header unit information. To import mor
29
29
30
30
The **`/headerUnit`** compiler option requires the [`/std:c++20`](std-specify-language-standard-version.md) or later compiler option (such as **`/std:c++latest`**).
31
31
32
-
The **`/headerUnit`** compiler option is available starting in Visual Studio 2019 version 16.10.
32
+
The **`/headerUnit`** compiler option is available in Visual Studio 2019 version 16.10, or later.
33
33
34
34
When the compiler comes across `import "file";` or `import <file>;`, this compiler option helps the compiler find the compiled header unit (*`.ifc`*) for the specified header file. The path to this file can be expressed in three ways:
35
35
@@ -39,9 +39,9 @@ When the compiler comes across `import "file";` or `import <file>;`, this compil
39
39
40
40
**`/headerUnit:angle`** looks up the compiled header unit file using the same rules as `#include <file>`.
41
41
42
-
The compiler can't map a single *`header-name`* to multiple *`.ifc`* files. While mapping multiple *`header-name`* arguments to a single *`.ifc`* is possible, we don't recommend it. The contents of the *`.ifc`* get imported as if it was only the header specified by *`header-name`*.
42
+
The compiler can't map a single *`header-name`* to multiple *`.ifc`* files. While mapping multiple *`header-name`* arguments to a single *`.ifc`* is possible, it isn't recommended. The contents of the *`.ifc`* get imported as if it was only the header specified by *`header-name`*.
43
43
44
-
The compiler implicitly enables the new preprocessor when this option is used. That is, [`/Zc:preprocessor`](zc-preprocessor.md) is added to the command line by the compiler if any form of `/headerUnit` is specified on the command line. To opt out of the implicit `/Zc:preprocessor`, specify: `/Zc:preprocessor-`
44
+
The compiler implicitly enables the new preprocessor when this option is used. If any form of `/headerUnit` is specified on the command line, [`/Zc:preprocessor`](zc-preprocessor.md) is added to the command line by the compiler . To opt out of the implicit `/Zc:preprocessor`, specify: `/Zc:preprocessor-`
45
45
46
46
If you disable the new preprocessor, but a file you compile imports a header unit, the compiler will report an error.
This command-line option generates a JSON file that lists module and header-unit dependencies.
13
13
14
-
It identifies which modules and header units need to be compiled before the project that uses them is compiled. For instance, it will list `import <library>;` or `import "library";` as a header unit dependency, and `import name;` as a module dependency.
14
+
It identifies which modules and header units to compile before the project that uses them is compiled. For instance, it will list `import <library>;` or `import "library";` as a header unit dependency, and `import name;` as a module dependency.
15
15
16
16
This command-line option is similar to [`/sourceDependencies`](sourcedependencies.md), but differs in the following ways:
17
17
@@ -50,7 +50,7 @@ All file paths appear as absolute paths in the output.
50
50
51
51
This switch is used in combination with [`/translateInclude`](translateinclude.md).
52
52
53
-
`header-units.json` is used with the build system's **Scan Sources for Module Dependencies** to determine which header files can be compiled into a header unit. When this switch is specified, header files found in the source files that are scanned, that are also listed in `header-units.json`, are considered eligible to be compiled into header units. Files not in the list are treated as a normal `#include`.
53
+
`header-units.json` is used with the build system's **Scan Sources for Module Dependencies** to determine which header files can be compiled into a header unit. When this switch is specified, header files found in the source files that are scanned, that are also listed in `header-units.json`, are considered eligible to compile into header units. Files not in the list are treated as a normal `#include`.
54
54
55
55
The compiler looks for `header-units.json` where the header being loaded is located. For more information about the format of this file, see [C++ header-units.json reference](header-unit-json-reference.md)
56
56
@@ -94,7 +94,7 @@ This command line produces a JSON file *`output.json`* with content like:
94
94
}
95
95
```
96
96
97
-
We've used `...` to abbreviate the reported paths. The report will contain the absolute paths. The paths reported depend on where the compiler finds the dependencies. If the results are unexpected, you may want to check your project's include path settings.
97
+
The previous example uses `...` to abbreviate the reported paths. The report contains the absolute paths. The paths reported depend on where the compiler finds the dependencies. If the results are unexpected, you might want to check your project's include path settings.
98
98
99
99
`ProvidedModule` lists exported module or module partition names.
Copy file name to clipboardExpand all lines: docs/build/reference/translateinclude.md
+4-4Lines changed: 4 additions & 4 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -11,7 +11,7 @@ helpviewer_keywords: ["/translateInclude", "Translate include directives into im
11
11
12
12
This switch instructs the compiler to treat `#include` as `import` for header files that have been built into header unit (`.ifc`) files and are specified on the command line with [`/headerUnit`](headerunit.md).
13
13
14
-
When used in conjunction with [`/scanDependencies`](scandependencies.md) or [`/sourceDependencies-directives`](sourcedependencies-directives.md), the compiler lists those headers that are both included in the source, and have a corresponding entry in a [`header-units.json`](header-unit-json-reference.md) file, as imported header units in the generated dependency file. This dependency info is used by the build system to generate compiled header unit `.ifc` files. Then, instead of treating the header file as an `#include`, it is treated as an `import`.
14
+
When used with [`/scanDependencies`](scandependencies.md) or [`/sourceDependencies-directives`](sourcedependencies-directives.md), the compiler lists those headers that are both included in the source, and have a corresponding entry in a [`header-units.json`](header-unit-json-reference.md) file, as imported header units in the generated dependency file. This dependency info is used by the build system to generate compiled header unit `.ifc` files. Then, instead of treating the header file as an `#include`, it is treated as an `import`.
15
15
16
16
For an example of how this switch is used, see [Walkthrough: Build and import header units in Microsoft Visual C++](../walkthrough-header-units.md).
17
17
@@ -21,16 +21,16 @@ For an example of how this switch is used, see [Walkthrough: Build and import he
21
21
22
22
## Remarks
23
23
24
-
`/translateInclude` is available starting in Visual Studio 2019 version 16.10.\
24
+
`/translateInclude` is available in Visual Studio 2019 version 16.10, or later.\
25
25
The **`/translateInclude`** compiler option requires [/std:c++20](std-specify-language-standard-version.md) or later.
26
26
27
27
The Microsoft build system does the following when **`/translateInclude`** and either [`/scanDependencies`](scandependencies.md) or [`/sourceDependencies:directives`](sourcedependencies-directives.md) is specified:
28
28
29
29
1. Get all header units and modules from referenced projects and add them, as well as their dependencies, via `/reference` and `/headerUnit` to the command line for all sources in the project.
30
-
1. The compiler scans all of the sources that are marked to be scanned. They are marked by default based on file extension, or may be marked explicitly in the IDE. For an example of marking files explicitly, see [Walkthrough: Build and import header units in Microsoft Visual C++](../walkthrough-header-units.md).
30
+
1. The compiler scans all of the sources that are marked to be scanned. They are marked by default based on file extension, or might be marked explicitly in the IDE. For an example of marking files explicitly, see [Walkthrough: Build and import header units in Microsoft Visual C++](../walkthrough-header-units.md).
31
31
1. Read the produced dependencies JSON files. If header units dependencies are reported in the dependency files, scan those headers too.
32
32
1. Repeat step #3 until no new header unit dependencies are reported.
33
-
1. Create a dependency graph using all dependency data.
33
+
1. Create a dependency graph from the dependency data.
34
34
1. Add `/reference` and `/headerUnit` for all directly and indirectly referenced modules and header units, as well as those from step #1.
35
35
1. Build the scanned sources based on the order of their dependencies.
36
36
1. Build the rest of the sources, adding `/reference` and `/headerUnit` for all built modules and header units, their dependencies, and referenced projects from step #1.
0 commit comments