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

[アーティクル]
10/12/2023

このファイルには 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このディレクトリには、次を含b.ha.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コンパイルされていない可能性があるためです。その場合、 MACRO コンパイル時 a.h には定義されません。 b.hつまり、依存関係a.hの一覧には表示されません。依存関係の一覧に含まれていないため、ビルドシステムでは、ファイルに一覧表示されているにもかかわらず、ヘッダーユニット b.h は header-units.json ビルドされません。

この問題を回避するために、別のヘッダーファイル内のマクロに依存関係がある場合、そのマクロを定義するヘッダーファイルは、ヘッダーユニットにコンパイルできるファイルの一覧から除外されます。このように、マクロを定義するヘッダーファイルは通常#includeMACROのファイルとして扱われ、依存関係の 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";

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

ただし、ディレクトリにb.h存在header-units.jsonし/translateInclude、指定されている場合は、次の処理が行われます。

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

[スキーマ]

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

Visual Studio の header-units.json インストールディレクトリの下にファイルが表示されます。例: %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 のリファレンス

理由

重複するシンボルの防止

[スキーマ]

規則の検索

関連項目

フィードバック

フィードバック

その他のリソース