C++ header-units.json başvurusu

Makale
10/12/2023

Dosya header-units.json iki amaca hizmet eder:

Belirtildiğinde /translateInclude hangi üst bilgi dosyalarının üst bilgi birimlerine çevrilebileceğini belirtin.
Derleme aktarım hızını artırmak için yinelenen simgeleri simge durumuna küçültün.

Bu dosya, eklenen üst bilgi dosyasıyla aynı dizinde olmalıdır. Bu dosya yalnızca veya /sourceDependencies:directivesile /scanDependencies birlikte belirtildiğinde /translateInclude kullanılır.

Mantığı

Bazı üst bilgi dosyaları, üst bilgi birimlerine güvenli bir şekilde çevrilemez. Komut satırında tanımlanmayan veya üst bilgi tarafından eklenen üst bilgi dosyalarında tanımlanmayan makrolara bağlı üst bilgi dosyaları üst bilgi birimlerine çevrilemez.

Üst bilgi, diğer üst bilgilerin dahil edilip edilmediğini etkileyen makroları tanımlarsa, güvenli bir şekilde çevrilemez. Örneğin, tümü a.haynı dizinde yer alan ve b.h verilen , ve macros.h:

// a.h

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

header-units.json Bu dizindeki ve içerebilir, ancak içeremez b.ha.h macros.h. Bu örnekte aşağıdakine header-units.json benzer olacaktır:

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

Bu header-units.json dosyada listelenememenin nedenimacros.h, tarama aşamasında üst bilgi biriminin (.ifc) için macros.hhenüz derlenmemiş olmasıdır. Bu durumda, MACRO derlendiğinde a.h tanımlanmayacaktır. Bu, için a.hbağımlılık listesinde eksik olacağı anlamına gelirb.h. Bağımlılık listesinde olmadığından, derleme sistemi dosyasında listelenmiş header-units.json olmasına rağmen için b.h bir üst bilgi birimi oluşturmaz.

Bu sorunu önlemek için, başka bir üst bilgi dosyasındaki bir makroya bağımlılık olduğunda, makroyu tanımlayan üst bilgi dosyası, üst bilgi birimine derlenebilir dosyalar listesinden çıkarılır. Bu şekilde, makroyu tanımlayan üst bilgi dosyası normal #include olarak değerlendirilir ve MACRO bağımlılıklardan biri olarak eklenip listelenecek şekilde görünür b.h .

Yinelenen simgeleri engelleme

Dosya header-units.json , yinelenen simgeler olmadan otomatik üst bilgi birimi oluşturmaya izin verdiğinden de önemlidir. Bunu, içinde header-units.jsonlistelenen dosyalar için "atomik" üst bilgi birimleri oluşturarak yapar. İçeri aktarılan üst bilgi birimleri, üst bilgi dosyası çevrilirken işlenen çeşitli #include yönergelerden yinelenen simgeler içermez.

Örneğin, her ikisi de ortak bir üst bilgi dosyası içeren iki üst bilgi dosyasını göz önünde bulundurun. Her iki üst bilgi dosyası da aynı kaynak dosya tarafından eklenir:

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

Derleyici , ve için a.hüst bilgi birimleri derlediyse, derlenmiş üst bilgi birimleri a.h.ifc, b.h.ifcve c.h.ifc her biri içindeki b.htüm türleri c.hiçerir. b.h derleme, Source.cpphem hem de a.h c.hiçeri aktaran derleyicinin türleri yinelenenleri kaldırmasını b.h gerektirir ve bu da derleme performansını etkiler.

Ancak dizininde b.h bir header-units.json varsa ve /translateInclude belirtilmişse, aşağıdakiler gerçekleşir:

derleyicisi tarafından oluşturulan bağımlılık tarama a.h dosyalarında üst bilgi birimi içeri aktarması olarak ve c.h b.h taramasını listeler.
Derleme sistemi bağımlılık tarama dosyalarını okur ve önce derlemeyi b.h.ifc belirler.
Ardından derleme sistemi, ve c.hderlemesi için komut satırlarına a.h öğesini ekler /headerUnit b.h.ifc. ve üst bilgi birimlerini a.h.ifc c.h.ifcderlemek için derleyiciyi çağırır. Çünkü /translateInclude belirtilir ve /headerUnit for b.h.ifc ayrıca belirtilir a.h.ifc ve c.h.ifc türleri içermez b.h , bu nedenle üretilen üst bilgi birimlerinde yineleme olmaz.

Şema

Standart Şablon Kitaplığı (STL) üst bilgileri için bir headerunits.json dosya vardır. Derleme sistemi, bir STL üst bilgi dosyası ve bağımlılıkları için üst bilgi birimi oluşturulup oluşturulmayacağını belirlemek için bunu kullanır. STL üst bilgi dosyası listede yoksa, üst bilgi birimi olarak içeri aktarmak yerine normal #include olarak değerlendirilir.

Dosyayı Visual Studio yükleme dizininin altında görebilirsiniz header-units.json . Örneğin: %ProgramFiles%\Microsoft Visual Studio\2022\Enterprise\VC\Tools\MSVC\14.30.30705\include\header-units.json

Dosya header-units.json şema sürümüyle başlar ve ardından üst bilgi birimlerinde yerleşik olarak oluşturulabilecek üst bilgiler için bir dosya adları dizisi gelir.

Şema burada gösterildiği gibi açıklamaları da destekler:

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

Arama kuralları

Derleyici, bu dosyayı işlenen üst bilgi dosyasıyla aynı dizinde arar. Kitaplığınız alt dizinler halinde düzenlenmişse, her alt dizinin kendi header-units.json dosyası gerekir.

Ayrıca bkz.

İzlenecek yol: STL kitaplıklarını üst bilgi birimi olarak içeri aktarma
İzlenecek yol: Visual C++ projelerinizde üst bilgi birimleri oluşturma ve içeri aktarma

Aracılığıyla paylaş