Precompiled header

In computer programming, a pre-compiled header is a technique used by some C or C++ compilers to reduce compilation time.

Overview

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, usually specified by the use of compiler directives in the source file.

Header files can sometimes contain a very large amount of source code (for instance, the header files windows.h and Cocoa/Cocoa.h on Microsoft Windows and Mac OS X, respectively).

To reduce compilation times some compilers allow header files to be precompiled 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 extensions .pch or .gch.

A related feature is the prefix header, which is a file that is automatically included by the compiler without requiring the use of any compiler directives. Prefix headers are commonly precompiled, but not all precompiled headers are prefix headers.

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 pre-compiled header feature turned on, the compiler will generate a pre-compiled header, header.pch. The next time, the compiler can skip the compilation phase relating to header.hpp and instead use header.pch directly.

Example with forward declaration

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

class A {
  ...
};

When class B is composed by an attribute of class A, normally the class A will become part of the class:

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

To prevent recompilation of B1.h, when class A changes, sometimes pointer syntax will be used; B2.h:

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 can be solved by the usage of pre-compiled headers. We can use the easier syntax in B1.h and advise the compiler to use pre-compiled headers. Then the files A.pch and B1.pch will be created.

When the class A is changed now, only A.h has to be parsed again and written to the pre-compiled header A.pch. As the file B1.h is not changed, it does not need to be parsed again and the already existing pre-compiled header B1.pch can be used.

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 pre-compile 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). Optionally, Visual Studio projects may avoid pre-compiled headers, as well as they may specify an alternative name (though stdafx.h is used by default).

GCC

Pre-compiled headers are supported in GCC (3.4 and newer). GCC's approach is similar to these of VC and compatible compilers. GCC saves the pre-compiled version using a ".gch" suffix. When compiling source files, the compiler checks whether those files are present. If possible, the pre-compiled version is used. If this is not possible, then, the normal header is still present as a fall-back plan.

GCC can only use the pre-compiled 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 pre-compiled header (because it must be directly or indirectly included through another normal header, before any compilable code).

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

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

• Single Compilation Unit
• Prefix header

External links

• The Care and Feeding of Pre-Compiled Headers
• Precompiled Headers with GCC
• Fractal eXtreme: Precompiled headers