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