Initial draft of PNaCl bitcode files.

native_client_sdk/src/doc/devguide/devcycle/building.rst

 .. _devcycle-building:
 
 ########
 Building
 ########
 
 .. contents:: Table Of Contents
   :local:
   :backlinks: none
   :depth: 2
@@ skipping 120 matching lines @@
 The PNaCl toolchain contains modified versions of the tools in the
 LLVM toolchain, as well as linkers and other tools from binutils.
 To determine which version of LLVM or binutils the tools are based upon,
 run the tool with the ``--version`` command line flag. These tools
 are used to compile and link applications into **.pexe** files. The toolchain
 also contains a tool to translate a **pexe** file into a
 architecture-specific **.nexe** (e.g., for debugging purposes).
 
 Some of the useful tools include:
 
-pnacl-abicheck
+``pnacl-abicheck``
   Checks that the **pexe** follows the PNaCl ABI rules.
-pnacl-ar
+``pnacl-ar``
   Creates archives (i.e., static libraries)
-pnacl-clang
+``pnacl-bcdis``
+  Object dumper for PNaCl bitcode files.
+``pnacl-clang``
   C compiler and compiler driver
-pnacl-clang++
+``pnacl-clang++``
   C++ compiler and compiler driver
-pnacl-compress
+``pnacl-compress``
   Compresses a finalized **pexe** file for deployment.
-pnacl-dis
+``pnacl-dis``
   Disassembler for both **pexe** files and **nexe** files
-pnacl-finalize
+``pnacl-finalize``
   Finalizes **pexe** files for deployment
-pnacl-ld
+``pnacl-ld``
   Bitcode linker
-pnacl-nm
+``pnacl-nm``
   Lists symbols in bitcode files, native code, and libraries
-pnacl-ranlib
+``pnacl-ranlib``
   Generates a symbol table for archives (i.e., static libraries)
-pnacl-translate
+``pnacl-translate``
   Translates a **pexe** to a native architecture, outside of the browser
 
 For the full list of tools, see the
 ``pepper_<version>/toolchain/<platform>_pnacl/bin`` directory.
 
 Using the PNaCl tools to compile, link, debug, and deploy
 =========================================================
 
 To build an application with the PNaCl SDK toolchain, you must compile
 your code, link it, test and debug it, and then deploy it. This section goes
@@ skipping 187 matching lines @@
 deployment (via ``pnacl-finalize``). Alternatively, you can apply this step as
 part of the finalizing step by adding the ``--compress`` flag to the
 ``pnacl-finalize`` command line.
 
 This compression step doesn't replace the gzip compression performed web servers
 configured for HTTP compression: both compressions are complementary. You'll
 want to configure your web server to gzip **pexe** files: the gzipped version of
 a compressed **pexe** file is smaller than the corresponding uncompressed
 **pexe** file by 7.5% to 10%.
 
+.. _pnacl-bcdis:
+
+Object dumping of PNaCl bitcode files
+=====================================
+
+Sometimes you may be interesting in the contents of a PNaCl bitcode file.  The
+tool ``pnacl-bcdis`` object dumps the contents of a PNaCl bitcode file.  For a
+description of the output produced by this tool, see
+:doc:`/reference/pnacl-bitcode-manual`.
+
+.. naclcode::
+ :prettyprint: 0
+
+  nacl_sdk/pepper_<version>/toolchain/win_pnacl/bin/pnacl-bcdis \
+    hello_world.final.pexe
+
+The output is the corresponding contents of the given **pexe**.
+
 The GNU-based toolchains
 ========================
 
 Besides the PNaCl toolchain, the Native Client SDK also includes modified
 versions of the tools in the standard GNU toolchain, including the GCC
 compilers and the linkers and other tools from binutils. These tools only
 support building **nexe** files. Run the tool with the ``--version``
 command line flag to determine the current version of the tools.
 
 Each tool in the toolchain is prefixed with the name of the target
@@ skipping 315 matching lines @@
   Function foo has disallowed type: i128 (i128)
   LLVM ERROR: PNaCl ABI verification failed
 
 When faced with a PNaCl ABI verification error, check the list of features
 that are :ref:`not supported by PNaCl <when-to-use-nacl>`.
 If the problem you face is not listed as restricted,
 :ref:`let us know <help>`!
 
 .. _glibc: http://www.gnu.org/software/libc/
 .. _newlib: http://sourceware.org/newlib/