Add section on compressing pexe files for deployment.

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

 .. _devcycle-building:
 
 ########
 Building
 ########
 
 .. contents:: Table Of Contents
   :local:
   :backlinks: none
   :depth: 2
@@ skipping 143 matching lines @@
 tools include:
 
 pnacl-abicheck
   Check that the **pexe** follows the PNaCl ABI rules.
 pnacl-ar
   Creates archives (i.e., static libraries)
 pnacl-clang
   C compiler and compiler driver
 pnacl-clang++
   C++ compiler and compiler driver
+pnacl-compress
+  Size compresses a finalized **pexe** file for deployment.
 pnacl-dis
   Disassembler for both **pexe** files and **nexe** files
 pnacl-finalize
   Finalizes **pexe** files for deployment
 pnacl-ld
   Bitcode linker
 pnacl-nm
   Lists symbols in bitcode files, native code, and libraries
 pnacl-ranlib
   Generates a symbol table for archives (i.e., static libraries)
@@ skipping 143 matching lines @@
 and will be supported by future versions of PNaCl. The finalization step
 also helps minimize the size of your application for distribution by
 stripping out debug information and other metadata.
 
 Once the application is finalized, be sure to adjust the manifest file to
 refer to the final version of the application before deployment.
 The ``create_nmf.py`` tool helps generate an ``.nmf`` file, but ``.nmf``
 files can also be written by hand.
 
 
+
+Compressing the **pexe** for deployment
+---------------------------------------
+
+Size compression is an optional step for deployment, and reduces the
+size of the pexe file that must be transmitted over the wire. The tool
+pnacl-compress applies compression strategies that are already built

[jvoung (off chromium), 2014/02/26 18:01:04]

Some of the tool names are formatted with "``" around them. E.g.,
``x86_64-nacl-gcc`` below and ``pnacl-clang++`` above.

[Karl, 2014/02/27 18:37:27]

Done.

+into the **stable** binary format of a pexe application. As such,
+compressed pexe files do not need any extra time to be decompressed on
+the client's side. All costs are upfront when you call pnacl-compress.

[jvoung (off chromium), 2014/02/26 18:01:04]

Might be worth mentioning that it doesn't replace gzip. The effects stack a bit.

size(foo.gzip) - size(foo.pnacl-compressed.gzip) > 0

a couple of pexes I checked -- python ~7.8%, amiga emulator 4%, dragons 9.5%,
some other pexe 9.4%...

[Karl, 2014/02/27 18:37:27]

Added paragraph for this.

+
+Currently, this tool will compress pexe files by about 25%. However,
+it is somewhat slow (can take from seconds to minutes on large
+appications). Hence, this step is optional.
+
+.. naclcode::
+  :prettyprint: 0
+
+  <NACL_SDK_ROOT>/toolchain/win_pnacl/bin/pnacl-compress ^
+    hello_world.final.pexe
+
+Tool pncl-compress must be called after a pexe file has been finalized

[JF, 2014/02/26 17:27:21]

s/pncl/pnacl/

[Karl, 2014/02/27 18:37:27]

Done.

+for 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.
+
+
 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 312 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/