Rearrange tables so that navigation can be added back to certain pages.

native_client_sdk/doc_generated/devguide/devcycle/dynamic-loading.html

 {{+bindTo:partials.standard_nacl_article}}
 
 <section id="dynamic-linking-and-loading-with-glibc">
 <h1 id="dynamic-linking-and-loading-with-glibc">Dynamic Linking and Loading with glibc</h1>
 <div class="contents local" id="contents" style="display: none">
 <ul class="small-gap">
-<li><p class="first"><a class="reference internal" href="#introduction" id="id1">Introduction</a></p>
+<li><a class="reference internal" href="#c-standard-libraries-glibc-and-newlib" id="id1">C standard libraries: glibc and newlib</a></li>
+<li><a class="reference internal" href="#sdk-toolchains" id="id2">SDK toolchains</a></li>
+<li><p class="first"><a class="reference internal" href="#specifying-and-delivering-shared-libraries" id="id3">Specifying and delivering shared libraries</a></p>
 <ul class="small-gap">
-<li><a class="reference internal" href="#c-standard-libraries-glibc-and-newlib" id="id2">C standard libraries: glibc and newlib</a></li>
-<li><a class="reference internal" href="#sdk-toolchains" id="id3">SDK toolchains</a></li>
-<li><a class="reference internal" href="#specifying-and-delivering-shared-libraries" id="id4">Specifying and delivering shared libraries</a></li>
+<li><a class="reference internal" href="#building-a-dynamically-linked-application" id="id4">Building a dynamically linked application</a></li>
+<li><a class="reference internal" href="#generating-a-native-client-manifest-file-for-a-dynamically-linked-application" id="id5">Generating a Native Client manifest file for a dynamically linked application</a></li>
+<li><a class="reference internal" href="#deploying-a-dynamically-linked-application" id="id6">Deploying a dynamically linked application</a></li>
+<li><a class="reference internal" href="#opening-a-shared-library-at-runtime" id="id7">Opening a shared library at runtime</a></li>
+<li><a class="reference internal" href="#troubleshooting" id="id8">Troubleshooting</a></li>
 </ul>
 </li>
-<li><a class="reference internal" href="#building-a-dynamically-linked-application" id="id5">Building a dynamically linked application</a></li>
-<li><a class="reference internal" href="#generating-a-native-client-manifest-file-for-a-dynamically-linked-application" id="id6">Generating a Native Client manifest file for a dynamically linked application</a></li>
-<li><a class="reference internal" href="#deploying-a-dynamically-linked-application" id="id7">Deploying a dynamically linked application</a></li>
-<li><a class="reference internal" href="#opening-a-shared-library-at-runtime" id="id8">Opening a shared library at runtime</a></li>
-<li><a class="reference internal" href="#troubleshooting" id="id9">Troubleshooting</a></li>
 </ul>
 
-</div><h2 id="introduction">Introduction</h2>
-<aside class="caution">
+</div><aside class="caution">
 Portable Native Client currently only supports static linking, and the
 only C library available for it is newlib. This page is only valid for
 Native Client, though PNaCl will eventually support some form of
 dynamic linking.
 </aside>
 <p>This document describes how to create and deploy dynamically linked and loaded
 applications with the glibc library in the Native Client SDK. Before reading
 this document, we recommend reading <a class="reference internal" href="/native-client/devguide/devcycle/building.html"><em>Building Native Client Modules</em></a></p>
-<h3 id="c-standard-libraries-glibc-and-newlib"><span id="c-libraries"></span>C standard libraries: glibc and newlib</h3>
+<h2 id="c-standard-libraries-glibc-and-newlib"><span id="c-libraries"></span>C standard libraries: glibc and newlib</h2>
 <p>The Native Client SDK comes with two C standard libraries &#8212; glibc and
 newlib. These libraries are described in the table below.</p>
 <table border="1" class="docutils">
 <colgroup>
 </colgroup>
 <thead valign="bottom">
 <tr class="row-odd"><th class="head">Library</th>
 <th class="head">Linking</th>
 <th class="head">License</th>
-<th class="head">Description</th>
 </tr>
 </thead>
 <tbody valign="top">
-<tr class="row-even"><td>glibc</td>
+<tr class="row-even"><td><dl class="first last docutils">
+<dt>glibc</dt>
+<dd>The GNU implementation of the <a class="reference external" href="http://en.wikipedia.org/wiki/POSIX">POSIX</a> standard

[mkearney1, 2014/09/12 23:40:34]

Small nit-- add period at the end of library description.

