Precompiled header

In computer programming, a precompiled header is a (C or C++) header file that is compiled into an intermediate form that is faster to process for the compiler. Usage of precompiled headers may significantly reduce compilation time, especially when applied to large header files, header files that include many other header files, or header files that are included in many translation units.

Rationale

In the C and C++ programming languages, a header file is a file whose text may be automatically included in another source file by the C preprocessor by the use of a preprocessor directive in the source file.

Header files can sometimes contain very large amounts of source code (for instance, the header files windows.h and Cocoa/Cocoa.h on Microsoft Windows and Mac OS X, respectively). This is especially true with the advent of large "header" libraries that make extensive use of templates, like the Eigen math library and Boost C++ libraries. They are written almost entirely as header files that the user #includes, rather than being linked at runtime. Thus, each time the user compiles their program, the user is essentially recompiling numerous header libraries as well that would ordinarily have been precompiled into shared objects or dynamic link libraries.

To reduce compilation times, some compilers allow header files to be compiled into a form that is faster for the compiler to process. This intermediate form is known as a precompiled header, and is commonly held in a file named with the extension .pch or similar, such as .gch under the GNU Compiler Collection.

Usage

Simple example

Given a C++ file source.cpp that includes header.hpp:

//header.hpp
...

//source.cpp
#include "header.hpp"
...

When compiling source.cpp for the first time with the precompiled header feature turned on, the compiler will generate a precompiled header, header.pch. The next time, if the timestamp of this header did not change, the compiler can skip the compilation phase relating to header.hpp and instead use header.pch directly.

Forward declaration

We have two classes: A (defined in A.hpp and implemented in A.cpp) and B (defined in B.hpp and implemented in B.cpp). Class A is quite simple:

class A {
  ...
};

Suppose class B refers to an attribute of class A.

#include "A.hpp"
 
class B1 {
  ...
  A mA;
};

If the definition of class A were to change, B.hpp would have to be recompiled. To avoid this, a programmer might refer to A by a pointer. Under this syntax, B.hpp would be:

class A;
 
class B2 {
  ...
  A *mA;
};

As can be seen, a forward declaration of class A is used instead of including the header. But this pointer syntax complicates the usage of the variable as price for lesser compilation.

This problem is solved by the usage of precompiled headers. When the files are compiled for the first time, A.hpp and B.hpp are compiled into A.pch and B.pch, and A.cpp and B.cpp are compiled into their object files. When the definition of class A is changed, B.hpp does not have to be parsed again.

Common implementations

stdafx.h

stdafx.h is a file, generated by Microsoft Visual Studio IDE wizards, that describes both standard system and project specific include files that are used frequently but hardly ever change.

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

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 is used by default, projects may specify an alternative name and handle all includes files containing in project file.

GCC

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.

C++Builder

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. 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.

See also

External links