wangtao
/
llvm-project
forked from OSchip/llvm-project
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

Start documenting precompiled headers 

llvm-svn: 72146
This commit is contained in:
Douglas Gregor 2009-05-20 00:16:32 +00:00
parent 68f1096212
commit 95fc37fd8f
2 changed files with 83 additions and 4 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

16
clang/docs/InternalsManual.html
View File

@ -31,7 +31,7 @@ td {
<ul>
</ul>
</li>
<li><a href="#pth">Pretokenized Headers (PTH)</a>
<li><a href="#pch">Precompiled Headers</a>
<li><a href="#libfrontend">The Frontend Library</a>
<ul>
</ul>
@ -548,11 +548,19 @@ This concept maps directly to the "spelling location" for the token.</p>
href="DriverInternals.html">here<a>.<p>
<!-- ======================================================================= -->
<h2 id="pth">Pretokenized Headers (PTH)</h2>
<h2 id="pch">Precompiled Headers</h2>
<!-- ======================================================================= -->
<p>Clang's current implementation of precompiled headers, known as PTH, is
documented <a href="PTHInternals.html">here</a>.</p>
<p>Clang supports two implementations of precompiled headers. The
default implementation, precompiled headers (<a
href="PCHInternals.html">PCH</a>) uses a serialized representation
of Clang's internal data structures, encoded with the <a
href="http://llvm.org/docs/BitCodeFormat.html">LLVM bitstream
format</a>. Pretokenized headers (<a
href="PTHInternals.html">PTH</a>), on the other hand, contain a
serialized representation of the tokens encountered when
preprocessing a header (and anything that header includes).</p>
<!-- ======================================================================= -->
<h2 id="libfrontend">The Frontend Library</h2>

71
clang/docs/PCHInternals.html Normal file
View File

@ -0,0 +1,71 @@
<!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>