docs/PCHInternals.rst

========================================
Precompiled Header and Modules Internals
========================================

.. contents::
   :local:

This document describes the design and implementation of Clang's precompiled
headers (PCH) and modules.  If you are interested in the end-user view, please
see the :ref:`User's Manual <usersmanual-precompiled-headers>`.

Using Precompiled Headers with ``clang``
----------------------------------------

The Clang compiler frontend, ``clang -cc1``, supports two command line options
for generating and using PCH files.

To generate PCH files using ``clang -cc1``, use the option `-emit-pch`:

.. code-block:: bash

  $ clang -cc1 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:

.. code-block:: bash

  $ clang -cc1 -include-pch test.h.pch test.c -o test.s

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.

Modules, as implemented in Clang, use the same mechanisms as precompiled
headers to save a serialized AST file (one per module) and use those AST
modules.  From an implementation standpoint, modules are a generalization of
precompiled headers, lifting a number of restrictions placed on precompiled
headers.  In particular, there can only be one precompiled header and it must
be included at the beginning of the translation unit.  The extensions to the
AST file format required for modules are discussed in the section on
:ref:`modules <pchinternals-modules>`.

Clang's AST files are designed with a compact on-disk representation, which
minimizes both creation time and the time required to initially load the AST
file.  The AST file itself contains a serialized representation of Clang's
abstract syntax trees and supporting data structures, stored using the same
compressed bitstream as `LLVM's bitcode file format
<http://llvm.org/docs/BitCodeFormat.html>`_.

Clang's AST files are loaded "lazily" from disk.  When an AST file is initially
loaded, Clang reads only a small amount of data from the AST file to establish
where certain important data structures are stored.  The amount of data read in
this initial load is independent of the size of the AST file, such that a
larger AST file does not lead to longer AST load times.  The actual header data
in the AST file --- macros, functions, variables, types, etc. --- is loaded
only when it is referenced from the user's code, at which point only that
entity (and those entities it depends on) are deserialized from the AST file.
With this approach, the cost of using an AST file for a translation unit is
proportional to the amount of code actually used from the AST file, rather than
being proportional to the size of the AST file itself.

When given the `-print-stats` option, Clang produces statistics
describing how much of the AST file was actually loaded from disk.  For a
simple "Hello, World!" program that includes the Apple ``Cocoa.h`` header
(which is built as a precompiled header), this option illustrates how little of
the actual precompiled header is required:

.. code-block:: none

  *** AST File Statistics:
    895/39981 source location entries read (2.238563%)
    19/15315 types read (0.124061%)
    20/82685 declarations read (0.024188%)
    154/58070 identifiers read (0.265197%)
    0/7260 selectors read (0.000000%)
    0/30842 statements read (0.000000%)
    4/8400 macros read (0.047619%)
    1/4995 lexical declcontexts read (0.020020%)
    0/4413 visible declcontexts read (0.000000%)
    0/7230 method pool entries read (0.000000%)
    0 method pool misses

For this small program, only a tiny fraction of the source locations, types,
declarations, identifiers, and macros were actually deserialized from the
precompiled header.  These statistics can be useful to determine whether the
AST file implementation can be improved by making more of the implementation
lazy.

Precompiled headers can be chained.  When you create a PCH while including an
existing PCH, Clang can create the new PCH by referencing the original file and
only writing the new data to the new file.  For example, you could create a PCH
out of all the headers that are very commonly used throughout your project, and
then create a PCH for every single source file in the project that includes the
code that is specific to that file, so that recompiling the file itself is very
fast, without duplicating the data from the common headers for every file.  The
mechanisms behind chained precompiled headers are discussed in a :ref:`later
section <pchinternals-chained>`.

AST File Contents
-----------------

