チュートリアル: Microsoft Visual C++ でヘッダーユニットをビルドしてインポートする

[アーティクル]
04/03/2023

この記事は、Visual Studio 2022 を使用するヘッダーユニットのビルドとインポートに関するものです。 C++ 標準ライブラリヘッダーをヘッダーユニットとしてインポートする方法については、「 Walkthrough: Import STL libraries as header unitsを参照してください。さらに速く確実に標準ライブラリをインポートする方法については、モジュールを使用した C++ 標準ライブラリのインポートのチュートリアルに関する記事をご覧ください。

ヘッダーユニットは、プリコンパイル済みヘッダーファイル (PCH) の代替手段として推奨されます。ヘッダーユニットはより簡単に設定して使用でき、ディスク上のサイズが大幅に縮小され、同等のパフォーマンス上の利点が得られます。また、共有 PCHよりも柔軟です。

ヘッダーユニットと、プログラムに機能を含める他の方法を比較するには、「 Compare ヘッダーユニット、モジュール、プリコンパイル済みヘッダー」を参照してください。

前提条件

ヘッダーユニットを使用するには、Visual Studio 2019 16.10 以降が必要です。

ヘッダーユニットとは

ヘッダーユニットは、ヘッダーファイルのバイナリ表現です。ヘッダーユニットの拡張子は .ifc です。名前付きモジュールでも同じ形式が使用されます。

ヘッダーユニットとヘッダーファイルの重要な違いは、ヘッダーユニットがヘッダーユニットの外部のマクロ定義の影響を受けないことです。つまり、ヘッダーユニットの動作が異なるプリプロセッサシンボルを定義することはできません。ヘッダーユニットをインポートするまでに、ヘッダーユニットは既にコンパイルされています。これは、 #include ファイルの処理方法とは異なります。インクルードされたファイルは、ヘッダーファイルを含むソースファイルをコンパイルするときにプリプロセッサを通過するため、ヘッダーファイルの外部にあるマクロ定義の影響を受ける可能性があります。

ヘッダーユニットは任意の順序でインポートできますが、ヘッダーファイルには当てはまりません。 1 つのヘッダーファイルで定義されているマクロ定義が後続のヘッダーファイルに影響を与える可能性があるため、ヘッダーファイルの順序が重要です。 1 つのヘッダーユニットのマクロ定義が、別のヘッダーユニットに影響を与えることはありません。

ヘッダーファイルから参照できるすべてのものは、ヘッダーユニット内で定義されたマクロを含め、ヘッダーユニットからも参照できます。

ヘッダーファイルは、インポートする前にヘッダーユニットに変換する必要があります。プリコンパイル済みヘッダーファイル (PCH) よりもヘッダーユニットの利点は、分散ビルドで使用できることです。同じコンパイラを使用して .ifc とそれをインポートし、同じプラットフォームとアーキテクチャを対象とするプログラムをコンパイルする限り、あるコンピューターで生成されたヘッダーユニットを別のコンピューターで使用できます。 PCH とは異なり、ヘッダーユニットが変更されると、そのユニットとそれに依存するもののみが再構築されます。ヘッダーユニットのサイズは、 .pchより大きく小さくすることができます。

ヘッダーユニットは、ヘッダーユニットを作成し、それを使用するコードを PCH よりもコンパイルするために使用されるコンパイラスイッチの組み合わせに必要な類似点に対する制約が少なくなります。ただし、スイッチの組み合わせやマクロ定義によっては、さまざまな変換単位間で 1 つの定義規則 (ODR) の違反が発生する場合があります。

最終的には、ヘッダーユニットは PCH よりも柔軟なものになります。 PCH では、PCH 内のヘッダーの 1 つのみを取り込むように選択することはできません。コンパイラによってそれらすべてが処理されます。ヘッダーユニットでは、それらをまとめてスタティックライブラリにコンパイルする場合でも、インポートしたヘッダーユニットの内容のみをアプリケーションに取り込むことになります。

ヘッダーユニットは、ヘッダーファイルと C++20 モジュールの間のステップです。モジュールのいくつかの利点が得られます。外部のマクロ定義は影響を受けないため、より堅牢であるため、任意の順序でインポートできます。また、コンパイラではヘッダーファイルよりも高速に処理できます。ただし、ヘッダーユニットにはモジュール内で定義されているマクロが公開されるため、ヘッダーユニットにはモジュールのすべての利点はありません (モジュールには定義されていません)。モジュールとは異なり、ヘッダーユニットでプライベート実装を非表示にする方法はありません。ヘッダーファイルを使用したプライベート実装を示すために、先頭のアンダースコアを名前に追加したり、実装名前空間に配置するなど、さまざまな手法が採用されています。モジュールは、どのような形式でもプライベート実装を公開しないため、これを行う必要はありません。

