running.rst revision 0f1bc08d4cfcc34181b0b5cbf065c40f687bf740
1.. _devcycle-running: 2 3####### 4Running 5####### 6 7.. contents:: 8 :local: 9 :backlinks: none 10 :depth: 2 11 12Introduction 13============ 14 15This document describes how to run Native Client applications during 16development. 17 18The workflow for PNaCl applications is straightfoward and will only be discussed 19briefly. For NaCl applications distributed through the web-store, there is a 20number of options and these will be discussed more in-depth. 21 22Portable Native Client (PNaCl) applications 23=========================================== 24 25Running PNaCl applications from the open web is enabled in Chrome version 31 and 26above; therefore, no special provisions are required to run and test such 27applications locally. An application that uses a PNaCl module can be tested 28similarly to any other web application that only consists of HTML, CSS and 29JavaScript. 30 31To better simulate a production environment, it's recommended to start a local 32web server to serve the application's files. The NaCl SDK comes with a simple 33local server built in, and the process of using it to run PNaCl applications is 34described in :ref:`the tutorial <tutorial_step_2>`. 35 36Native Client applications and the Chrome Web Store 37=================================================== 38 39Before reading about how to run Native Client applications, it's important to 40understand a little bit about how Native Client applications are distributed. 41As explained in :doc:`Distributing Your Application <../distributing>`, Native 42Client applications must currently be distributed through the **Chrome Web 43Store (CWS)**. Applications in the CWS are one of three types: 44 45* A **hosted application** is an application that you host on a server of your 46 choice. To distribute an application as a hosted application, you upload 47 application metadata to the CWS. 48 49* A **packaged application** is an application that is hosted in the CWS and 50 downloaded to the user's machine. To distribute an application as a packaged 51 application, you upload the entire application, including all application 52 assets and metadata, to the CWS. 53 54* An **extension** is a packaged application that has a tiny UI component 55 (extensions are typically used to extend the functionality of the Chrome 56 browser). To distribute an application as an extension, you upload the entire 57 application, including all application assets and metadata, to the CWS. 58 59It's clearly not convenient to package and upload files to the Chrome Web Store 60every time you want to run a new build of your application, but there are four 61alternative techniques you can use to run the application during development. 62These techniques are listed in the following table and described in detail 63below. Each technique has certain requirements (NaCl flag, web server, and/or 64CWS metadata); these are explained in the :ref:`Requirements <requirements>` 65section below. 66 67.. list-table:: 68 :header-rows: 1 69 70 * - # 71 - Technique 72 - Requires NaCl flag 73 - Requires Web Server 74 - Requires CWS Metadata 75 - Description 76 * - 1 77 - Local server 78 - |CHK| 79 - |CHK| 80 - 81 - Run a local server and simply point your browser to your application on 82 the server. 83 * - 2 84 - Packaged application loaded as an unpacked extension 85 - 86 - 87 - |CHK| 88 - Load your packaged application into Chrome as an unpacked extension and 89 run it without a server. An unpacked extension is simply an application 90 whose source and metadata files are located in a plain (unzipped) folder 91 on your development machine. The CWS manifest file (explained below) must 92 specify a ``local_path`` field. 93 * - 3 94 - Hosted application loaded as an unpacked extension 95 - 96 - |CHK| 97 - |CHK| 98 - Load your hosted application into Chrome as an unpacked extension and run 99 it from a server (which can be a local server). The CWS manifest file 100 must specify a ``web_url`` field. 101 * - 4 102 - CWS application with untrusted testers 103 - 104 - 105 - |CHK| 106 - This is the standard technique for distributing a packaged or hosted 107 application in the CWS, but you can limit the application to a few 108 trusted testers. This technique requires a server if your application is 109 a hosted application. 110 111.. |CHK| image:: /images/check-red.png 112 113Which of the above techniques you use to run your application during development 114is largely a matter of personal preference (i.e., would you rather start a local 115server or create CWS metadata?). As a general rule, once you have an idea of how 116you plan to distribute your application, you should use the corresponding 117technique during development. Choosing a distribution option depends on a number 118of factors such as application size, application start-up time, hosting costs, 119offline functionality, etc. (see :doc:`Distributing Your Application 120<../distributing>` for details), but you don't need to make a decision about how 121to distribute your application at the outset. 122 123The next two sections of this document describe a couple of prerequisites for 124running applications during development, and explain the three requirements 125listed in the table above (NaCl flag, web server, and CWS metadata). The 126subsequent sections of the document provide instructions for how to use each of 127the four techniques. 128 129Prerequisites 130============= 131 132Browser and Pepper versions 133--------------------------- 134 135Before you run a new build of your application, make sure that you're using the 136correct version of Chrome. Each version of Chrome supports a corresponding 137version of the Pepper API. You (and your users) must use a version of Chrome 138that is equal to or higher than the version of the Pepper API that your 139application uses. For example, if you compiled your application using the 140``pepper_31`` bundle, your application uses the Pepper 31 API, and you must run 141the application in Chrome 31 or higher. To check which version of Chrome you're 142using, type ``about:version`` in the Chrome address bar. 143 144.. _cache: 145 146Chrome Cache 147------------ 148 149Chrome caches resources aggressively. You should disable Chrome's cache whenever 150you are developing a Native Client application in order to make sure Chrome 151loads new versions of your application. Follow the instructions :ref:`in the 152tutorial <tutorial_step_3>`. 153 154.. _requirements: 155 156Requirements 157============ 158 159.. _flag: 160 161Native Client flag 162------------------ 163 164Native Client is automatically enabled for applications that are installed from 165the Chrome Web Store. To enable Native Client for applications that are not 166installed from the Chrome Web Store, you must explicitly turn on the Native 167Client flag in Chrome as follows: 168 169#. Type ``about:flags`` in the Chrome address bar. 170#. Scroll down to "Native Client". 171#. If the link below "Native Client" says "Disable", then Native Client is 172 already enabled and you don't need to do anything else. 173#. If the link below "Native Client" says "Enable": 174 175 * Click the "Enable" link. 176 * Click the "Relaunch Now" button in the bottom of the screen. **Native 177 Client will not be enabled until you relaunch your browser**. All browser 178 windows will restart when you relaunch Chrome. 179 180If you enable the Native Client flag and still can't run applications from 181outside the Chrome Web Store, you may need to enable the Native Client plugin: 182 183#. Type ``about:plugins`` in the Chrome address bar. 184#. Scroll down to "Native Client". 185#. If the link below "Native Client" says "Enable", click the link to enable 186 the Native Client plugin. You do not need to relaunch Chrome after enabling 187 the Native Client plugin. 188 189.. _web_server: 190 191Web server 192---------- 193 194For security reasons, Native Client applications must come from a server (you 195can't simply drag HTML files into your browser). The Native Client SDK comes 196with a lightweight Python web server that you can run to serve your application 197locally. The server can be invoked from a Makefile. Here is how to run the 198server: 199 200.. naclcode:: 201 :prettyprint: 0 202 203 $ cd examples 204 $ make serve 205 206By default, the server listens for requests on port 5103. You can use the server 207to run most applications under the ``examples`` directory where you started the 208server. For example, to run the ``flock`` example in the SDK, start the server 209and point your browser to http://localhost:5103/demo/flock/. 210 211Some of the applications need special flags to Chrome, and must be run with the 212``make run`` command. See :ref:`running_the_sdk_examples` for more details. 213 214.. _metadata: 215 216Chrome Web Store metadata 217~~~~~~~~~~~~~~~~~~~~~~~~~ 218 219Applications published in the Chrome Web Store must be accompanied by CWS 220metadata; specifically, a Chrome Web Store manifest file named 221``manifest.json``, and at least one icon. 222 223Below is an example of a CWS manifest file for a **hosted application**: 224 225.. naclcode:: 226 227 { 228 "name": "My NaCl App", 229 "description": "Simple game implemented using Native Client", 230 "version": "0.1", 231 "icons": { 232 "128": "icon128.png" 233 }, 234 "app": { 235 "urls": [ 236 "http://mysubdomain.example.com/" 237 ], 238 "launch": { 239 "web_url": "http://mysubdomain.example.com/my_app_main_page.html" 240 } 241 } 242 } 243 244 245For a **packaged application**, you can omit the urls field, and replace the 246``web_url`` field with a ``local_path`` field, as shown below: 247 248.. naclcode:: 249 250 { 251 "name": "My NaCl App", 252 "description": "Simple game implemented using Native Client", 253 "version": "0.1", 254 "icons": { 255 "16": "icon16.png", 256 "128": "icon128.png" 257 }, 258 "app": { 259 "launch": { 260 "local_path": "my_app_main_page.html" 261 } 262 } 263 } 264 265You must put the ``manifest.json`` file in the same directory as your 266application's main HTML page. 267 268If you don't have icons for your application, you can use the following icons as 269placeholders: 270 271|ICON16| 272 273|ICON128| 274 275.. |ICON16| image:: /images/icon16.png 276.. |ICON128| image:: /images/icon128.png 277 278Put the icons in the same directory as the CWS manifest file. For more 279information about CWS manifest files and application icons, see: 280 281* `Chrome Web Store Tutorial: Getting Started 282 <https://developers.google.com/chrome/web-store/docs/get_started_simple>`_ 283* `Chrome Web Store Formats: Manifest Files 284 <http://code.google.com/chrome/extensions/manifest.html>`_ 285 286Technique 1: Local server 287========================= 288 289To run your application from a local server: 290 291* Enable the :ref:`Native Client flag <flag>` in Chrome. 292* Start a :ref:`local web server <web_server>`. 293* Put your application under the examples directory in the SDK bundle you are 294 using (e.g., in the directory ``pepper_31/examples/my_app``). 295* Access your application on the local server by typing the location of its 296 HTML file in Chrome, e.g.: 297 ``http://localhost:5103/my_app/my_app_main_page.html``. 298 299.. Note:: 300 :class: note 301 302 **Note:** You don't have to use a local web server---you can use another 303 server if you already have one running. You must still enable the Native 304 Client flag in order to run your application from the server. 305 306Technique 2: Packaged application loaded as an unpacked extension 307================================================================= 308 309For development purposes, Chrome lets you load a packaged application as an 310unpacked extension. To load and run your packaged application as an unpacked 311extension: 312 313#. Create a Chrome Web Store manifest file and one or more icons for your 314 application. 315 316 * Follow the instructions above under Chrome Web Store metadata to create 317 these files. 318 * Note that the CWS manifest file should contain the ``local_path`` field 319 rather than the ``web_url`` field. 320#. Put the CWS manifest file and the application icon(s) in the same directory 321 as your application's main HTML page. 322#. Load the application as an unpacked extension in Chrome: 323 324 * Bring up the extensions management page in Chrome by clicking the menu 325 icon |menu-icon| and choosing **Tools > Extensions**. 326 * Check the box for **Developer mode** and then click the **Load unpacked 327 extension** button: 328 |extensions| 329 * In the file dialog that appears, select your application directory. Unless 330 you get an error dialog, you've now installed your app in Chrome. 331#. Open a new tab in Chrome and click the **Apps** link at the bottom of the 332 page to show your installed apps: 333 |new-tab-apps| 334#. The icon for your newly installed app should appear on the New Tab page. 335 Click the icon to launch the app. 336 337For additional information about how to create CWS metadata and load your 338application into Chrome (including troubleshooting information), see the 339`Chrome Web Store Tutorial: Getting Started 340<https://developers.google.com/chrome/web-store/docs/get_started_simple>`_. 341 342See also :ref:`run_sdk_examples_as_packaged`. 343 344Technique 3: Hosted application loaded as an unpacked extension 345=============================================================== 346 347For development purposes, Chrome lets you load a hosted application as an 348unpacked extension. To load and run your hosted application as an unpacked 349extension: 350 351#. Start a web server to serve your application. 352 353 * You can use the :ref:`local web server <web_server>` included with the 354 Native Client SDK if you want. 355#. Upload your application (.html, .nmf, .nexe, .css, .js, image files, etc.) 356 to the server. 357 358 * If you're using the local server included with the Native Client SDK, 359 simply put your application under the ``examples`` directory in the SDK 360 bundle you are using (e.g., in the directory 361 ``pepper_31/examples/my_app``). 362#. Create a Chrome Web Store manifest file and one or more icons for your 363 application. 364 365 * Follow the instructions above under :ref:`Chrome Web Store metadata 366 <metadata>` to create these files. 367 * In the CWS manifest file, the ``web_url`` field should specify the 368 location of your application on your server. If you're using the local 369 server included with the SDK, the ``web_url`` field should look something 370 like ``http://localhost:5103/my_app/my_app_main_page.html``. 371#. Put the CWS manifest file and the application icon(s) in the same directory 372 as your application's main HTML page. 373#. Load the application as an unpacked extension in Chrome: 374 375 * Bring up the extensions management page in Chrome by clicking the menu 376 icon |menu-icon| and choosing **Tools > Extensions**. 377 * Check the box for **Developer mode** and then click the **Load unpacked 378 extension** button: 379 |extensions| 380 * In the file dialog that appears, select your application directory. Unless 381 you get an error dialog, you've now installed your app in Chrome. 382#. Open a new tab in Chrome and click the **Apps** link at the bottom of the 383 page to show your installed apps: 384 |new-tab-apps| 385#. The icon for your newly installed app should appear on the New Tab page. 386 Click the icon to launch the app. 387 388For additional information about how to create CWS metadata and load your 389application into Chrome (including troubleshooting information), see the 390`Chrome Web Store Tutorial: Getting Started 391<https://developers.google.com/chrome/web-store/docs/get_started_simple>`_. 392 393Technique 4: Chrome Web Store application with trusted testers 394============================================================== 395 396When you're ready to test your application more broadly, you can upload the 397application to the Chrome Web Store and let some trusted testers run it. Here 398is how to do so: 399 400#. Create the Chrome Web Store metadata required to publish your application: 401 402 * First, create a Chrome Web Store manifest file and one or more icons for 403 your application, as described above under :ref:`Chrome Web Store metadata 404 <metadata>`. Note that packaged applications must have at least two icons 405 (a 16x16 icon and a 128x128 icon). 406 * You also need to create the following additional assets before you can 407 publish your application: 408 409 * a screenshot (size must be 640x400 or 1280x800) 410 * a promotional image called a "small tile" (size must be 440x280) 411 412#. For a **packaged application**: 413 414 * Create a zip file with the CWS manifest file, the application icons, and 415 all your application files (.html, .nmf, .nexe, .css, .js, image files, 416 etc.) 417 418#. For a **hosted application**: 419 420 * Create a zip file with the CWS manifest file and the application icon(s). 421 * Upload the application files (.html, .nmf, .nexe, .css, .js, image files, 422 etc.) to the server on which the application is being hosted. 423 * Use `Google Webmaster Tools <http://www.google.com/webmasters/tools/>`_ to 424 verify ownership of the web site on which the application runs. 425 426#. Log in to the `Chrome Web Store Developer Dashboard 427 <https://chrome.google.com/webstore/developer/dashboard>`_. 428 429 * The first time you log in, click the "Add new item" button to display the 430 Google Chrome Web Store Developer Agreement. Review and accept the 431 agreement and then return to the `Developer Dashboard 432 <https://chrome.google.com/webstore/developer/dashboard>`_. 433 434#. Click "Edit your tester accounts" at the bottom of the Developer Dashboard. 435#. Enter a series of email addresses for your testers (separated by commas or 436 whitespace), and click the "Save Changes" button. 437#. Click the "Add new item" button to add your application to the Chrome Web 438 Store. 439#. Click the "Choose file" button and select the zip file you created earlier. 440#. Click the "Upload" button; this uploads your zip file and opens the "Edit 441 item" page. 442#. Edit the following required fields on the "Edit item" page: 443 444 * Upload an application icon. 445 * Upload a screenshot. 446 * Upload a small tile. 447 * Select a category for your application (accounting application, action 448 game, etc.). 449 * Select a language for your application. 450#. If you are an owner or manager of a Google Group, you can select that group 451 in the "Trusted testers" field. 452 453 * You may want to create a Google Group specifically for your testers. When 454 you add a group to the "Trusted testers" field, all group members will be 455 able to test the application, in addition to the individuals you added to 456 the "trusted tester accounts" field on the Developer Dashboard. 457#. Click the "Publish to test accounts" button at the bottom of the page and 458 click "OK". 459#. A page comes up that shows your application's listing in the Chrome Web 460 Store. Copy the URL and mail it to your trusted testers. 461 462 * When you publish an application to test accounts, the application's CWS 463 listing is visible only to you and to people who are logged into those 464 accounts. Your application won't appear in search results, so you need to 465 give testers a direct link to your application's CWS listing. Users won't 466 be able to find the application by searching in the CWS. 467 468To publish an application to the world after publishing it to test accounts, 469you must first unpublish the application. For additional information see 470`Publishing Your App 471<https://developers.google.com/chrome/web-store/docs/publish>`_, and in 472particular `Publishing to test accounts 473<https://developers.google.com/chrome/web-store/docs/publish#testaccounts>`_. 474 475.. |menu-icon| image:: /images/menu-icon.png 476.. |extensions| image:: /images/extensions-management.png 477.. |new-tab-apps| image:: /images/new-tab-apps.png 478