Getting Started

This page tells you how to install Native Client and run demos, both in and outside of the browser. On Linux and Mac OS X, you can also recompile demos and run them as standalone applications.

Note: If you've already installed a previous version of the Native Client plug-in, you don't need to uninstall it. Just get the software and install the plug-in.

Contents

• Get the software
• Run an example as a Native Client app
• Install and use the plug-in
• Use make to compile and run standalone examples (Linux or Mac)
• What next?

Get the software

To run the examples as Native Client modules, you need Native Client, Python, and a browser — we recommend Firefox 3. If you want to develop your own Native Client modules, you'll also need platform-specific development tools such as Xcode on the Mac and Visual Studio on Windows, as described in the make section and the page Building Native Client.

Technical detail: Native Client doesn't itself require Python. We use Python for scripts such as those that build and run examples and that install the Native Client plug-in. We're working on simpler installers that don't require Python.

Here's how to install Native Client and Python.

1. Choose an installation directory (install_dir). Because Native Client is frequently updated, you might want a path that indicates the download or build date. For example:

   • /home/me/NaCl/Testing/2009-02-11    (Linux)
   • /Users/me/NaCl/Testing/2009-02-11   (Mac)
   • C:\NaCl\Testing\2009-02-11          (Windows)

   Important: Make sure the full path of install_dir contains no spaces.

2. Download the Native Client .tgz or .zip file for your platform.

3. Extract the files into install_dir. For example:

   Linux:

   tar xvf nacl_linux*.tgz
   

   Mac:

   tar xvf nacl_mac*.tgz
   

   Windows:

   Do not use Cygwin unzip. Instead, you can use the built-in Windows support or 7-Zip. For example: In the file manager, right-click the nacl_windows_*.zip file and choose Extract All.

4. Test your version of Python.

   python -V  #Note: That's an uppercase 'V'
   

   The output should be something like Python 2.4.3. If your system can't find python or the version isn't 2.4 or 2.5, get the right version of Python and make sure it's in your path. For details, see the Native Client build instructions.

   Windows note: Do not use Cygwin's version of Python. Instead, use the standard Python distribution. For details, see the Windows setup instructions.

Run an example as a Native Client app

Now you'll learn how to run an example app in Native Client.

Technical detail: You might be wondering why we start you off with a command-line application, rather than with the browser. The reason is that when you create your own Native Client modules, it's easier to get started if you're working outside the browser.

1. In a terminal window, go to the earth demo's directory.

   Linux or Mac:

   cd install_dir/nacl/googleclient/native_client/tests/earth
   

   Windows:

   cd install_dir\nacl\googleclient\native_client\tests\earth
   

2. Run the earth demo as a Native Client application. The command is the same on all platforms:

python run.py

A window should appear that contains a spinning, ray-traced globe. The title of the window, NaCl Application, indicates that you're running a Native Client module in a dedicated process.

You can quit the earth demo by clicking the close (X) button in its window frame. Or just wait; it quits automatically after displaying 10000 frames.

Troubleshooting: If no window appears and you get a message starting with ERROR: Cannot find Native Client executable, you've probably downloaded the source-only distribution of Native Client. You can either download the distribution for your platform (Linux, Mac, or Windows) or build Native Client and its SDK.

Install and use the plug-in

Now it's time to run some Native Client modules inside a browser. To do so, you need to install the Native Client plug-in and then load a page that refers to one or more Native Client modules.

1. Go to the native_client directory:

   Linux or Mac:

   cd install_dir/nacl/googleclient/native_client
   

   Windows:

   cd install_dir\nacl\googleclient\native_client
   

2. Bookmark this page, both online and in your Native Client distribution (install_dir/nacl/googleclient/native_client/documentation/getting_started.html). The bookmarks will make it easier for you to get back to these instructions after restarting your browser. Consider printing out this page, as well, or saving these instructions to a text or PDF file.

3. Exit Firefox if you're running it. Also exit any other browsers that might have run a Native Client module. The plug-in might not install correctly if Firefox is running or if any other browser is running a Native Client module.

4. Install the plug-in. Answer y when asked whether you want to continue.

   Linux or Mac:

   ./scons --prebuilt firefox_install
   
   ...
   
   Okay to continue? [y/n] y
   
   ...
   

   Technical detail: The --prebuilt option isn't strictly necessary, but it makes the install go much more quickly. Without it, SCons attempts to rebuild some of the Native Client binaries.

   Linux note: If you're using a 64-bit Linux system, we recommend that you use a 32-bit browser. For instructions, search for [linux 32-bit 64-bit browser]. If you're adventurous and your modules don't use NPAPI, then you might be able to instead use NSPluginWrapper (version 1.1.2 or newer) to make the Native Client plug-in work in a 64-bit browser. Don't use NSPluginWrapper if your modules depend on NPAPI; the performance impact of NSPluginWrapper's NPAPI forwarding can be huge.

   Windows:

   .\scons.bat --prebuilt firefox_install
   
   ...
   
   Okay to continue? [y/n] y
   
   ...
   

   Vista note: If UAC is enabled, you can't use SCons to install the plug-in on Vista. Instead, you need to copy three files into C:\Program Files\Mozilla Firefox\plugins:

   • install_dir\nacl\googleclient\native_client\scons-out\opt-win\staging\npGoogleNaClPlugin.dll
   • install_dir\nacl\googleclient\native_client\scons-out\opt-win\staging\SDL.dll
   • install_dir\nacl\googleclient\native_client\scons-out\opt-win\staging\sel_ldr.exe