An AST file produced by clang is an object file container with a ``clangast``
(COFF) or ``__clangast`` (ELF and Mach-O) section containing the serialized AST.
Other target-specific sections in the object file container are used to hold
debug information for the data types defined in the AST.  Tools built on top of
libclang that do not need debug information may also produce raw AST files that
only contain the serialized AST.

The ``clangast`` section is organized into several different blocks, each of
which contains the serialized representation of a part of Clang's internal
representation.  Each of the blocks corresponds to either a block or a record
within `LLVM's bitstream format <http://llvm.org/docs/BitCodeFormat.html>`_.
The contents of each of these logical blocks are described below.

.. image:: PCHLayout.png

The ``llvm-objdump`` utility provides a ``-raw-clang-ast`` option to extract the
binary contents of the AST section from an object file container.

The `llvm-bcanalyzer <http://llvm.org/docs/CommandGuide/llvm-bcanalyzer.html>`_
utility can be used to examine the actual structure of the bitstream for the AST
section.  This information can be used both to help understand the structure of
the AST section and to isolate areas where the AST representation can still be
optimized, e.g., through the introduction of abbreviations.


Metadata Block
^^^^^^^^^^^^^^

The metadata block contains several records that provide information about how
the AST file was built.  This metadata is primarily used to validate the use of
an AST file.  For example, a precompiled header built for a 32-bit x86 target
cannot be used when compiling for a 64-bit x86 target.  The metadata block
contains information about:

Language options
  Describes the particular language dialect used to compile the AST file,
  including major options (e.g., Objective-C support) and more minor options
  (e.g., support for "``//``" comments).  The contents of this record correspond to
  the ``LangOptions`` class.

Target architecture
  The target triple that describes the architecture, platform, and ABI for
  which the AST file was generated, e.g., ``i386-apple-darwin9``.

AST version
  The major and minor version numbers of the AST file format.  Changes in the
  minor version number should not affect backward compatibility, while changes
  in the major version number imply that a newer compiler cannot read an older
  precompiled header (and vice-versa).

Original file name
  The full path of the header that was used to generate the AST file.

Predefines buffer
  Although not explicitly stored as part of the metadata, the predefines buffer
  is used in the validation of the AST file.  The predefines buffer itself
  contains code generated by the compiler to initialize the preprocessor state
  according to the current target, platform, and command-line options.  For
  example, the predefines buffer will contain "``#define __STDC__ 1``" when we
  are compiling C without Microsoft extensions.  The predefines buffer itself
  is stored within the :ref:`pchinternals-sourcemgr`, but its contents are
  verified along with the rest of the metadata.

A chained PCH file (that is, one that references another PCH) and a module
(which may import other modules) have additional metadata containing the list
of all AST files that this AST file depends on.  Each of those files will be
loaded along with this AST file.

For chained precompiled headers, the language options, target architecture and
predefines buffer data is taken from the end of the chain, since they have to
match anyway.

.. _pchinternals-sourcemgr:

Source Manager Block
^^^^^^^^^^^^^^^^^^^^

