[NaCl SDK Docs] Check in the generated NaCl SDK Documentation.

native_client_sdk/src/doc/_developer.chrome.com_generated/sdk/examples.html

+{{+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>
+<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&#8217;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>
+<section id="configure-the-google-chrome-browser">
+<h2 id="configure-the-google-chrome-browser">Configure the Google Chrome Browser</h2>
+<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&#8217;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&#8217;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>
+<ul class="small-gap">
+<li><p class="first">Type <code>about:flags</code> in the Chrome address bar and scroll down to
+&#8220;Native Client&#8221;.</p>
+</li>
+<li><p class="first">If the link below &#8220;Native Client&#8221; says &#8220;Disable&#8221;, then Native Client is
+already enabled and you don&#8217;t need to do anything else.</p>
+</li>
+<li><p class="first">If the link below &#8220;Native Client&#8221; says &#8220;Enable&#8221;, click the &#8220;Enable&#8221;
+link, scroll down to the bottom of the page, and click the &#8220;Relaunch
+Now&#8221; 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&#8217;s developer tools by clicking the menu icon <img alt="menu-icon" src="/native-client/images/menu-icon.png" /> and
+choosing Tools &gt; 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 &#8220;General&#8221; settings, check the box next to &#8220;Disable cache&#8221;.</p>
+</li>
+</ul>
+</li>
+</ol>
+</section><section id="build-the-sdk-examples">
+<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>
+<pre class="prettyprint">
+$ cd pepper_31/examples
+$ 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
+...
+</pre>
+<p>Calling <code>make</code> from inside a particular example&#8217;s directory will build only
+that example:</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
+</pre>
+<p>You can call <code>make</code> with the <code>TOOLCHAIN</code> and <code>CONFIG</code> parameters to
+override the defaults:</p>
+<pre class="prettyprint">
+$ make TOOLCHAIN=pnacl CONFIG=Release
+  CXX  pnacl/Release/core_pnacl.o
+  LINK pnacl/Release/core.bc
+  FINALIZE pnacl/Release/core.pexe
+  CREATE_NMF pnacl/Release/core.nmf
+</pre>
+<p>You can also set <code>TOOLCHAIN</code> to &#8220;all&#8221; to build one or more examples with
+all available toolchains:</p>
+<pre class="prettyprint">
+$ 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 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_pnacl.o
+  LINK pnacl/Debug/core.bc
+  FINALIZE pnacl/Debug/core.pexe
+  TRANSLATE pnacl/Debug/core_x86_32.nexe
+  TRANSLATE pnacl/Debug/core_x86_64.nexe
+  TRANSLATE pnacl/Debug/core_arm.nexe
+  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'
+</pre>
+<p>After running <code>make</code>, each example directory will contain one or more of
+the following subdirectories:</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>
+</ul>
+<p>For the newlib and glibc toolchains the Debug and Release subdirectories
+contain .nexe files for all target architectures. For the PNaCl toolchain
+they contain a single .pexe file. PNaCl debug also produces pre-translated
+.nexe files, for ease of debugging. All Debug and Release directories contain
+a manifest (.nmf) file that references the associated .nexe or .pexe files.
+For information about Native Client manifest files, see the <a class="reference internal" href="/native-client/overview.html"><em>Technical
+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 &#8216;make&#8217; 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>
+</section><section id="run-the-sdk-examples">
+<span id="id1"></span><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>
+<pre class="prettyprint">
+$ cd pepper_31/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
+<a class="reference external" href="http://localhost:5103">http://localhost:5103</a>. 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
+<code>PATH</code> environment variable. If it can&#8217;t, you&#8217;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.
+</pre>
+<p>Set the CHROME_PATH environment variable to the location of your Chrome
+executable.</p>
+<ul class="small-gap">
+<li><p class="first">On Windows:</p>
+<p>The default install location of Chrome is
+<code>C:\Program Files (x86)\Google\Chrome\Application\chrome.exe</code> for Chrome
+stable and
+<code>C:\Users\&lt;username&gt;\AppData\Local\Google\Chrome SxS\Application\chrome.exe</code>
+for Chrome Canary; try looking in those directories first:</p>
+<pre class="prettyprint">
+&gt; set CHROME_PATH=&lt;Path to chrome.exe&gt;
+</pre>
+</li>
+<li><p class="first">On Linux:</p>
+<pre class="prettyprint">
+$ export CHROME_PATH=&lt;Path to google-chrome&gt;
+</pre>
+</li>
+<li><p class="first">On Mac:</p>
+<p>The default install location of Chrome is
+<code>/Applications/Google Chrome.app/Contents/MacOS/Google Chrome</code> for
+Chrome Stable and
+<code>Applications/Google Chrome Canary.app/Contents/MacOS/Google Chrome Canary</code>
+for Chrome Canary. Note that you have to reference the executable inside the
+application bundle, not the top-level <code>.app</code> directory:</p>
+<pre class="prettyprint">
+$ export CHROME_PATH=&lt;Path to Google Chrome&gt;
+</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>
+</section><section id="run-the-sdk-examples-as-packaged-apps">
+<span id="run-sdk-examples-as-packaged"></span><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 appliction</em></a>.  For general information about packaged apps, see the
+<a class="reference external" href="http://developer.chrome.com/apps/about_apps.html">Chrome apps documentation</a>.</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>
+<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>
+</section><section id="debugging-the-sdk-examples">
+<span id="id2"></span><h2 id="debugging-the-sdk-examples"><span id="id2"></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>
+<pre class="prettyprint">
+(gdb) target remote :4014
+</pre>
+<p>This tells GDB to connect to a TCP port on localhost:4014&#8211;the port that
+Chrome is listening on. GDB will respond:</p>
+<pre class="prettyprint">
+Remote debugging using :4014
+0x000000000fa00080 in ?? ()
+</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>
+</section></section>
+
+{{/partials.standard_nacl_article}}