| Douglas Gregor | 32110df | 2009-05-20 00:16:32 +0000 | [diff] [blame^] | 1 | <!DOCTYPE HTML PUBLIC "-//IETF//DTD HTML//EN"> |
| 2 | <html> <head> |
| 3 | <title>Precompiled Headers (PCH)</title> |
| 4 | </head> |
| 5 | |
| 6 | <body> |
| 7 | |
| 8 | <!--#include virtual="../menu.html.incl"--> |
| 9 | |
| 10 | <div id="content"> |
| 11 | |
| 12 | <h1>Precompiled Headers</h1> |
| 13 | |
| 14 | <p>This document describes the design and implementation of Clang's |
| 15 | precompiled headers (PCH). If you are interested in the end-user |
| 16 | view, please see the <a |
| 17 | href="UsersManual.html#precompiledheaders">User's Manual</a>.</p> |
| 18 | |
| 19 | <h2>Using precompiled headers with <tt>clang-cc</tt></h2> |
| 20 | |
| 21 | <p>The low-level Clang compiler, <tt>clang-cc</tt>, supports two command |
| 22 | line options for generating and using PCH files.<p> |
| 23 | |
| 24 | <p>To generate PCH files using <tt>clang-cc</tt>, use the option |
| 25 | <b><tt>-emit-pch</tt></b>: |
| 26 | |
| 27 | <pre> $ clang-cc test.h -emit-pch -o test.h.pch </pre> |
| 28 | |
| 29 | <p>This option is transparently used by <tt>clang</tt> when generating |
| 30 | PCH files. The resulting PCH file contains the serialized form of the |
| 31 | compiler's internal representation after it has completed parsing and |
| 32 | semantic analysis. The PCH file can then be used as a prefix header |
| 33 | with the <b><tt>-include-pch</tt></b> option:</p> |
| 34 | |
| 35 | <pre> |
| 36 | $ clang-cc -include-pch test.h.pch test.c -o test.s |
| 37 | </pre> |
| 38 | |
| 39 | <h2>PCH Design Philosophy</h2> |
| 40 | |
| 41 | <p>Precompiled headers are meant to improve overall compile times for |
| 42 | projects, so the design of precompiled headers is entirely driven by |
| 43 | performance concerns. The use case for precompiled headers is |
| 44 | relatively simple: when there is a common set of headers that is |
| 45 | included in nearly every source file in the project, we |
| 46 | <i>precompile</i> that bundle of headers into a single precompiled |
| 47 | header (PCH file). Then, when compiling the source files in the |
| 48 | project, we load the PCH file first (as a prefix header), which acts |
| 49 | as a stand-in for that bundle of headers.</p> |
| 50 | |
| 51 | <p>A precompiled header implementation improves performance when:</p> |
| 52 | <ul> |
| 53 | <li>Loading the PCH file is significantly faster than re-parsing the |
| 54 | bundle of headers stored within the PCH file. Thus, a precompiled |
| 55 | header design attempts to minimize the cost of reading the PCH |
| 56 | file. Ideally, this cost should not vary with the size of the |
| 57 | precompiled header file.</li> |
| 58 | |
| 59 | <li>The cost of generating the PCH file initially is not so large |
| 60 | that it counters the per-source-file performance improvement due to |
| 61 | eliminating the need to parse the bundled headers in the first |
| 62 | place. This is particularly important on multi-core systems, because |
| 63 | PCH file generation serializes the build when all compilations |
| 64 | require the PCH file to be up-to-date.</li> |
| 65 | </ul> |
| 66 | |
| 67 | <p>More to be written...</p> |
| 68 | </div> |
| 69 | |
| 70 | </body> |
| 71 | </html> |