プリコンパイル済みヘッダーをヘッダーユニットに置き換えることを検討してください。あなたは同じ速度の利点を得ますが、他のコード衛生と柔軟性の利点もあります。

ヘッダーユニットをコンパイルする方法

ファイルをヘッダーユニットにコンパイルするには、いくつかの方法があります。

共有ヘッダーユニットプロジェクトをビルドします。この方法では、組織をより詳細に制御し、インポートされたヘッダーユニットを再利用できるため、この方法をお勧めします。必要なヘッダーユニットを含むスタティックライブラリプロジェクトを作成し、それを参照してヘッダーユニットをインポートします。この方法のチュートリアルについては、ヘッダーユニットのヘッダーユニットスタティックライブラリプロジェクトのビルドに関する記述を参照してください。
ヘッダーユニットに変換する個々のファイルを選択する。この方法では、ヘッダーユニットとして扱われるものをファイルごとに制御できます。また、既定の拡張子 (.ixx、.cppm、.h.hpp) を持たないので、通常はヘッダーユニットにコンパイルされないファイルをヘッダーユニットとしてコンパイルする必要がある場合にも便利です。この方法についてはこのチュートリアルで示します。開始するには、「 Approach 1: 特定のファイルをヘッダーユニットに変換するを参照してください。
ヘッダーユニットを自動的にスキャンしてビルドする。この方法は便利ですが、最適なビルドスループットが保証されないため、より小さなプロジェクトに最適です。この方法の詳細については、「方法 2: ヘッダーユニットを自動的にスキャンする」を参照してください。
概要で説明したように、STL ヘッダーファイルをビルドしてヘッダーユニットとしてインポートし、STL ライブラリヘッダーの #include をコードを書き直さずに import として自動的に処理できます。その方法を確認する場合は、「チュートリアル: STL ライブラリをヘッダーユニットとしてインポートする」を参照してください。

方法 1: 特定のファイルをヘッダーユニットに変換する

このセクションでは、ヘッダーユニットに変換する特定のファイルを選択する方法を示します。 Visual Studio で次の手順を使用して、ヘッダーファイルをヘッダーユニットとしてコンパイルします。

新しい C++ コンソールアプリプロジェクトを作成します。

ソースファイルの内容を次のように置き換えます。

#include "Pythagorean.h"

int main()
{
    PrintPythagoreanTriple(2,3);
    return 0;
}

Pythagorean.h というヘッダーファイルを追加してから、その内容をこのコードに置き換えます。

#ifndef PYTHAGOREAN
#define PYTHAGOREAN

#include <iostream>

inline void PrintPythagoreanTriple(int a, int b)
{
    std::cout << "Pythagorean triple a:" << a << " b:" << b << " c:" << a*a + b*b << std::endl;
}
#endif

プロジェクトプロパティを設定する

ヘッダーユニットを有効にするには、まず、次の手順で C++ 言語標準 を /std:c++20 以降に設定します。

ソリューションエクスプローラーでプロジェクト名を右クリックし、[プロパティ] を選択します。
プロジェクトのプロパティページウィンドウの左ペインで、[構成プロパティ]>[全般] を選択します。
[C++ 言語標準] ドロップダウンで、ISO C++20 標準 (/std:c++20) 以降を選択します。 [OK] を選択してダイアログボックスを閉じます。

次のようにして、ヘッダーファイルをヘッダーユニットとしてコンパイルします。

ソリューションエクスプローラーで、ヘッダーユニットとしてコンパイルするファイル (この場合は Pythagorean.h) を選択します。ファイルを右クリックし、 Properties を選択します。
[構成プロパティ]>[一般]>[アイテムの種類] ドロップダウンを [C/C++ コンパイラ] に設定して [Ok] を選択します。

このチュートリアルの後半でこのプロジェクトをビルドすると、 Pythagorean.h はヘッダーユニットに変換されます。このヘッダーファイルの項目の種類が C/C++ コンパイラに設定されているため、ヘッダーユニットに変換されますこの方法で設定された .h ファイルと .hpp ファイルの既定のアクションは、ファイルをヘッダーユニットに変換するためです。

Note

このチュートリアルではこれは必須ではありませんが、お客様の情報が提供されます。たとえば、 .cpp などの既定のヘッダーユニットファイル拡張子を持たないヘッダーユニットとしてファイルをコンパイルするには、 構成プロパティ>C/C++>Advanced>Compile As を C++ ヘッダーユニット (/exportHeader) として Compile に設定します。 C++ ヘッダーユニット (/exportHeader) としてコンパイルするように高度な>コンパイル> C/C++ >構成プロパティの変更を示すスクリーンショット。

