Precompiled header

Short description: Optimized type of file in computer programming

This article has multiple issues. Please help improve it or discuss these issues on the talk page. (Learn how and when to remove these template messages)

This article's lead section does not adequately summarize key points of its contents. Please consider expanding the lead to provide an accessible overview of all important aspects of the article. Please discuss this issue on the article's talk page. (December 2012)

|

(Learn how and when to remove this template message)

In computer programming, a precompiled header (PCH) 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. The ideas of precompiled headers were central to the development of C++ modules.

## Contents

* 1 Rationale
* 2 Usage
* 3 Common implementations
* 3.1 Microsoft Visual C and C++
* 3.2 GCC
* 3.3 clang
* 3.4 C++Builder
* 4 Pretokenized headers
* 5 Modules
* 6 See also
* 7 Notes
* 8 References
* 9 External links

## 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 OS X, respectively). This is especially true with the advent of large "header" libraries that make extensive use of templates, like Eigen, Boost, and POCO. They are written almost entirely as header files that the user `#include`s, rather than being linked at runtime. Thus, each time the user compiles their program, the user is essentially recompiling numerous header libraries as well. (These would be precompiled into shared objects or dynamic link libraries in non "header" 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

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

## Common implementations

### Microsoft Visual C and C++

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

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

### clang

The clang compiler added support for PCH in Clang 2.5 / LLVM 2.5 of 2009.[5] The compiler both tokenizes the input source code and performs syntactic and semantic analyses of headers, writing out the compiler's internal generated abstract syntax tree (AST) and symbol table to a precompiled header file.[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]

### 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.[7]: 76 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.

## Pretokenized headers

A pretokenized header (PTH) is a header file stored in a form that has been run through lexical analysis, but no semantic operations have been done on it. PTH is present in Clang before it supported PCH, and has also been tried in a branch of GCC.[8]

Compared to a full PCH mechanism, PTH has the advantages of language (and dialect) independence, as lexical analysis is similar for the C-family languages, and architecture independence, as the same stream of tokens can be used when compiling for different target architectures.[9] 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. In addition, 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 (PCH in clang allows random access).[9]

Clang's 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.[9]

## Modules

Modules, introduced in C++20, function similarly to precompiled headers, and are compiled to .pcm (precompiled module) files, similar to .pch files for precompiled headers. Modules allow greater encapsulation and control of exported symbols, and like precompiled headers allow for faster compilation.[10] Modules are handled entirely by the compiler rather than the preprocessor, and thus unlike precompiled headers, cannot export macros due to being handled after the preprocessing step.

Since C++23, the C++ standard library is provided as a module.[11]

## See also

* Prefix header
* Single compilation unit
* Modules (C++)
* Java package
* Java Platform Module System

## Notes

## References

1. ↑ "Creating Precompiled Header Files". MSDN. Microsoft. 2015. https://msdn.microsoft.com/en-gb/library/szfdksca.aspx.
2. ↑ "Two Choices for Precompiling Code". MSDN. Microsoft. 2015. https://msdn.microsoft.com/en-gb/library/2yzw0wyd.aspx.
3. ↑ 3.0 3.1 3.2 "/Yc (Create Precompiled Header File)". MSDN. Microsoft. 2015. https://msdn.microsoft.com/en-gb/library/7zc28563.aspx.
4. ↑ "Can I use #include "pch.h" instead of #include "stdafx.h" as my precompile header in Visual Studio C++?". https://stackoverflow.com/questions/51928685/can-i-use-include-pch-h-instead-of-include-stdafx-h-as-my-precompile-heade.
5. ↑ "LLVM 2.5 Release Notes". https://releases.llvm.org/2.5/docs/ReleaseNotes.html.
6. ↑ 6.0 6.1 6.2 The Clang Team (2018). "Precompiled Header and Modules Internals". Clang 7 documentation. http://clang.llvm.org/docs/PCHInternals.html.
7. ↑ Borland C++ Builder 6 Developer's Guide. Sams Publishing. 2003. ISBN 9780672324802.
8. ↑ "pph - GCC Wiki". https://gcc.gnu.org/wiki/pph.
9. ↑ 9.0 9.1 9.2 The Clang Team (2018). "Pretokenized Headers (PTH)". Clang 7 documentation. http://clang.llvm.org/docs/PTHInternals.html.
10. ↑ cppreference.com (2025). "Modules (since C++20)". https://en.cppreference.com/w/cpp/language/modules.
11. ↑ cppreference.com (2025). "C++ Standard Library". https://en.cppreference.com/w/cpp/standard_library.

## External links

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

* v
* t
* e

C++

* C++
* C++98
* C++03
* C++11
* C++14
* C++17
* C++20
* C++23

Features|

* Classes
* Exception handling
* Function overloading
* new and delete
* Operator overloading
* Operators
* Templates

Standard Library|

* I/O Streams
* Smart pointers
* STL
* Strings

Compilers|

* Comparison of C++ compilers
* Borland C++
* Borland Turbo C++
* C++Builder
* Clang
* GCC
* Intel C++ Compiler
* Oracle Solaris Studio
* Visual C++
* Watcom C/C++

IDEs|

* Comparison of C IDEs
* Anjuta
* CLion
* Code
* CodeLite
* Eclipse
* Geany
* Microsoft Visual Studio
* NetBeans
* KDevelop
* Qt Creator

Superset languages|

* Objective-C++
* C++/CLI
* ( C++/CX )
* Ch
* SYCL

Dialects|

* Embedded C++

Relative to
other languages|

* Compatibility of C and C++
* Comparison of Java and C++
* Comparison of ALGOL 68 and C++
* Comparison of programming languages

* Category

0.00

(0 votes)

Original source: https://en.wikipedia.org/wiki/Precompiled header. Read more

|

Retrieved from "https://handwiki.org/wiki/index.php?title=Precompiled_header&oldid=3873650"
*[v]: View this template
*[t]: Discuss this template
*[e]: Edit this template