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