src/native_client_sdk/doc_generated/sdk/examples.html

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