C++ header-units.json のリファレンス

[アーティクル]
08/03/2024

header-units.json ファイルには、次の 2 つの目的があります。

/translateIncludeを指定した場合にヘッダー単位に変換できるヘッダーファイルを指定します。
重複するシンボルを最小限に抑えて、ビルドのスループットを向上させます。

このファイルは、含まれているヘッダーファイルと同じディレクトリに存在する必要があります。このファイルは、/scanDependenciesまたは/sourceDependencies:directivesと共に/translateIncludeが指定されている場合にのみ使用されます。

理由

一部のヘッダーファイルは、ヘッダーユニットに安全に変換できません。コマンドラインで定義されていないマクロに依存するヘッダーファイル、またはヘッダーに含まれるヘッダーファイルで定義されていないヘッダーファイルは、ヘッダーユニットに変換できません。

ヘッダーが他のヘッダーを含めるかどうかに影響するマクロを定義している場合、安全に変換することはできません。たとえば、 a.h、 b.h 、 macros.hを指定します。これらはすべて同じディレクトリにあります。

// a.h

#include "macros.h" // #defines MACRO=1
#ifdef MACRO
#include "b.h"
#endif

このディレクトリ内の header-units.json には、 a.h と b.hを含めることができますが、 macros.hは含まれません。この例の header-units.json は次のようになります。

{
    "Version": "1.0",
    "BuildAsHeaderUnits": [
        // macros.h should not be listed
        "a.h",
        "b.h"         
     ] 
}

このheader-units.json ファイルmacros.h一覧表示できない理由は、スキャンフェーズ中にヘッダーユニット (.ifc) がmacros.h用にまだコンパイルされていない可能性があるためです。その場合、a.hのコンパイル時にMACROは定義されません。つまり、 b.h は a.hの依存関係の一覧に表示されません。依存関係の一覧には含まれていないため、ビルドシステムは、header-units.json ファイルに一覧表示されているにもかかわらず、b.hのヘッダーユニットをビルドしません。

この問題を回避するために、別のヘッダーファイル内のマクロに依存関係がある場合、そのマクロを定義するヘッダーファイルは、ヘッダーユニットにコンパイルできるファイルの一覧から除外されます。このように、マクロを定義するヘッダーファイルは通常の #include として扱われ、 MACRO が表示され、依存関係の 1 つとして b.h が含まれて一覧表示されます。

重複するシンボルの防止

また、 header-units.json ファイルは、重複するシンボルを使用せずにヘッダーユニットを自動的に作成できるため、重要です。これを行うには、 header-units.jsonに記載されているファイルの "アトミック" ヘッダーユニットを作成します。インポートされたヘッダーユニットには、ヘッダーファイルの変換中に処理されたさまざまな #include ディレクティブの重複したシンボルは含まれません。

たとえば、両方に共通のヘッダーファイルを含む 2 つのヘッダーファイルがあるとします。両方のヘッダーファイルは、同じソースファイルに含まれています。

// a.h
#include "b.h"
 
// c.h
#include "b.h"
 
// Source.cpp
import "a.h";
import "c.h";

コンパイラが a.h、 b.h 、および c.hのヘッダーユニットをビルドした場合、コンパイルされたヘッダーユニット a.h.ifc、 b.h.ifc、 c.h.ifc には、 b.hのすべての型が含まれます。 a.hとc.hの両方をインポートするSource.cppをコンパイルするには、コンパイラがb.h型を重複除去する必要があり、ビルドのパフォーマンスに影響します。

ただし、b.h ディレクトリにheader-units.jsonがあり、/translateIncludeが指定されている場合は、次のようになります。

a.hとc.hのスキャンでは、コンパイラによって生成された依存関係スキャンファイルにヘッダーユニットのインポートとしてb.hが一覧表示されます。
ビルドシステムは依存関係スキャンファイルを読み取り、最初にビルド b.h.ifc 決定します。
その後、ビルドシステムは、a.hとc.hをコンパイルするためのコマンドラインにb.h.ifcの/headerUnitを追加します。コンパイラを呼び出して、 a.h.ifc および c.h.ifcヘッダーユニットをビルドします。 /translateIncludeが指定され、/headerUnit for b.h.ifcも指定されているため、a.h.ifcとc.h.ifcにはb.h型が含まれていないため、生成されたヘッダーユニットに重複はありません。

[スキーマ]

標準テンプレートライブラリ (STL) ヘッダー用の headerunits.json ファイルがあります。ビルドシステムはそれを使用して、STL ヘッダーファイルとその依存関係のヘッダーユニットを作成するかどうかを決定します。 STL ヘッダーファイルがリストにない場合、ヘッダーユニットとしてインポートするのではなく、通常の #include ファイルとして扱われます。

header-units.json ファイルは、Visual Studio のインストールディレクトリの下に表示されます。例: %ProgramFiles%\Microsoft Visual Studio\2022\Enterprise\VC\Tools\MSVC\14.30.30705\include\header-units.json

header-units.json ファイルはスキーマバージョンから始まり、ヘッダーユニットに組み込むことができるヘッダーのファイル名の配列が続きます。

スキーマでは、次に示すようにコメントもサポートされています。

{
    "Version": "1.0",
    "BuildAsHeaderUnits": [
        // "__msvc_all_public_headers.hpp", // for testing, not production
        "__msvc_system_error_abi.hpp",
        "__msvc_tzdb.hpp",
        "__msvc_xlocinfo_types.hpp",
        "algorithm",
        "any",
        "array",
        "atomic",
        "barrier",
        "bit",
        "bitset",
        // "cassert", // design is permanently incompatible with header units
        ...
}

規則の検索

コンパイラは、処理中のヘッダーファイルと同じディレクトリでこのファイルを検索します。ライブラリがサブディレクトリに編成されている場合、各サブディレクトリには独自の header-units.json ファイルが必要です。

次の方法で共有

C++ header-units.json のリファレンス

理由

重複するシンボルの防止

[スキーマ]

規則の検索

関連項目

フィードバック

その他のリソース