{{+bindTo:partials.standard_nacl_article}}
NOTE:
Deprecation of the technologies described here has been announced
for platforms other than ChromeOS.
Please visit our
migration guide
for details.
This document describes how to run Native Client applications during development.
The workflow for PNaCl applications is straightfoward and will only be discussed briefly. For NaCl applications distributed through the web-store, there is a number of options and these will be discussed more in-depth.
Running PNaCl applications from the open web is enabled in Chrome version 31 and above; therefore, no special provisions are required to run and test such applications locally. An application that uses a PNaCl module can be tested similarly to any other web application that only consists of HTML, CSS and JavaScript.
To better simulate a production environment, it’s recommended to start a local web server to serve the application’s files. The NaCl SDK comes with a simple local server built in, and the process of using it to run PNaCl applications is described in the tutorial.
Before reading about how to run Native Client applications, it’s important to understand a little bit about how Native Client applications are distributed. As explained in Distributing Your Application, Native Client applications must currently be distributed through the Chrome Web Store (CWS). Applications in the CWS are one of three types:
The web store documentation contains a handy guide to help you choose which to use.
It’s clearly not convenient to package and upload files to the Chrome Web Store every time you want to run a new build of your application, but there are four alternative techniques you can use to run the application during development. These techniques are listed in the following table and described in detail below. Each technique has certain requirements (NaCl flag, web server, and/or CWS metadata); these are explained in the Requirements section below.
Technique | Requires Web Server | Requires CWS Metadata | |
---|---|---|---|
1. Local server
|
![]() |
||
2. Packaged application loaded as an unpacked extension
|
![]() |
||
3. Hosted application loaded as an unpacked extension
|
![]() |
![]() |
|
4. CWS application with untrusted testers
|
![]() |
Which of the above techniques you use to run your application during development is largely a matter of personal preference (i.e., would you rather start a local server or create CWS metadata?). As a general rule, once you have an idea of how you plan to distribute your application, you should use the corresponding technique during development. Choosing a distribution option depends on a number of factors such as application size, application start-up time, hosting costs, offline functionality, etc. (see Distributing Your Application for details), but you don’t need to make a decision about how to distribute your application at the outset.
The next two sections of this document describe a couple of prerequisites for running applications during development, and explain the three requirements listed in the table above (NaCl flag, web server, and CWS metadata). The subsequent sections of the document provide instructions for how to use each of the four techniques.
Before you run a new build of your application, make sure that you’re using the
correct version of Chrome. Each version of Chrome supports a corresponding
version of the Pepper API. You (and your users) must use a version of Chrome
that is equal to or higher than the version of the Pepper API that your
application uses. For example, if you compiled your application using the
pepper_37
bundle, your application uses the Pepper 37 API, and you must run
the application in Chrome 37 or higher. To check which version of Chrome you’re
using, type about:version
in the Chrome address bar.
Chrome caches resources aggressively. You should disable Chrome’s cache whenever you are developing a Native Client application in order to make sure Chrome loads new versions of your application. Follow the instructions in the tutorial.
Native Client is automatically enabled for applications that are installed from the Chrome Web Store. To enable Native Client for applications that are not installed from the Chrome Web Store, you must explicitly turn on the Native Client flag in Chrome as follows:
about:flags
in the Chrome address bar.If you enable the Native Client flag and still can’t run applications from outside the Chrome Web Store, you may need to enable the Native Client plugin:
about:plugins
in the Chrome address bar.For security reasons, Native Client applications must come from a server (you can’t simply drag HTML files into your browser). The Native Client SDK comes with a lightweight Python web server that you can run to serve your application locally. The server can be invoked from a Makefile. Here is how to run the server:
$ cd examples $ make serve
By default, the server listens for requests on port 5103. You can use the server
to run most applications under the examples
directory where you started the
server. For example, to run the flock
example in the SDK, start the server
and point your browser to http://localhost:5103/demo/flock/
.
Some of the applications need special flags to Chrome, and must be run with the
make run
command. See Run the SDK examples for more details.
Applications published in the Chrome Web Store must be accompanied by CWS
metadata; specifically, a Chrome Web Store manifest file named
manifest.json
, and at least one icon.
Below is an example of a CWS manifest file for a hosted application:
{ "name": "My NaCl App", "description": "Simple game implemented using Native Client", "version": "0.1", "icons": { "128": "icon128.png" }, "app": { "urls": [ "http://mysubdomain.example.com/" ], "launch": { "web_url": "http://mysubdomain.example.com/my_app_main_page.html" } } }
For a packaged application, you can omit the urls field, and replace the
web_url
field with a local_path
field, as shown below:
{ "name": "My NaCl App", "description": "Simple game implemented using Native Client", "version": "0.1", "icons": { "16": "icon16.png", "128": "icon128.png" }, "app": { "launch": { "local_path": "my_app_main_page.html" } } }
You must put the manifest.json
file in the same directory as your
application’s main HTML page.
If you don’t have icons for your application, you can use the following icons as placeholders:
Put the icons in the same directory as the CWS manifest file. For more information about CWS manifest files and application icons, see:
To run your application from a local server:
pepper_35/examples/my_app
).http://localhost:5103/my_app/my_app_main_page.html
.For development purposes, Chrome lets you load a packaged application as an unpacked extension. To load and run your packaged application as an unpacked extension:
local_path
field
rather than the web_url
field.For additional information about how to create CWS metadata and load your application into Chrome (including troubleshooting information), see the Chrome Web Store Tutorial: Getting Started.
See also Run the SDK examples as Chrome apps.
For development purposes, Chrome lets you load a hosted application as an unpacked extension. To load and run your hosted application as an unpacked extension:
examples
directory in the SDK
bundle you are using (e.g., in the directory
pepper_37/examples/my_app
).web_url
field should specify the
location of your application on your server. If you’re using the local
server included with the SDK, the web_url
field should look something
like http://localhost:5103/my_app/my_app_main_page.html
.For additional information about how to create CWS metadata and load your application into Chrome (including troubleshooting information), see the Chrome Web Store Tutorial: Getting Started.
When you’re ready to test your application more broadly, you can upload the application to the Chrome Web Store and let some trusted testers run it. Here is how to do so:
To publish an application to the world after publishing it to test accounts, you must first unpublish the application. For additional information see Publishing Your App, and in particular Publishing to test accounts.