Initial draft of PNaCl bitcode files.

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="id17">The GNU-based toolchains</a></p>
+<li><a class="reference internal" href="#object-dumping-of-pnacl-bitcode-files" id="id17">Object dumping of PNaCl bitcode files</a></li>
+<li><p class="first"><a class="reference internal" href="#the-gnu-based-toolchains" id="id18">The GNU-based toolchains</a></p>
 <ul class="small-gap">
-<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>
+<li><a class="reference internal" href="#compiling" id="id19">Compiling</a></li>
+<li><a class="reference internal" href="#creating-libraries-and-linking" id="id20">Creating libraries and Linking</a></li>
+<li><a class="reference internal" href="#finalizing-a-nexe-for-deployment" id="id21">Finalizing a <strong>nexe</strong> for deployment</a></li>
 </ul>
 </li>
-<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>
+<li><a class="reference internal" href="#using-make" id="id22">Using make</a></li>
+<li><a class="reference internal" href="#libraries-and-header-files-provided-with-the-sdk" id="id23">Libraries and header files provided with the SDK</a></li>
+<li><p class="first"><a class="reference internal" href="#troubleshooting" id="id24">Troubleshooting</a></p>
 <ul class="small-gap">
-<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>
+<li><a class="reference internal" href="#undefined-reference-error" id="id25">&#8220;Undefined reference&#8221; error</a></li>
+<li><a class="reference internal" href="#can-t-find-libraries-containing-necessary-symbols" id="id26">Can&#8217;t find libraries containing necessary symbols</a></li>
+<li><a class="reference internal" href="#pnacl-abi-verification-errors" id="id27">PNaCl ABI Verification errors</a></li>
 </ul>
 </li>
 </ul>
 
 </div><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>
 <h3 id="target-architectures"><span id="id1"></span>Target architectures</h3>
@@ skipping 73 matching lines @@
 <h2 id="the-pnacl-toolchain">The PNaCl toolchain</h2>
 <p>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 <code>--version</code> command line flag. These tools
 are used to compile and link applications into <strong>.pexe</strong> files. The toolchain
 also contains a tool to translate a <strong>pexe</strong> file into a
 architecture-specific <strong>.nexe</strong> (e.g., for debugging purposes).</p>
 <p>Some of the useful tools include:</p>
 <dl class="docutils">
-<dt>pnacl-abicheck</dt>
+<dt><code>pnacl-abicheck</code></dt>
 <dd>Checks that the <strong>pexe</strong> follows the PNaCl ABI rules.</dd>
-<dt>pnacl-ar</dt>
+<dt><code>pnacl-ar</code></dt>
 <dd>Creates archives (i.e., static libraries)</dd>
-<dt>pnacl-clang</dt>
+<dt><code>pnacl-bcdis</code></dt>
+<dd>Object dumper for PNaCl bitcode files.</dd>
+<dt><code>pnacl-clang</code></dt>
 <dd>C compiler and compiler driver</dd>
-<dt>pnacl-clang++</dt>
+<dt><code>pnacl-clang++</code></dt>
 <dd>C++ compiler and compiler driver</dd>
-<dt>pnacl-compress</dt>
+<dt><code>pnacl-compress</code></dt>
 <dd>Compresses a finalized <strong>pexe</strong> file for deployment.</dd>
-<dt>pnacl-dis</dt>
+<dt><code>pnacl-dis</code></dt>
 <dd>Disassembler for both <strong>pexe</strong> files and <strong>nexe</strong> files</dd>
-<dt>pnacl-finalize</dt>
+<dt><code>pnacl-finalize</code></dt>
 <dd>Finalizes <strong>pexe</strong> files for deployment</dd>
-<dt>pnacl-ld</dt>
+<dt><code>pnacl-ld</code></dt>
 <dd>Bitcode linker</dd>
-<dt>pnacl-nm</dt>
+<dt><code>pnacl-nm</code></dt>
 <dd>Lists symbols in bitcode files, native code, and libraries</dd>
-<dt>pnacl-ranlib</dt>
+<dt><code>pnacl-ranlib</code></dt>
 <dd>Generates a symbol table for archives (i.e., static libraries)</dd>
-<dt>pnacl-translate</dt>
+<dt><code>pnacl-translate</code></dt>
 <dd>Translates a <strong>pexe</strong> to a native architecture, outside of the browser</dd>
 </dl>
 <p>For the full list of tools, see the
 <code>pepper_&lt;version&gt;/toolchain/&lt;platform&gt;_pnacl/bin</code> directory.</p>
 <h2 id="using-the-pnacl-tools-to-compile-link-debug-and-deploy">Using the PNaCl tools to compile, link, debug, and deploy</h2>
 <p>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
 over some examples of how to use the tools.</p>
 <h3 id="compile">Compile</h3>
 <p>To compile a simple application consisting of <code>file1.cc</code> and <code>file2.cc</code> into
@@ skipping 133 matching lines @@
 </pre>
 <p><code>pnacl-compress</code> must be called after a <strong>pexe</strong> 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
 <code>pnacl-finalize</code> command line.</p>
 <p>This compression step doesn&#8217;t replace the gzip compression performed web servers
 configured for HTTP compression: both compressions are complementary. You&#8217;ll
 want to configure your web server to gzip <strong>pexe</strong> files: the gzipped version of
 a compressed <strong>pexe</strong> file is smaller than the corresponding uncompressed
 <strong>pexe</strong> file by 7.5% to 10%.</p>
+<h2 id="object-dumping-of-pnacl-bitcode-files"><span id="pnacl-bcdis"></span>Object dumping of PNaCl bitcode files</h2>
+<p>Sometimes you may be interesting in the contents of a PNaCl bitcode file.  The
+tool <code>pnacl-bcdis</code> object dumps the contents of a PNaCl bitcode file.  For a
+description of the output produced by this tool, see
+<a class="reference internal" href="/native-client/reference/pnacl-bitcode-manual.html"><em>Contents Of PNaCl Bitcode Files</em></a>.</p>
+<pre>
+ nacl_sdk/pepper_&lt;version&gt;/toolchain/win_pnacl/bin/pnacl-bcdis \
+   hello_world.final.pexe
+</pre>
+<p>The output is the corresponding contents of the given <strong>pexe</strong>.</p>
 <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
 the x86 target architecture, there are actually two versions of each
@@ skipping 255 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>
 
 {{/partials.standard_nacl_article}}