The source manager block contains the serialized representation of Clang's
:ref:`SourceManager <SourceManager>` class, which handles the mapping from
source locations (as represented in Clang's abstract syntax tree) into actual
column/line positions within a source file or macro instantiation.  The AST
file's representation of the source manager also includes information about all
of the headers that were (transitively) included when building the AST file.

The bulk of the source manager block is dedicated to information about the
various files, buffers, and macro instantiations into which a source location
can refer.  Each of these is referenced by a numeric "file ID", which is a
unique number (allocated starting at 1) stored in the source location.  Clang
serializes the information for each kind of file ID, along with an index that
maps file IDs to the position within the AST file where the information about
that file ID is stored.  The data associated with a file ID is loaded only when
required by the front end, e.g., to emit a diagnostic that includes a macro
instantiation history inside the header itself.

The source manager block also contains information about all of the headers
that were included when building the AST file.  This includes information about
the controlling macro for the header (e.g., when the preprocessor identified
that the contents of the header dependent on a macro like
``LLVM_CLANG_SOURCEMANAGER_H``).

.. _pchinternals-preprocessor:

Preprocessor Block
^^^^^^^^^^^^^^^^^^

The preprocessor block contains the serialized representation of the
preprocessor.  Specifically, it contains all of the macros that have been
defined by the end of the header used to build the AST file, along with the
token sequences that comprise each macro.  The macro definitions are only read
from the AST file when the name of the macro first occurs in the program.  This
lazy loading of macro definitions is triggered by lookups into the
:ref:`identifier table <pchinternals-ident-table>`.

.. _pchinternals-types:

Types Block
^^^^^^^^^^^

The types block contains the serialized representation of all of the types
referenced in the translation unit.  Each Clang type node (``PointerType``,
``FunctionProtoType``, etc.) has a corresponding record type in the AST file.
When types are deserialized from the AST file, the data within the record is
used to reconstruct the appropriate type node using the AST context.

Each type has a unique type ID, which is an integer that uniquely identifies
that type.  Type ID 0 represents the NULL type, type IDs less than
``NUM_PREDEF_TYPE_IDS`` represent predefined types (``void``, ``float``, etc.),
while other "user-defined" type IDs are assigned consecutively from
``NUM_PREDEF_TYPE_IDS`` upward as the types are encountered.  The AST file has
an associated mapping from the user-defined types block to the location within
the types block where the serialized representation of that type resides,
enabling lazy deserialization of types.  When a type is referenced from within
the AST file, that reference is encoded using the type ID shifted left by 3
bits.  The lower three bits are used to represent the ``const``, ``volatile``,
and ``restrict`` qualifiers, as in Clang's :ref:`QualType <QualType>` class.

.. _pchinternals-decls:

Declarations Block
^^^^^^^^^^^^^^^^^^

The declarations block contains the serialized representation of all of the
declarations referenced in the translation unit.  Each Clang declaration node
(``VarDecl``, ``FunctionDecl``, etc.) has a corresponding record type in the
AST file.  When declarations are deserialized from the AST file, the data
within the record is used to build and populate a new instance of the
corresponding ``Decl`` node.  As with types, each declaration node has a
numeric ID that is used to refer to that declaration within the AST file.  In
addition, a lookup table provides a mapping from that numeric ID to the offset
within the precompiled header where that declaration is described.

Declarations in Clang's abstract syntax trees are stored hierarchically.  At
the top of the hierarchy is the translation unit (``TranslationUnitDecl``),
which contains all of the declarations in the translation unit but is not
actually written as a specific declaration node.  Its child declarations (such
as functions or struct types) may also contain other declarations inside them,
and so on.  Within Clang, each declaration is stored within a :ref:`declaration
context <DeclContext>`, as represented by the ``DeclContext`` class.
Declaration contexts provide the mechanism to perform name lookup within a
given declaration (e.g., find the member named ``x`` in a structure) and
iterate over the declarations stored within a context (e.g., iterate over all
of the fields of a structure for structure layout).

In Clang's AST file format, deserializing a declaration that is a
``DeclContext`` is a separate operation from deserializing all of the
declarations stored within that declaration context.  Therefore, Clang will
deserialize the translation unit declaration without deserializing the
declarations within that translation unit.  When required, the declarations
stored within a declaration context will be deserialized.  There are two
representations of the declarations within a declaration context, which
correspond to the name-lookup and iteration behavior described above:

* When the front end performs name lookup to find a name ``x`` within a given
  declaration context (for example, during semantic analysis of the expression
  ``p->x``, where ``p``'s type is defined in the precompiled header), Clang
  refers to an on-disk hash table that maps from the names within that
  declaration context to the declaration IDs that represent each visible
  declaration with that name.  The actual declarations will then be
  deserialized to provide the results of name lookup.
* When the front end performs iteration over all of the declarations within a
  declaration context, all of those declarations are immediately
  de-serialized.  For large declaration contexts (e.g., the translation unit),
  this operation is expensive; however, large declaration contexts are not
  traversed in normal compilation, since such a traversal is unnecessary.
  However, it is common for the code generator and semantic analysis to
  traverse declaration contexts for structs, classes, unions, and
  enumerations, although those contexts contain relatively few declarations in
  the common case.

Statements and Expressions
^^^^^^^^^^^^^^^^^^^^^^^^^^

Statements and expressions are stored in the AST file in both the :ref:`types
<pchinternals-types>` and the :ref:`declarations <pchinternals-decls>` blocks,
because every statement or expression will be associated with either a type or
declaration.  The actual statement and expression records are stored
immediately following the declaration or type that owns the statement or
expression.  For example, the statement representing the body of a function
will be stored directly following the declaration of the function.

As with types and declarations, each statement and expression kind in Clang's
abstract syntax tree (``ForStmt``, ``CallExpr``, etc.) has a corresponding
record type in the AST file, which contains the serialized representation of
that statement or expression.  Each substatement or subexpression within an
expression is stored as a separate record (which keeps most records to a fixed
size).  Within the AST file, the subexpressions of an expression are stored, in
reverse order, prior to the expression that owns those expression, using a form
of `Reverse Polish Notation
<http://en.wikipedia.org/wiki/Reverse_Polish_notation>`_.  For example, an
expression ``3 - 4 + 5`` would be represented as follows:

+-----------------------+
| ``IntegerLiteral(5)`` |
+-----------------------+
| ``IntegerLiteral(4)`` |
+-----------------------+
| ``IntegerLiteral(3)`` |
+-----------------------+
| ``IntegerLiteral(-)`` |
+-----------------------+
| ``IntegerLiteral(+)`` |
+-----------------------+
|       ``STOP``        |
+-----------------------+

When reading this representation, Clang evaluates each expression record it
encounters, builds the appropriate abstract syntax tree node, and then pushes
that expression on to a stack.  When a record contains *N* subexpressions ---
``BinaryOperator`` has two of them --- those expressions are popped from the
top of the stack.  The special STOP code indicates that we have reached the end
of a serialized expression or statement; other expression or statement records
may follow, but they are part of a different expression.

.. _pchinternals-ident-table:

Identifier Table Block
^^^^^^^^^^^^^^^^^^^^^^

The identifier table block contains an on-disk hash table that maps each
identifier mentioned within the AST file to the serialized representation of
the identifier's information (e.g, the ``IdentifierInfo`` structure).  The
serialized representation contains:

* The actual identifier string.
* Flags that describe whether this identifier is the name of a built-in, a
  poisoned identifier, an extension token, or a macro.
* If the identifier names a macro, the offset of the macro definition within
  the :ref:`pchinternals-preprocessor`.
* If the identifier names one or more declarations visible from translation
  unit scope, the :ref:`declaration IDs <pchinternals-decls>` of these
  declarations.

When an AST file is loaded, the AST file reader mechanism introduces itself
into the identifier table as an external lookup source.  Thus, when the user
program refers to an identifier that has not yet been seen, Clang will perform
a lookup into the identifier table.  If an identifier is found, its contents
(macro definitions, flags, top-level declarations, etc.) will be deserialized,
at which point the corresponding ``IdentifierInfo`` structure will have the
same contents it would have after parsing the headers in the AST file.

Within the AST file, the identifiers used to name declarations are represented
with an integral value.  A separate table provides a mapping from this integral
value (the identifier ID) to the location within the on-disk hash table where
that identifier is stored.  This mapping is used when deserializing the name of
a declaration, the identifier of a token, or any other construct in the AST
file that refers to a name.

.. _pchinternals-method-pool:

Method Pool Block
^^^^^^^^^^^^^^^^^

The method pool block is represented as an on-disk hash table that serves two
purposes: it provides a mapping from the names of Objective-C selectors to the
set of Objective-C instance and class methods that have that particular
selector (which is required for semantic analysis in Objective-C) and also
stores all of the selectors used by entities within the AST file.  The design
of the method pool is similar to that of the :ref:`identifier table
<pchinternals-ident-table>`: the first time a particular selector is formed
during the compilation of the program, Clang will search in the on-disk hash
table of selectors; if found, Clang will read the Objective-C methods
associated with that selector into the appropriate front-end data structure
(``Sema::InstanceMethodPool`` and ``Sema::FactoryMethodPool`` for instance and
class methods, respectively).

As with identifiers, selectors are represented by numeric values within the AST
file.  A separate index maps these numeric selector values to the offset of the
selector within the on-disk hash table, and will be used when de-serializing an
Objective-C method declaration (or other Objective-C construct) that refers to
the selector.

AST Reader Integration Points
-----------------------------

The "lazy" deserialization behavior of AST files requires their integration
into several completely different submodules of Clang.  For example, lazily
deserializing the declarations during name lookup requires that the name-lookup
routines be able to query the AST file to find entities stored there.

For each Clang data structure that requires direct interaction with the AST
reader logic, there is an abstract class that provides the interface between
the two modules.  The ``ASTReader`` class, which handles the loading of an AST
file, inherits from all of these abstract classes to provide lazy
deserialization of Clang's data structures.  ``ASTReader`` implements the
following abstract classes:

``ExternalSLocEntrySource``
  This abstract interface is associated with the ``SourceManager`` class, and
  is used whenever the :ref:`source manager <pchinternals-sourcemgr>` needs to
  load the details of a file, buffer, or macro instantiation.

``IdentifierInfoLookup``
  This abstract interface is associated with the ``IdentifierTable`` class, and
  is used whenever the program source refers to an identifier that has not yet
  been seen.  In this case, the AST reader searches for this identifier within
  its :ref:`identifier table <pchinternals-ident-table>` to load any top-level
  declarations or macros associated with that identifier.

``ExternalASTSource``
  This abstract interface is associated with the ``ASTContext`` class, and is
  used whenever the abstract syntax tree nodes need to loaded from the AST
  file.  It provides the ability to de-serialize declarations and types
  identified by their numeric values, read the bodies of functions when
  required, and read the declarations stored within a declaration context
  (either for iteration or for name lookup).

``ExternalSemaSource``
  This abstract interface is associated with the ``Sema`` class, and is used
  whenever semantic analysis needs to read information from the :ref:`global
  method pool <pchinternals-method-pool>`.

.. _pchinternals-chained:

Chained precompiled headers
---------------------------

Chained precompiled headers were initially intended to improve the performance
of IDE-centric operations such as syntax highlighting and code completion while
a particular source file is being edited by the user.  To minimize the amount
of reparsing required after a change to the file, a form of precompiled header
--- called a precompiled *preamble* --- is automatically generated by parsing
all of the headers in the source file, up to and including the last
``#include``.  When only the source file changes (and none of the headers it
depends on), reparsing of that source file can use the precompiled preamble and
start parsing after the ``#include``\ s, so parsing time is proportional to the
size of the source file (rather than all of its includes).  However, the
compilation of that translation unit may already use a precompiled header: in
this case, Clang will create the precompiled preamble as a chained precompiled
header that refers to the original precompiled header.  This drastically
reduces the time needed to serialize the precompiled preamble for use in
reparsing.

Chained precompiled headers get their name because each precompiled header can
depend on one other precompiled header, forming a chain of dependencies.  A
translation unit will then include the precompiled header that starts the chain
(i.e., nothing depends on it).  This linearity of dependencies is important for
the semantic model of chained precompiled headers, because the most-recent
precompiled header can provide information that overrides the information
provided by the precompiled headers it depends on, just like a header file
``B.h`` that includes another header ``A.h`` can modify the state produced by
parsing ``A.h``, e.g., by ``#undef``'ing a macro defined in ``A.h``.

There are several ways in which chained precompiled headers generalize the AST
file model:

Numbering of IDs
  Many different kinds of entities --- identifiers, declarations, types, etc.
  --- have ID numbers that start at 1 or some other predefined constant and
  grow upward.  Each precompiled header records the maximum ID number it has
  assigned in each category.  Then, when a new precompiled header is generated
  that depends on (chains to) another precompiled header, it will start
  counting at the next available ID number.  This way, one can determine, given
  an ID number, which AST file actually contains the entity.

Name lookup
  When writing a chained precompiled header, Clang attempts to write only
  information that has changed from the precompiled header on which it is
  based.  This changes the lookup algorithm for the various tables, such as the
  :ref:`identifier table <pchinternals-ident-table>`: the search starts at the
  most-recent precompiled header.  If no entry is found, lookup then proceeds
  to the identifier table in the precompiled header it depends on, and so one.
  Once a lookup succeeds, that result is considered definitive, overriding any
  results from earlier precompiled headers.

Update records
  There are various ways in which a later precompiled header can modify the
  entities described in an earlier precompiled header.  For example, later
  precompiled headers can add entries into the various name-lookup tables for
  the translation unit or namespaces, or add new categories to an Objective-C
  class.  Each of these updates is captured in an "update record" that is
  stored in the chained precompiled header file and will be loaded along with
  the original entity.

.. _pchinternals-modules:

Modules
-------

Modules generalize the chained precompiled header model yet further, from a
linear chain of precompiled headers to an arbitrary directed acyclic graph
(DAG) of AST files.  All of the same techniques used to make chained
precompiled headers work --- ID number, name lookup, update records --- are
shared with modules.  However, the DAG nature of modules introduce a number of
additional complications to the model:

Numbering of IDs
  The simple, linear numbering scheme used in chained precompiled headers falls
  apart with the module DAG, because different modules may end up with
  different numbering schemes for entities they imported from common shared
  modules.  To account for this, each module file provides information about
  which modules it depends on and which ID numbers it assigned to the entities
  in those modules, as well as which ID numbers it took for its own new
  entities.  The AST reader then maps these "local" ID numbers into a "global"
  ID number space for the current translation unit, providing a 1-1 mapping
  between entities (in whatever AST file they inhabit) and global ID numbers.
  If that translation unit is then serialized into an AST file, this mapping
  will be stored for use when the AST file is imported.

Declaration merging
  It is possible for a given entity (from the language's perspective) to be
  declared multiple times in different places.  For example, two different
  headers can have the declaration of ``printf`` or could forward-declare
  ``struct stat``.  If each of those headers is included in a module, and some
  third party imports both of those modules, there is a potentially serious
  problem: name lookup for ``printf`` or ``struct stat`` will find both
  declarations, but the AST nodes are unrelated.  This would result in a
  compilation error, due to an ambiguity in name lookup.  Therefore, the AST
  reader performs declaration merging according to the appropriate language
  semantics, ensuring that the two disjoint declarations are merged into a
  single redeclaration chain (with a common canonical declaration), so that it
  is as if one of the headers had been included before the other.

Name Visibility
  Modules allow certain names that occur during module creation to be "hidden",
  so that they are not part of the public interface of the module and are not
  visible to its clients.  The AST reader maintains a "visible" bit on various
  AST nodes (declarations, macros, etc.) to indicate whether that particular
  AST node is currently visible; the various name lookup mechanisms in Clang
  inspect the visible bit to determine whether that entity, which is still in
  the AST (because other, visible AST nodes may depend on it), can actually be
  found by name lookup.  When a new (sub)module is imported, it may make
  existing, non-visible, already-deserialized AST nodes visible; it is the
  responsibility of the AST reader to find and update these AST nodes when it
  is notified of the import.