Add section on compressing pexe files for deployment.

native_client_sdk/doc_generated/devguide/devcycle/building.html

 {{+bindTo:partials.standard_nacl_article}}
 
 <section id="building">
 <span id="devcycle-building"></span><h1 id="building"><span id="devcycle-building"></span>Building</h1>
 <div class="contents local" id="table-of-contents" style="display: none">
 <p class="topic-title first">Table Of Contents</p>
 <ul class="small-gap">
 <li><p class="first"><a class="reference internal" href="#introduction" id="id4">Introduction</a></p>
 <ul class="small-gap">
 <li><a class="reference internal" href="#target-architectures" id="id5">Target architectures</a></li>
 <li><a class="reference internal" href="#c-libraries" id="id6">C libraries</a></li>
 <li><a class="reference internal" href="#c-standard-libraries" id="id7">C++ standard libraries</a></li>
 <li><a class="reference internal" href="#sdk-toolchains" id="id8">SDK toolchains</a></li>
 <li><a class="reference internal" href="#sdk-toolchains-versus-your-hosted-toolchain" id="id9">SDK toolchains versus your hosted toolchain</a></li>
 </ul>
 </li>
 <li><a class="reference internal" href="#the-pnacl-toolchain" id="id10">The PNaCl toolchain</a></li>
 <li><p class="first"><a class="reference internal" href="#using-the-pnacl-tools-to-compile-link-debug-and-deploy" id="id11">Using the PNaCl tools to compile, link, debug, and deploy</a></p>
 <ul class="small-gap">
 <li><a class="reference internal" href="#compile" id="id12">Compile</a></li>
 <li><a class="reference internal" href="#create-a-static-library" id="id13">Create a static library</a></li>
 <li><a class="reference internal" href="#link-the-application" id="id14">Link the application</a></li>
 <li><a class="reference internal" href="#finalizing-the-pexe-for-deployment" id="id15">Finalizing the <strong>pexe</strong> for deployment</a></li>
+<li><a class="reference internal" href="#compressing-the-pexe-for-deployment" id="id16">Compressing the <strong>pexe</strong> for deployment</a></li>
 </ul>
 </li>
-<li><p class="first"><a class="reference internal" href="#the-gnu-based-toolchains" id="id16">The GNU-based toolchains</a></p>
+<li><p class="first"><a class="reference internal" href="#the-gnu-based-toolchains" id="id17">The GNU-based toolchains</a></p>
 <ul class="small-gap">
-<li><a class="reference internal" href="#compiling" id="id17">Compiling</a></li>
-<li><a class="reference internal" href="#creating-libraries-and-linking" id="id18">Creating libraries and Linking</a></li>
-<li><a class="reference internal" href="#finalizing-a-nexe-for-deployment" id="id19">Finalizing a <strong>nexe</strong> for deployment</a></li>
+<li><a class="reference internal" href="#compiling" id="id18">Compiling</a></li>
+<li><a class="reference internal" href="#creating-libraries-and-linking" id="id19">Creating libraries and Linking</a></li>
+<li><a class="reference internal" href="#finalizing-a-nexe-for-deployment" id="id20">Finalizing a <strong>nexe</strong> for deployment</a></li>
 </ul>
 </li>
-<li><a class="reference internal" href="#using-make" id="id20">Using make</a></li>
-<li><a class="reference internal" href="#libraries-and-header-files-provided-with-the-sdk" id="id21">Libraries and header files provided with the SDK</a></li>
-<li><p class="first"><a class="reference internal" href="#troubleshooting" id="id22">Troubleshooting</a></p>
+<li><a class="reference internal" href="#using-make" id="id21">Using make</a></li>
+<li><a class="reference internal" href="#libraries-and-header-files-provided-with-the-sdk" id="id22">Libraries and header files provided with the SDK</a></li>
+<li><p class="first"><a class="reference internal" href="#troubleshooting" id="id23">Troubleshooting</a></p>
 <ul class="small-gap">
-<li><a class="reference internal" href="#undefined-reference-error" id="id23">&#8220;Undefined reference&#8221; error</a></li>
-<li><a class="reference internal" href="#can-t-find-libraries-containing-necessary-symbols" id="id24">Can&#8217;t find libraries containing necessary symbols</a></li>
-<li><a class="reference internal" href="#pnacl-abi-verification-errors" id="id25">PNaCl ABI Verification errors</a></li>
+<li><a class="reference internal" href="#undefined-reference-error" id="id24">&#8220;Undefined reference&#8221; error</a></li>
+<li><a class="reference internal" href="#can-t-find-libraries-containing-necessary-symbols" id="id25">Can&#8217;t find libraries containing necessary symbols</a></li>
+<li><a class="reference internal" href="#pnacl-abi-verification-errors" id="id26">PNaCl ABI Verification errors</a></li>
 </ul>
 </li>
 </ul>
 
 </div><section id="introduction">
 <h2 id="introduction">Introduction</h2>
 <p>This document describes how to build Native Client modules. It is intended for
 developers who have experience writing, compiling, and linking C and C++ code.
 If you haven&#8217;t read the Native Client <a class="reference internal" href="/native-client/overview.html"><em>Technical Overview</em></a> and <a class="reference internal" href="/native-client/devguide/tutorial/index.html"><em>Tutorial</em></a>, we recommend starting
 with those.</p>
