Precompiled header

Microsoft Visual C++ (version 6.0 and newer) can precompile any code, not just headers.[1] It can do this in two ways: either precompiling all code up to a file whose name matches the /Ycfilename option or (when /Yc is specified without any filename) precompiling all code up to the first occurrence of #pragma hdrstop in the code[2][3] The precompiled output is saved in a file named after the filename given to the /Yc option, with a .pch extension, or in a file named according to the name supplied by the /Fpfilename option.[3] The /Yu option, subordinate to the /Yc option if used together, causes the compiler to make used of already precompiled code from such a file.[3]

pch.h (named stdafx.h before Visual Studio 2017[4]) is a file generated by the Microsoft Visual Studio IDE wizard, that describes both standard system and project specific include files that are used frequently but hardly ever change.

The afx in stdafx.h stands for application framework extensions. AFX was the original abbreviation for the Microsoft Foundation Classes (MFC). While the name stdafx.h was used by default in MSVC projects prior to version 2017, any alternative name may be manually specified.

Compatible compilers will precompile this file to reduce overall compile times. Visual C++ will not compile anything before the #include "pch.h" in the source file, unless the compile option /Yu'pch.h' is unchecked (by default); it assumes all code in the source up to and including that line is already compiled.

The clang compiler has two mechanisms.

The original, simpler and less powerful, mechanism was pretokenized headers where the stream of lexical tokens in one or more source files is stored in what is in effect a token cache, from which they can be more quickly retrieved in subsequent compilations than performing lexical analysis again on the original source files.[5]

Compared to a full precompiled header mechanism this has the advantages of language independence, as lexical analysis is the same in clang for the C, C++, Objective C, and Objective C++ languages, and architecture independence, as the same stream of tokens can be used when compiling for different target architectures.[5] It however has the disadvantage of not going any further than simple lexical analysis, requiring that syntactic and semantic analysis of the token stream be performed with every compilation; and the time to compile scaling linearly with the size, in lexical tokens, of the pretokenized file, which is not necessarily the case for a fully-fledged precompilation mechanism.[5]

The pretokenization mechanism includes several minor mechanisms for assisting the pre-processor: caching of file existence and datestamp information, and recording inclusion guards so that guarded code can be quickly skipped over.[5]

Later clang development thus introduced a fully fledged precompiled header mechanism.[6] This both tokenizes the input source code and performs syntactic and semantic analyses of it, writing out the compiler's internal generated abstract syntax tree (AST) and symbol table to a precompiled header file.[6]

Compared to the pretokenized header mechanism, this scales much better, as when reading the precompiled header file back in the compiler is not constrained by the fact that the input is a stream (of lexical tokens) to read the file linearly, using sequential I/O.[6] The AST is written to the precompiled header file in such a way that the compiler can read it in using random-access I/O, in particular not reading in the parts of the precompiled AST that subsequent code does not in fact reference, which is a common occurrence with headers that provide large template libraries.[6] This eliminates the problem of reading the cache file scaling linearly with the size of the precompiled input.[6]

The downside is, however, the loss of generality compared to the pretokenization mechanism.[5][6] The precompiled header has to store information about the language dialect being used, down to the level of whether things like C++-style // comments are enabled in non-C++ languages, the target architecture, the compiler version (more specifically, the version of the internal AST data structure that the compiler is using), and the list of predefined pre-processor macros; so that upon re-reading the precompiled header file the compiler can ensure that it is using a precompiled header that is valid for the compilation at hand.[6]

clang's precompiled header scheme, with some improvements such as the ability for one precompiled header to reference another, internally used, precompiled header, also forms the basis for its modules mechanism.[6] It uses the same bitcode file format that is employed by LLVM, encapsulated in clang-specific sections within Common Object File Format or Extensible Linking Format files.[6]

Precompiled headers are supported in GCC (3.4 and newer). GCC's approach is similar to these of VC and compatible compilers. GCC saves precompiled versions of header files using a ".gch" suffix. When compiling a source file, the compiler checks whether this file is present in the same directory and uses it if possible.

GCC can only use the precompiled version if the same compiler switches are set as when the header was compiled and it may use at most one. Further, only preprocessor instructions may be placed before the precompiled header (because it must be directly or indirectly included through another normal header, before any compilable code).

GCC automatically identifies most header files by their extension. However, if this fails (e.g. because of non-standard header extensions), the -x switch can be used to ensure that GCC treats the file as a header.

In the default project configuration, the C++Builder compiler implicitly generates precompiled headers for all headers included by a source module until the line #pragma hdrstop is found.[7] Precompiled headers are shared for all modules of the project if possible. For example, when working with the Visual Component Library, it is common to include the vcl.h header first which contains most of the commonly used VCL header files. Thus, the precompiled header can be shared across all project modules, which dramatically reduces the build times.

In addition, C++Builder can be instrumented to use a specific header file as precompiled header, similar to the mechanism provided by Visual C++.

C++Builder 2009 introduces a "Precompiled Header Wizard" which parses all source modules of the project for included header files, classifies them (i.e. excludes header files if they are part of the project or do not have an Include guard) and generates and tests a precompiled header for the specified files automatically.