ヘッダーユニットをインポートするようにコードを変更する

サンプルプロジェクトのソースファイルで、 #include "Pythagorean.h" を import "Pythagorean.h"; 末尾のセミコロンを忘れないでください。 importステートメントに必要です。プロジェクトに対してローカルなディレクトリ内のヘッダーファイルであるため、 import ステートメント ( import "file";) で引用符を使用しました。独自のプロジェクトで、システムヘッダーからヘッダーユニットをコンパイルするには、山かっこを使用します。 import <file>;
メインメニューの [ビルド]>[ソリューションのビルド] を選択して、ソリューションをビルドします。これを実行して、予想される出力 (Pythagorean triple a:2 b:3 c:13) が生成されることを確認します。

独自のプロジェクトで、このプロセスを繰り返して、ヘッダーユニットとしてインポートするヘッダーファイルをコンパイルします。

ごく少数のヘッダーファイルをヘッダーユニットに変換する場合は、この方法をお勧めします。ただし、コンパイルするヘッダーファイルが多数あり、ビルドシステムで自動的に処理されるためにビルドパフォーマンスが低下する可能性が高い場合は、次のセクションを参照してください。

特に STL ライブラリヘッダーをヘッダーユニットとしてインポートすることに関心がある場合は、「チュートリアル: STL ライブラリをヘッダーユニットとしてインポートする」を参照してください。

方法 2: ヘッダーユニットを自動的にスキャンしてビルドする

すべてのソースファイルのヘッダーユニットをスキャンし、それらをビルドする時間がかかるため、次のアプローチは小規模なプロジェクトに最適です。最適なビルドスループットは保証されません。

この方法では、次の 2 つの Visual Studio プロジェクトの設定を組み合わせます。

[モジュールの依存関係のソースをスキャンする] では、ビルドシステムによってコンパイラが呼び出され、インポートされたモジュールとヘッダーユニットがすべてビルドされてから、それらに依存するファイルがコンパイルされます。 Translate Includes to Imports と組み合わせると、ヘッダーファイルと同じディレクトリにあるheader-units.json ファイルにも指定されているソースに含まれるヘッダーファイルは、ヘッダーユニットにコンパイルされます。
[インクルードをインポートに変換する] では、#include で、ヘッダーユニットとしてコンパイルできるヘッダーファイルを参照し (header-units.json ファイルで指定されている場合)、コンパイル済みのヘッダーユニットをヘッダーファイルで使用できる場合は、ヘッダーファイルを import として扱います。それ以外の場合、ヘッダーファイルは通常の #include として扱われます。 header-units.json ファイルは、シンボルの重複を伴わずに、各#includeのヘッダーユニットを自動的にビルドするために使用されます。

これらの設定は、プロジェクトのプロパティで有効にできます。これを行うには、ソリューションエクスプローラーでプロジェクトを右クリックし、[プロパティ] を選択します。その後、[構成プロパティ]>[C/C++]>[全般] の順に選択します。

[構成] が強調表示され、[すべての構成] が選択されているプロジェクトのプロパティ画面を示すスクリーンショット。[C/C++ > 全般] で、[モジュールの依存関係のソースのスキャン] が強調表示され、[はい] に設定され、[インポートに含まれる翻訳] が強調表示され、[はい] (/translateInclude) に設定されます。

[モジュールの依存関係のソースをスキャンする] は、次に示すように [プロジェクトのプロパティ] でプロジェクト内のすべてのファイルに対して、または [ファイルのプロパティ] で個々のファイルに対して設定できます。モジュールとヘッダーユニットは常にスキャンされます。このオプションは、自動的にビルドするヘッダーユニットをインポートする .cpp ファイルがあり、まだビルドされていない可能性がある場合に設定します。

これらの設定は、次の条件下でヘッダーユニットを自動的にビルドおよびインポートするために連動します。

