In
computer programming
Computer programming is the process of performing a particular computation (or more generally, accomplishing a specific computing result), usually by designing and building an executable computer program. Programming involves tasks such as anal ...
, a precompiled header (PCH) is a (
C or
C++
C++ (pronounced "C plus plus") is a high-level general-purpose programming language created by Danish computer scientist Bjarne Stroustrup as an extension of the C programming language, or "C with Classes". The language has expanded significan ...
)
header file
Many programming languages and other computer files have a directive, often called include (sometimes copy or import), that causes the contents of the specified file to be inserted into the original file. These included files are called copybooks ...
that is compiled into an
intermediate form that is faster to process for the
compiler
In computing, a compiler is a computer program that translates computer code written in one programming language (the ''source'' language) into another language (the ''target'' language). The name "compiler" is primarily used for programs tha ...
. 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++
C++ (pronounced "C plus plus") is a high-level general-purpose programming language created by Danish computer scientist Bjarne Stroustrup as an extension of the C programming language, or "C with Classes". The language has expanded significan ...
programming language
A programming language is a system of notation for writing computer programs. Most programming languages are text-based formal languages, but they may also be graphical. They are a kind of computer language.
The description of a programming ...
s, a
header file
Many programming languages and other computer files have a directive, often called include (sometimes copy or import), that causes the contents of the specified file to be inserted into the original file. These included files are called copybooks ...
is a file whose text may be automatically included in another
source file
In computing, source code, or simply code, is any collection of code, with or without comments, written using a human-readable programming language, usually as plain text. The source code of a program is specially designed to facilitate the wo ...
by the
C preprocessor
The C preprocessor is the macro preprocessor for the C, Objective-C and C++ computer programming languages. The preprocessor provides the ability for the inclusion of header files, macro expansions, conditional compilation, and line control ...
by the use of a
preprocessor directive
In computer programming, a directive or pragma (from "pragmatic") is a language construct that specifies how a compiler (or other translator) should process its input. Directives are not part of the grammar of a programming language, and may vary ...
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
template
Template may refer to:
Tools
* Die (manufacturing), used to cut or shape material
* Mold, in a molding process
* Stencil, a pattern or overlay used in graphic arts (drawing, painting, etc.) and sewing to replicate letters, shapes or designs
...
s, like the
Eigen math library and
Boost C++ libraries
Boost, boosted or boosting may refer to:
Science, technology and mathematics
* Boost, positive manifold pressure in turbocharged engines
* Boost (C++ libraries), a set of free peer-reviewed portable C++ libraries
* Boost (material), a material b ...
. 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
The GNU Compiler Collection (GCC) is an optimizing compiler produced by the GNU Project supporting various programming languages, hardware architectures and operating systems. The Free Software Foundation (FSF) distributes GCC as free softwar ...
.
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++
Microsoft Visual C++ (MSVC) is a compiler for the C, C++ and C++/CX programming languages by Microsoft. MSVC is proprietary software; it was originally a standalone product but later became a part of Visual Studio and made available in both tri ...
(version 6.0 and newer) can precompile any code, not just headers.
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
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.
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.
pch.h
(named
stdafx.h
before Visual Studio 2017) 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
Microsoft Foundation Class Library (MFC) is a C++ object-oriented library for developing desktop applications for Windows.
MFC was introduced by Microsoft in 1992 and quickly gained widespread use. While Microsoft has introduced alternative app ...
(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
Clang is a compiler front end for the C, C++, Objective-C, and Objective-C++ programming languages, as well as the OpenMP, OpenCL, RenderScript, CUDA, and HIP frameworks. It acts as a drop-in replacement for the GNU Compiler Collection ...
compiler added support for PCH in Clang 2.5 / LLVM 2.5 of 2009. 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
In computer science, an abstract syntax tree (AST), or just syntax tree, is a tree representation of the abstract syntactic structure of text (often source code) written in a formal language. Each node of the tree denotes a construct occurr ...
(AST) and
symbol table
In computer science, a symbol table is a data structure used by a language translator such as a compiler or interpreter, where each identifier (or symbols), constants, procedures and functions in a program's source code is associated with info ...
to a precompiled header file.
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.
It uses the same ''bitcode'' file format that is employed by
LLVM
LLVM is a set of compiler and toolchain technologies that can be used to develop a front end for any programming language and a back end for any instruction set architecture. LLVM is designed around a language-independent intermediate repre ...
, encapsulated in clang-specific sections within
Common Object File Format
The Common Object File Format (COFF) is a format for executable, object code, and shared library computer files used on Unix systems. It was introduced in Unix System V, replaced the previously used a.out format, and formed the basis for exten ...
or
Extensible Linking Format files.
C++Builder
In the default project configuration, the
C++Builder
C++Builder is a rapid application development (RAD) environment, originally developed by Borland and owned by Embarcadero Technologies (a subsidiary of Idera), for writing programs in the C++ programming language currently targeting Windows (bo ...
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
The Visual Component Library (VCL) is a visual component-based object-oriented framework for developing the user interface of Microsoft Windows applications. It is written in Object Pascal.
History
The VCL was developed by Borland for use i ...
, 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
In the C and C++ programming languages, an #include guard, sometimes called a macro guard, header guard or file guard, is a particular construct used to avoid the problem of ''double inclusion'' when dealing with the include directive.
The ...
) and generates and tests a precompiled header for the specified files automatically.
Pretokenized header
A pretokenized header (PTH) is a header file stored in a form that has been run through
lexical analysis
In computer science, lexical analysis, lexing or tokenization is the process of converting a sequence of characters (such as in a computer program or web page) into a sequence of ''lexical tokens'' ( strings with an assigned and thus identified ...
, 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.
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.
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).
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.
See also
*
Prefix header
*
Single compilation unit
Single compilation unit (SCU) is a computer programming technique for the C and C++ languages, which reduces compilation time for programs spanning multiple files. Specifically, it allows the compiler to keep data from shared header files, defin ...
References
{{reflist, 30em, refs=
[{{cite web, ref={{harvid, MSDN, 2015a, title=Creating Precompiled Header Files, work=]MSDN
Microsoft Developer Network (MSDN) was the division of Microsoft responsible for managing the firm's relationship with developers and testers, such as hardware developers interested in the operating system (OS), and software developers developing ...
, publisher=Microsoft, url=https://msdn.microsoft.com/en-gb/library/szfdksca.aspx, year=2015, access-date=2018-03-28, archive-url=https://web.archive.org/web/20180328165615/https://msdn.microsoft.com/en-gb/library/szfdksca.aspx, archive-date=2018-03-28, url-status=dead
[{{cite web, ref={{harvid, MSDN, 2015b, title=Two Choices for Precompiling Code, work=MSDN, publisher=Microsoft, url=https://msdn.microsoft.com/en-gb/library/2yzw0wyd.aspx, year=2015, access-date=2018-03-28]
[{{cite web, ref={{harvid, MSDN, 2015c, title=/Yc (Create Precompiled Header File), work=MSDN, publisher=Microsoft, url=https://msdn.microsoft.com/en-gb/library/7zc28563.aspx, year=2015, access-date=2018-03-28]
[{{cite web, ref={{harvid, clang, 2018a, title=Pretokenized Headers (PTH), url=http://clang.llvm.org/docs/PTHInternals.html, work=Clang 7 documentation, author=The Clang Team, year=2018, access-date=2018-03-28, archive-url=https://web.archive.org/web/20180322163257/https://clang.llvm.org/docs/PTHInternals.html, archive-date=2018-03-22, url-status=dead]
[{{cite web, ref={{harvid, clang, 2018b, title=Precompiled Header and Modules Internals, url=http://clang.llvm.org/docs/PCHInternals.html, work=Clang 7 documentation, author=The Clang Team, year=2018, access-date=2018-03-28]
External links
The Care and Feeding of Pre-Compiled Headers
Source code
C (programming language) headers
C++