Skip to content

Commit 43bdd91

Browse files
TylerMSFTTylerMSFT
TylerMSFT
authored and
TylerMSFT
committed
fix links
1 parent 764c70b commit 43bdd91

6 files changed

Lines changed: 12 additions & 12 deletions

‎docs/build/compare-inclusion-methods.md‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -13,7 +13,7 @@ Precompiled headers (PCH) were introduced to speed compilation by translating th
1313

1414
In C++20, modules were introduced as a significant improvement on header files and precompiled headers.
1515

16-
Header units were introduced as a way of temporarily bridging the gap between header files and modules so that you can get some of the speed and robustness benefits of modules while you migrate your code.
16+
Header units were introduced as a way to temporarily bridge the gap between header files and modules. They provide some of the speed and robustness benefits of modules while you migrate your code.
1717

1818
Then, the C++23 standard library introduced support for importing the standard library as named modules--which is the fastest and most robust way to consume the standard library.
1919

@@ -23,7 +23,7 @@ The following table is arranged by compiler processing speed and robustness, wit
2323

2424
| Method | Summary |
2525
|---|---|
26-
| `#include` | This is the 'classic' way of doing things. On disadvantage is that they exposes macros and internal implementation. Internal implementation is often exposed as functions and types that start with an underscore, which is a convention to indicate that it's internal and shouldn't be used. Header files are fragile because the order of #includes can modify behavior or break code and are affected by macro definitions. Header files slow compilation, particularly when the same file is included in multiple files because the header file has to be processed for each file that includes it. |
26+
| `#include` | The 'classic' way of doing things. One disadvantage is that they expose macros and internal implementation. Internal implementation is often exposed as functions and types that start with an underscore, which is a convention to indicate that it's internal and shouldn't be used. Header files are fragile because the order of #includes can modify behavior or break code and are affected by macro definitions. Header files slow compilation, particularly when the same file is included by multiple files because the header file is reprocessed by every file that includes it. |
2727
| [Precompiled header](../build/creating-precompiled-header-files.md) | A precompiled header (PCH) improves compile time by creating a compiler memory snapshot of a set of header files. This is an improvement on rebuilding header files over and over. PCH files have restrictions that make them difficult to build and maintain. In terms of speed and robustness, PCH files are faster than `#include` but slower than `import`.|
2828
| [Header units](../build/walkthrough-header-units.md) | This is a new feature in C++20 that allows you to import 'well-behaved' header files as modules. Header units are faster than `#include`, and are easier, significantly smaller, and faster than pre-compiled header files (PCH). Header units are an 'in-between' step meant to help transition to named modules in cases where you rely on macros defined in header files, since named modules don't expose macros. Header units are slower than importing a named module. Header units aren't affected by macro defines unless they're specified on the command line when the header unit is built--making them more robust than header files. Header units expose the macros and internal implementation defined in them just as header file do, which named modules don't. As a rough approximation of file size, a 250-megabyte PCH file might be represented by an 80-megabyte header unit file. |
2929
| [Modules](../cpp/modules-cpp.md) | This is the fastest and most robust way to import functionality. Support for importing modules was introduced in C++20. The C++23 standard library introduces the two named modules described in this topic. When you import `std`, you get the standard names such as `std::vector`, `std::cout`, but no extensions, no internal helpers such as `_Sort_unchecked`, and no macros. The order of imports doesn't matter because there are no macro or other side-effects. As a rough approximation of file size, a 250-megabyte PCH file might be represented by an 80-megabyte header unit file, which might be represented by a 25-megabyte module. The reason named modules are faster is because when a named module is compiled into an `.ifc` file and an `.obj` file, the compiler emits a structured representation of the source code that can be loaded quickly when the module is imported. The compiler can do some work (like name resolution) before emitting the `.ifc` file because of how named modules are order-independent and macro-independent--so this work doesn't have to be done when the module is imported. In contrast, when a header file is consumed with `#include`, its contents must be preprocessed and compiled again and again in every translation unit. Precompiled headers, which are compiler memory snapshots, can mitigate those costs, but not as well as named modules. |

