clang/docs/PCHInternals.rst

40 common set of headers that is included in nearly every source file in the
41 project, we *precompile* that bundle of headers into a single precompiled
43 load the PCH file first (as a prefix header), which acts as a stand-in for that
53 * The cost of generating the PCH file initially is not so large that it
78 this initial load is independent of the size of the AST file, such that a
81 only when it is referenced from the user's code, at which point only that
89 simple "Hello, World!" program that includes the Apple ``Cocoa.h`` header
117 out of all the headers that are very commonly used throughout your project, and
118 then create a PCH for every single source file in the project that includes the
119 code that is specific to that file, so that recompiling the file itself is very
131 libclang that do not need debug information may also produce raw AST files that
155 The metadata block contains several records that provide information about how
168   The target triple that describes the architecture, platform, and ABI for
174   in the major version number imply that a newer compiler cannot read an older
178   The full path of the header that was used to generate the AST file.
190 A chained PCH file (that is, one that references another PCH) and a module
192 of all AST files that this AST file depends on.  Each of those files will be
209 of the headers that were (transitively) included when building the AST file.
215 serializes the information for each kind of file ID, along with an index that
217 that file ID is stored.  The data associated with a file ID is loaded only when
218 required by the front end, e.g., to emit a diagnostic that includes a macro
222 that were included when building the AST file.  This includes information about
224 that the contents of the header dependent on a macro like
233 preprocessor.  Specifically, it contains all of the macros that have been
235 token sequences that comprise each macro.  The macro definitions are only read
251 Each type has a unique type ID, which is an integer that uniquely identifies
252 that type.  Type ID 0 represents the NULL type, type IDs less than
257 the types block where the serialized representation of that type resides,
259 the AST file, that reference is encoded using the type ID shifted left by 3
274 numeric ID that is used to refer to that declaration within the AST file.  In
275 addition, a lookup table provides a mapping from that numeric ID to the offset
276 within the precompiled header where that declaration is described.
290 In Clang's AST file format, deserializing a declaration that is a
292 declarations stored within that declaration context.  Therefore, Clang will
294 declarations within that translation unit.  When required, the declarations
302   refers to an on-disk hash table that maps from the names within that
303   declaration context to the declaration IDs that represent each visible
304   declaration with that name.  The actual declarations will then be
323 immediately following the declaration or type that owns the statement or
330 that statement or expression.  Each substatement or subexpression within an
333 reverse order, prior to the expression that owns those expression, using a form
354 that expression on to a stack.  When a record contains *N* subexpressions ---
356 top of the stack.  The special STOP code indicates that we have reached the end
365 The identifier table block contains an on-disk hash table that maps each
371 * Flags that describe whether this identifier is the name of a built-in, a
381 program refers to an identifier that has not yet been seen, Clang will perform
390 that identifier is stored.  This mapping is used when deserializing the name of
392 file that refers to a name.
399 The method pool block is represented as an on-disk hash table that serves two
401 set of Objective-C instance and class methods that have that particular
404 of the method pool is similar to that of the :ref:`identifier table
408 associated with that selector into the appropriate front-end data structure
415 Objective-C method declaration (or other Objective-C construct) that refers to
423 deserializing the declarations during name lookup requires that the name-lookup
426 For each Clang data structure that requires direct interaction with the AST
427 reader logic, there is an abstract class that provides the interface between
440   is used whenever the program source refers to an identifier that has not yet
443   declarations or macros associated with that identifier.
470 depends on), reparsing of that source file can use the precompiled preamble and
473 compilation of that translation unit may already use a precompiled header: in
475 header that refers to the original precompiled header.  This drastically
481 translation unit will then include the precompiled header that starts the chain
484 precompiled header can provide information that overrides the information
486 ``B.h`` that includes another header ``A.h`` can modify the state produced by
494   --- have ID numbers that start at 1 or some other predefined constant and
497   that depends on (chains to) another precompiled header, it will start
503   information that has changed from the precompiled header on which it is
508   Once a lookup succeeds, that result is considered definitive, overriding any
516   class.  Each of these updates is captured in an "update record" that is
542   If that translation unit is then serialized into an AST file, this mapping
555   semantics, ensuring that the two disjoint declarations are merged into a
556   single redeclaration chain (with a common canonical declaration), so that it
560   Modules allow certain names that occur during module creation to be "hidden",
561   so that they are not part of the public interface of the module and are not
563   AST nodes (declarations, macros, etc.) to indicate whether that particular
565   inspect the visible bit to determine whether that entity, which is still in