+runtime library for the C programming language.
+Designed for portability and performance, glibc is
+one of the most popular implementations of the C
+library. It is comprised of a set of interdependent
+libraries including libc, libpthreads, libdl, and
+others. For documentation, FAQs, and additional
+information about glibc, see <a class="reference external" href="http://www.gnu.org/software/libc/index.html">GLIBC</a></dd>
+</dl>
+</td>
 <td>dynamic
 or static</td>
 <td>GNU Lesser
 General
 Public
 License
 (LGPL)</td>
-<td>glibc is the GNU implementation of the
-<a class="reference external" href="http://en.wikipedia.org/wiki/POSIX">POSIX</a> standard runtime library for the C
-programming language. Designed for
-portability and performance, glibc is one
-of the most popular implementations of the
-C library. It is comprised of a set of
-interdependent libraries including libc,
-libpthreads, libdl, and others. For
-documentation, FAQs, and additional
-information about glibc, see <a class="reference external" href="http://www.gnu.org/software/libc/index.html">GLIBC</a></td>
 </tr>
-<tr class="row-odd"><td>newlib</td>
+<tr class="row-odd"><td><dl class="first last docutils">
+<dt>newlib</dt>
+<dd>newlib is a C library intended for use in embedded
+systems. Like glibc, newlib is a conglomeration of
+several libraries. It is available for use under
+BSD-type free software licenses, which generally
+makes it more suitable to link statically in
+commercial, closed-source applications. For
+documentation, FAQs, and additional information
+about newlib, see <a class="reference external" href="http://sourceware.org/newlib/">newlib</a></dd>

[mkearney1, 2014/09/12 23:40:34]

Small nit-- add period at the end of library description.

+</dl>
+</td>
 <td>static</td>
 <td>Berkeley
 Software
 Distribution
 (BSD) type
 free
 software
 licenses</td>
-<td>newlib is a C library intended for use in
-embedded systems. Like glibc, newlib is a
-conglomeration of several library parts.
-It is available for use under BSD-type free
-software licenses, which generally makes it
-more suitable to link statically in
-commercial, closed-source applications. For
-documentation, FAQs, and additional
-information about newlib, see the <a class="reference external" href="http://sourceware.org/newlib/">newlib</a>
-documentation.</td>
 </tr>
 </tbody>
 </table>
 <p>For proprietary (closed-source) applications, your options are to either
 statically link to newlib, or dynamically link to glibc. We recommend
 dynamically linking to glibc, for a couple of reasons:</p>
 <ul class="small-gap">
 <li>The glibc library is widely distributed (it&#8217;s included in Linux
 distributions), and as such it&#8217;s mature, hardened, and feature-rich. Your
 code is more likely to compile out-of-the-box with glibc.</li>
@@ skipping 27 matching lines @@
 <p><strong>Notes:</strong></p>
 <ul class="small-gap">
 <li>Static linking with glibc is rarely used. Use this feature with caution.</li>
 <li>The standard C++ runtime in Native Client is provided by libstdc++; this
 library is independent from and layered on top of glibc. Because of
 licensing restrictions, libstdc++ must be statically linked for commercial
 uses, even if the rest of an application is dynamically linked.</li>
 </ul>
 
 </aside>
-<h3 id="sdk-toolchains">SDK toolchains</h3>
+<h2 id="sdk-toolchains">SDK toolchains</h2>
 <p>The Native Client SDK contains multiple toolchains, which are differentiated by
 <a class="reference internal" href="/native-client/devguide/devcycle/building.html#target-architectures"><em>target architecture</em></a> and C library:</p>
 <table border="1" class="docutils">
 <colgroup>
 </colgroup>
 <thead valign="bottom">
 <tr class="row-odd"><th class="head">Target architecture</th>
 <th class="head">C library</th>
 <th class="head">Toolchain directory</th>
 </tr>
@@ skipping 20 matching lines @@
 <p>In the directories listed above, &lt;platform&gt; is the platform of your development
 machine (i.e., win, mac, or linux). For example, in the Windows SDK, the x86
 toolchain that uses glibc is in <code>toolchain/win_x86_glibc</code>.</p>
 <aside class="note">
 <strong>Note:</strong> The ARM and PNaCl toolchains are currently restricted to newlib.
 </aside>
 <p>To use the glibc library and dynamic linking in your application, you <strong>must</strong>
 use a glibc toolchain. (Currently the only glibc toolchain is
 <code>&lt;platform&gt;_x86_glibc</code>.) Note that you must build all code in your application
 with one toolchain. Code from multiple toolchains cannot be mixed.</p>
