From 32110dfd1c612e97996fa87c3ca6180461b9fb1f Mon Sep 17 00:00:00 2001 From: Douglas Gregor Date: Wed, 20 May 2009 00:16:32 +0000 Subject: [PATCH] Start documenting precompiled headers git-svn-id: https://llvm.org/svn/llvm-project/cfe/trunk@72146 91177308-0d34-0410-b5e6-96231b3b80d8 --- docs/InternalsManual.html | 16 ++++++--- docs/PCHInternals.html | 71 +++++++++++++++++++++++++++++++++++++++ 2 files changed, 83 insertions(+), 4 deletions(-) create mode 100644 docs/PCHInternals.html 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 { -
  • Pretokenized Headers (PTH) +
  • Precompiled Headers
  • The Frontend Library @@ -548,11 +548,19 @@ This concept maps directly to the "spelling location" for the token.

    href="DriverInternals.html">here.

    -

    Pretokenized Headers (PTH)

    +

    Precompiled Headers

    -

    Clang's current implementation of precompiled headers, known as PTH, is -documented here.

    +

    Clang supports two implementations of precompiled headers. The + default implementation, precompiled headers (PCH) uses a serialized representation + of Clang's internal data structures, encoded with the LLVM bitstream + format. Pretokenized headers (PTH), on the other hand, contain a + serialized representation of the tokens encountered when + preprocessing a header (and anything that header includes).

    +

    The Frontend Library

    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 @@ + + +Precompiled Headers (PCH) + + + + + + +
    + +

    Precompiled Headers

    + +

    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 User's Manual.

    + +

    Using precompiled headers with clang-cc

    + +

    The low-level Clang compiler, clang-cc, supports two command +line options for generating and using PCH files.

    + +

    To generate PCH files using clang-cc, use the option +-emit-pch: + +

     $ clang-cc test.h -emit-pch -o test.h.pch
    + +

    This option is transparently used by clang 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 -include-pch option:

    + +
    +  $ clang-cc -include-pch test.h.pch test.c -o test.s
+
    + +

    PCH Design Philosophy

    + +

    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 + precompile 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.

    + +

    A precompiled header implementation improves performance when:

    +
      +
    • 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.
      • + +
    • 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.
      • +
    + +

    More to be written...

    +
    + + + -- 2.50.1