‎docs/build/creating-precompiled-header-files.md‎

Lines changed: 3 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -20,7 +20,7 @@ Precompiled code is useful during the development cycle to reduce compilation ti
2020

2121
- You always use a large body of code that changes infrequently.
2222

23-
- Your program comprises multiple modules, all of which use a standard set of include files and the same compilation options. In this case, all include files can be precompiled into one precompiled header. For more information about newer ways to handle include files, see [Compare header units, modules, and precompiled headers](compare-header-units-modules-and-precompiled-headers.md).
23+
- Your program comprises multiple modules, all of which use a standard set of include files and the same compilation options. In this case, all include files can be precompiled into one precompiled header. For more information about newer ways to handle include files, see [Compare header units, modules, and precompiled headers](compare-inclusion-methods.md).
2424

2525
The first compilation (the one that creates the precompiled header file) takes a bit longer than subsequent compilations. Subsequent compilations can proceed more quickly by including the precompiled code.
2626

@@ -340,10 +340,10 @@ int main( void )
340340

341341
## See also
342342

343-
[Compare header units, modules, and precompiled headers](compare-header-units-modules-and-precompiled-headers.md)\
343+
[Compare header units, modules, and precompiled headers](compare-inclusion-methods.md)\
344344
[C/C++ building reference](reference/c-cpp-building-reference.md)\
345345
[MSVC compiler options](reference/compiler-options.md)
346-
[Overview of modules in C++](modules-cpp.md)\
346+
[Overview of modules in C++](../cpp/modules-cpp.md)\
347347
[Tutorial: Import the C++ standard library using modules](../cpp/tutorial-import-stl-named-module.md)\
348348
[Walkthrough: Build and import header units in your Visual C++ projects](walkthrough-header-units.md)\
349349
[Walkthrough: Import STL libraries as header units](walkthrough-import-stl-header-units.md#approach1)

‎docs/build/walkthrough-header-units.md‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -15,7 +15,7 @@ This article is about building and importing header units with Visual Studio 202
1515

1616
Header units are the recommended alternative to [precompiled header files](creating-precompiled-header-files.md) (PCH). Header units are easier to set up and use, are significantly smaller on disk, provide similar performance benefits, and are more flexible than a [shared PCH](https://devblogs.microsoft.com/cppblog/shared-pch-usage-sample-in-visual-studio).
1717

18-
To contrast header units with other ways to include functionality in your programs, see [Compare header units, modules, and precompiled headers](compare-header-units-modules-and-precompiled-headers.md).
18+
To contrast header units with other ways to include functionality in your programs, see [Compare header units, modules, and precompiled headers](compare-inclusion-methods.md).
1919
## Prerequisites
2020

2121
To use header units, you need Visual Studio 2019 16.10 or later.
@@ -157,7 +157,7 @@ Enabling the new preprocessor affects the processing of variadic macros. For mor
157157
[`/exportHeader`](./reference/module-exportheader.md)\
158158
[`/headerUnit`](./reference/headerunit.md)\
159159
[`header-units.json`](./reference/header-unit-json-reference.md)\
160-
[Compare header units, modules, and precompiled headers](compare-header-units-modules-and-precompiled-headers.md)\
160+
[Compare header units, modules, and precompiled headers](compare-inclusion-methods.md)\
161161
[Overview of modules in C++](../cpp/modules-cpp.md)\
162162
[Tutorial: Import the C++ standard library using modules](../cpp/tutorial-import-stl-named-module.md)\
163163
[Walkthrough: Import STL libraries as header units](walkthrough-import-stl-header-units.md#approach1)

‎docs/build/walkthrough-import-stl-header-units.md‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -14,7 +14,7 @@ This walkthrough shows how to import C++ Standard Template Library (STL) librari
1414

1515
Importing an STL header as a header unit is simpler than using [precompiled header files](creating-precompiled-header-files.md). Header units are easier to set up and use, are substantially smaller on disk, provide similar performance benefits, and are more flexible than a [shared PCH](https://devblogs.microsoft.com/cppblog/shared-pch-usage-sample-in-visual-studio).
1616

17-
For more detailed information about what header units are and the benefits they provide, see [What is a header unit?](walkthrough-header-units.md#what-is-a-header-unit). To contrast header units with other ways to import the standard library, see [Compare header units, modules, and precompiled headers](compare-header-units-modules-and-precompiled-headers.md).
17+
For more detailed information about what header units are and the benefits they provide, see [What is a header unit?](walkthrough-header-units.md#what-is-a-header-unit). To contrast header units with other ways to import the standard library, see [Compare header units, modules, and precompiled headers](compare-inclusion-methods.md).
1818

1919
## Prerequisites
2020

@@ -219,7 +219,7 @@ The main consideration for whether to use this approach is the balance between c
219219
220220
## See also
221221
222-
[Compare header units, modules, and precompiled headers](compare-header-units-modules-and-precompiled-headers.md)\
222+
[Compare header units, modules, and precompiled headers](compare-inclusion-methods.md)\
223223
[Tutorial: Import the C++ standard library using modules](../cpp/tutorial-import-stl-named-module.md)\
224224
[Walkthrough: Build and import header units in your Visual C++ projects](walkthrough-header-units.md)\
225225
[`/translateInclude`](./reference/translateinclude.md)

‎docs/cpp/modules-cpp.md‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -10,7 +10,7 @@ C++20 introduces *modules*, a modern solution that turns C++ libraries and progr
1010

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

13-
To contrast modules with other ways to import the standard library, see [Compare header units, modules, and precompiled headers](compare-header-units-modules-and-precompiled-headers.md).
13+
To contrast modules with other ways to import the standard library, see [Compare header units, modules, and precompiled headers](../build/compare-inclusion-methods.md).
1414

1515
## Enable modules in the Microsoft C++ compiler
1616

@@ -203,4 +203,4 @@ import "myheader.h";
203203

204204
[`module`, `import`, `export`](import-export-module.md)\
205205
[Named modules tutorial](tutorial-named-modules-cpp.md)\
206-
[Compare header units, modules, and precompiled headers](compare-header-units-modules-and-precompiled-headers.md)
206+
[Compare header units, modules, and precompiled headers](../build/compare-inclusion-methods.md)

‎docs/cpp/tutorial-import-stl-named-module.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -35,7 +35,7 @@ The C++23 standard library introduces two named modules: `std` and `std.compat`.
3535
- `std` exports the declarations and names defined in the C++ standard library that are in namespace `std` such as `std::vector` and `std::sort`. It also exports the contents of C wrapper headers such as `<cmath>`, `<cstdio>`, `<cstdlib>` that provide `std::byte`, `std::printf()`, and so on. The C functions defined in the *global namespace* such as `::printf()` and `::fopen` aren't exported. This improves the situation where previously including a C wrapper header like `<cstdio>` which provides `std::` qualified versions of the C runtime functions *also* included the actual C header, like `stdio.h`, which meant the C global namespace versions were also brought in. This is no longer a problem if you import `std`.
3636
- `std.compat` exports everything in `std`, and adds the global namespace counterparts of the C runtime such as `::printf`, `::fopen`, `::size_t`, `::strlen`, and so on. This module makes it easier when working with a codebase that refers to many C runtime functions/types in the global namespace.
3737

38-
The compiler imports the entire standard library when you use `import std;` or `import std.compat;` and does it faster than bringing in a single header file. That is, it's faster to bring in the entire standard library with `import std;` (or `import std.compat`) than it is to `#include <vector>`, for example.
38+
The compiler imports the entire standard library when you use `import std;` or `import std.compat;` and does it faster than bringing in a single header file. That is, it's faster to bring in the entire standard library with `import std;` (or `import std.compat`) than it's to `#include <vector>`, for example.
3939

4040
Because named modules don't expose macros, macros like `assert`, `errno`, `offsetof`, `va_arg`, and others aren't available when you import `std` or `std.compat`. See [Standard library named module considerations](#standard-library-named-module-considerations) for workarounds.
4141

0 commit comments

Comments
 (0)