-<h3 id="specifying-and-delivering-shared-libraries">Specifying and delivering shared libraries</h3>
+<h2 id="specifying-and-delivering-shared-libraries">Specifying and delivering shared libraries</h2>
 <p>One significant difference between newlib and glibc applications is that glibc
 applications must explicitly list and deploy the shared libraries that they
 use.</p>
 <p>In a desktop environment, when the user launches a dynamically linked
 application, the operating system&#8217;s program loader determines the set of
 libraries the application requires by reading explicit inter-module
 dependencies from executable file headers, and loads the required libraries
 into the address space of the application process. Typically the required
 libraries will have been installed on the system as a part of the application&#8217;s
 installation process. Often the desktop application developer doesn&#8217;t know or
 think about the libraries that are required by an application, as those details
 are taken care of by the user&#8217;s operating system.</p>
 <p>In the Native Client sandbox, dynamic linking can&#8217;t rely in the same way on the
 operating system or the local file system. Instead, the application developer
 must identify the set of libraries that are required by an application, list
 those libraries in a Native Client <a class="reference internal" href="/native-client/devguide/coding/application-structure.html#manifest-file"><em>manifest file</em></a>, and
 deploy the libraries along with the application. Instructions for how to build
 a dynamically linked Native Client application, generate a Native Client
 manifest (.nmf) file, and deploy an application are provided below.</p>
-<h2 id="building-a-dynamically-linked-application">Building a dynamically linked application</h2>
+<h3 id="building-a-dynamically-linked-application">Building a dynamically linked application</h3>
 <p>Applications built with the glibc toolchain will by dynamically linked by
 default. Application that load shared libraries at runtime using <code>dlopen()</code>
 must link with the libdl library (<code>-ldl</code>).</p>
 <p>Like other gcc-based toolchains building a dynamic library for NaCl is normally
 done by linking with the <code>-shared</code> flag and compiling with the <code>-fPIC</code> flag.
 The SDK build system will do this automatically when the <code>SO_RULE</code> Makefile
 rule is used.</p>
 <p>The Native Client SDK includes an example that demonstrates how to build a
 shared library, and how to use the <code>dlopen()</code> interface to load that library
 at runtime (after the application is already running). Many applications load
@@ skipping 26 matching lines @@
 <aside class="note">
 <strong>Note:</strong> The Makefiles for most of the examples in the SDK build the
 examples using multiple toolchains (x86 newlib, x86 glibc, ARM, and PNaCl).
 With a few exceptions (listed in the <a class="reference internal" href="/native-client/sdk/release-notes.html#sdk-release-notes"><em>Release Notes</em></a>), running &#8220;make&#8221; in each example&#8217;s directory builds
 multiple versions of the example using the SDK toolchains. The dlopen example
 is one of those exceptions – it is only built with the x86 glibc toolchain,
 as that is currently the only toolchain that supports glibc and thus dynamic
 linking and loading. Take a look at the example Makefiles and the generated
 .nmf files for details on how to build dynamically linked applications.
 </aside>
-<h2 id="generating-a-native-client-manifest-file-for-a-dynamically-linked-application"><span id="dynamic-loading-manifest"></span>Generating a Native Client manifest file for a dynamically linked application</h2>
+<h3 id="generating-a-native-client-manifest-file-for-a-dynamically-linked-application"><span id="dynamic-loading-manifest"></span>Generating a Native Client manifest file for a dynamically linked application</h3>
 <p>The Native Client manifest file specifies the name of the executable to run
 and must also specify any shared libraries that the application directly
 depends on. For indirect dependencies (such as libraries opened via
 <code>dlopen()</code>) it is also convenient to list libraries in the manifest file.
 However it is possile to load arbitrary shared libraries at runtime that
 are not mentioned in the manifest by using the <a class="reference external" href="nacl_io">nacl_io library</a>
 to mount a filesystem that contains the shared libraries which will then
 allow <code>dlopen()</code> to access them.</p>
 <p>In this example we demonstrate both loading directly from via the manifest
 file (<code>libeightball.so</code>) and loading indirectly via a http mount
@@ skipping 56 matching lines @@
 </dl>
 <aside class="note">
 <strong>Note:</strong> The <code>create_nmf</code> script can only automatically detect explicit
 shared library dependencies (for example, dependencies specified with the -l
 flag for the compiler/linker). If you want to include libraries that you
 intend to dlopen() at runtime you must explcitly list them in your call to
 <code>create_nmf</code>.
 </aside>
 <p>As an alternative to using <code>create_nmf</code>, it is possible to manually calculate
 the list of shared library dependencies using tools such as <code>objdump_</code>.</p>
