| {{+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’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’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> |
| <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> |
| </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’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 “all” 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.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' |
| </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 ‘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> |
| </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 |
| <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 |
| <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. |
| </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\<username>\AppData\Local\Google\Chrome SxS\Application\chrome.exe</code> |
| for Chrome Canary; try looking in those directories first:</p> |
| <pre class="prettyprint"> |
| > set CHROME_PATH=<Path to chrome.exe> |
| </pre> |
| </li> |
| <li><p class="first">On Linux:</p> |
| <pre class="prettyprint"> |
| $ export CHROME_PATH=<Path to google-chrome> |
| </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=<Path to Google Chrome> |
| </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 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>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 <code>localhost:4014</code>–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}} |
