C++ header-units.json 참조

아티클
10/12/2023

이 파일은 header-units.json 다음 두 가지 용도로 사용됩니다.

지정된 경우 /translateInclude 헤더 단위로 변환할 수 있는 헤더 파일을 지정합니다.
중복 기호를 최소화하여 빌드 처리량을 높입니다.

이 파일은 포함된 헤더 파일과 동일한 디렉터리에 있어야 합니다. 이 파일은 둘 중 하나 /scanDependencies 또는 /sourceDependencies:directives.와 함께 지정된 경우에만 사용됩니다/translateInclude.

이유

일부 헤더 파일은 헤더 단위로 안전하게 변환할 수 없습니다. 명령줄에 정의되지 않았거나 헤더에 포함된 헤더 파일에 정의되지 않은 매크로에 의존하는 헤더 파일은 헤더 단위로 변환할 수 없습니다.

헤더가 다른 헤더가 포함되는지 여부에 영향을 주는 매크로를 정의하는 경우 안전하게 변환할 수 없습니다. 예를 들어 지정된 a.hb.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입니다. 이 경우 MACRO 컴파일될 때 a.h 정의되지 않습니다. 즉 b.h , 에 대한 a.h종속성 목록에서 누락됩니다. 종속성 목록에 없으므로 빌드 시스템은 파일에 나열 header-units.json 되어 있음에도 불구하고 헤더 단위를 b.h 빌드하지 않습니다.

이 문제를 방지하기 위해 다른 헤더 파일의 매크로에 대한 종속성이 있는 경우 매크로를 정의하는 헤더 파일은 헤더 단위로 컴파일할 수 있는 파일 목록에서 제외됩니다. 이렇게 하면 매크로를 정의하는 헤더 파일이 정상 #include 으로 처리되고 MACRO 종속성 중 하나로 포함되고 나열되도록 b.h 표시됩니다.

중복 기호 방지

중복 header-units.json 된 기호 없이 자동 헤더 단위를 만들 수 있으므로 파일도 중요합니다. 이 작업은 나열된 파일에 대한 "atomic" 헤더 단위를 만들어서 수행합니다 header-units.json. 가져온 헤더 단위는 헤더 파일을 변환하는 동안 처리된 다양한 #include 지시문의 중복 기호를 포함하지 않습니다.

예를 들어 공통 헤더 파일을 모두 포함하는 두 개의 헤더 파일을 고려해 보세요. 두 헤더 파일은 동일한 소스 파일에 포함됩니다.

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

컴파일러가 에 대한 a.hb.h 헤더 단위를 빌드한 c.h다음 컴파일된 헤더 단위b.h.ifca.h.ifc를 빌드한 c.h.ifc 경우 각각에 있는 모든 형식b.h이 포함됩니다. Source.cpp둘 다 a.h c.h가져오는 컴파일을 수행하려면 컴파일러가 형식을 중복 제거 b.h 해야 하며 이는 빌드 성능에 영향을 줍니다.

그러나 디렉터리에 /translateInclude 있고 header-units.json b.h 지정된 경우 다음이 발생합니다.

컴파일러에서 생성한 종속성 검사 파일에서 헤더 단위 가져오기로 나열되는 검색 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 않으므로 생성된 헤더 단위에는 중복이 없습니다.

스키마

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 파일이 필요합니다.

참고 항목

연습: STL 라이브러리를 헤더 단위로 가져오기
연습: Visual C++ 프로젝트에서 헤더 단위 빌드 및 가져오기

다음을 통해 공유

C++ header-units.json 참조

이유

중복 기호 방지

스키마

규칙 검색

참고 항목

피드백

추가 리소스