モジュールの依存関係のソースをスキャン ヘッダーユニットとして扱うことができるファイルとその依存関係のソースをスキャンします。拡張子 .ixxを持つファイルと、 File プロパティ>C/C++>Compile As プロパティが Compile as C++ Header Unit (/export)に設定されているファイルは、この設定に関係なく常にスキャンされます。また、コンパイラによって、ヘッダーユニットの依存関係を識別する import ステートメントも検索されます。 /translateInclude が指定されている場合、コンパイラによって、ヘッダーユニットとして扱うために header-units.json ファイルでも指定されている #include ディレクティブもスキャンされます。依存関係グラフは、プロジェクト内のすべてのモジュールとヘッダーユニットから構成されます。
インクルードをインポートに変換する: コンパイラによって #include ステートメントが検出され、指定されたヘッダーファイルに一致するヘッダーユニットファイル (#include) が存在する場合、コンパイラでは、ヘッダーファイルを .ifc として扱うのではなく、ヘッダーユニットをインポートします。 [依存関係のスキャン] と組み合わせると、ヘッダーユニットにコンパイルできるすべてのヘッダーファイルが、コンパイラによって検索されます。許可リストは、ヘッダーユニットにコンパイルできるヘッダーファイルを決定するためにコンパイラに参照されます。このリストは、含まれているファイルと同じディレクトリにある必要がある header-units.json ファイルに格納されます。 Visual Studio のインストールディレクトリにある header-units.json ファイルの例を参照できます。たとえば、%ProgramFiles%\Microsoft Visual Studio\2022\Enterprise\VC\Tools\MSVC\14.30.30705\include\header-units.json は、標準テンプレートライブラリヘッダーをヘッダーユニットにコンパイルできるかどうかを判断するために、コンパイラによって使用されます。この機能は、ヘッダーユニットのいくつかの利点を得るために、レガシコードとの橋渡し役として存在します。

header-units.json ファイルには 2 つの目的があります。ヘッダーユニットにコンパイルできるヘッダーファイルを指定するだけでなく、シンボルの重複を最小限に抑えてビルドスループットを向上させます。シンボルの重複の詳細については、「C++ header-units.json のリファレンス」を参照してください。

これらのスイッチと header-unit.json では、ヘッダーユニットのいくつかの利点が得られます。便利ですが、その代わり、ビルドスループットに影響します。この方法は、最適なビルド時間が保証されないため、より大きなプロジェクトには最適ではない場合があります。また、同じヘッダーファイルが繰り返し再処理される可能性があるため、ビルド時間が長くなります。しかし、プロジェクトによっては便利な場合があります。

これらの機能はレガシコード用に設計されています。新しいコードの場合は、ヘッダーユニットや #include ファイルではなく、モジュールに移動します。モジュールの使用に関するチュートリアルについては、「名前付きモジュールのチュートリアル (C++)」を参照してください。

この手法を使用して STL ヘッダーファイルをヘッダーユニットとしてインポートする方法の例については、「チュートリアル: STL ライブラリをヘッダーユニットとしてインポートする」を参照してください。

プリプロセッサへの影響

ヘッダーユニットを作成して使用するには、標準の C99/C++11 準拠プリプロセッサが必要です。コンパイラは、任意の形式の/exportHeaderが使用されるたびにコマンドラインに/Zc:preprocessorを暗黙的に追加することで、ヘッダーユニットをコンパイルするときに新しい C99/C++11 準拠プリプロセッサを有効にします。これをオフにしようとすると、コンパイルエラーが発生します。

新しいプリプロセッサを有効にすると、可変マクロの処理に影響します。詳細については、「 Variadic マクロ解説」セクションを参照してください。

次の方法で共有

チュートリアル: Microsoft Visual C++ でヘッダーユニットをビルドしてインポートする

前提条件

ヘッダーユニットとは

ヘッダーユニットをコンパイルする方法

方法 1: 特定のファイルをヘッダーユニットに変換する

プロジェクトプロパティを設定する

ヘッダーユニットをインポートするようにコードを変更する

方法 2: ヘッダーユニットを自動的にスキャンしてビルドする

プリプロセッサへの影響

関連項目

フィードバック

その他のリソース

次の方法で共有

チュートリアル: Microsoft Visual C++ でヘッダー ユニットをビルドしてインポートする

前提条件

ヘッダー ユニットとは

ヘッダー ユニットをコンパイルする方法

方法 1: 特定のファイルをヘッダー ユニットに変換する

プロジェクト プロパティを設定する

ヘッダー ユニットをインポートするようにコードを変更する

方法 2: ヘッダー ユニットを自動的にスキャンしてビルドする

プリプロセッサへの影響

関連項目

フィードバック

その他のリソース

チュートリアル: Microsoft Visual C++ でヘッダーユニットをビルドしてインポートする

ヘッダーユニットとは

ヘッダーユニットをコンパイルする方法

方法 1: 特定のファイルをヘッダーユニットに変換する

プロジェクトプロパティを設定する

ヘッダーユニットをインポートするようにコードを変更する

方法 2: ヘッダーユニットを自動的にスキャンしてビルドする