documentation/examples.html

   1 <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
   2 <html xmlns="http://www.w3.org/1999/xhtml">
   3 <head>
   4 <meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
   5 <title>Native Client: Examples and Tests</title>
   6 <link href="stylesheet.css" type="text/css" rel="stylesheet"></link>
   7 </head>
   8
   9 <body>
  10
  11 <div id="toplink">
  12 <a href="../README.html">Back to README</a>
  13 </div>
  14
  15 <h1>Examples and Tests</h1>
  16
  17 <p>
  18 This page describes the Native Client example and test programs.
  19 In general,
  20 directory paths in this document are relative to
  21 <code>nacl/googleclient/native_client</code>.
  22 For example, the source files for all the examples and tests are under the
  23 <code>tests</code> directory of
  24 <code>nacl/googleclient/native_client</code>.
  25 </p>
  26
  27 <p>
  28 If you haven't already run an example or test, go to
  29 <a href="getting_started.html">Getting Started</a>.
  30 That page leads you through setting up Native Client.
  31 It then shows you to run examples and tests in three modes:
  32 </p>
  33
  34 <ul>
  35 <li> as Native Client applications </li>
  36 <li> as standalone Linux and Mac applications </li>
  37 <li> in a browser (using the Native Client plug-in) </li>
  38 </ul>
  39
  40 <p>
  41 Once you've installed the Native Client plug-in,
  42 it's easy to run
  43 any of the prebuilt examples and tests that work in the browser.
  44 Just go to
  45 <a href="../scons-out/nacl/staging/index.html"><code>scons-out/nacl/staging/index.html</code></a>
  46 and click the Run button for the example or test.
  47 </p>
  48
  49 <h3>Contents</h3>
  50
  51 <ul>
  52   <li> <a href="#eg-hello">Hello world examples</a></li>
  53   <li> <a href="#eg-multimedia">Multimedia examples</a></li>
  54   <li> <a href="#eg-browser">Browser plug-in examples and tests</a>
  55     <ul>
  56     <li> <a href="#eg-browser-egs">Examples</a></li>
  57     <li> <a href="#eg-browser-ftests">Functionality tests</a></li>
  58     <li> <a href="#eg-browser-ptests">Performance tests</a></li>
  59     </ul> </li>
  60   <li> <a href="#eg-other">Other examples and tests</a>
  61     <ul>
  62     <li> <a href="#eg-smoke">Smoke test suite</a></li>
  63     <li> <a href="#eg-quake">Quake, XaoS, and Lua</a></li>
  64     <li> <a href="#eg-misc">Miscellaneous</a></li>
  65     </ul></li>
  66 <li><a href="#build-run">How to build and run tests</a>
  67   <ul>
  68   <li> <a href="#run-py">Running with run.py</a> </li>
  69   <li> <a href="#run-make">Building and running with GNU make</a> </li>
  70   <li> <a href="#run-scons">Building and running with SCons</a>
  71     <ul>
  72     <li> <a href="#run-smoke">Running the smoke test suite</a> </li>
  73     </ul></li>
  74   </ul></li>
  75 </ul>
  76
  77 <h2> <a name="list"> </a> List of examples and tests </h2>
  78
  79 <p>
  80 The Native Client examples and tests fall into the following rough categories:
  81
  82 <ul>
  83 <li> <a href="#eg-hello">Hello world examples</a></li>
  84 <li> <a href="#eg-multimedia">Multimedia examples</a></li>
  85 <li> <a href="#eg-browser">Browser plug-in examples and tests</a></li>
  86 <li> <a href="#eg-other">Other examples and tests</a></li>
  87 </ul>
  88
  89 <h2> <a name="eg-hello"> </a> Hello world examples </h2>
  90
  91 <p>
  92 Two hello world examples show how to create a simple Native Client module
  93 that runs in the browser.
  94 A third is an app that's part of the smoke test suite.
  95 </p>
  96
  97 <table>
  98 <tr>
  99 <th>Example</th> <th>Description</th> <th>How to run</th> <th>Source code</th>
 100 </tr>
 101
 102 <tr>
 103 <td> NPAPI hello world </td>
 104 <td> Shows how to pass an integer and a string
 105      between a Native Client module and the browser,
 106      using NPAPI.
 107      </td>
 108 <td> See <a href="#eg-browser">Browser plug-in examples and tests</a> </td>
 109 </td>
 110 <td>
 111      <a href="../tests/npapi_hw/">tests/npapi_hw/</a>
 112 </td>
 113 </tr>
 114
 115 <tr>
 116 <td> SRPC hello world </td>
 117 <td> Shows how to pass an integer and a string
 118      between a Native Client module and the browser,
 119      using the Native Client Simple RPC API.
 120      </td>
 121 <td> See <a href="#eg-browser">Browser plug-in examples and tests</a> </td>
 122 <td> <a href="../tests/srpc_hw/">tests/srpc_hw/</a> </td>
 123 </tr>
 124
 125 <tr>
 126 <td> Command-line hello world </td>
 127 <td> A C program that works equally well as a standalone app or
 128      a Native Client app.
 129      Does <em>not</em> execute in the browser.
 130      </td>
 131 <td> See <a href="#run-smoke">Running the smoke test suite</a> </td>
 132 <td> <a href="../tests/hello_world/">tests/hello_world/</a> </td>
 133 </tr>
 134 </table>
 135
 136
 137 <h2> <a name="eg-multimedia"> </a> Multimedia examples</h2>
 138
 139 <p>
 140 The following four demos
 141 can run either as Native Client applications
 142 or (on Linux and Mac) as standalone applications.
 143 The Earth, Life, and Voronoi examples
 144 can also run in the browser.
 145 For directions on building and running these examples,
 146 see <a href="getting_started.html">Getting Started</a>,
 147 <a href="#eg-browser-egs">Examples</a> (in this page),
 148 <a href="#run-py">Running with run.py</a> (in this page), and
 149 <a href="#run-make">Building and running with GNU make</a> (also in this page).
 150 </p>
 151
 152 <p>
 153 These examples share an architecture defined in
 154 <code>nacl/googleclient/native_client/common</code>.
 155 </p>
 156
 157 <table>
 158 <tr>
 159 <th>Example</th> <th>Description</th> <th>Source code</th>
 160 </tr>
 161
 162 <tr>
 163 <td> Earth </td>
 164 <td> Rotating, ray-traced globe </td>
 165 <td> <a href="../tests/earth/">tests/earth/</a> </td>
 166 </tr>
 167
 168 <tr>
 169 <td> Life </td>
 170 <td> Cellular automaton; accepts mouse input </td>
 171 <td> <a href="../tests/life/">tests/life/</a> </td>
 172 </tr>
 173
 174 <tr>
 175 <td> Tone </td>
 176 <td> No visible UI; creates and plays a sound </td>
 177 <td> <a href="../tests/tone/">tests/tone/</a> </td>
 178 </tr>
 179
 180 <tr>
 181 <td> Voronoi </td>
 182 <td> Animated Voronoi diagram </td>
 183 <td> <a href="../tests/voronoi/">tests/voronoi/</a> </td>
 184 </tr>
 185 </table>
 186
 187 <p>
 188 Also see
 189 the browser plug-in examples and tests
 190 listed in the following section, as well as
 191 <a href="#eg-quake">Quake, XaoS, and Lua</a>.
 192 </p>
 193
 194
 195 <h2> <a name="eg-browser"> </a> Browser plug-in examples and tests </h2>
 196
 197 <p>
 198 These examples and tests require the Native Client plug-in.
 199 You can find instructions for installing the plug-in
 200 in <a href="getting_started.html">Getting Started</a>.
 201 Once you've installed the plug-in,
 202 go to the following page and click the Go button
 203 for the example or test you want to run:
 204 </p>
 205
 206 <blockquote>
 207 <a href="../scons-out/nacl/staging/index.html"><code>scons-out/nacl/staging/index.html</code></a>
 208 </blockquote>
 209
 210 <p>
 211 That file has links to HTML pages that let you run three kinds of tests:
 212 </p>
 213
 214 <ul>
 215   <li> <a href="#eg-browser-egs">Examples</a></li>
 216   <li> <a href="#eg-browser-ftests">Functionality tests</a></li>
 217   <li> <a href="#eg-browser-ptests">Performance tests</a></li>
 218 </ul>
 219
 220 <p>
 221 For more examples to run in the browser,
 222 also see
 223 <a href="#eg-quake">Quake, XaoS, and Lua</a>.
 224 </p>
 225
 226 <a name="eg-browser-egs"> </a> <h3>Examples</h3>
 227
 228 <table>
 229 <tr>
 230 <th>Example</th> <th>Description</th> <th>Source code</th>
 231 </tr>
 232
 233 <tr>
 234 <td> NPAPI hello world example </td>
 235 <td> See <a href="#eg-hello">Hello world examples</a> </td>
 236 <td> <a href="../tests/npapi_hw/">tests/npapi_hw/</a> </td>
 237 </tr>
 238
 239 <tr>
 240 <td> SRPC hello world example </td>
 241 <td> See <a href="#eg-hello">Hello world examples</a> </td>
 242 <td> <a href="../tests/srpc_hw/">tests/srpc_hw/</a> </td>
 243 </tr>
 244
 245 <tr>
 246 <td> CloudFS - URLs via file descriptors </td>
 247 <td> A simple demo of how to fetch URLs using NPAPI
 248      and then manipulate them like files.
 249      Uses <code>NaClNPN_OpenURL()</code>. </td>
 250 <td> <a href="../tests/cloudfs/">tests/cloudfs/</a> </td>
 251 </tr>
 252
 253 <tr>
 254 <td> NPAPI Monte Carlo estimate for pi </td>
 255 <td> Demonstrates using NPAPI for simple graphics and DOM updates.</td>
 256 <td> <a href="../tests/npapi_pi/">tests/npapi_pi/</a> </td>
 257 </tr>
 258
 259 <tr>
 260 <td> Spinning earth </td>
 261 <td> See <a href="#eg-multimedia">Multimedia examples</a> </td>
 262 <td> <a href="../tests/earth/">tests/earth/</a> </td>
 263 </tr>
 264
 265 <tr>
 266 <td> Interactive Life simulation </td>
 267 <td> See <a href="#eg-multimedia">Multimedia examples</a> </td>
 268 <td> <a href="../tests/life/">tests/life/</a> </td>
 269 </tr>
 270
 271 <tr>
 272 <td> Animated Voronoi diagram </td>
 273 <td> See <a href="#eg-multimedia">Multimedia examples</a> </td>
 274 <td> <a href="../tests/voronoi/">tests/voronoi/</a> </td>
 275 </tr>
 276
 277 <tr>
 278 <td> Three demos on one page </td>
 279 <td> Life, Voronoi, and Earth execute simultaneously within a single HTML page</td>
 280 <td> <a href="../tests/many/">tests/many/</a> </td>
 281 </tr>
 282
 283 <tr>
 284 <td> Nine demos on one page </td>
 285 <td> Three instances each of Life, Voronoi, and Earth execute simultaneously within a single HTML page</td>
 286 <td> <a href="../tests/many/">tests/many/</a> </td>
 287 </tr>
 288
 289 <tr>
 290 <td id="eg-mandelbrot-viewer"> Mandelbrot viewer </td>
 291 <td> Home-grown Mandelbrot viewer,
 292      demonstrating SRPC and simple user-interface integration.
 293      See also
 294      <a href="#eg-quake">XaoS</a> and the
 295      <a href="#eg-mandelbrot-perf">Mandelbrot performance test</a>.</td>
 296 <td> <a href="../tests/mandel_nav/">tests/mandel_nav/</a> </td>
 297 </tr>
 298
 299 </table>
 300
 301 <h3> <a name="eg-browser-ftests"> </a> Functionality tests </h3>
 302
 303 <table>
 304 <tr>
 305 <th>Example</th> <th>Description</th> <th>Source code</th>
 306 </tr>
 307
 308 <tr>
 309 <td> NPAPI bridge test </td>
 310 <td> Manual smoke tests for a variety of NPAPI interfaces.</td>
 311 <td> <a href="../tests/npapi_bridge/">tests/npapi_bridge/</a> </td>
 312 </tr>
 313
 314 <tr>
 315 <td> NPAPI bridge drawing test </td>
 316 <td> Simple graphics interface test.</td>
 317 <td> <a href="../tests/npapi_bridge/">tests/npapi_bridge/</a> </td>
 318 </tr>
 319
 320 <tr>
 321 <td> Simple RPC resource descriptor transfer test </td>
 322 <td> Unit tests for transferring Native Client resource descriptors
 323      between the browser and a Native Client module.</td>
 324 <td> <a href="../tests/srpc/">tests/srpc/</a> </td>
 325 </tr>
 326
 327 <tr>
 328 <td> URL content as NaCl resource descriptor test </td>
 329 <td> Tests the Native Client implementation of its
 330      <a href="http://wikipedia.org/wiki/Same_origin_policy">same-origin policy</a>
 331      for URL references from Native Client modules.</td>
 332 <td> <a href="../tests/srpc/">tests/srpc/</a> </td>
 333 </tr>
 334 </table>
 335
 336
 337 <h3> <a name="eg-browser-ptests"> </a> Performance tests </h3>
 338
 339 <table>
 340 <tr>
 341 <th>Example</th> <th>Description</th> <th>Source code</th>
 342 </tr>
 343
 344 <tr>
 345 <td id="eg-mandelbrot-perf"> Mandelbrot performance (tiled Native Client) </td>
 346 <td> Compares the performance of JavaScript and C++
 347      Mandelbrot implementations.
 348      See also
 349      <a href="#eg-quake">XaoS</a> and the
 350      <a href="#eg-mandelbrot-viewer">Mandelbrot viewer example</a>.
 351      <br />
 352      <b>Warning:</b> The JavaScript implementation is very slow!
 353      </td>
 354 <td> <a href="../tests/mandel/">tests/mandel/</a> </td>
 355 </tr>
 356
 357 <tr>
 358 <td> Simple RPC performance </td>
 359 <td> Performance test for our IMC-based simple RPC implementation.</td>
 360 <td> <a href="../tests/srpc/">tests/srpc/</a> </td>
 361 </tr>
 362
 363 <tr>
 364 <td> NPAPI bridge RPC performance </td>
 365 <td> Performance test for our IMC-based NPAPI implementation.</td>
 366 <td> <a href="../tests/npapi_bridge/">tests/npapi_bridge/</a> </td>
 367 </tr>
 368 </table>
 369
 370
 371 <h2> <a name="eg-other"> </a> Other examples and tests </h2>
 372
 373
 374 <h3> <a name="eg-smoke"> </a> Smoke test suite </h3>
 375
 376 <p>
 377 The smoke test suite contains a variety of tests
 378 that you can run as group with a single command,
 379 as described in
 380 <a href="#run-smoke">Running the smoke test suite</a>.
 381 </p>
 382
 383 <ul>
 384 <li> app_lib </li>
 385 <li> fib/fib_array </li>
 386 <li> fib/fib_scalar </li>
 387 <li> hello_world </li>
 388 <li> mandel </li>
 389 <li> mmap </li>
 390 <li> noop </li>
 391 <li> syscalls </li>
 392 <li> voronoi </li>
 393 </ul>
 394
 395 <h3> <a name="eg-quake"> </a> Quake, XaoS, and Lua </h3>
 396
 397 <p>
 398 The
 399 <a href="../tests/quake/"><code>tests/quake/</code></a>,
 400 <a href="../tests/xaos/"><code>tests/xaos/</code></a>,
 401 and
 402 <a href="../tests/lua/"><code>tests/lua/</code></a>
 403 directories have files you can use
 404 to build Quake, XaoS, and Lua for Native Client.
 405 You can run the resulting modules in the browser.
 406 </p>
 407
 408 <p>
 409 <b>Note:</b>
 410 These examples are not prebuilt.
 411 </p>
 412
 413 <p>
 414 Quake is a classic, popular 3D game developed
 415 and generously open sourced by id Software.
 416 The open-source version of Quake is no longer
 417 officially supported by id Software.
 418 For more information about Quake, see
 419 <a href="http://www.google.com/url?sa=D&amp;q=http%3A%2F%2Fen.wikipedia.org/wiki/Quake">http:/en.wikipedia.org/wiki/Quake</a>.
 420 For information on building Quake for Native Client, see the
 421 <code>README.nacl</code> file in the
 422 <code>tests/quake</code> directory.
 423 </p>
 424
 425 <p>
 426 XaoS is an interactive fractal viewer
 427 that lets you continuously zoom in or out of a
 428 Mandelbrot pattern or other fractal image.
 429 For information about XaoS, see
 430 <a href="http://www.google.com/url?sa=D&amp;q=http%3A%2F%2Fen.wikipedia.org/wiki/XaoS">http:/en.wikipedia.org/wiki/XaoS</a>.
 431 For information on building XaoS for Native Client, see the
 432 <code>README.nacl</code> file in the
 433 <code>tests/xaos</code> directory.
 434 </p>
 435
 436 <p>
 437 Lua is a scripting language
 438 designed to be powerful, fast, lightweight, embeddable, and extensible.
 439 For information about Lua, see
 440 <a href="http://www.lua.org/">http://www.lua.org</a>.
 441 For information on building Lua for Native Client, see the
 442 <code>README.nacl</code> file in the
 443 <code>tests/lua</code> directory.
 444 </p>
 445
 446 <h3> <a name="eg-misc"> </a> Miscellaneous </h3>
 447
 448 <ul>
 449 <li> createthreads
 450      - Test in development </li>
 451 <li> file
 452      - Runs in the same way as the
 453        <a href="#eg-multimedia">multimedia examples</a> </li>
 454 <li> imc_shm_mmap
 455      - Test in development</li>
 456 <li> nrd_xfer
 457      - Test in development </li>
 458 <li> null
 459      - Test in development </li>
 460 <li> eviltests
 461      - Would-be malicious code that should be rejected by
 462        the Native Client validator. Not a part of the standard build. </li>
 463 </ul>
 464
 465 <h2> <a name="build-run"> </a> How to build and run tests </h2>
 466
 467 <p>
 468 The examples and tests in the Native Client distribution are,
 469 with the exception of
 470 <a href="#eg-quake">Quake, XaoS, and Lua</a>,
 471 already built,
 472 so you can easily run them.
 473 You can also build them, if you like.
 474 The following tools let you build and run examples:
 475 </p>
 476
 477 <ul>
 478 <li> <a href="#run-py">Python files such as run.py</a>
 479 - Provided by some examples as an easy way to
 480   run the example.</li>
 481 <li> <a href="#run-make">GNU make</a>
 482 - Supported by some examples,
 483   giving you an easy way to
 484   rebuild and run the example.</li>
 485 <li> <a href="#run-scons">SCons</a>
 486 - The main build tool.
 487   You can build all of the examples and tests at once, as described in
 488   <a href="building.html">Building Native Client</a>.</li>
 489 </ul>
 490
 491 <h3> <a name="run-py"> </a> Running with run.py </h3>
 492
 493 <p>
 494 If an example has a <code>run.py</code> file,
 495 you can run the already built example like this:
 496 </p>
 497
 498 <pre class="platform-all">
 499 $ <b>python run.py</b>
 500 </pre>
 501
 502 <p>
 503 The Python script <code>run.py</code>
 504 executes binaries that are in the
 505 <code>scons-out/nacl/staging</code> directory.
 506 The binaries under <code>scons-out</code> are prebuilt for you,
 507 but you can always rebuild using SCons,
 508 as described in <a href="building.html">Building Native Client</a>.
 509 </p>
 510
 511 <h3> <a name="run-make"> </a> Building and running with GNU make </h3>
 512
 513 <p>
 514 When building with <code>make</code>,
 515 the executable is placed directly in the same folder
 516 as the source for the example.
 517 Examples that have makefiles can be built either
 518 as standalone traditional executables
 519 or as portable Native Client <code>.nexe</code> files
 520 that execute as applications.
 521 The standalone versions are normal executables
 522 that can be debugged with GDB or a visual front end to GDB such as KDbg.
 523 Currently, using <code>make</code> is supported only on Linux and Mac;
 524 in some cases it may work under Cygwin on Windows.
 525 </p>
 526
 527 <p>
 528 You can use the following <code>make</code> commands in
 529 any of the following directories:
 530 </p>
 531
 532 <pre>
 533 earth   file   life   mmap   syscalls   tone   voronoi
 534 </pre>
 535
 536 <p>
 537 First, start by going to the directory of the example. Example:
 538
 539 <pre class="platform-linux-mac">
 540 <b>cd </b><em>install_dir</em><b>/nacl/googleclient/native_client/tests/earth</b>
 541 </pre>
 542
 543 <p>
 544 To build a <b>standalone application</b>, suitable for debugging with GDB:
 545 </p>
 546
 547 <pre class="platform-linux-mac">
 548 <b>make debug run</b>
 549 </pre>
 550
 551 <p>
 552 To build and run as a <b>Native Client application</b>:<br />
 553 </p>
 554
 555 <pre class="platform-linux-mac">
 556 <b>make release nacl run</b>
 557 </pre>
 558
 559 <p>
 560 To <b>clean</b>:
 561 </p>
 562
 563 <pre class="platform-linux-mac">
 564 <b>make clean</b>
 565 </pre>
 566
 567 <p>
 568 For more options, see <code>common/Makefile.mk</code>.
 569 </p>
 570
 571 <h3> <a name="run-scons"> </a> Building and running with SCons </h3>
 572
 573 <p>
 574 <a href="building.html">Building Native Client</a>
 575 shows how to build everything with SCons,
 576 including the examples and tests.
 577 You can also run the smoke test suite using SCons.
 578 </p>
 579
 580
 581 <h4> <a name="run-smoke"> </a> Running the smoke test suite </h4>
 582
 583 <p>
 584 For information about this test suite, see the
 585 <a href="#eg-smoke">smoke test suite</a> section.
 586 Here's how you run it.
 587 </p>
 588
 589 <p>
 590 Linux or Mac:
 591 </p>
 592
 593 <pre class="platform-linux-mac">
 594 <b>cd </b><em>install_dir</em><b>/nacl/googleclient/native_client</b>
 595 <b>./scons --mode=nacl smoke_test</b>
 596 </pre>
 597
 598 <p>
 599 Windows:
 600 </p>
 601
 602 <pre class="platform-windows">
 603 <b>cd </b><em>install_dir</em><b>\nacl\googleclient\native_client</b>
 604 <b>scons.bat --mode=nacl smoke_test</b>
 605 </pre>
 606
 607 <p>
 608 The output of the smoke test suite
 609 appears in the
 610 <code>scons-out/nacl/obj/tests/results</code>
 611 directory.
 612 </p>
 613
 614 <p id="license">
 615 Except as otherwise
 616 <a href="http://code.google.com/policies.html#restrictions">noted</a>,
 617 the content of this page is licensed under a
 618 <a href="http://www.google.com/url?sa=D&amp;q=http%3A%2F%2Fcreativecommons.org/licenses/by/2.5/">Creative Commons
 619 Attribution 2.5 license</a>.
 620 </p>
 621
 622 </body>
 623 </html>