diff options
| author | Douglas Gregor <dgregor@apple.com> | 2009-05-20 00:16:32 +0000 |
|---|---|---|
| committer | Douglas Gregor <dgregor@apple.com> | 2009-05-20 00:16:32 +0000 |
| commit | 32110dfd1c612e97996fa87c3ca6180461b9fb1f (patch) | |
| tree | e429897fb88f326e50d1a3e7d2dcd7f26202f0b3 /docs | |
| parent | 0529519a9feb1995ba88d179197454103b758866 (diff) | |
Start documenting precompiled headers
git-svn-id: https://llvm.org/svn/llvm-project/cfe/trunk@72146 91177308-0d34-0410-b5e6-96231b3b80d8
Diffstat (limited to 'docs')
| -rw-r--r-- | docs/InternalsManual.html | 16 | ||||
| -rw-r--r-- | docs/PCHInternals.html | 71 |
2 files changed, 83 insertions, 4 deletions
diff --git a/docs/InternalsManual.html b/docs/InternalsManual.html index 05b45a6ab3..a4d5a057eb 100644 --- a/docs/InternalsManual.html +++ b/docs/InternalsManual.html @@ -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> diff --git a/docs/PCHInternals.html b/docs/PCHInternals.html new file mode 100644 index 0000000000..d90c446e9f --- /dev/null +++ b/docs/PCHInternals.html @@ -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> |