Precompiled Headers

This document describes the design and implementation of Clang's precompiled headers (PCH). If you are interested in the end-user view, please see the User's Manual.

Using precompiled headers with clang-cc

The low-level Clang compiler, clang-cc, supports two command line options for generating and using PCH files.

To generate PCH files using clang-cc, use the option -emit-pch:

 $ clang-cc test.h -emit-pch -o test.h.pch 

This option is transparently used by clang when generating PCH files. The resulting PCH file contains the serialized form of the compiler's internal representation after it has completed parsing and semantic analysis. The PCH file can then be used as a prefix header with the -include-pch option:

  $ clang-cc -include-pch test.h.pch test.c -o test.s

PCH Design Philosophy

Precompiled headers are meant to improve overall compile times for projects, so the design of precompiled headers is entirely driven by performance concerns. The use case for precompiled headers is relatively simple: when there is a common set of headers that is included in nearly every source file in the project, we precompile that bundle of headers into a single precompiled header (PCH file). Then, when compiling the source files in the project, we load the PCH file first (as a prefix header), which acts as a stand-in for that bundle of headers.

A precompiled header implementation improves performance when:

• Loading the PCH file is significantly faster than re-parsing the bundle of headers stored within the PCH file. Thus, a precompiled header design attempts to minimize the cost of reading the PCH file. Ideally, this cost should not vary with the size of the precompiled header file.
• The cost of generating the PCH file initially is not so large that it counters the per-source-file performance improvement due to eliminating the need to parse the bundled headers in the first place. This is particularly important on multi-core systems, because PCH file generation serializes the build when all compilations require the PCH file to be up-to-date.

More to be written...