@@ skipping 102 matching lines @@
 tools include:</p>
 <dl class="docutils">
 <dt>pnacl-abicheck</dt>
 <dd>Check that the <strong>pexe</strong> follows the PNaCl ABI rules.</dd>
 <dt>pnacl-ar</dt>
 <dd>Creates archives (i.e., static libraries)</dd>
 <dt>pnacl-clang</dt>
 <dd>C compiler and compiler driver</dd>
 <dt>pnacl-clang++</dt>
 <dd>C++ compiler and compiler driver</dd>
+<dt>pnacl-compress</dt>
+<dd>Size compresses a finalized <strong>pexe</strong> file for deployment.</dd>
 <dt>pnacl-dis</dt>
 <dd>Disassembler for both <strong>pexe</strong> files and <strong>nexe</strong> files</dd>
 <dt>pnacl-finalize</dt>
 <dd>Finalizes <strong>pexe</strong> files for deployment</dd>
 <dt>pnacl-ld</dt>
 <dd>Bitcode linker</dd>
 <dt>pnacl-nm</dt>
 <dd>Lists symbols in bitcode files, native code, and libraries</dd>
 <dt>pnacl-ranlib</dt>
 <dd>Generates a symbol table for archives (i.e., static libraries)</dd>
@@ skipping 107 matching lines @@
 <p>Prior to finalization, the application <strong>pexe</strong> is stored in a binary
 format that is subject to change.  After finalization, the application
 pexe is <strong>rewritten</strong> into a different binary format that is <strong>stable</strong>
 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.</p>
 <p>Once the application is finalized, be sure to adjust the manifest file to
 refer to the final version of the application before deployment.
 The <code>create_nmf.py</code> tool helps generate an <code>.nmf</code> file, but <code>.nmf</code>
 files can also be written by hand.</p>
+</section><section id="compressing-the-pexe-for-deployment">
+<h3 id="compressing-the-pexe-for-deployment">Compressing the <strong>pexe</strong> for deployment</h3>
+<p>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
+<code>pnacl-compress</code> applies compression strategies that are already built
+into the <strong>stable</strong> binary format of a pexe application. As such,
+compressed pexe files do not need any extra time to be decompressed on
+the client&#8217;s side. All costs are upfront when you call <code>pnacl-compress</code>.</p>
+<p>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.</p>
+<pre>
+&lt;NACL_SDK_ROOT&gt;/toolchain/win_pnacl/bin/pnacl-compress ^
+  hello_world.final.pexe
+</pre>
+<p>Tool <code>pnacl-compress</code> must be called after a pexe file has been finalized
+for deployment (via <code>pnacl-finalize</code>). Alternatively, you can apply this
+step as part of the finalizing step by adding the <code>--compress</code> flag
+to the pnacl-finalize command line.</p>
+<p>Note that this compression step doesn&#8217;t replace gzip. This compression
+step is in addition to gzipping a file for deployment. One should note
+that while the gzipped version of a compressed pexe file is still
+smaller than the corresponding uncompressed pexe file, the gains is
+somewhat smaller after being gzipped. Expected reduction in size
+(after being gzipped) is more like 7.5% to 10%.</p>
 </section></section><section id="the-gnu-based-toolchains">
 <h2 id="the-gnu-based-toolchains">The GNU-based toolchains</h2>
 <p>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 <strong>nexe</strong> files. Run the tool with the <code>--version</code>
 command line flag to determine the current version of the tools.</p>
 <p>Each tool in the toolchain is prefixed with the name of the target
 architecture. In the toolchain for the ARM target architecture, each
 tool&#8217;s name is preceded by the prefix &#8220;arm-nacl-&#8221;. In the toolchains for
@@ skipping 262 matching lines @@
 Function foo has disallowed type: i128 (i128)
 LLVM ERROR: PNaCl ABI verification failed
 </pre>
 <p>When faced with a PNaCl ABI verification error, check the list of features
 that are <a class="reference internal" href="/native-client/nacl-and-pnacl.html#when-to-use-nacl"><em>not supported by PNaCl</em></a>.
 If the problem you face is not listed as restricted,
 <a class="reference internal" href="/native-client/help.html#help"><em>let us know</em></a>!</p>
 </section></section></section>
 
 {{/partials.standard_nacl_article}}