forked from OSchip/llvm-project
72 lines
2.6 KiB
HTML
72 lines
2.6 KiB
HTML
|
<!DOCTYPE HTML PUBLIC "-//IETF//DTD HTML//EN">
|
||
|
|
<html> <head>
|
||
|
|
<title>Precompiled Headers (PCH)</title>
|
||
|
|
</head>
|
||
|
|
|
||
|
|
<body>
|
||
|
|
|
||
|
|
<!--#include virtual="../menu.html.incl"-->
|
||
|
|
|
||
|
|
<div id="content">
|
||
|
|
|
||
|
|
<h1>Precompiled Headers</h1>
|
||
|
|
|
||
|
|
<p>This document describes the design and implementation of Clang's
|
||
|
|
precompiled headers (PCH). If you are interested in the end-user
|
||
|
|
view, please see the <a
|
||
|
|
href="UsersManual.html#precompiledheaders">User's Manual</a>.</p>
|
||
|
|
|
||
|
|
<h2>Using precompiled headers with <tt>clang-cc</tt></h2>
|
||
|
|
|
||
|
|
<p>The low-level Clang compiler, <tt>clang-cc</tt>, supports two command
|
||
|
|
line options for generating and using PCH files.<p>
|
||
|
|
|
||
|
|
<p>To generate PCH files using <tt>clang-cc</tt>, use the option
|
||
|
|
<b><tt>-emit-pch</tt></b>:
|
||
|
|
|
||
|
|
<pre> $ clang-cc test.h -emit-pch -o test.h.pch </pre>
|
||
|
|
|
||
|
|
<p>This option is transparently used by <tt>clang</tt> when generating
|
||
|
|
PCH files. The resulting PCH file contains the serialized form of the
|
||
|
|
compiler's internal representation after it has completed parsing and
|
||
|
|
semantic analysis. The PCH file can then be used as a prefix header
|
||
|
|
with the <b><tt>-include-pch</tt></b> option:</p>
|
||
|
|
|
||
|
|
<pre>
|
||
|
|
$ clang-cc -include-pch test.h.pch test.c -o test.s
|
||
|
|
</pre>
|
||
|
|
|
||
|
|
<h2>PCH Design Philosophy</h2>
|
||
|
|
|
||
|
|
<p>Precompiled headers are meant to improve overall compile times for
|
||
|
|
projects, so the design of precompiled headers is entirely driven by
|
||
|
|
performance concerns. The use case for precompiled headers is
|
||
|
|
relatively simple: when there is a common set of headers that is
|
||
|
|
included in nearly every source file in the project, we
|
||
|
|
<i>precompile</i> that bundle of headers into a single precompiled
|
||
|
|
header (PCH file). Then, when compiling the source files in the
|
||
|
|
project, we load the PCH file first (as a prefix header), which acts
|
||
|
|
as a stand-in for that bundle of headers.</p>
|
||
|
|
|
||
|
|
<p>A precompiled header implementation improves performance when:</p>
|
||
|
|
<ul>
|
||
|
|
<li>Loading the PCH file is significantly faster than re-parsing the
|
||
|
|
bundle of headers stored within the PCH file. Thus, a precompiled
|
||
|
|
header design attempts to minimize the cost of reading the PCH
|
||
|
|
file. Ideally, this cost should not vary with the size of the
|
||
|
|
precompiled header file.</li>
|
||
|
|
|
||
|
|
<li>The cost of generating the PCH file initially is not so large
|
||
|
|
that it counters the per-source-file performance improvement due to
|
||
|
|
eliminating the need to parse the bundled headers in the first
|
||
|
|
place. This is particularly important on multi-core systems, because
|
||
|
|
PCH file generation serializes the build when all compilations
|
||
|
|
require the PCH file to be up-to-date.</li>
|
||
|
|
</ul>
|
||
|
|
|
||
|
|
<p>More to be written...</p>
|
||
|
|
</div>
|
||
|
|
|
||
|
|
</body>
|
||
|
|
</html>
|