{{+bindTo:partials.standard_nacl_article}}

Building a NaCl App

In the browser!

Follow along with Brad Nelson’s Google I/O 2014 talk. Explore our new in-browser development environment and debugger.

Learn how easy it is to edit, build, and debug NaCl application all in your desktop web browser or on a Chromebook. Work either on-line or off-line!

Work in Progress

These development tools are a work in progress, see Feature Status. At this point, they are a learning tool and demonstration of NaCl’s flexibility, but are not the recommended tools for a production application. To develop a substantial application for Native Client / Portable Native Client, we currently recommend you use the Native Client SDK.

NOTE: The NaCl Development Environment is not yet stable. Ideally user data is preserved, but currently it can be lost during updates or sporadically. We're working to resolve this.

Installation

The setup process currently requires several steps. We’re working to reduce the number of steps in future releases. As the process gets easier, we’ll update this page.

To install the development environment:

  • Install the NaCl Development Environment.

  • Navigate to: chrome://flags and:

    • Enable Native Client.
    • Restart your browser by clicking Relaunch Now.
  • First run is slow (as it downloads and installs packages). Launch and allow initial install to complete before first use.

When initially experimenting with the development environment, at this time, we recommend you run it without the debugger activated. Once you’re ready to apply the debugger, follow these steps:

Editor

To follow along in this tutorial, you’ll need to use a text editor to modify various files in our development environment. There are currently two editor options, nano or vim. Emacs is coming soon... If you’re unsure what to pick, nano is simpler to start with and has on-screen help.

  • You can open nano like this:

    $ nano <filename>

    Here’s an online nano tutorial.

  • You can open vim like this:

    $ vim <filename>

    Here’s an online vim tutorial.

Git Setup

This tutorial also uses a revision control program called git. In order to commit to a git repository, you need to setup your environment to with your identity.

You’ll need to add these lines to ~/.bashrc to cause them to be invoked each time you start the development environment.

git config --global user.name "John Doe"
git config --global user.email johndoe@example.com

You can reload you ~/.bashrc by running:

source ~/.bashrc

Tour (follow the video)

Create a working directory and go into it:

$ mkdir work
$ cd work

Download a zip file containing our sample:

$ curl http://nacltools.storage.googleapis.com/io2014/voronoi.zip -O
$ ls -l

Unzip the sample:

$ unzip voronoi.zip

Go into the sample and take a look at the files inside:

$ cd voronoi
$ ls

Our project combines voronoi.cc with several C++ libraries to produce a NEXE (or Native Client Executable).

/native-client/images/voronoi1.png

The resulting application combines the NEXE with some Javascript to load the NaCl module, producing the complete application.

/native-client/images/voronoi2.png

Let’s use git (a revision control program) to track our changes.

First, create a new repository:

$ git init

Add everything here:

$ git add .

Then commit our starting state:

$ git commit -m "imported voronoi demo"

Now, likes run make to compile our program (NOTE: Changed since video, we’ve got Makefiles!):

$ make

Oops, we get this error:

voronoi.cc: In member function 'void Voronoi::Update()':
voronoi.cc:506: error: 'struct PSContext2D_t' has no member named 'hieght'

We’ll need to start an editor to fix this. You’ll want to change hieght to height on line 506. Then rebuild:

$ make -j10

Lets look at the diff:

$ git diff

And commit our fix:

$ git commit -am "fixed build error"

To test our application, we run a local web server, written in python. Run the server with this command (NOTE: Running through a Makefile now):

$ make serve

Then, navigate to http://localhost:5103/ to test the demo.

If you follow along with the demo video, you will discover the sample crashes when you change the thread count.

Debugging

If you haven’t installed the debugger at this point, skip to the next section.

At this point, if you have the debugger installed, you should be able to open the developer console and view the resulting crash.

You can see a backtrace with:

bt

You can see active threads with:

info threads

Currently, symbol information is limited for GLibC executables. We have improvements coming that will improve the experience further.

For newlib and PNaCl executables you can retrieve full symbols information with:

remote get irt irt
add-symbol-file irt
remote get nexe nexe
add-symbol-file nexe

Fix it up

Return to the development environment and stop the test server, by pressing Ctrl-C.

Open your editor again, navigate to line 485 and change valu to value.

Then rebuild:

$ make -j10

Check the diff and commit our fix:

$ git diff
$ git commit -am "fixed thread ui bug"

Now look at your commit history:

$ git log

Run the demo again. And everything now works:

$ make serve

Thanks

Thanks for checking out our environment. Things are rapidly changing and in the coming months you can expect to see further improvements and filling out of our platform and library support.

Check back at this page for the latest status.

Feature Status

Here is a summary of feature status. We hope to overcome these limitations in the near future:

  • NaCl Development Environment

    • General

      • Supported:

        • Python (built-in)
        • GCC w/ GLibC (x86-32 and x86-64 only)
        • Lua (install with: package -i lua && . setup-environment)
        • Ruby (install with: package -i ruby && . setup-environment)
        • Nethack! (install with: package -i nethack && . setup-environment)

      • Unsupported:

        • Targeting Newlib
        • Targeting PNaCl
        • Forking in bash
        • Pipes / Redirection
        • Symbolic and hard links

    • Missing / broken on ARM:

      • Git (broken)
      • GCC (unsupported)

  • Debugger

    • Runs reliably only on a recent Beta or Dev Channel (M36+) build.

    • Currently unreliable on some platforms:

      • ChromeOS
      • Mac OSX
      • Windows
{{/partials.standard_nacl_article}}