r241690 - Update PCHInternals.rst to document PCH wrapped in object file containers.

[Adrian Prantl]

Author: adrian
Date: Wed Jul  8 11:52:51 2015
New Revision: 241690

URL: http://llvm.org/viewvc/llvm-project?rev=241690&view=rev
Log:
Update PCHInternals.rst to document PCH wrapped in object file containers.

Modified:
    cfe/trunk/docs/PCHInternals.rst

Modified: cfe/trunk/docs/PCHInternals.rst
URL: http://llvm.org/viewvc/llvm-project/cfe/trunk/docs/PCHInternals.rst?rev=241690&r1=241689&r2=241690&view=diff
==============================================================================
--- cfe/trunk/docs/PCHInternals.rst (original)
+++ cfe/trunk/docs/PCHInternals.rst Wed Jul  8 11:52:51 2015
@@ -124,20 +124,30 @@ section <pchinternals-chained>`.
 AST File Contents
 -----------------
 
-Clang's AST files are organized into several different blocks, each of which
-contains the serialized representation of a part of Clang's internal
+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
 
-For a given AST file, 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 file.  This
-information can be used both to help understand the structure of the AST file
-and to isolate areas where AST files can still be optimized, e.g., through the
-introduction of abbreviations.
+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
 ^^^^^^^^^^^^^^