src/native_client_sdk/doc_generated/sdk/examples.html

   1 {{+bindTo:partials.standard_nacl_article}}
   2
   3 <section id="running-the-sdk-examples">
   4 <span id="sdk-examples-2"></span><h1 id="running-the-sdk-examples"><span id="sdk-examples-2"></span>Running the SDK Examples</h1>
   5 <p>Every Native Client SDK bundle comes with a folder of example applications.
   6 Each example demonstrates one or two key Native Client programming concepts.
   7 After you&#8217;ve <a class="reference internal" href="/native-client/sdk/download.html"><em>downloaded the SDK</em></a>, follow the instructions
   8 on this page to build and run the examples.</p>
   9 <h2 id="configure-the-google-chrome-browser">Configure the Google Chrome Browser</h2>
  10 <ol class="arabic">
  11 <li><p class="first">Your version of Chrome must be equal to or greater than the version of
  12 your SDK bundle. For example, if you&#8217;re developing with the <code>pepper_31</code>
  13 bundle, you must use Google Chrome version 31 or greater. To find out what
  14 version of Chrome you&#8217;re using, type <code>about:chrome</code> or <code>about:version</code>
  15 in the Chrome address bar.</p>
  16 </li>
  17 <li><p class="first">For Portable Native Client, no extra Chrome flags are needed as of
  18 Chrome version 31.</p>
  19 <p>For other Native Client applications, or to <strong>debug</strong> Portable Native
  20 Client applications by translating the <strong>pexe</strong> to a <strong>nexe</strong> ahead of
  21 time, enable the Native Client flag. Native Client is enabled by default
  22 only for applications distributed through the Chrome Web Store. To run
  23 Native Client applications that are not distributed through the Chrome
  24 Web Store, like the SDK examples, you must specifically enable the Native
  25 Client flag in Chrome:</p>
  26 <ul class="small-gap">
  27 <li><p class="first">Type <code>about:flags</code> in the Chrome address bar and scroll down to
  28 &#8220;Native Client&#8221;.</p>
  29 </li>
  30 <li><p class="first">If the link below &#8220;Native Client&#8221; says &#8220;Disable&#8221;, then Native Client is
  31 already enabled and you don&#8217;t need to do anything else.</p>
  32 </li>
  33 <li><p class="first">If the link below &#8220;Native Client&#8221; says &#8220;Enable&#8221;, click the &#8220;Enable&#8221;
  34 link, scroll down to the bottom of the page, and click the &#8220;Relaunch
  35 Now&#8221; button. All browser windows will restart when you relaunch Chrome.</p>
  36 </li>
  37 </ul>
  38 </li>
  39 <li><p class="first">Disable the Chrome cache. Chrome caches resources aggressively; when you
  40 are building a Native Client application you should disable the cache to
  41 make sure that Chrome loads the latest version:</p>
  42 <ul class="small-gap">
  43 <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
  44 choosing Tools &gt; Developer tools.</p>
  45 </li>
  46 <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
  47 Chrome window.</p>
  48 </li>
  49 <li><p class="first">Under the &#8220;General&#8221; settings, check the box next to &#8220;Disable cache&#8221;.</p>
  50 </li>
  51 </ul>
  52 </li>
  53 </ol>
  54 <h2 id="build-the-sdk-examples">Build the SDK examples</h2>
  55 <p>Starting with the <code>pepper_24</code> bundle, the Makefile scripts for the SDK
  56 examples build multiple versions of the examples using all three SDK
  57 toolchains (newlib, glibc, and PNaCl) and in both release and debug
  58 configurations.  (Note that some examples build only with the particular
  59 toolchains).</p>
  60 <p>To build all the examples, go to the examples directory in a specific SDK
  61 bundle and run <code>make</code>:</p>
  62 <pre class="prettyprint">
  63 $ cd pepper_31/examples
  64 $ make
  65 make -C api  all
  66 make[1]: Entering directory `pepper_31/examples/api'
  67 make -C audio  all
  68 make[2]: Entering directory `pepper_31/examples/api/audio'
  69   CXX  newlib/Debug/audio_x86_32.o
  70   LINK newlib/Debug/audio_x86_32.nexe
  71   CXX  newlib/Debug/audio_x86_64.o
  72   LINK newlib/Debug/audio_x86_64.nexe
  73   CXX  newlib/Debug/audio_arm.o
  74   LINK newlib/Debug/audio_arm.nexe
  75   CREATE_NMF newlib/Debug/audio.nmf
  76 make[2]: Leaving directory `pepper_31/examples/api/audio'
  77 make -C url_loader  all
  78 make[2]: Entering directory `pepper_31/examples/api/url_loader'
  79   CXX  newlib/Debug/url_loader_x86_32.o
  80 ...
  81 </pre>
  82 <p>Calling <code>make</code> from inside a particular example&#8217;s directory will build only
  83 that example:</p>
  84 <pre class="prettyprint">
  85 $ cd pepper_31/examples/api/core
  86 $ make
  87   CXX  newlib/Debug/core_x86_32.o
  88   LINK newlib/Debug/core_x86_32.nexe
  89   CXX  newlib/Debug/core_x86_64.o
  90   LINK newlib/Debug/core_x86_64.nexe
  91   CXX  newlib/Debug/core_arm.o
  92   LINK newlib/Debug/core_arm.nexe
  93   CREATE_NMF newlib/Debug/core.nmf
  94 </pre>
  95 <p>You can call <code>make</code> with the <code>TOOLCHAIN</code> and <code>CONFIG</code> parameters to
  96 override the defaults:</p>
  97 <pre class="prettyprint">
  98 $ make TOOLCHAIN=pnacl CONFIG=Release
  99   CXX  pnacl/Release/core_pnacl.o
 100   LINK pnacl/Release/core.bc
 101   FINALIZE pnacl/Release/core.pexe
 102   CREATE_NMF pnacl/Release/core.nmf
 103 </pre>
 104 <p>You can also set <code>TOOLCHAIN</code> to &#8220;all&#8221; to build one or more examples with
 105 all available toolchains:</p>
 106 <pre class="prettyprint">
 107 $ make TOOLCHAIN=all
 108 make TOOLCHAIN=newlib
 109 make[1]: Entering directory `pepper_31/examples/api/core'
 110   CXX  newlib/Debug/core_x86_32.o
 111   LINK newlib/Debug/core_x86_32.nexe
 112   CXX  newlib/Debug/core_x86_64.o
 113   LINK newlib/Debug/core_x86_64.nexe
 114   CXX  newlib/Debug/core_arm.o
 115   LINK newlib/Debug/core_arm.nexe
 116   CREATE_NMF newlib/Debug/core.nmf
 117 make[1]: Leaving directory `pepper_31/examples/api/core'
 118 make TOOLCHAIN=glibc
 119 make[1]: Entering directory `pepper_31/examples/api/core'
 120   CXX  glibc/Debug/core_x86_32.o
 121   LINK glibc/Debug/core_x86_32.nexe
 122   CXX  glibc/Debug/core_x86_64.o
 123   LINK glibc/Debug/core_x86_64.nexe
 124   CREATE_NMF glibc/Debug/core.nmf
 125 make[1]: Leaving directory `pepper_31/examples/api/core'
 126 make TOOLCHAIN=pnacl
 127 make[1]: Entering directory `pepper_31/examples/api/core'
 128   CXX  pnacl/Debug/core.o
 129   LINK pnacl/Debug/core_unstripped.bc
 130   FINALIZE pnacl/Debug/core_unstripped.pexe
 131   CREATE_NMF pnacl/Debug/core.nmf
 132 make[1]: Leaving directory `pepper_31/examples/api/core'
 133 make TOOLCHAIN=linux
 134 make[1]: Entering directory `pepper_31/examples/api/core'
 135   CXX  linux/Debug/core.o
 136   LINK linux/Debug/core.so
 137 make[1]: Leaving directory `pepper_31/examples/api/core'
 138 </pre>
 139 <p>After running <code>make</code>, each example directory will contain one or more of
 140 the following subdirectories:</p>
 141 <ul class="small-gap">
 142 <li>a <code>newlib</code> directory with subdirectories <code>Debug</code> and <code>Release</code>;</li>
 143 <li>a <code>glibc</code> directory with subdirectories <code>Debug</code> and <code>Release</code>;</li>
 144 <li>a <code>pnacl</code> directory with subdirectories <code>Debug</code> and <code>Release</code>;</li>
 145 </ul>
 146 <p>For the newlib and glibc toolchains the Debug and Release subdirectories
 147 contain .nexe files for all target architectures. For the PNaCl toolchain
 148 they contain a single .pexe file. PNaCl debug also produces pre-translated
 149 .nexe files, for ease of debugging. All Debug and Release directories contain
 150 a manifest (.nmf) file that references the associated .nexe or .pexe files.
 151 For information about Native Client manifest files, see the <a class="reference internal" href="/native-client/overview.html"><em>Technical
 152 Overview</em></a>.</p>
 153 <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
 154 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>
 155 <h2 id="run-the-sdk-examples"><span id="id1"></span>Run the SDK examples</h2>
 156 <p>To run the SDK examples, you can use the <code>make run</code> command:</p>
 157 <pre class="prettyprint">
 158 $ cd pepper_31/examples/api/core
 159 $ make run
 160 </pre>
 161 <p>This will launch a local HTTP server which will serve the data for the
 162 example. It then launches Chrome with the address of this server, usually
 163 <code>http://localhost:5103</code>. After you close Chrome, the local HTTP server is
 164 automatically shutdown.</p>
 165 <p>This command will try to find an executable named <code>google-chrome</code> in your
 166 <code>PATH</code> environment variable. If it can&#8217;t, you&#8217;ll get an error message like
 167 this:</p>
 168 <pre class="prettyprint">
 169 pepper_31/tools/common.mk:415: No valid Chrome found at CHROME_PATH=
 170 pepper_31/tools/common.mk:415: *** Set CHROME_PATH via an environment variable, or command-line..  Stop.
 171 </pre>
 172 <p>Set the CHROME_PATH environment variable to the location of your Chrome
 173 executable.</p>
 174 <ul class="small-gap">
 175 <li><p class="first">On Windows:</p>
 176 <p>The default install location of Chrome is
 177 <code>C:\Program Files (x86)\Google\Chrome\Application\chrome.exe</code> for Chrome
 178 stable and
 179 <code>C:\Users\&lt;username&gt;\AppData\Local\Google\Chrome SxS\Application\chrome.exe</code>
 180 for Chrome Canary; try looking in those directories first:</p>
 181 <pre class="prettyprint">
 182 &gt; set CHROME_PATH=&lt;Path to chrome.exe&gt;
 183 </pre>
 184 </li>
 185 <li><p class="first">On Linux:</p>
 186 <pre class="prettyprint">
 187 $ export CHROME_PATH=&lt;Path to google-chrome&gt;
 188 </pre>
 189 </li>
 190 <li><p class="first">On Mac:</p>
 191 <p>The default install location of Chrome is
 192 <code>/Applications/Google Chrome.app/Contents/MacOS/Google Chrome</code> for
 193 Chrome Stable and
 194 <code>Applications/Google Chrome Canary.app/Contents/MacOS/Google Chrome Canary</code>
 195 for Chrome Canary. Note that you have to reference the executable inside the
 196 application bundle, not the top-level <code>.app</code> directory:</p>
 197 <pre class="prettyprint">
 198 $ export CHROME_PATH=&lt;Path to Google Chrome&gt;
 199 </pre>
 200 </li>
 201 </ul>
 202 <p>You can run via a different toolchain or configuration by using the
 203 <code>TOOLCHAIN</code> and <code>CONFIG</code> parameters to make:</p>
 204 <pre class="prettyprint">
 205 $ make run TOOLCHAIN=pnacl CONFIG=Debug
 206 </pre>
 207 <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>
 208 <p>Each example can also be launched as a packaged app. For more information about
 209 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
 210 <a class="reference external" href="/apps/about_apps">Chrome apps documentation</a>.</p>
 211 <p>Some Pepper features, such as TCP/UDP socket access, are only allowed in
 212 packaged apps. The examples that use these features must be run as packaged
 213 apps, by using the <code>make run_package</code> command:</p>
 214 <pre class="prettyprint">
 215 $ make run_package
 216 </pre>
 217 <p>You can use <code>TOOLCHAIN</code> and <code>CONFIG</code> parameters as above to run with a
 218 different toolchain or configuration.</p>
 219 <h2 id="debugging-the-sdk-examples"><span id="id2"></span>Debugging the SDK examples</h2>
 220 <p>The NaCl SDK uses <a class="reference external" href="https://www.gnu.org/software/gdb/">GDB</a> to debug Native
 221 Client code. The SDK includes a prebuilt version of GDB that is compatible with
 222 NaCl code. To use it, run the <code>make debug</code> command from an example directory:</p>
 223 <pre class="prettyprint">
 224 $ make debug
 225 </pre>
 226 <p>This will launch Chrome with the <code>--enable-nacl-debug</code> flag set. This flag
 227 will cause Chrome to pause when a NaCl module is first loaded, waiting for a
 228 connection from gdb. The <code>make debug</code> command also simultaneously launches
 229 GDB and loads the symbols for that NEXE. To connect GDB to Chrome, in the GDB
 230 console, type:</p>
 231 <pre class="prettyprint">
 232 (gdb) target remote :4014
 233 </pre>
 234 <p>This tells GDB to connect to a TCP port on <code>localhost:4014</code>&#8211;the port that
 235 Chrome is listening on. GDB will respond:</p>
 236 <pre class="prettyprint">
 237 Remote debugging using :4014
 238 0x000000000fa00080 in ?? ()
 239 </pre>
 240 <p>At this point, you can use the standard GDB commands to debug your NaCl module.
 241 The most common commands you will use to debug are <code>continue</code>, <code>step</code>,
 242 <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
 243 application.</p>
 244 </section>
 245
 246 {{/partials.standard_nacl_article}}