{{+bindTo:partials.standard_nacl_article}}
-<section id="running-the-sdk-examples">
-<span id="sdk-examples-2"></span><h1 id="running-the-sdk-examples"><span id="sdk-examples-2"></span>Running the SDK Examples</h1>
+<span class="target" id="sdk-examples-2"></span><section id="examples">
+<h1 id="examples">Examples</h1>
<p>Every Native Client SDK bundle comes with a folder of example applications.
Each example demonstrates one or two key Native Client programming concepts.
After you’ve <a class="reference internal" href="/native-client/sdk/download.html"><em>downloaded the SDK</em></a>, follow the instructions
on this page to build and run the examples.</p>
-<h2 id="configure-the-google-chrome-browser">Configure the Google Chrome Browser</h2>
+<p>Your version of Chrome must be equal to or greater than the version of your SDK
+bundle. For example, if you’re developing with the <code>pepper_35</code> bundle, you
+must use Google Chrome version 35 or greater. To find out what version of Chrome
+you’re using, type <code>about:chrome</code> or <code>about:version</code> in the Chrome address
+bar.</p>
+<h2 id="enable-native-client"><span id="id1"></span>Enable Native Client</h2>
+<p>If you are using Chrome 31 or later, you can skip this section. To run Portable
+Native Client applications you must specifically enable Native Client in Chrome:</p>
<ol class="arabic">
-<li><p class="first">Your version of Chrome must be equal to or greater than the version of
-your SDK bundle. For example, if you’re developing with the <code>pepper_31</code>
-bundle, you must use Google Chrome version 31 or greater. To find out what
-version of Chrome you’re using, type <code>about:chrome</code> or <code>about:version</code>
-in the Chrome address bar.</p>
-</li>
-<li><p class="first">For Portable Native Client, no extra Chrome flags are needed as of
-Chrome version 31.</p>
-<p>For other Native Client applications, or to <strong>debug</strong> Portable Native
-Client applications by translating the <strong>pexe</strong> to a <strong>nexe</strong> ahead of
-time, enable the Native Client flag. Native Client is enabled by default
-only for applications distributed through the Chrome Web Store. To run
-Native Client applications that are not distributed through the Chrome
-Web Store, like the SDK examples, you must specifically enable the Native
-Client flag in Chrome:</p>
+<li><p class="first">Type <code>about:flags</code> in the Chrome address bar and scroll down to “Native
+Client”.</p>
<ul class="small-gap">
-<li><p class="first">Type <code>about:flags</code> in the Chrome address bar and scroll down to
-“Native Client”.</p>
-</li>
<li><p class="first">If the link below “Native Client” says “Disable”, then Native Client is
already enabled and you don’t need to do anything else.</p>
</li>
-<li><p class="first">If the link below “Native Client” says “Enable”, click the “Enable”
-link, scroll down to the bottom of the page, and click the “Relaunch
-Now” button. All browser windows will restart when you relaunch Chrome.</p>
-</li>
</ul>
-</li>
-<li><p class="first">Disable the Chrome cache. Chrome caches resources aggressively; when you
-are building a Native Client application you should disable the cache to
-make sure that Chrome loads the latest version:</p>
<ul class="small-gap">
-<li><p class="first">Open Chrome’s developer tools by clicking the menu icon <img alt="menu-icon" src="/native-client/images/menu-icon.png" /> and
-choosing Tools > Developer tools.</p>
-</li>
-<li><p class="first">Click the gear icon <img alt="gear-icon" src="/native-client/images/gear-icon.png" /> in the bottom right corner of the
-Chrome window.</p>
-</li>
-<li><p class="first">Under the “General” settings, check the box next to “Disable cache”.</p>
+<li><p class="first">If the link below “Native Client” says “Enable”, click the “Enable”
+link.</p>
</li>
</ul>
</li>
+<li><p class="first">Scroll down to the bottom of the page, and click “Relaunch Now”. All browser
+windows will restart when you relaunch Chrome.</p>
+</li>
</ol>
-<h2 id="build-the-sdk-examples">Build the SDK examples</h2>
-<p>Starting with the <code>pepper_24</code> bundle, the Makefile scripts for the SDK
-examples build multiple versions of the examples using all three SDK
-toolchains (newlib, glibc, and PNaCl) and in both release and debug
-configurations. (Note that some examples build only with the particular
-toolchains).</p>
-<p>To build all the examples, go to the examples directory in a specific SDK
-bundle and run <code>make</code>:</p>
+<h2 id="build-the-sdk-examples"><span id="id2"></span>Build the SDK examples</h2>
+<p>The Makefile scripts for the SDK examples can build multiple versions of the
+examples using any of the three SDK toolchains (newlib, glibc, and PNaCl) and in
+both release and debug configurations. Note that some examples, <code>dlopen</code> for
+example, build only with particular toolchains.</p>
+<p>Find the toolchains for each example by looking at the <code>VALID_TOOLCHAINS</code>
+variable in the Makefile for a particular example. The first item listed is the
+default. It’s built when you run an example make file without parameters. for
+example running make in the <code>core</code> directory of pepper_35 builds the example
+using the <code>newlib</code> toolchain.</p>
<pre class="prettyprint">
-$ cd pepper_31/examples
+$ cd pepper_35/examples/api/core
$ make
-make -C api all
-make[1]: Entering directory `pepper_31/examples/api'
-make -C audio all
-make[2]: Entering directory `pepper_31/examples/api/audio'
- CXX newlib/Debug/audio_x86_32.o
- LINK newlib/Debug/audio_x86_32.nexe
- CXX newlib/Debug/audio_x86_64.o
- LINK newlib/Debug/audio_x86_64.nexe
- CXX newlib/Debug/audio_arm.o
- LINK newlib/Debug/audio_arm.nexe
- CREATE_NMF newlib/Debug/audio.nmf
-make[2]: Leaving directory `pepper_31/examples/api/audio'
-make -C url_loader all
-make[2]: Entering directory `pepper_31/examples/api/url_loader'
- CXX newlib/Debug/url_loader_x86_32.o
-...
+ CXX newlib/Release/core_x86_32.o
+ LINK newlib/Release/core_unstripped_x86_32.nexe
+ VALIDATE newlib/Release/core_unstripped_x86_32.nexe
+ CXX newlib/Release/core_x86_64.o
+ LINK newlib/Release/core_unstripped_x86_64.nexe
+ VALIDATE newlib/Release/core_unstripped_x86_64.nexe
+ CXX newlib/Release/core_arm.o
+ LINK newlib/Release/core_unstripped_arm.nexe
+ VALIDATE newlib/Release/core_unstripped_arm.nexe
+ STRIP newlib/Release/core_x86_32.nexe
+ STRIP newlib/Release/core_x86_64.nexe
+ STRIP newlib/Release/core_arm.nexe
+ CREATE_NMF newlib/Release/core.nmf
</pre>
-<p>Calling <code>make</code> from inside a particular example’s directory will build only
-that example:</p>
+<p>As you can see, this produces a number of architecture specific nexe files in
+the <code>pepper_35/examples/api/core/Release</code> directory. Create debug versions by
+using the <code>CONFIG</code> parameter of the make command.</p>
<pre class="prettyprint">
-$ cd pepper_31/examples/api/core
-$ make
- CXX newlib/Debug/core_x86_32.o
- LINK newlib/Debug/core_x86_32.nexe
- CXX newlib/Debug/core_x86_64.o
- LINK newlib/Debug/core_x86_64.nexe
- CXX newlib/Debug/core_arm.o
- LINK newlib/Debug/core_arm.nexe
- CREATE_NMF newlib/Debug/core.nmf
+$make CONFIG=Debug
</pre>
-<p>You can call <code>make</code> with the <code>TOOLCHAIN</code> and <code>CONFIG</code> parameters to
-override the defaults:</p>
+<p>This creates similar output, but in <code>pepper_35/examples/api/core/Debug</code>.</p>
+<p>Select a different toolchain with the <code>TOOLCHAIN</code> parameter. For example:</p>
<pre class="prettyprint">
+$ cd pepper_35/examples/api/core
$ make TOOLCHAIN=pnacl CONFIG=Release
- CXX pnacl/Release/core_pnacl.o
- LINK pnacl/Release/core.bc
- FINALIZE pnacl/Release/core.pexe
+ CXX pnacl/Release/core.o
+ LINK pnacl/Release/core_unstripped.bc
+ FINALIZE pnacl/Release/core_unstripped.pexe
CREATE_NMF pnacl/Release/core.nmf
</pre>
-<p>You can also set <code>TOOLCHAIN</code> to “all” to build one or more examples with
-all available toolchains:</p>
+<p>You can also set <code>TOOLCHAIN</code> to <code>all</code> to build all Release versions with
+default toolchains.</p>
<pre class="prettyprint">
+$ cd pepper_35/examples/api/core
$ make TOOLCHAIN=all
make TOOLCHAIN=newlib
-make[1]: Entering directory `pepper_31/examples/api/core'
- CXX newlib/Debug/core_x86_32.o
- LINK newlib/Debug/core_x86_32.nexe
- CXX newlib/Debug/core_x86_64.o
- LINK newlib/Debug/core_x86_64.nexe
- CXX newlib/Debug/core_arm.o
- LINK newlib/Debug/core_arm.nexe
- CREATE_NMF newlib/Debug/core.nmf
-make[1]: Leaving directory `pepper_31/examples/api/core'
+make[1]: Entering directory 'pepper_35/examples/api/core'
+ CXX newlib/Release/core_x86_32.o
+ LINK newlib/Release/core_unstripped_x86_32.nexe
+ VALIDATE newlib/Release/core_unstripped_x86_32.nexe
+ CXX newlib/Release/core_x86_64.o
+ LINK newlib/Release/core_unstripped_x86_64.nexe
+ VALIDATE newlib/Release/core_unstripped_x86_64.nexe
+ CXX newlib/Release/core_arm.o
+ LINK newlib/Release/core_unstripped_arm.nexe
+ VALIDATE newlib/Release/core_unstripped_arm.nexe
+ STRIP newlib/Release/core_x86_32.nexe
+ STRIP newlib/Release/core_x86_64.nexe
+ STRIP newlib/Release/core_arm.nexe
+ CREATE_NMF newlib/Release/core.nmf
+make[1]: Leaving directory 'pepper_35/examples/api/core'
make TOOLCHAIN=glibc
-make[1]: Entering directory `pepper_31/examples/api/core'
- CXX glibc/Debug/core_x86_32.o
- LINK glibc/Debug/core_x86_32.nexe
- CXX glibc/Debug/core_x86_64.o
- LINK glibc/Debug/core_x86_64.nexe
- CREATE_NMF glibc/Debug/core.nmf
-make[1]: Leaving directory `pepper_31/examples/api/core'
-make TOOLCHAIN=pnacl
-make[1]: Entering directory `pepper_31/examples/api/core'
- CXX pnacl/Debug/core.o
- LINK pnacl/Debug/core_unstripped.bc
- FINALIZE pnacl/Debug/core_unstripped.pexe
- CREATE_NMF pnacl/Debug/core.nmf
-make[1]: Leaving directory `pepper_31/examples/api/core'
-make TOOLCHAIN=linux
-make[1]: Entering directory `pepper_31/examples/api/core'
- CXX linux/Debug/core.o
- LINK linux/Debug/core.so
-make[1]: Leaving directory `pepper_31/examples/api/core'
+make[1]: Entering directory 'pepper_35/examples/api/core'
+ CXX glibc/Release/core_x86_32.o
+ LINK glibc/Release/core_unstripped_x86_32.nexe
+ VALIDATE glibc/Release/core_unstripped_x86_32.nexe
+ CXX glibc/Release/core_x86_64.o
+ LINK glibc/Release/core_unstripped_x86_64.nexe
+ VALIDATE glibc/Release/core_unstripped_x86_64.nexe
+ ...
+ (content excerpted)
+ ...
</pre>
-<p>After running <code>make</code>, each example directory will contain one or more of
-the following subdirectories:</p>
+<h3 id="build-results"><span id="id3"></span>Build results</h3>
+<p>After running <code>make</code>, example directories will contain one or more of the
+following subdirectories, depending on which Makefile you run:</p>
<ul class="small-gap">
-<li>a <code>newlib</code> directory with subdirectories <code>Debug</code> and <code>Release</code>;</li>
-<li>a <code>glibc</code> directory with subdirectories <code>Debug</code> and <code>Release</code>;</li>
-<li>a <code>pnacl</code> directory with subdirectories <code>Debug</code> and <code>Release</code>;</li>
+<li><code>newlib</code> with subdirectories <code>Debug</code> and <code>Release</code>;</li>
+<li><code>glibc</code> with subdirectories <code>Debug</code> and <code>Release</code>;</li>
+<li><code>pnacl</code> with subdirectories <code>Debug</code> and <code>Release</code>;</li>
</ul>
<p>For the newlib and glibc toolchains the Debug and Release subdirectories
contain .nexe files for all target architectures. For the PNaCl toolchain
Overview</em></a>.</p>
<p>For details on how to use <code>make</code>, see the <a class="reference external" href="http://www.gnu.org/software/make/manual/make.html">GNU ‘make’ Manual</a>. For details on how to
use the SDK toolchain itself, see <a class="reference internal" href="/native-client/devguide/devcycle/building.html"><em>Building Native Client Modules</em></a>.</p>
-<h2 id="run-the-sdk-examples"><span id="id1"></span>Run the SDK examples</h2>
-<p>To run the SDK examples, you can use the <code>make run</code> command:</p>
+<h2 id="run-the-sdk-examples"><span id="running-the-sdk-examples"></span>Run the SDK examples</h2>
+<h3 id="disable-the-chrome-cache"><span id="disable-chrome-cache"></span>Disable the Chrome cache</h3>
+<p>Chrome’s intelligent caching caches resources aggressively. When building a
+Native Client application you should disable the cache to make sure that Chrome
+loads the latest version. Intelligent caching only remains inactive while
+Developer Tools are open. Otherwise, agressive caching continues.</p>
+<ol class="arabic simple">
+<li>Open Chrome’s developer tools by clicking the menu icon <img alt="menu-icon" src="/native-client/images/menu-icon.png" /> and
+choosing Tools > Developer tools.</li>
+<li>Click the gear icon <img alt="gear-icon" src="/native-client/images/gear-icon.png" /> in the bottom right corner of the Chrome
+window.</li>
+<li>Under the “General” settings, check the box next to “Disable cache”.</li>
+</ol>
+<h3 id="run-the-examples"><span id="id4"></span>Run the examples</h3>
+<p>To run the SDK examples, use the <code>make run</code> command:</p>
<pre class="prettyprint">
-$ cd pepper_31/examples/api/core
+$ cd pepper_35/examples/api/core
$ make run
</pre>
-<p>This will launch a local HTTP server which will serve the data for the
-example. It then launches Chrome with the address of this server, usually
-<code>http://localhost:5103</code>. After you close Chrome, the local HTTP server is
-automatically shutdown.</p>
-<p>This command will try to find an executable named <code>google-chrome</code> in your
+<p>This launches a local HTTP server that serves the example. It then launches
+Chrome with the address of this server, usually <code>http://localhost:5103</code>.
+After you close Chrome, the local HTTP server automatically shuts down.</p>
+<p>This command tries to find an executable named <code>google-chrome</code> in your
<code>PATH</code> environment variable. If it can’t, you’ll get an error message like
this:</p>
<pre class="prettyprint">
-pepper_31/tools/common.mk:415: No valid Chrome found at CHROME_PATH=
-pepper_31/tools/common.mk:415: *** Set CHROME_PATH via an environment variable, or command-line.. Stop.
+pepper_35/tools/common.mk:415: No valid Chrome found at CHROME_PATH=
+pepper_35/tools/common.mk:415: *** Set CHROME_PATH via an environment variable, or command-line.. Stop.
</pre>
+<h3 id="add-an-environment-variable-for-chrome"><span id="add-an-env-variable-for-chrome"></span>Add an environment variable for Chrome</h3>
<p>Set the CHROME_PATH environment variable to the location of your Chrome
executable.</p>
<ul class="small-gap">
<code>C:\Program Files (x86)\Google\Chrome\Application\chrome.exe</code> for Chrome
stable and
<code>C:\Users\<username>\AppData\Local\Google\Chrome SxS\Application\chrome.exe</code>
-for Chrome Canary; try looking in those directories first:</p>
+for Chrome Canary. Try looking in those directories first:</p>
<pre class="prettyprint">
> set CHROME_PATH=<Path to chrome.exe>
</pre>
</pre>
</li>
</ul>
-<p>You can run via a different toolchain or configuration by using the
-<code>TOOLCHAIN</code> and <code>CONFIG</code> parameters to make:</p>
-<pre class="prettyprint">
-$ make run TOOLCHAIN=pnacl CONFIG=Debug
-</pre>
<h2 id="run-the-sdk-examples-as-packaged-apps"><span id="run-sdk-examples-as-packaged"></span>Run the SDK examples as packaged apps</h2>
-<p>Each example can also be launched as a packaged app. For more information about
-using Native Client for packaged apps, see <a class="reference internal" href="/native-client/devguide/distributing.html#distributing-packaged"><em>Packaged application</em></a>. For general information about packaged apps, see the
-<a class="reference external" href="/apps/about_apps">Chrome apps documentation</a>.</p>
+<p>Each example can also be launched as a packaged application. A packaged
+application is a special zip file (with a .crx extension) hosted in the Chrome
+Web Store. This file contains all of the application parts: A Chrome Web Store
+manifest file (manifest.json), an icon, and all of the regular Native Client
+application files. Refer to <a class="reference external" href="/apps/about_apps">What are Chrome Apps</a> for more
+information about creating a packaged application.</p>
<p>Some Pepper features, such as TCP/UDP socket access, are only allowed in
-packaged apps. The examples that use these features must be run as packaged
-apps, by using the <code>make run_package</code> command:</p>
+packaged applications. The examples that use these features must be run as
+packaged applications, by using the following command:</p>
<pre class="prettyprint">
$ make run_package
</pre>
-<p>You can use <code>TOOLCHAIN</code> and <code>CONFIG</code> parameters as above to run with a
-different toolchain or configuration.</p>
-<h2 id="debugging-the-sdk-examples"><span id="id2"></span>Debugging the SDK examples</h2>
+<p>You can use <code>TOOLCHAIN</code> and <code>CONFIG</code> parameters as described above to run
+with a different toolchain or configuration.</p>
+<h2 id="debugging-the-sdk-examples"><span id="id5"></span>Debugging the SDK examples</h2>
<p>The NaCl SDK uses <a class="reference external" href="https://www.gnu.org/software/gdb/">GDB</a> to debug Native
Client code. The SDK includes a prebuilt version of GDB that is compatible with
NaCl code. To use it, run the <code>make debug</code> command from an example directory:</p>
<pre class="prettyprint">
$ make debug
</pre>
-<p>This will launch Chrome with the <code>--enable-nacl-debug</code> flag set. This flag
-will cause Chrome to pause when a NaCl module is first loaded, waiting for a
-connection from gdb. The <code>make debug</code> command also simultaneously launches
-GDB and loads the symbols for that NEXE. To connect GDB to Chrome, in the GDB
-console, type:</p>
+<p>This launches Chrome with the <code>--enable-nacl-debug</code> flag set. This flag causes
+Chrome to pause when a NaCl module is first loaded, waiting for a connection
+from gdb. The <code>make debug</code> command also simultaneously launches GDB and loads
+the symbols for that NEXE. To connect GDB to Chrome, in the GDB console, type:</p>
<pre class="prettyprint">
(gdb) target remote :4014
</pre>
-<p>This tells GDB to connect to a TCP port on <code>localhost:4014</code>–the port that
+<p>This tells GDB to connect to a TCP port on <code>localhost:4014</code>, the port that
Chrome is listening on. GDB will respond:</p>
<pre class="prettyprint">
Remote debugging using :4014
</pre>
<p>At this point, you can use the standard GDB commands to debug your NaCl module.
The most common commands you will use to debug are <code>continue</code>, <code>step</code>,
-<code>next</code>, <code>break</code> and <code>backtrace</code>. See <a class="reference internal" href="/native-client/devguide/devcycle/debugging.html"><em>Debugging</em></a> for more information about debugging a Native Client
-application.</p>
+<code>next</code>, <code>break</code> and <code>backtrace</code>. See
+<a class="reference internal" href="/native-client/devguide/devcycle/debugging.html"><em>Debugging</em></a> for more information about
+debugging a Native Client application.</p>
</section>
{{/partials.standard_nacl_article}}
projects / platform / framework / web / crosswalk.git / blobdiff