1 {{+bindTo:partials.standard_nacl_article}} 2 3 <span class="target" id="sdk-examples-2"></span><section id="examples"> 4 <h1 id="examples">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 <p>Your version of Chrome must be equal to or greater than the version of your SDK 10 bundle. For example, if you’re developing with the <code>pepper_35</code> bundle, you 11 must use Google Chrome version 35 or greater. To find out what version of Chrome 12 you’re using, type <code>about:chrome</code> or <code>about:version</code> in the Chrome address 13 bar.</p> 14 <h2 id="enable-native-client"><span id="id1"></span>Enable Native Client</h2> 15 <p>If you are using Chrome 31 or later, you can skip this section. To run Portable 16 Native Client applications you must specifically enable Native Client in Chrome:</p> 17 <ol class="arabic"> 18 <li><p class="first">Type <code>about:flags</code> in the Chrome address bar and scroll down to “Native 19 Client”.</p> 20 <ul class="small-gap"> 21 <li><p class="first">If the link below “Native Client” says “Disable”, then Native Client is 22 already enabled and you don’t need to do anything else.</p> 23 </li> 24 </ul> 25 <ul class="small-gap"> 26 <li><p class="first">If the link below “Native Client” says “Enable”, click the “Enable” 27 link.</p> 28 </li> 29 </ul> 30 </li> 31 <li><p class="first">Scroll down to the bottom of the page, and click “Relaunch Now”. All browser 32 windows will restart when you relaunch Chrome.</p> 33 </li> 34 </ol> 35 <h2 id="build-the-sdk-examples"><span id="id2"></span>Build the SDK examples</h2> 36 <p>The Makefile scripts for the SDK examples can build multiple versions of the 37 examples using any of the three SDK toolchains (newlib, glibc, and PNaCl) and in 38 both release and debug configurations. Note that some examples, <code>dlopen</code> for 39 example, build only with particular toolchains.</p> 40 <p>Find the toolchains for each example by looking at the <code>VALID_TOOLCHAINS</code> 41 variable in the Makefile for a particular example. The first item listed is the 42 default. It’s built when you run an example make file without parameters. for 43 example running make in the <code>core</code> directory of pepper_35 builds the example 44 using the <code>newlib</code> toolchain.</p> 45 <pre class="prettyprint"> 46 $ cd pepper_35/examples/api/core 47 $ make 48 CXX newlib/Release/core_x86_32.o 49 LINK newlib/Release/core_unstripped_x86_32.nexe 50 VALIDATE newlib/Release/core_unstripped_x86_32.nexe 51 CXX newlib/Release/core_x86_64.o 52 LINK newlib/Release/core_unstripped_x86_64.nexe 53 VALIDATE newlib/Release/core_unstripped_x86_64.nexe 54 CXX newlib/Release/core_arm.o 55 LINK newlib/Release/core_unstripped_arm.nexe 56 VALIDATE newlib/Release/core_unstripped_arm.nexe 57 STRIP newlib/Release/core_x86_32.nexe 58 STRIP newlib/Release/core_x86_64.nexe 59 STRIP newlib/Release/core_arm.nexe 60 CREATE_NMF newlib/Release/core.nmf 61 </pre> 62 <p>As you can see, this produces a number of architecture specific nexe files in 63 the <code>pepper_35/examples/api/core/Release</code> directory. Create debug versions by 64 using the <code>CONFIG</code> parameter of the make command.</p> 65 <pre class="prettyprint"> 66 $make CONFIG=Debug 67 </pre> 68 <p>This creates similar output, but in <code>pepper_35/examples/api/core/Debug</code>.</p> 69 <p>Select a different toolchain with the <code>TOOLCHAIN</code> parameter. For example:</p> 70 <pre class="prettyprint"> 71 $ cd pepper_35/examples/api/core 72 $ make TOOLCHAIN=pnacl CONFIG=Release 73 CXX pnacl/Release/core.o 74 LINK pnacl/Release/core_unstripped.bc 75 FINALIZE pnacl/Release/core_unstripped.pexe 76 CREATE_NMF pnacl/Release/core.nmf 77 </pre> 78 <p>You can also set <code>TOOLCHAIN</code> to <code>all</code> to build all Release versions with 79 default toolchains.</p> 80 <pre class="prettyprint"> 81 $ cd pepper_35/examples/api/core 82 $ make TOOLCHAIN=all 83 make TOOLCHAIN=newlib 84 make[1]: Entering directory 'pepper_35/examples/api/core' 85 CXX newlib/Release/core_x86_32.o 86 LINK newlib/Release/core_unstripped_x86_32.nexe 87 VALIDATE newlib/Release/core_unstripped_x86_32.nexe 88 CXX newlib/Release/core_x86_64.o 89 LINK newlib/Release/core_unstripped_x86_64.nexe 90 VALIDATE newlib/Release/core_unstripped_x86_64.nexe 91 CXX newlib/Release/core_arm.o 92 LINK newlib/Release/core_unstripped_arm.nexe 93 VALIDATE newlib/Release/core_unstripped_arm.nexe 94 STRIP newlib/Release/core_x86_32.nexe 95 STRIP newlib/Release/core_x86_64.nexe 96 STRIP newlib/Release/core_arm.nexe 97 CREATE_NMF newlib/Release/core.nmf 98 make[1]: Leaving directory 'pepper_35/examples/api/core' 99 make TOOLCHAIN=glibc 100 make[1]: Entering directory 'pepper_35/examples/api/core' 101 CXX glibc/Release/core_x86_32.o 102 LINK glibc/Release/core_unstripped_x86_32.nexe 103 VALIDATE glibc/Release/core_unstripped_x86_32.nexe 104 CXX glibc/Release/core_x86_64.o 105 LINK glibc/Release/core_unstripped_x86_64.nexe 106 VALIDATE glibc/Release/core_unstripped_x86_64.nexe 107 ... 108 (content excerpted) 109 ... 110 </pre> 111 <h3 id="build-results"><span id="id3"></span>Build results</h3> 112 <p>After running <code>make</code>, example directories will contain one or more of the 113 following subdirectories, depending on which Makefile you run:</p> 114 <ul class="small-gap"> 115 <li><code>newlib</code> with subdirectories <code>Debug</code> and <code>Release</code>;</li> 116 <li><code>glibc</code> with subdirectories <code>Debug</code> and <code>Release</code>;</li> 117 <li><code>pnacl</code> with subdirectories <code>Debug</code> and <code>Release</code>;</li> 118 </ul> 119 <p>For the newlib and glibc toolchains the Debug and Release subdirectories 120 contain .nexe files for all target architectures. For the PNaCl toolchain 121 they contain a single .pexe file. PNaCl debug also produces pre-translated 122 .nexe files, for ease of debugging. All Debug and Release directories contain 123 a manifest (.nmf) file that references the associated .nexe or .pexe files. 124 For information about Native Client manifest files, see the <a class="reference internal" href="/native-client/overview.html"><em>Technical 125 Overview</em></a>.</p> 126 <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 127 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> 128 <h2 id="run-the-sdk-examples"><span id="running-the-sdk-examples"></span>Run the SDK examples</h2> 129 <h3 id="disable-the-chrome-cache"><span id="disable-chrome-cache"></span>Disable the Chrome cache</h3> 130 <p>Chrome’s intelligent caching caches resources aggressively. When building a 131 Native Client application you should disable the cache to make sure that Chrome 132 loads the latest version. Intelligent caching only remains inactive while 133 Developer Tools are open. Otherwise, agressive caching continues.</p> 134 <ol class="arabic simple"> 135 <li>Open Chrome’s developer tools by clicking the menu icon <img alt="menu-icon" src="/native-client/images/menu-icon.png" /> and 136 choosing Tools > Developer tools.</li> 137 <li>Click the gear icon <img alt="gear-icon" src="/native-client/images/gear-icon.png" /> in the bottom right corner of the Chrome 138 window.</li> 139 <li>Under the “General” settings, check the box next to “Disable cache”.</li> 140 </ol> 141 <h3 id="run-the-examples"><span id="id4"></span>Run the examples</h3> 142 <p>To run the SDK examples, use the <code>make run</code> command:</p> 143 <pre class="prettyprint"> 144 $ cd pepper_35/examples/api/core 145 $ make run 146 </pre> 147 <p>This launches a local HTTP server that serves the example. It then launches 148 Chrome with the address of this server, usually <code>http://localhost:5103</code>. 149 After you close Chrome, the local HTTP server automatically shuts down.</p> 150 <p>This command tries to find an executable named <code>google-chrome</code> in your 151 <code>PATH</code> environment variable. If it can’t, you’ll get an error message like 152 this:</p> 153 <pre class="prettyprint"> 154 pepper_35/tools/common.mk:415: No valid Chrome found at CHROME_PATH= 155 pepper_35/tools/common.mk:415: *** Set CHROME_PATH via an environment variable, or command-line.. Stop. 156 </pre> 157 <h3 id="add-an-environment-variable-for-chrome"><span id="add-an-env-variable-for-chrome"></span>Add an environment variable for Chrome</h3> 158 <p>Set the CHROME_PATH environment variable to the location of your Chrome 159 executable.</p> 160 <ul class="small-gap"> 161 <li><p class="first">On Windows:</p> 162 <p>The default install location of Chrome is 163 <code>C:\Program Files (x86)\Google\Chrome\Application\chrome.exe</code> for Chrome 164 stable and 165 <code>C:\Users\<username>\AppData\Local\Google\Chrome SxS\Application\chrome.exe</code> 166 for Chrome Canary. Try looking in those directories first:</p> 167 <pre class="prettyprint"> 168 > set CHROME_PATH=<Path to chrome.exe> 169 </pre> 170 </li> 171 <li><p class="first">On Linux:</p> 172 <pre class="prettyprint"> 173 $ export CHROME_PATH=<Path to google-chrome> 174 </pre> 175 </li> 176 <li><p class="first">On Mac:</p> 177 <p>The default install location of Chrome is 178 <code>/Applications/Google Chrome.app/Contents/MacOS/Google Chrome</code> for 179 Chrome Stable and 180 <code>Applications/Google Chrome Canary.app/Contents/MacOS/Google Chrome Canary</code> 181 for Chrome Canary. Note that you have to reference the executable inside the 182 application bundle, not the top-level <code>.app</code> directory:</p> 183 <pre class="prettyprint"> 184 $ export CHROME_PATH=<Path to Google Chrome> 185 </pre> 186 </li> 187 </ul> 188 <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> 189 <p>Each example can also be launched as a packaged application. A packaged 190 application is a special zip file (with a .crx extension) hosted in the Chrome 191 Web Store. This file contains all of the application parts: A Chrome Web Store 192 manifest file (manifest.json), an icon, and all of the regular Native Client 193 application files. Refer to <a class="reference external" href="/apps/about_apps">What are Chrome Apps</a> for more 194 information about creating a packaged application.</p> 195 <p>Some Pepper features, such as TCP/UDP socket access, are only allowed in 196 packaged applications. The examples that use these features must be run as 197 packaged applications, by using the following command:</p> 198 <pre class="prettyprint"> 199 $ make run_package 200 </pre> 201 <p>You can use <code>TOOLCHAIN</code> and <code>CONFIG</code> parameters as described above to run 202 with a different toolchain or configuration.</p> 203 <h2 id="debugging-the-sdk-examples"><span id="id5"></span>Debugging the SDK examples</h2> 204 <p>The NaCl SDK uses <a class="reference external" href="https://www.gnu.org/software/gdb/">GDB</a> to debug Native 205 Client code. The SDK includes a prebuilt version of GDB that is compatible with 206 NaCl code. To use it, run the <code>make debug</code> command from an example directory:</p> 207 <pre class="prettyprint"> 208 $ make debug 209 </pre> 210 <p>This launches Chrome with the <code>--enable-nacl-debug</code> flag set. This flag causes 211 Chrome to pause when a NaCl module is first loaded, waiting for a connection 212 from gdb. The <code>make debug</code> command also simultaneously launches GDB and loads 213 the symbols for that NEXE. To connect GDB to Chrome, in the GDB console, type:</p> 214 <pre class="prettyprint"> 215 (gdb) target remote :4014 216 </pre> 217 <p>This tells GDB to connect to a TCP port on <code>localhost:4014</code>, the port that 218 Chrome is listening on. GDB will respond:</p> 219 <pre class="prettyprint"> 220 Remote debugging using :4014 221 0x000000000fa00080 in ?? () 222 </pre> 223 <p>At this point, you can use the standard GDB commands to debug your NaCl module. 224 The most common commands you will use to debug are <code>continue</code>, <code>step</code>, 225 <code>next</code>, <code>break</code> and <code>backtrace</code>. See 226 <a class="reference internal" href="/native-client/devguide/devcycle/debugging.html"><em>Debugging</em></a> for more information about 227 debugging a Native Client application.</p> 228 </section> 229 230 {{/partials.standard_nacl_article}} 231
