C++ Tutorial: Getting Started (Part 1)

Overview

This tutorial shows how to build and run a web application using Portable Native Client (PNaCl). This is a client-side application that uses HTML, JavaScript and a Native Client module written in C++. The PNaCl toolchain is used to enable running the Native Client module directly from a web page.

It’s recommended to read the Native Client Technical Overview prior to going through this tutorial.

Step 1: Download and install the Native Client SDK

Follow the instructions on the Download page to download and install the Native Client SDK.

Step 2: Start a local server

To simulate a production environment, the SDK provides a simple web server that can be used to serve the application on localhost. A convenience Makefile rule called serve is the easiest way to invoke it:

$ cd pepper_$(VERSION)/getting_started
$ make serve

If no port number is specified, the server defaults to port 5103, and can be accessed at http://localhost:5103.

Any server can be used for the purpose of development. The one provided with the SDK is just a convenience, not a requirement.

Step 3: Set up the Chrome browser

PNaCl is enabled by default in Chrome version 31 and later. Please make sure that you have a suitable version to work through this tutorial. It’s also important to use a Chrome version that’s the same or newer than the SDK bundle used to build the Native Client modules.

For a better development experience, it’s also recommended to disable the Chrome cache. Chrome caches resources aggressively; disabling the cache helps make sure that the latest version of the Native Client module is loaded during development.

• Open Chrome’s developer tools by clicking the menu icon and choosing Tools > Developer tools.
• Click the gear icon in the bottom right corner of the Chrome window.
• Under the “General” settings, check the box next to “Disable cache (while DevTools is open)”.
• Keep the Developer Tools pane open while developing Native Client applications.

Step 4: Stub code for the tutorial

The stub code for the tutorial is avalable in the SDK, in pepper_$(VERSION)/getting_started/part1. It contains the following files:

• index.html: Contains the HTML layout of the page as well as the JavaScript code that interacts with the Native Client module.

  The Native Client module is included in the page with an <embed> tag that points to a manifest file.

• hello_tutorial.nmf: A manifest file that’s used to point the HTML to the Native Client module and optionally provide additional commands to the PNaCl translator that is part of the Chrome browser.
• hello_tutorial.cc: C++ code for a simple Native Client module.
• Makefile: Compilation commands to build the pexe (portable executable) from the C++ code in hello_tutorial.cc.

It’s a good idea to take a look at these files now—they contain a large amount of comments that help explain their structure and contents. For more details on the structure of a typical Native Client application, see Application Structure.

The stub code is intentionally very minimal. The C++ code does not do anything except correctly initialize itself. The JavaScript code waits for the Native Client module to load and changes the status text on the web page accordingly.

Step 5: Compile the Native Client module and run the stub application

To compile the Native Client module, run make:

$ cd pepper_$(VERSION)/getting_started/part1
$ make

Since the sample is located within the SDK tree, the Makefile knows how to find the PNaCl toolchain automatically and use it to build the module. If you’re building applications outside the NaCl SDK tree, you should set the $NACL_SDK_ROOT environment variable. See Building Native Client Modules for more details.

Assuming the local server was started according to the instructions in Step 2, you can now load the sample by pointing Chrome to http://localhost:5103/part1. Chrome should load the Native Client module successfully and the Status text should change from “LOADING...” to “SUCCESS”. If you run into problems, check out the Troubleshooting section below.

Step 6: Modify the JavaScript code to send a message to the Native Client module

In this step, you’ll modify the web page (index.html) to send a message to the Native Client module after the page loads the module.

Look for the JavaScript function moduleDidLoad(), and add new code to send a ‘hello’ message to the module. The new function should look as follows:

function moduleDidLoad() {
  HelloTutorialModule = document.getElementById('hello_tutorial');
  updateStatus('SUCCESS');
  // Send a message to the Native Client module
  HelloTutorialModule.postMessage('hello');
}

Step 7: Implement a message handler in the Native Client module

In this step, you’ll modify the Native Client module (hello_tutorial.cc) to respond to the message received from the JavaScript code in the application. Specifically, you’ll:

• Implement the HandleMessage() member function of the module instance.
• Use the PostMessage() member function to send a message from the module to the JavaScript code.

First, add code to define the variables used by the Native Client module (the ‘hello’ string you’re expecting to receive from JavaScript and the reply string you want to return to JavaScript as a response). In the file hello_tutorial.cc, add this code after the #include statements:

namespace {
// The expected string sent by the browser.
const char* const kHelloString = "hello";
// The string sent back to the browser upon receipt of a message
// containing "hello".
const char* const kReplyString = "hello from NaCl";
} // namespace

Now, implement the HandleMessage() member function to check for kHelloString and return kReplyString. Look for the following line:

// TODO(sdk_user): 1. Make this function handle the incoming message.

Populate the member function with code, as follows:

virtual void HandleMessage(const pp::Var& var_message) {
  if (!var_message.is_string())
    return;
  std::string message = var_message.AsString();
  pp::Var var_reply;
  if (message == kHelloString) {
    var_reply = pp::Var(kReplyString);
    PostMessage(var_reply);
  }
}

See the Pepper API documentation for additional information about the pp::Instance.HandleMessage and pp::Instance.PostMessage member functions.

Step 8: Compile the Native Client module and run the application again

Compile the Native Client module by running the make command again.

Re-run the application by reloading http://localhost:5103/part1 in Chrome.

After Chrome loads the Native Client module, you should see an alert panel appear with the message sent from the module.

Troubleshooting

If your application doesn’t run, see Step 3 above to verify that you’ve set up your environment correctly, including both the Chrome browser and the local server. Make sure that you’re running a correct version of Chrome, which is also greater or equal than the SDK bundle version you are using.

Another useful debugging aid is the Chrome JavaScript console (available via the Tools menu in Chrome). Examine it for clues about what went wrong. For example, if there’s a message saying “NaCl module crashed”, there is a possibility that the Native Client module has a bug; debugging may be required.

There’s more information about troubleshooting in the documentation:

• FAQ Troubleshooting.
• The Progress Events document contains some useful information about handling error events.

Next steps

• See the Application Structure chapter in the Developer’s Guide for information about how to structure a Native Client module.
• Check the C++ Reference for details about how to use the Pepper APIs.
• Browse through the source code of the SDK examples (in the examples directory) to learn additional techniques for writing Native Client applications and using the Pepper APIs.
• See the Building, Running, and Debugging pages for information about how to build, run, and debug Native Client applications.
• Check the naclports project to see what libraries have been ported for use with Native Client. If you port an open-source library for your own use, we recommend adding it to naclports (see How to check code into naclports).