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

adrian-prantl · adrian-prantl · commit 26686c4af0cb · 2015-07-08T16:52:51.000Z
llvm-svn: 241690
diff --git a/clang/docs/PCHInternals.rst b/clang/docs/PCHInternals.rst
@@ -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
 ^^^^^^^^^^^^^^
