Examples and Tests

This page describes the Native Client example and test programs. In general, directory paths in this document are relative to build/native_client. For example, the source files for all the examples and tests are under the tests directory of build/native_client.

If you haven't already run an example or test, go to Getting Started. That page leads you through setting up Native Client. It then shows you to run examples and tests in three modes:

Contents

List of examples and tests

The Native Client examples and tests fall into the following rough categories:

Hello world examples

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.

Example Description How to run Source code
NPAPI hello world Shows how to pass an integer and a string between a Native Client module and the browser, using NPAPI. See Browser plug-in examples and tests tests/npapi_hw/
SRPC hello world Shows how to pass an integer and a string between a Native Client module and the browser, using the Native Client Simple RPC API. See Browser plug-in examples and tests tests/srpc_hw/
Command-line hello world A C program that works equally well as a standalone app or a Native Client app. Does not execute in the browser. See Running the smoke test suite tests/hello_world/

Multimedia examples

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 Getting Started, Examples (in this page), Running with run.py (in this page), and Building and running with GNU make (also in this page).

These examples share an architecture defined in build/native_client/common.

Example Description Source code
Earth Rotating, ray-traced globe tests/earth/
Life Cellular automaton; accepts mouse input tests/life/
Tone No visible UI; creates and plays a sound tests/tone/
Voronoi Animated Voronoi diagram tests/voronoi/

Also see the browser plug-in examples and tests listed in the following section, as well as Quake, XaoS, Lua, and AWK.

Browser plug-in examples and tests

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 Getting Started. Once you're at the browser test page, click the Go button for the example or test you want to run.

Note: The URL for the browser test page recently changed to http://localhost:5103/scons-out/nacl-x86-32/staging/examples.html. For that link to work, you must be running a local HTTP server.

The browser test page has links to HTML pages that let you run four kinds of tests:

For more examples to run in the browser, also see Quake, XaoS, Lua, and AWK.

Examples

Example Description Source code
NPAPI hello world example See Hello world examples tests/npapi_hw/
SRPC hello world example See Hello world examples tests/srpc_hw/
CloudFS - URLs via file descriptors A simple demo of how to fetch URLs using NPAPI and then manipulate them like files. Uses NaClNPN_OpenURL(). tests/cloudfs/
NPAPI Monte Carlo estimate for pi Demonstrates using NPAPI for simple graphics and DOM updates. tests/npapi_pi/
Spinning earth See Multimedia examples tests/earth/
Interactive Life simulation See Multimedia examples tests/life/
Animated Voronoi diagram See Multimedia examples tests/voronoi/
Three demos on one page Life, Voronoi, and Earth execute simultaneously within a single HTML page tests/many/
Nine demos on one page Three instances each of Life, Voronoi, and Earth execute simultaneously within a single HTML page tests/many/
Mandelbrot viewer Home-grown Mandelbrot viewer, demonstrating SRPC and simple user-interface integration. See also XaoS and the Mandelbrot performance test. tests/mandel_nav/

Functionality tests

Example Description Source code
NPAPI bridge test Manual smoke tests for a variety of NPAPI interfaces. tests/npapi_bridge/
NPAPI bridge drawing test Simple graphics interface test. tests/npapi_bridge/
SRPC plugin properties test Test the properties of a plugin instance. tests/srpc/
SRPC shared memory API test Test the creation and use of shared memory objects. tests/srpc/
Simple RPC resource descriptor transfer test Unit tests for transferring Native Client resource descriptors between the browser and a Native Client module. tests/srpc/
URL content as NaCl resource descriptor test Tests the Native Client implementation of its same-origin policy for URL references from Native Client modules. tests/srpc/

Performance tests

Example Description Source code
Mandelbrot performance (tiled Native Client) Compares the performance of JavaScript and C++ Mandelbrot implementations. See also XaoS and the Mandelbrot viewer example.
Warning: The JavaScript implementation is very slow!
tests/mandel/
Simple RPC performance Performance test for our IMC-based simple RPC implementation. tests/srpc/
NPAPI bridge RPC performance Performance test for our IMC-based NPAPI implementation. tests/npapi_bridge/
Automatic page reloading Tests the performance of repeatedly loading a specified page. tests/autoloader/

Regression tests

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 tests/contest_issues/.

Other examples and tests

Smoke test suite

The smoke test suite contains a variety of tests that you can run as group with a single command, as described in Running the smoke test suite.

Quake, XaoS, Lua, and AWK

The tests/quake/, tests/xaos/, tests/lua/, and tests/awk/ directories have files you can use to build Quake, XaoS, Lua, and AWK for Native Client. With the exception of AWK, you can run the resulting modules in the browser.

Note: These examples are not prebuilt.

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 http:/en.wikipedia.org/wiki/Quake. For information on building Quake for Native Client, see the README.nacl file in the tests/quake directory.

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 http:/en.wikipedia.org/wiki/XaoS. For information on building XaoS for Native Client, see the README.nacl file in the tests/xaos directory.

Lua is a scripting language designed to be powerful, fast, lightweight, embeddable, and extensible. For information about Lua, see http://www.lua.org. For information on building Lua for Native Client, see the README.nacl file in the tests/lua directory.

AWK is a programming language designed for processing text-based data. For information about AWK, see http:/en.wikipedia.org/wiki/AWK. For information on building AWK for Native Client, see the README.nacl file in the tests/awk directory.

Miscellaneous

How to build and run tests

The examples and tests in the Native Client distribution are, with the exception of Quake, XaoS, Lua, and AWK, 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:

Running with run.py

If an example has a run.py file, you can run the already built example like this:

python run.py

The Python script run.py executes binaries that are in the scons-out/nacl/staging directory. The binaries under scons-out are prebuilt for you, but you can always rebuild using SCons, as described in Building Native Client.

Building and running with GNU make

When building with make, 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 .nexe 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 make is supported only on Linux and Mac; in some cases it may work under Cygwin on Windows.

You can use the following make commands in any of the following directories:

earth   file   life   mmap   syscalls   tone   voronoi

First, start by going to the directory of the example. Example:

cd install_dir/build/native_client/tests/earth

To build a standalone application, suitable for debugging with GDB:

make debug run

To build and run as a Native Client application:

make release nacl run

To clean:

make clean

For more options, see common/Makefile.mk.

Building and running with SCons

Building Native Client shows how to build everything with SCons, including the examples and tests. You can also run the smoke test suite using SCons.

Running the smoke test suite

For information about this test suite, see the smoke test suite section. Here's how you run it.

Linux or Mac:

cd install_dir/build/native_client
./scons --mode=nacl smoke_test

Windows:

cd install_dir\build\native_client
scons.bat --mode=nacl smoke_test

The output of the smoke test suite appears in the scons-out/nacl/obj/tests/results directory.

Except as otherwise noted, the content of this page is licensed under a Creative Commons Attribution 2.5 license.