-<h2 id="deploying-a-dynamically-linked-application">Deploying a dynamically linked application</h2>
+<h3 id="deploying-a-dynamically-linked-application">Deploying a dynamically linked application</h3>
 <p>As described above, an application&#8217;s manifest file must explicitly list all the
 executable code modules that the application directly depends on, including
 modules from the application itself (.nexe and .so files), modules from the
 Native Client SDK (e.g., libppapi_cpp.so), and perhaps also modules from
 <a class="reference external" href="http://code.google.com/p/naclports/">naclports</a> or from
 <a class="reference external" href="../../community/middleware">middleware systems</a> that
 the application uses. You must provide all of those modules as part of the
 application deployment process.</p>
 <p>As explained in <a class="reference internal" href="/native-client/devguide/distributing.html"><em>Distributing Your Application</em></a>, there are two basic ways to deploy an application:</p>
 <ul class="small-gap">
@@ skipping 10 matching lines @@
 in the Native Client manifest file, and be named relative to the location of
 the manifest file. Remember that some of the libraries named in the manifest
 file may be located in directories you specified with the -L option to
 <code>create_nmf.py</code>. You are free to rename/rearrange files and directories
 referenced by the Native Client manifest file, so long as the modules are
 available in the locations indicated by the manifest file. If you move or
 rename modules, it may be easier to re-run <code>create_nmf.py</code> to generate a new
 manifest file rather than edit the original manifest file. For hosted
 applications, you can check for name mismatches during testing by watching the
 request log of the web server hosting your test deployment.</p>
-<h2 id="opening-a-shared-library-at-runtime">Opening a shared library at runtime</h2>
+<h3 id="opening-a-shared-library-at-runtime">Opening a shared library at runtime</h3>
 <p>Native Client supports a version of the POSIX standard <code>dlopen()</code> interface
 for opening libraries explicitly, after an application is already running.
 Calling <code>dlopen()</code> may cause a library download to occur, and automatically
 loads all libraries that are required by the named library.</p>
 <aside class="note">
 <strong>Caution:</strong> Since <code>dlopen()</code> can potentially block, you must initially
 call <code>dlopen()</code> off your application&#8217;s main thread. Initial calls to
 <code>dlopen()</code> from the main thread will always fail in the current
 implementation of Native Client.
 </aside>
@@ skipping 16 matching lines @@
 and makes calls to <code>Magic8Ball()</code> and <code>Reverse()</code> in response to requests
 from JavaScript.</li>
 </ul>
 <p>When the Native Client module starts, it kicks off a worker thread that calls
 <code>dlopen()</code> to load the two shared libraries. Once the module has a handle to
 the library, it fetches the addresses of the <code>Magic8Ball()</code> and <code>Reverse()</code>
 functions using <code>dlsym()</code>. When a user types in a query and clicks the &#8216;ASK!&#8217;
 button, the module calls <code>Magic8Ball()</code> to generate an answer, and returns
 the result to the user. Likewise when the user clicks the &#8216;Reverse&#8217; button
 it calls the <code>Reverse()</code> function to reverse the string.</p>
-<h2 id="troubleshooting">Troubleshooting</h2>
+<h3 id="troubleshooting">Troubleshooting</h3>
 <p>If your .nexe isn&#8217;t loading, the best place to look for information that can
 help you troubleshoot the JavaScript console and standard output from Chrome.
 See <a class="reference internal" href="/native-client/devguide/devcycle/debugging.html#devcycle-debugging"><em>Debugging</em></a> for more information.</p>
 <p>Here are a few common error messages and explanations of what they mean:</p>
 <dl class="docutils">
 <dt><strong>/main.nexe: error while loading shared libraries: /main.nexe: failed to allocate code and data space for executable</strong></dt>
 <dd>The .nexe may not have been compiled correctly (e.g., the .nexe may be
 statically linked). Try cleaning and recompiling with the glibc toolchain.</dd>
 <dt><strong>/main.nexe: error while loading shared libraries: libpthread.so.xxxx: cannot open shared object file: Permission denied</strong></dt>
 <dd>(xxxx is a version number, for example, 5055067a.) This error can result from
@@ skipping 18 matching lines @@
 in the .nmf file &#8211; either the files are the wrong type or kind, or an
 expected library is missing.</dd>
 <dt><strong>undefined reference to &#8216;dlopen&#8217; collect2: ld returned 1 exit status</strong></dt>
 <dd>This is a linker ordering problem that usually results from improper ordering
 of command line flags when linking. Reconfigure your command line string to
 list libraries after the -o flag.</dd>
 </dl>
 </section>
 
 {{/partials.standard_nacl_article}}