5. Look at the installer output to make sure the installation was successful.

6. Launch Firefox and return to this page.

7. Start up a local HTTP server, if one isn't already running on your computer. One way you can do this is by launching tools/httpd.py from the native_client directory.

   Note: Use Python 2.5 (not 2.4) to run httpd.py, if possible. If you use 2.4 and reload a module that has been recompiled, you'll continue to see the old, cached version in your browser. The reason is that while 2.5 provides a Last-Modified header, 2.4 does not. If you must use 2.4, you can reload a changed module by either bypassing your browser's cache (see http://en.wikipedia.org/wiki/Bypass_your_cache) or emptying the cache.

   Linux:

   cd install_dir/nacl/googleclient/native_client
   
   /usr/bin/python2.5 tools/httpd.py
   

   Mac:

   cd install_dir/nacl/googleclient/native_client
   
   python tools/httpd.py
   

   Windows:

   cd install_dir\nacl\googleclient\native_client
   
   python tools\httpd.py
   

   Technical detail: You need a local HTTP server because, for now, Native Client uses a whitelist that ensures that module URLs begin with http://localhost. If you want to use other URLs, you can modify the Native Client whitelist, rebuild Native Client, and install the new build. For details, see the FAQ.

8. In Firefox, visit the browser test page (native_client/scons-out/nacl/staging/index.html), using a URL that begins with http://localhost. If you're using httpd.py, as shown in the previous step, then here's the URL you'll need:

   http://localhost:5103/scons-out/nacl/staging/index.html

9. Click the bottom-left link to go to the Mandelbrot viewer page. This page has a Native Client implementation of a Mandelbrot drawing. You should see something like this:

   

   Figure: The Mandelbrot viewer demo

   Play with the demo. You can click the Cycle Colors button to see an everchanging display of colors. Press and hold the + button to zoom in. Use the arrows on the large round button to change which part of the Mandelbrot you can see.

For information about the other demos you can run in your browser, see Examples and Tests.

Use make to compile and run standalone examples (Linux or Mac)

In this section, you'll use GNU make to compile and run the same example that you've already run. First, you'll make a version that runs as a standalone application. Next, you'll use make to recompile the example and run it again as a Native Client app, using the binaries that you created instead of prebuilt binaries. Finally, you'll use make clean and run the Native Client app again using the prebuilt binaries.

Technical detail: The standard build tool for Native Client is SCons, not make. You can compile our examples (on any platform) using SCons, following the instructions in Building Native Client. The Makefiles exist so that you can more easily use our examples as templates for your own programs, and so you can run our examples as either Native Client or standalone applications (on Linux and Mac). Running a module as a standalone application can be handy when you're debugging.

To perform the steps in this section, your development environment needs to be set up as described in the build instructions for your platform — Setup: Linux or Setup: Mac OS X. Native Client doesn't support make or standalone apps on Windows.

1. In a terminal window, go to the earth demo's directory:

   cd install_dir/nacl/googleclient/native_client/tests/earth
   

2. Recompile the demo as a standalone application and run it.

   make debug run
   

   Just like before, you should see a window with a spinning globe. This time, the title of the window is Standalone Application. You'll also see the g++ command used to compile the demo as an app.

3. Recompile the demo as a Native Client module and run it again:

   make release nacl run
   

   Again you should see a spinning globe with the title NaCl Application. You'll also see the nacl-g++ command that compiles the demo and the sel_ldr command that runs it in the Native Client environment.

4. Remove the binaries you built, and use the prebuilt binaries to run the example again as a Native Client module.

   make clean
   
   python run.py
   

   You can still run the example after running make clean because the Makefile refers to binaries in the current directory. The Python script, on the other hand, refers to binaries that are in the scons-out/nacl/staging directory (which is under nacl/googleclient/native_client). The binaries under scons-out are prebuilt for you, but you can always rebuild using SCons, as described in Building Native Client.

What next?

Please try these:

• Run all the examples and tests.
• Build Native Client from scratch.
• Build Quake and XaoS for Native Client; run them. For instructions, see the README.nacl files under nacl/googleclient/native_client/tests/quake and nacl/googleclient/native_client/tests/xaos.
• Browse the documentation, including the Native Client paper [PDF].
• Browse the project site, http://code.google.com/p/nativeclient, including the wiki.

For even more fun, consider:

• Port existing open-source packages to run as Native Client module components.
• Write new Native Client modules that use Native Client's reduced system call interface, NPAPI, and SRPC to communicate with the browser.
• Defeat the NaCl sandbox. Can you create a NaCl module that creates a file in the local file system or otherwise directly executes a system call? Exploits using sel_ldr from the command line or from the browser plug-in are both of interest. Don't use the -d debug flag — that would be too easy. For more suggestions and details, see the wiki page WhatToTest.

And please participate in the Native Client community:

• Join the discussion group and the announcement group.
• File issues about any Native Client problems you've noticed or features you'd like.

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