Skip to content

Repo sync for protected CLA branch #3648

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 2 commits into from
Jan 12, 2022
Merged

Repo sync for protected CLA branch #3648

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
4fd05e8
1/12/2021 AM Publish (#4041)
Taojunshen Jan 12, 2022
5380d3b
Merging changes synced from https://github.com/MicrosoftDocs/cpp-docs…
opbld17 Jan 12, 2022
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
38 changes: 18 additions & 20 deletions docs/build/walkthrough-header-units.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,7 +1,7 @@
---
description: "Learn more about C++ header units by converting a header file to a header unit by using Visual Studio 2019."
title: "Walkthrough: Build and import header units in Visual C++ projects"
ms.date: "5/18/2021"
ms.date: 01/10/2022
ms.custom: "conceptual"
author: "tylermsft"
ms.author: "twhitney"
Expand All @@ -12,7 +12,7 @@ helpviewer_keywords: ["import", "header unit", "ifc"]

This article is about building and importing header units by using Visual Studio 2019. See [Walkthrough: Import STL libraries as header units](walkthrough-import-stl-header-units.md) to learn specifically how to import Standard Template Library headers as header units.

Header units are the recommended alternative to [precompiled header files](creating-precompiled-header-files.md) (PCH). They're easier to set up and use than [shared PCH](https://devblogs.microsoft.com/cppblog/shared-pch-usage-sample-in-visual-studio), but they provide similar performance benefits. Unlike a PCH, when a header unit changes, only it and its dependencies are rebuilt.
Header units are the recommended alternative to [precompiled header files](creating-precompiled-header-files.md) (PCH). They're easier to set up and use than a [shared PCH](https://devblogs.microsoft.com/cppblog/shared-pch-usage-sample-in-visual-studio), but they provide similar performance benefits. Unlike a PCH, when a header unit changes, only it and what depends on it are rebuilt.

## Prerequisites

Expand All @@ -26,27 +26,27 @@ An important difference between a header unit and a header file is that header u

A similarity is that everything visible from a header file is also visible from a header unit.

Before you can import a header unit, you need to compile a header file into a header unit. An advantage of header units over PCH is that they can be used in distributed builds. For example, as long as you're using the same compiler to compile the *`.ifc`* and the program that imports it and are targeting the same platform and architecture, a header unit produced on one computer can be used on another.
Before you can import a header unit, you need to compile a header file into a header unit. An advantage of header units over PCH is that they can be used in distributed builds. For example, as long as you compile the *`.ifc`* and the program that imports it with the same compiler, and target the same platform and architecture, a header unit produced on one computer can be used on another.

Another advantage of header units over PCH is that there's more flexibility for the compiler flags used to compile the header unit and for the program that imports it. With a PCH, more compiler flags must be the same. But with header units, these flags should be the same:
Another advantage of header units over PCH is that there's more flexibility for differences between the compiler flags used to compile the header unit and the program that imports it. With a PCH, more compiler flags must be the same. With header units, only the following flags need to be the same:

- Exception handling options like **`/EHsc`**.
- **`/MD[d]`** or **`MT[d]`**.
- **`/D`**. You can define additional macros when you build the program that imports the header unit. But the ones used to build the header unit should also be present and defined the same way when you build the program that imports the header unit.
- **`/D`**. You can define other macros when you build the program that imports the header unit. But the ones used to build the header unit should also be present and defined the same way when you build the program that imports the header unit.

## Ways to compile a header unit

There are several ways to compile a file into a header unit:

- **Automatically scan for header units**. This approach is best suited to smaller projects that include many different header files. See [Walkthrough: Import STL libraries as header units](walkthrough-import-stl-header-units.md#approach1) for a demonstration of this approach. This approach is better suited to smaller projects because it can't guarantee optimal build throughput. That's because it scans all the files to find what should be built into header units.

- **Build a shared header unit project**. This approach is best suited for larger projects and for when you want more control over the organization of the imported header units. You create a static library project (or projects) that contain the header units that you want. Then reference the library project (or projects) from the project that then imports the header units it needs. See [Walkthrough: Import STL libraries as header units](walkthrough-import-stl-header-units.md#approach2) for a demonstration of this approach.
- **Build a shared header unit project**. This approach is best suited for larger projects and for when you want more control over the organization of the imported header units. You create a static library project (or projects) that contain the header units that you want. Then reference that library project (or projects) to import the header units. See [Walkthrough: Import STL libraries as header units](walkthrough-import-stl-header-units.md#approach2) for a demonstration of this approach.

- **Choose individual header units to build**. This approach gives you file-by-file control over which header files are treated as header units. It's also a good way to quickly and selectively try out header units in your project. This approach is demonstrated in this walkthrough.
- **Choose individual header units to build**. This approach gives you file-by-file control over which header files are treated as header units. It's also a good way to try out header units in your project. This approach is demonstrated in this walkthrough.

## Convert a project to use header units

In this example, you'll compile a header file as a header unit. Start by creating the following project in Visual Studio:
Compile a header file as a header unit using the following steps in Visual Studio:

1. Create a new C++ console app project.
1. Replace the source file content as follows:
Expand All @@ -61,7 +61,7 @@ In this example, you'll compile a header file as a header unit. Start by creatin
}
```

1. Add a header file called `Pythagorean.h`, and replace its content with this code:
1. Add a header file called `Pythagorean.h` and then replace its content with this code:

```cpp
#ifndef PYTHAGOREAN
Expand All @@ -76,31 +76,29 @@ In this example, you'll compile a header file as a header unit. Start by creatin
#endif
```

To enable header units, first set the **C++ Language Standard** to [`/std:c++20`](./reference/std-specify-language-standard-version.md) or later.
To enable header units, first set the **C++ Language Standard** to [`/std:c++20`](./reference/std-specify-language-standard-version.md) or later:

1. On the Visual Studio main menu, select **Project** > **Properties**.
1. In the left pane of the project property pages window, select **Configuration Properties** > **General**.
1. In the **C++ Language Standard** list, select **ISO C++20 Standard (/std:c++20)** or later. (In versions before Visual Studio 2019 version 16.11, select **Preview - Features from the Latest C++ Working Draft (/std:c++latest)**.)
1. In the **C++ Language Standard** list, select **ISO C++20 Standard (/std:c++20)** or later. In versions before Visual Studio 2019 version 16.11, select **Preview - Features from the Latest C++ Working Draft (/std:c++latest)**.

### Compile a header file as a header unit

In **Solution Explorer**, select the file you want to compile as a header unit. Right-click the file and select **Properties**. Then do one of the following, depending on the file type:

**For header files**:

Set the **Item Type** property to **C/C++ compiler**. By default, header files have an **Item Type** of **C/C++ header**. Setting this property also sets **C/C++** > **Advanced** > **Compile As** to **Compile as C++ Header Unit (/exportHeader)**.
In **Solution Explorer**, select the file you want to compile as a header unit (in this case, `Pythagorean.h`). Right-click the file and select **Properties**. Since this is a header file, set the **Item Type** property to **C/C++ compiler**. By default, header files have an **Item Type** of **C/C++ header**. Setting this property also sets **C/C++** > **Advanced** > **Compile As** to **Compile as C++ Header Unit (/exportHeader)**.
:::image type="content" source="media/change-item-type.png" alt-text="Screenshot that shows changing the item type to C/C++ compiler.":::

**For source files** (or header files that don't have an *`.h`* or *`.hpp`* extension):
**Compile a source file as a header unit**:

Set the **Compile As** property to **Compile as C++ Header Unit (/exportHeader)**.
If you want to compile a file that doesn't have an *`.h`* or *`.hpp`* extension as a header unit, set the **Compile As** property to **Compile as C++ Header Unit (/exportHeader)**.
:::image type="content" source="media/change-compile-as.png" alt-text="Screenshot that shows changing Compile As to Compile as C++ Header Unit.":::

### Change your code to import a header unit

In the source file for the example project, that is, the file that contains `main()`, change `#include "Pythagorean.h"` to `import "Pythagorean.h";`. (Don't forget the trailing semicolon that's required for `import` statements.) When you're compiling a header unit from a system header, use angle brackets (`import <file>;`). If it's a project header, use `import "file";`.
In the source file for the example project that contains `main()`, change `#include "Pythagorean.h"` to `import "Pythagorean.h";`. Don't forget the trailing semicolon that's required for `import` statements.

When compiling a header unit from a system header, use angle brackets (`import <file>;`). If it's a project header, use `import "file";`.

Build the solution. (**Build** > **Build Solution** on the main menu.) Run it to see that it produces the expected output: `Pythagorean triple a:2 b:3 c:13`
Build the solution by selecting **Build** > **Build Solution** on the main menu. Run it to see that it produces the expected output: `Pythagorean triple a:2 b:3 c:13`

In your own projects, repeat this process to compile the header files you want to import as header units.

Expand Down
Loading