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