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">
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>
12 <a href=
"../README.html">Back to README
</a>
15 <h1>Examples and Tests
</h1>
18 This page describes the Native Client example and test programs.
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>.
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:
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>
43 <li> <a href=
"#eg-hello">Hello world examples
</a></li>
44 <li> <a href=
"#eg-multimedia">Multimedia examples
</a></li>
45 <li> <a href=
"#eg-browser">Browser plug-in examples and tests
</a>
47 <li> <a href=
"#eg-browser-egs">Examples
</a></li>
48 <li> <a href=
"#eg-browser-ftests">Functionality tests
</a></li>
49 <li> <a href=
"#eg-browser-ptests">Performance tests
</a></li>
50 <li> <a href=
"#eg-browser-regression">Regression tests
</a></li>
52 <li> <a href=
"#eg-other">Other examples and tests
</a>
54 <li> <a href=
"#eg-smoke">Smoke test suite
</a></li>
55 <li> <a href=
"#eg-quake">Quake, XaoS, Lua, and AWK
</a></li>
56 <li> <a href=
"#eg-misc">Miscellaneous
</a></li>
58 <li><a href=
"#build-run">How to build and run tests
</a>
60 <li> <a href=
"#run-py">Running with run.py
</a> </li>
61 <li> <a href=
"#run-make">Building and running with GNU make
</a> </li>
62 <li> <a href=
"#run-scons">Building and running with SCons
</a>
64 <li> <a href=
"#run-smoke">Running the smoke test suite
</a> </li>
69 <h2> <a name=
"list"> </a> List of examples and tests
</h2>
72 The Native Client examples and tests fall into the following rough categories:
75 <li> <a href=
"#eg-hello">Hello world examples
</a></li>
76 <li> <a href=
"#eg-multimedia">Multimedia examples
</a></li>
77 <li> <a href=
"#eg-browser">Browser plug-in examples and tests
</a></li>
78 <li> <a href=
"#eg-other">Other examples and tests
</a></li>
81 <h2> <a name=
"eg-hello"> </a> Hello world examples
</h2>
84 Two hello world examples show how to create a simple Native Client module
85 that runs in the browser.
86 A third is an app that's part of the smoke test suite.
89 <table summary=
"hello world examples">
91 <th>Example
</th> <th>Description
</th> <th>How to run
</th> <th>Source code
</th>
95 <td> NPAPI hello world
</td>
96 <td> Shows how to pass an integer and a string
97 between a Native Client module and the browser,
100 <td> See
<a href=
"#eg-browser">Browser plug-in examples and tests
</a> </td>
102 <a href=
"../tests/npapi_hw/">tests/npapi_hw/
</a>
107 <td> SRPC hello world
</td>
108 <td> Shows how to pass an integer and a string
109 between a Native Client module and the browser,
110 using the Native Client Simple RPC API.
112 <td> See
<a href=
"#eg-browser">Browser plug-in examples and tests
</a> </td>
113 <td> <a href=
"../tests/srpc_hw/">tests/srpc_hw/
</a> </td>
117 <td> Command-line hello world
</td>
118 <td> A C program that works equally well as a standalone app or
120 Does
<em>not
</em> execute in the browser.
122 <td> See
<a href=
"#run-smoke">Running the smoke test suite
</a> </td>
123 <td> <a href=
"../tests/hello_world/">tests/hello_world/
</a> </td>
128 <h2> <a name=
"eg-multimedia"> </a> Multimedia examples
</h2>
131 The following four demos
132 can run either as Native Client applications
133 or (on Linux and Mac) as standalone applications.
134 The Earth, Life, and Voronoi examples
135 can also run in the browser.
136 For directions on building and running these examples,
137 see
<a href=
"getting_started.html">Getting Started
</a>,
138 <a href=
"#eg-browser-egs">Examples
</a> (in this page),
139 <a href=
"#run-py">Running with run.py
</a> (in this page), and
140 <a href=
"#run-make">Building and running with GNU make
</a> (also in this page).
144 These examples share an architecture defined in
145 <code>nacl/googleclient/native_client/common
</code>.
148 <table summary=
"multimedia examples">
150 <th>Example
</th> <th>Description
</th> <th>Source code
</th>
155 <td> Rotating, ray-traced globe
</td>
156 <td> <a href=
"../tests/earth/">tests/earth/
</a> </td>
161 <td> Cellular automaton; accepts mouse input
</td>
162 <td> <a href=
"../tests/life/">tests/life/
</a> </td>
167 <td> No visible UI; creates and plays a sound
</td>
168 <td> <a href=
"../tests/tone/">tests/tone/
</a> </td>
173 <td> Animated Voronoi diagram
</td>
174 <td> <a href=
"../tests/voronoi/">tests/voronoi/
</a> </td>
180 the browser plug-in examples and tests
181 listed in the following section, as well as
182 <a href=
"#eg-quake">Quake, XaoS, Lua, and AWK
</a>.
186 <h2> <a name=
"eg-browser"> </a> Browser plug-in examples and tests
</h2>
189 These examples and tests require the Native Client plug-in.
190 You can find instructions for installing the plug-in,
191 starting a local HTTP server,
192 and finding the browser test page
193 in
<a href=
"getting_started.html">Getting Started
</a>.
194 Once you're at the browser test page,
196 for the example or test you want to run.
201 The URL for the browser test page recently changed from
202 <code>index.html
</code> to
203 <code><a href=
"http://localhost:5103/scons-out/nacl/staging/examples.html">examples.html
</a></code>.
204 For that link to work,
205 you must be running a
206 <a href=
"getting_started.html#httpd">local HTTP server
</a>.
210 The browser test page has links to HTML pages
211 that let you run four kinds of tests:
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 <li> <a href=
"#eg-browser-regression">Regression tests
</a></li>
222 For more examples to run in the browser,
224 <a href=
"#eg-quake">Quake, XaoS, Lua, and AWK
</a>.
227 <a name=
"eg-browser-egs"> </a> <h3>Examples
</h3>
229 <table summary=
"examples that run in the browser">
231 <th>Example
</th> <th>Description
</th> <th>Source code
</th>
235 <td> NPAPI hello world example
</td>
236 <td> See
<a href=
"#eg-hello">Hello world examples
</a> </td>
237 <td> <a href=
"../tests/npapi_hw/">tests/npapi_hw/
</a> </td>
241 <td> SRPC hello world example
</td>
242 <td> See
<a href=
"#eg-hello">Hello world examples
</a> </td>
243 <td> <a href=
"../tests/srpc_hw/">tests/srpc_hw/
</a> </td>
247 <td> CloudFS - URLs via file descriptors
</td>
248 <td> A simple demo of how to fetch URLs using NPAPI
249 and then manipulate them like files.
250 Uses
<code>NaClNPN_OpenURL()
</code>.
</td>
251 <td> <a href=
"../tests/cloudfs/">tests/cloudfs/
</a> </td>
255 <td> NPAPI Monte Carlo estimate for pi
</td>
256 <td> Demonstrates using NPAPI for simple graphics and DOM updates.
</td>
257 <td> <a href=
"../tests/npapi_pi/">tests/npapi_pi/
</a> </td>
261 <td> Spinning earth
</td>
262 <td> See
<a href=
"#eg-multimedia">Multimedia examples
</a> </td>
263 <td> <a href=
"../tests/earth/">tests/earth/
</a> </td>
267 <td> Interactive Life simulation
</td>
268 <td> See
<a href=
"#eg-multimedia">Multimedia examples
</a> </td>
269 <td> <a href=
"../tests/life/">tests/life/
</a> </td>
273 <td> Animated Voronoi diagram
</td>
274 <td> See
<a href=
"#eg-multimedia">Multimedia examples
</a> </td>
275 <td> <a href=
"../tests/voronoi/">tests/voronoi/
</a> </td>
279 <td> Three demos on one page
</td>
280 <td> Life, Voronoi, and Earth execute simultaneously within a single HTML page
</td>
281 <td> <a href=
"../tests/many/">tests/many/
</a> </td>
285 <td> Nine demos on one page
</td>
286 <td> Three instances each of Life, Voronoi, and Earth execute simultaneously within a single HTML page
</td>
287 <td> <a href=
"../tests/many/">tests/many/
</a> </td>
291 <td id=
"eg-mandelbrot-viewer"> Mandelbrot viewer
</td>
292 <td> Home-grown Mandelbrot viewer,
293 demonstrating SRPC and simple user-interface integration.
295 <a href=
"#eg-quake">XaoS
</a> and the
296 <a href=
"#eg-mandelbrot-perf">Mandelbrot performance test
</a>.
</td>
297 <td> <a href=
"../tests/mandel_nav/">tests/mandel_nav/
</a> </td>
302 <h3> <a name=
"eg-browser-ftests"> </a> Functionality tests
</h3>
304 <table summary=
"functionality tests that run in the browser">
306 <th>Example
</th> <th>Description
</th> <th>Source code
</th>
310 <td> NPAPI bridge test
</td>
311 <td> Manual smoke tests for a variety of NPAPI interfaces.
</td>
312 <td> <a href=
"../tests/npapi_bridge/">tests/npapi_bridge/
</a> </td>
316 <td> NPAPI bridge drawing test
</td>
317 <td> Simple graphics interface test.
</td>
318 <td> <a href=
"../tests/npapi_bridge/">tests/npapi_bridge/
</a> </td>
322 <td> SRPC plugin properties test
</td>
323 <td> Test the properties of a plugin instance.
</td>
324 <td> <a href=
"../tests/srpc/">tests/srpc/
</a> </td>
328 <td> SRPC shared memory API test
</td>
329 <td> Test the creation and use of shared memory objects.
</td>
330 <td> <a href=
"../tests/srpc/">tests/srpc/
</a> </td>
334 <td> Simple RPC resource descriptor transfer test
</td>
335 <td> Unit tests for transferring Native Client resource descriptors
336 between the browser and a Native Client module.
</td>
337 <td> <a href=
"../tests/srpc/">tests/srpc/
</a> </td>
341 <td> URL content as NaCl resource descriptor test
</td>
342 <td> Tests the Native Client implementation of its
343 <a href=
"http://wikipedia.org/wiki/Same_origin_policy">same-origin policy
</a>
344 for URL references from Native Client modules.
</td>
345 <td> <a href=
"../tests/srpc/">tests/srpc/
</a> </td>
350 <h3> <a name=
"eg-browser-ptests"> </a> Performance tests
</h3>
352 <table summary=
"performance tests that run in the browser">
354 <th>Example
</th> <th>Description
</th> <th>Source code
</th>
358 <td id=
"eg-mandelbrot-perf"> Mandelbrot performance (tiled Native Client)
</td>
359 <td> Compares the performance of JavaScript and C++
360 Mandelbrot implementations.
362 <a href=
"#eg-quake">XaoS
</a> and the
363 <a href=
"#eg-mandelbrot-viewer">Mandelbrot viewer example
</a>.
365 <b>Warning:
</b> The JavaScript implementation is very slow!
367 <td> <a href=
"../tests/mandel/">tests/mandel/
</a> </td>
371 <td> Simple RPC performance
</td>
372 <td> Performance test for our IMC-based simple RPC implementation.
</td>
373 <td> <a href=
"../tests/srpc/">tests/srpc/
</a> </td>
377 <td> NPAPI bridge RPC performance
</td>
378 <td> Performance test for our IMC-based NPAPI implementation.
</td>
379 <td> <a href=
"../tests/npapi_bridge/">tests/npapi_bridge/
</a> </td>
383 <td> Automatic page reloading
</td>
384 <td> Tests the performance of repeatedly loading a specified page.
</td>
385 <td> <a href=
"../tests/autoloader/">tests/autoloader/
</a> </td>
390 <h3> <a name=
"eg-browser-regression"> </a> Regression tests
</h3>
393 This column points to regression tests
394 for issues that we've fixed.
395 Currently it points to a page with tests
396 for security contest issues.
397 The source code for these tests is in
398 <a href=
"../tests/contest_issues/">tests/contest_issues/
</a>.
402 <h2> <a name=
"eg-other"> </a> Other examples and tests
</h2>
405 <h3> <a name=
"eg-smoke"> </a> Smoke test suite
</h3>
408 The smoke test suite contains a variety of tests
409 that you can run as group with a single command,
411 <a href=
"#run-smoke">Running the smoke test suite
</a>.
416 <li> fib/fib_array
</li>
417 <li> fib/fib_scalar
</li>
418 <li> hello_world
</li>
427 <h3> <a name=
"eg-quake"> </a> Quake, XaoS, Lua, and AWK
</h3>
431 <a href=
"../tests/quake/"><code>tests/quake/
</code></a>,
432 <a href=
"../tests/xaos/"><code>tests/xaos/
</code></a>,
433 <a href=
"../tests/lua/"><code>tests/lua/
</code></a>, and
434 <a href=
"../tests/awk/"><code>tests/awk/
</code></a>
435 directories have files you can use
436 to build Quake, XaoS, Lua, and AWK for Native Client.
437 With the exception of AWK,
438 you can run the resulting modules in the browser.
443 These examples are not prebuilt.
447 Quake is a classic, popular
3D game developed
448 and generously open sourced by id Software.
449 The open-source version of Quake is no longer
450 officially supported by id Software.
451 For more information about Quake, see
452 <a href=
"http://en.wikipedia.org/wiki/Quake">http:/en.wikipedia.org/wiki/Quake
</a>.
453 For information on building Quake for Native Client, see the
454 <code>README.nacl
</code> file in the
455 <code>tests/quake
</code> directory.
459 XaoS is an interactive fractal viewer
460 that lets you continuously zoom in or out of a
461 Mandelbrot pattern or other fractal image.
462 For information about XaoS, see
463 <a href=
"http://en.wikipedia.org/wiki/XaoS">http:/en.wikipedia.org/wiki/XaoS
</a>.
464 For information on building XaoS for Native Client, see the
465 <code>README.nacl
</code> file in the
466 <code>tests/xaos
</code> directory.
470 Lua is a scripting language
471 designed to be powerful, fast, lightweight, embeddable, and extensible.
472 For information about Lua, see
473 <a href=
"http://www.lua.org/">http://www.lua.org
</a>.
474 For information on building Lua for Native Client, see the
475 <code>README.nacl
</code> file in the
476 <code>tests/lua
</code> directory.
480 AWK is a programming language
481 designed for processing text-based data.
482 For information about AWK, see
483 <a href=
"http://en.wikipedia.org/wiki/AWK">http:/en.wikipedia.org/wiki/AWK
</a>.
484 For information on building AWK for Native Client, see the
485 <code>README.nacl
</code> file in the
486 <code>tests/awk
</code> directory.
489 <h3> <a name=
"eg-misc"> </a> Miscellaneous
</h3>
493 - Test in development
</li>
495 - Runs in the same way as the
496 <a href=
"#eg-multimedia">multimedia examples
</a> </li>
498 - Test in development
</li>
500 - Test in development
</li>
502 - Test in development
</li>
504 - Would-be malicious code that should be rejected by
505 the Native Client validator. Not a part of the standard build.
</li>
508 <h2> <a name=
"build-run"> </a> How to build and run tests
</h2>
511 The examples and tests in the Native Client distribution are,
512 with the exception of
513 <a href=
"#eg-quake">Quake, XaoS, Lua, and AWK
</a>,
515 so you can easily run them.
516 You can also build them, if you like.
517 The following tools let you build and run examples:
521 <li> <a href=
"#run-py">Python files such as run.py
</a>
522 - Provided by some examples as an easy way to
523 run the example.
</li>
524 <li> <a href=
"#run-make">GNU make
</a>
525 - Supported by some examples,
526 giving you an easy way to
527 rebuild and run the example.
</li>
528 <li> <a href=
"#run-scons">SCons
</a>
529 - The main build tool.
530 You can build all of the examples and tests at once, as described in
531 <a href=
"building.html">Building Native Client
</a>.
</li>
534 <h3> <a name=
"run-py"> </a> Running with run.py
</h3>
537 If an example has a
<code>run.py
</code> file,
538 you can run the already built example like this:
541 <pre class=
"platform-all">
542 <kbd>python run.py
</kbd>
546 The Python script
<code>run.py
</code>
547 executes binaries that are in the
548 <code>scons-out/nacl/staging
</code> directory.
549 The binaries under
<code>scons-out
</code> are prebuilt for you,
550 but you can always rebuild using SCons,
551 as described in
<a href=
"building.html">Building Native Client
</a>.
554 <h3> <a name=
"run-make"> </a> Building and running with GNU make
</h3>
557 When building with
<code>make
</code>,
558 the executable is placed directly in the same folder
559 as the source for the example.
560 Examples that have makefiles can be built either
561 as standalone traditional executables
562 or as portable Native Client
<code>.nexe
</code> files
563 that execute as applications.
564 The standalone versions are normal executables
565 that can be debugged with GDB or a visual front end to GDB such as KDbg.
566 Currently, using
<code>make
</code> is supported only on Linux and Mac;
567 in some cases it may work under Cygwin on Windows.
571 You can use the following
<code>make
</code> commands in
572 any of the following directories:
576 earth file life mmap syscalls tone voronoi
580 First, start by going to the directory of the example. Example:
582 <pre class=
"platform-linux-mac">
583 <kbd>cd
<em>install_dir
</em>/nacl/googleclient/native_client/tests/earth
</kbd>
587 To build a
<b>standalone application
</b>, suitable for debugging with GDB:
590 <pre class=
"platform-linux-mac">
591 <kbd>make debug run
</kbd>
595 To build and run as a
<b>Native Client application
</b>:
<br />
598 <pre class=
"platform-linux-mac">
599 <kbd>make release nacl run
</kbd>
606 <pre class=
"platform-linux-mac">
607 <kbd>make clean
</kbd>
611 For more options, see
<code>common/Makefile.mk
</code>.
614 <h3> <a name=
"run-scons"> </a> Building and running with SCons
</h3>
617 <a href=
"building.html">Building Native Client
</a>
618 shows how to build everything with SCons,
619 including the examples and tests.
620 You can also run the smoke test suite using SCons.
624 <h4> <a name=
"run-smoke"> </a> Running the smoke test suite
</h4>
627 For information about this test suite, see the
628 <a href=
"#eg-smoke">smoke test suite
</a> section.
629 Here's how you run it.
636 <pre class=
"platform-linux-mac">
637 <kbd>cd
<em>install_dir
</em>/nacl/googleclient/native_client
</kbd>
638 <kbd>./scons --mode=nacl smoke_test
</kbd>
645 <pre class=
"platform-windows">
646 <kbd>cd
<em>install_dir
</em>\nacl\googleclient\native_client
</kbd>
647 <kbd>scons.bat --mode=nacl smoke_test
</kbd>
651 The output of the smoke test suite
653 <code>scons-out/nacl/obj/tests/results
</code>
659 <a href=
"http://code.google.com/policies.html#restrictions">noted
</a>,
660 the content of this page is licensed under a
661 <a href=
"http://creativecommons.org/licenses/by/2.5/">Creative Commons
662 Attribution
2.5 license
</a>.