Referenční informace k C++ header-units.json

Článek
10/12/2023

Soubor header-units.json slouží dvěma účelům:

Určete, které soubory hlaviček lze při zadání přeložit do jednotek /translateInclude záhlaví.
Minimalizujte duplicitní symboly, abyste zvýšili propustnost sestavení.

Tento soubor musí být ve stejném adresáři jako zahrnutý soubor hlaviček. Tento soubor se používá pouze v případě, že /translateInclude je zadán spolu s parametrem nebo /scanDependencies/sourceDependencies:directives.

Odůvodnění

Některé soubory hlaviček se nedají bezpečně přeložit do jednotek záhlaví. Soubory hlaviček, které jsou závislé na makrech, která nejsou definovaná na příkazovém řádku nebo které nejsou definované v hlavičkových souborech zahrnutých v záhlaví, se nedají přeložit do jednotek záhlaví.

Pokud záhlaví definuje makra, která ovlivňují, jestli jsou zahrnutá jiná záhlaví, není možné je bezpečně přeložit. Například dané a.hb.h a macros.h, které jsou všechny ve stejném adresáři:

// a.h

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

V header-units.json tomto adresáři může obsahovat a.h a b.h, ale ne macros.h. Příklad header-units.json by byl podobný tomuto:

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

macros.h Důvodem není, že v tomto header-units.json souboru nelze uvést, že během fáze kontroly nemusí být jednotka záhlaví (.ifc) ještě zkompilována pro macros.h. V takovém případě nebude definován a.h při MACRO kompilaci. To znamená b.h , že v seznamu závislostí pro a.h. Vzhledem k tomu, že není v seznamu závislostí, systém sestavení nevystaví jednotku hlavičky, a b.h to i přes to, že je uvedená v header-units.json souboru.

Chcete-li se tomuto problému vyhnout, pokud je závislost na makre v jiném souboru záhlaví, je soubor záhlaví, který definuje makro, vyloučen ze seznamu souborů, které lze zkompilovat do jednotky záhlaví. Tímto způsobem se soubor záhlaví, který definuje makro, považuje za normální #include a MACRO bude viditelný tak, aby b.h byl zahrnut a uveden jako jedna ze závislostí.

Zabránění duplicitním symbolům

Soubor header-units.json je také důležitý, protože umožňuje automatické vytváření jednotek záhlaví bez duplicitních symbolů. Dělá to vytvořením "atomických" hlaviček jednotek pro soubory uvedené v header-units.json. Importované jednotky záhlaví neobsahují duplicitní symboly z různých #include direktiv, které byly zpracovány při překladu souboru hlavičky.

Představte si například dva soubory hlaviček, které obsahují společný soubor hlaviček. Oba soubory hlaviček jsou součástí stejného zdrojového souboru:

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

Pokud kompilátor sestavil jednotky hlaviček pro a.ha , pak zkompilované jednotky a.h.ifczáhlaví , b.h.ifca c.h.ifc každý z nich by obsahoval všechny typy z b.h.c.hb.h Kompilace Source.cpp, která importuje obě a.h a c.h, by vyžadovala, aby kompilátor deduplikoval b.h typy, což by mělo vliv na výkon sestavení.

Pokud je header-units.json ale v b.h adresáři a /translateInclude je zadaný, stane se toto:

Kontrola a.h a c.h seznamy b.h jako import jednotek hlaviček v souborech kontroly závislostí vygenerovaných kompilátorem.
Systém sestavení čte soubory kontroly závislostí a určí, že se má sestavit b.h.ifc jako první.
Potom se systém sestavení přidá /headerUnit do b.h.ifc příkazového řádku pro kompilaci a.h a c.h. Volá kompilátor pro sestavení jednotek a.h.ifc záhlaví a c.h.ifc. Protože /translateInclude je zadán a /headerUnit for b.h.ifc je také zadán a.h.ifc a c.h.ifc nebude obsahovat b.h typy, takže v vytvořených jednotkách hlaviček nebudou žádné duplicity.

Schéma

Pro hlavičky STL (Standard Template Library) existuje headerunits.json soubor. Systém sestavení ho používá k určení, zda vytvořit jednotku záhlaví pro soubor hlaviček STL a pro jeho závislosti. Pokud soubor záhlaví STL není v seznamu, považuje se za normální #include místo importu jako jednotky záhlaví.

Soubor můžete zobrazit header-units.json v instalačním adresáři pro Visual Studio. Například: %ProgramFiles%\Microsoft Visual Studio\2022\Enterprise\VC\Tools\MSVC\14.30.30705\include\header-units.json

Soubor header-units.json začíná verzí schématu a za ním pole názvů hlaviček, které lze integrovat do jednotek hlaviček.

Schéma také podporuje komentáře, jak je znázorněno tady:

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

Pravidla hledání

Kompilátor hledá tento soubor ve stejném adresáři jako zpracovávaný soubor hlaviček. Pokud je knihovna uspořádaná do podadresářů, každý podadresář potřebuje svůj vlastní header-units.json soubor.

Viz také

Návod: Import knihoven STL jako jednotek hlaviček
Návod: Sestavení a import jednotek hlaviček v projektech Visual C++

Share via