Bagikan melalui

Referensi header-units.json C++

File ini header-units.json melayani dua tujuan:

  • Tentukan file header mana yang dapat diterjemahkan ke dalam unit header ketika /translateInclude ditentukan.
  • Minimalkan simbol duplikat untuk meningkatkan throughput build.

File ini harus berada dalam direktori yang sama dengan file header yang disertakan. File ini hanya digunakan ketika /translateInclude ditentukan bersama dengan /scanDependencies atau /sourceDependencies:directives.

Alasan

Beberapa file header tidak dapat diterjemahkan dengan aman ke unit header. File header yang bergantung pada makro yang tidak ditentukan pada baris perintah, atau yang tidak ditentukan dalam file header yang disertakan oleh header, tidak dapat diterjemahkan ke unit header.

Jika header menentukan makro yang memengaruhi apakah header lain disertakan, header tersebut tidak dapat diterjemahkan dengan aman. Misalnya, diberikan a.h, b.h dan macros.h, yang semuanya berada dalam direktori yang sama:

// a.h

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

Dalam header-units.json direktori ini dapat berisi a.h dan b.h, tetapi tidak macros.h. header-units.json Untuk contoh ini akan mirip dengan ini:

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

Alasan macros.h tidak dapat dicantumkan dalam file ini header-units.json adalah bahwa selama fase pemindaian, unit header (.ifc) mungkin belum dikompilasi untuk macros.h. Dalam hal ini, MACRO tidak akan didefinisikan ketika a.h dikompilasi. Itu berarti b.h akan hilang dari daftar dependensi untuk a.h. Karena tidak ada dalam daftar dependensi, sistem build tidak akan membangun unit header meskipun b.h tercantum dalam header-units.json file.

Untuk menghindari masalah ini, ketika ada dependensi pada makro di file header lain, file header yang menentukan makro dikecualikan dari daftar file yang dapat dikompilasi ke dalam unit header. Dengan cara ini file header yang mendefinisikan makro diperlakukan sebagai normal #include dan MACRO akan terlihat sehingga b.h disertakan dan dicantumkan sebagai salah satu dependensi.

Mencegah simbol duplikat

File header-units.json ini juga penting karena memungkinkan pembuatan unit header otomatis tanpa simbol duplikat. Ini dilakukan dengan membuat unit header "atom" untuk file yang tercantum di header-units.json. Unit header yang diimpor tidak berisi simbol duplikat dari berbagai #include arahan yang diproses saat menerjemahkan file header.

Misalnya, pertimbangkan dua file header yang keduanya menyertakan file header umum. Kedua file header disertakan oleh file sumber yang sama:

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

Jika kompiler membangun unit header untuk , dan , maka unit a.h.ifcheader yang dikompilasi , , b.h.ifcdan c.h.ifc masing-masing akan berisi semua jenis dari b.h.c.hb.h a.h Mengkompilasi Source.cpp, yang mengimpor dan a.h c.h, akan mengharuskan pengkompilasi untuk mendeduplikasi b.h jenis, yang akan memengaruhi performa build.

Tetapi jika ada header-units.json di b.h direktori, dan /translateInclude ditentukan, maka hal berikut terjadi:

  1. Pemindaian a.h dan c.h daftar b.h sebagai impor unit header dalam file pemindaian dependensi yang dihasilkan oleh pengkompilasi.
  2. Sistem build membaca file pemindaian dependensi dan menentukan untuk membangun b.h.ifc terlebih dahulu.
  3. Kemudian sistem build menambahkan /headerUnit ke b.h.ifc baris perintah untuk mengkompilasi a.h dan c.h. Ini memanggil pengkompilasi untuk membangun unit a.h.ifc header dan c.h.ifc. Karena /translateInclude ditentukan, dan /headerUnit for b.h.ifc juga ditentukan, a.h.ifc dan c.h.ifc tidak akan berisi b.h jenis, sehingga tidak akan ada duplikasi di unit header yang diproduksi.

Skema

Ada headerunits.json file untuk header Pustaka Templat Standar (STL). Sistem build menggunakannya untuk menentukan apakah akan membuat unit header untuk file header STL, dan untuk dependensinya. Jika file header STL tidak ada dalam daftar, file tersebut diperlakukan sebagai normal #include alih-alih mengimpornya sebagai unit header.

Anda dapat melihat file di header-units.json bawah direktori penginstalan untuk Visual Studio. Misalnya: %ProgramFiles%\Microsoft Visual Studio\2022\Enterprise\VC\Tools\MSVC\14.30.30705\include\header-units.json

File header-units.json dimulai dengan versi skema, diikuti dengan array nama file untuk header yang dapat dibangun ke dalam unit header.

Skema ini juga mendukung komentar, seperti yang ditunjukkan di sini:

{
    "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
        ...
}

Cari aturan

Pengkompilasi mencari file ini dalam direktori yang sama dengan file header yang sedang diproses. Jika pustaka Anda diatur ke dalam subdirektori, setiap subdirektori memerlukan filenya sendiri header-units.json .

Lihat juga

Panduan: Mengimpor pustaka STL sebagai unit header
Panduan: Membangun dan mengimpor unit header di proyek Visual C++ Anda

  • Last updated on