This repository has been archived by the owner on Mar 14, 2024. It is now read-only.
-
Notifications
You must be signed in to change notification settings - Fork 1.6k
/
running.html
452 lines (443 loc) · 24.8 KB
/
running.html
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
---json
{"title":"Running"}
---
<html><head></head><body>
{% Partial 'nacl-warning.njk' %}
<hr><section id="running" class="stack">
<div class="contents local stack-recursive" id="contents" style="display: none">
<ul>
<li><a class="reference internal" href="#introduction" id="id6">Introduction</a></li>
<li><a class="reference internal" href="#portable-native-client-pnacl-applications" id="id7">Portable Native Client (PNaCl) applications</a></li>
<li><a class="reference internal" href="#native-client-applications-and-the-chrome-web-store" id="id8">Native Client applications and the Chrome Web Store</a></li>
<li><p class="first"><a class="reference internal" href="#prerequisites" id="id9">Prerequisites</a></p>
<ul>
<li><a class="reference internal" href="#browser-and-pepper-versions" id="id10">Browser and Pepper versions</a></li>
<li><a class="reference internal" href="#chrome-cache" id="id11">Chrome Cache</a></li>
</ul>
</li>
<li><p class="first"><a class="reference internal" href="#requirements" id="id12">Requirements</a></p>
<ul>
<li><a class="reference internal" href="#native-client-flag" id="id13">Native Client flag</a></li>
<li><a class="reference internal" href="#web-server" id="id14">Web server</a></li>
</ul>
</li>
<li><a class="reference internal" href="#technique-1-local-server" id="id15">Technique 1: Local server</a></li>
<li><a class="reference internal" href="#technique-2-packaged-application-loaded-as-an-unpacked-extension" id="id16">Technique 2: Packaged application loaded as an unpacked extension</a></li>
<li><a class="reference internal" href="#technique-3-hosted-application-loaded-as-an-unpacked-extension" id="id17">Technique 3: Hosted application loaded as an unpacked extension</a></li>
<li><a class="reference internal" href="#technique-4-chrome-web-store-application-with-trusted-testers" id="id18">Technique 4: Chrome Web Store application with trusted testers</a></li>
</ul>
</div><h2 id="introduction">Introduction</h2>
<p>This document describes how to run Native Client applications during
development.</p>
<p>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.</p>
<h2 id="portable-native-client-pnacl-applications">Portable Native Client (PNaCl) applications</h2>
<p>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.</p>
<p>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 <a class="reference internal" href="/docs/native-client/devguide/tutorial/tutorial-part1#tutorial-step-2"><em>the tutorial</em></a>.</p>
<h2 id="native-client-applications-and-the-chrome-web-store">Native Client applications and the Chrome Web Store</h2>
<p>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 <a class="reference internal" href="/docs/native-client/devguide/distributing"><em>Distributing Your Application</em></a>, Native
Client applications must currently be distributed through the <strong>Chrome Web
Store (CWS)</strong>. Applications in the CWS are one of three types:</p>
<ul>
<li>A <strong>hosted application</strong> is an application that you host on a server of your
choice. To distribute an application as a hosted application, you upload
application metadata to the CWS. Learn more on the <a class="reference external" href="/apps">Chrome App</a>
documentation page.</li>
<li>A <strong>packaged application</strong> is an application that is hosted in the CWS and
downloaded to the user’s machine. To distribute an application as a packaged
application, you upload the entire application, including all application
assets and metadata, to the CWS. Learn more on the <a class="reference external" href="/apps">Chrome App</a>
documentation page.</li>
<li>An <strong>extension</strong> is a packaged application that has a tiny UI component
(extensions are typically used to extend the functionality of the Chrome
browser). To distribute an application as an extension, you upload the entire
application, including all application assets and metadata, to the CWS. Learn
more on the <a class="reference external" href="/extensions">Chrome extensions</a> documentation page.</li>
</ul>
<p>The web store documentation contains a handy guide to <a class="reference external" href="/webstore/choosing">help you choose which to
use</a>.</p>
<p>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 <a class="reference internal" href="#requirements"><em>Requirements</em></a>
section below.</p>
<table border="1" class="docutils">
<colgroup>
</colgroup>
<thead valign="bottom">
<tr class="row-odd"><th class="head" colspan="2">Technique</th>
<th class="head">Requires
Web
Server</th>
<th class="head">Requires
CWS
Metadata</th>
</tr>
</thead>
<tbody valign="top">
<tr class="row-even"><td colspan="2"><p class="first"><strong>1. Local server</strong></p>
<div>
<div><p>Run a local server and simply point your browser to
your application on the server.</p>
<aside class="note">
This technique requires the NaCl flag.
</aside>
</div>
</div>
</td>
<td><img alt="CHK" src="/docs/native-client/images/check-red.png"></td>
<td> </td>
</tr>
<tr class="row-odd"><td colspan="2"><p class="first"><strong>2. Packaged application loaded as an unpacked
extension</strong></p>
<div>
<div>Load your packaged application into Chrome as an
unpacked extension and run it without a server. An
unpacked extension is an application whose source and
metadata files are located in an unzipped folder on
your development machine. The CWS manifest file
(explained below) must specify a local_path field.</div>
</div>
</td>
<td> </td>
<td><img alt="CHK" src="/docs/native-client/images/check-red.png"></td>
</tr>
<tr class="row-even"><td colspan="2"><p class="first"><strong>3. Hosted application loaded as an unpacked
extension</strong></p>
<div>
<div>Load your hosted application into Chrome as an
unpacked extension and run it from a server (which can
be a local server). The CWS manifest file must specify
a web_url field.</div>
</div>
</td>
<td><img alt="CHK" src="/docs/native-client/images/check-red.png"></td>
<td><img alt="CHK" src="/docs/native-client/images/check-red.png"></td>
</tr>
<tr class="row-odd"><td colspan="2"><p class="first"><strong>4. CWS application with untrusted testers</strong></p>
<div>
<div>The standard technique for distributing a packaged or
hosted application in the CWS. You can limit the
application to trusted testers. This technique
requires a server if your application is a hosted
application.</div>
</div>
</td>
<td> </td>
<td><img alt="CHK" src="/docs/native-client/images/check-red.png"></td>
</tr>
</tbody>
</table>
<p>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 <a class="reference internal" href="/docs/native-client/devguide/distributing"><em>Distributing Your Application</em></a> for details), but you don’t need to make a decision about how
to distribute your application at the outset.</p>
<p>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.</p>
<h2 id="prerequisites">Prerequisites</h2>
<h3 id="browser-and-pepper-versions">Browser and Pepper versions</h3>
<p>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
<code>pepper_37</code> 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 <code>about:version</code> in the Chrome address bar.</p>
<h3 id="chrome-cache"><span id="cache"></span>Chrome Cache</h3>
<p>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 <a class="reference internal" href="/docs/native-client/devguide/tutorial/tutorial-part1#tutorial-step-3"><em>in the
tutorial</em></a>.</p>
<h2 id="requirements"><span id="id2"></span>Requirements</h2>
<h3 id="native-client-flag"><span id="flag"></span>Native Client flag</h3>
<p>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:</p>
<ol>
<li>Type <code>about:flags</code> in the Chrome address bar.</li>
<li>Scroll down to “Native Client”.</li>
<li>If the link below “Native Client” says “Disable”, then Native Client is
already enabled and you don’t need to do anything else.</li>
<li>If the link below “Native Client” says “Enable”:<ul>
<li>Click the “Enable” link.</li>
<li>Click the “Relaunch Now” button in the bottom of the screen. <strong>Native
Client will not be enabled until you relaunch your browser</strong>. All browser
windows will restart when you relaunch Chrome.</li>
</ul>
</li>
</ol>
<p>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:</p>
<ol>
<li>Type <code>about:plugins</code> in the Chrome address bar.</li>
<li>Scroll down to “Native Client”.</li>
<li>If the link below “Native Client” says “Enable”, click the link to enable
the Native Client plugin. You do not need to relaunch Chrome after enabling
the Native Client plugin.</li>
</ol>
<h3 id="web-server"><span id="id3"></span>Web server</h3>
<p>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:</p>
<pre>$ cd examples
$ make serve
</pre>
<p>By default, the server listens for requests on port 5103. You can use the server
to run most applications under the <code>examples</code> directory where you started the
server. For example, to run the <code>flock</code> example in the SDK, start the server
and point your browser to <code>http://localhost:5103/demo/flock/</code>.</p>
<p>Some of the applications need special flags to Chrome, and must be run with the
<code>make run</code> command. See <a class="reference internal" href="/docs/native-client/sdk/examples#running-the-sdk-examples"><em>Run the SDK examples</em></a> for more details.</p>
<h4 id="chrome-web-store-metadata"><span id="metadata"></span>Chrome Web Store metadata</h4>
<p>Applications published in the Chrome Web Store must be accompanied by CWS
metadata; specifically, a Chrome Web Store manifest file named
<code>manifest.json</code>, and at least one icon.</p>
<p>Below is an example of a CWS manifest file for a <strong>hosted application</strong>:</p>
<pre class="prettyprint">{
"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"
}
}
}
</pre>
<p>For a <strong>packaged application</strong>, you can omit the urls field, and replace the
<code>web_url</code> field with a <code>local_path</code> field, as shown below:</p>
<pre class="prettyprint">{
"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"
}
}
}
</pre>
<p>You must put the <code>manifest.json</code> file in the same directory as your
application’s main HTML page.</p>
<p>If you don’t have icons for your application, you can use the following icons as
placeholders:</p>
<p><img alt="ICON16" src="/docs/native-client/images/icon16.png"></p>
<p><img alt="ICON128" src="/docs/native-client/images/icon128.png"></p>
<p>Put the icons in the same directory as the CWS manifest file. For more
information about CWS manifest files and application icons, see:</p>
<ul>
<li><a class="reference external" href="/webstore/get_started_simple">Chrome Web Store Tutorial: Getting Started</a></li>
<li><a class="reference external" href="/extensions/manifest">Chrome Web Store Formats: Manifest Files</a></li>
</ul>
<h2 id="technique-1-local-server">Technique 1: Local server</h2>
<p>To run your application from a local server:</p>
<ul>
<li>Enable the <a class="reference internal" href="#flag"><em>Native Client flag</em></a> in Chrome.</li>
<li>Start a <a class="reference internal" href="#web-server"><em>local web server</em></a>.</li>
<li>Put your application under the examples directory in the SDK bundle you are
using (for example, in the directory <code>pepper_35/examples/my_app</code>).</li>
<li>Access your application on the local server by typing the location of its
HTML file in Chrome, for example:
<code>http://localhost:5103/my_app/my_app_main_page.html</code>.</li>
</ul>
<aside class="note">
<strong>Note:</strong> You don’t have to use a local web server—you can use another
server if you already have one running. You must still enable the Native
Client flag in order to run your application from the server.
</aside>
<h2 id="technique-2-packaged-application-loaded-as-an-unpacked-extension">Technique 2: Packaged application loaded as an unpacked extension</h2>
<p>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:</p>
<ol>
<li>Create a Chrome Web Store manifest file and one or more icons for your
application.<ul>
<li>Follow the instructions above under Chrome Web Store metadata to create
these files.</li>
<li>Note that the CWS manifest file should contain the <code>local_path</code> field
rather than the <code>web_url</code> field.</li>
</ul>
</li>
<li>Put the CWS manifest file and the application icon(s) in the same directory
as your application’s main HTML page.</li>
<li>Load the application as an unpacked extension in Chrome:<ul>
<li>Bring up the extensions management page in Chrome by clicking the menu
icon <img alt="menu-icon" src="/docs/native-client/images/menu-icon.png"> and choosing <strong>Tools > Extensions</strong>.</li>
<li>Check the box for <strong>Developer mode</strong> and then click the <strong>Load unpacked
extension</strong> button:
<img alt="extensions" src="/docs/native-client/images/extensions-management.png"></li>
<li>In the file dialog that appears, select your application directory. Unless
you get an error dialog, you’ve now installed your app in Chrome.</li>
</ul>
</li>
<li>Open a new tab in Chrome and click the <strong>Apps</strong> link at the bottom of the
page to show your installed apps:
<img alt="new-tab-apps" src="/docs/native-client/images/new-tab-apps.png"></li>
<li>The icon for your newly installed app should appear on the New Tab page.
Click the icon to launch the app.</li>
</ol>
<p>For additional information about how to create CWS metadata and load your
application into Chrome (including troubleshooting information), see the
<a class="reference external" href="/webstore/get_started_simple">Chrome Web Store Tutorial: Getting Started</a>.</p>
<p>See also <a class="reference internal" href="/docs/native-client/sdk/examples#run-sdk-examples-as-packaged"><em>Run the SDK examples as Chrome apps</em></a>.</p>
<h2 id="technique-3-hosted-application-loaded-as-an-unpacked-extension">Technique 3: Hosted application loaded as an unpacked extension</h2>
<p>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:</p>
<ol>
<li>Start a web server to serve your application.<ul>
<li>You can use the <a class="reference internal" href="#web-server"><em>local web server</em></a> included with the
Native Client SDK if you want.</li>
</ul>
</li>
<li>Upload your application (.html, .nmf, .nexe, .css, .js, image files, etc.)
to the server.<ul>
<li>If you’re using the local server included with the Native Client SDK,
simply put your application under the <code>examples</code> directory in the SDK
bundle you are using (e.g., in the directory
<code>pepper_37/examples/my_app</code>).</li>
</ul>
</li>
<li>Create a Chrome Web Store manifest file and one or more icons for your
application.<ul>
<li>Follow the instructions above under <a class="reference internal" href="#metadata"><em>Chrome Web Store metadata</em></a> to create these files.</li>
<li>In the CWS manifest file, the <code>web_url</code> field should specify the
location of your application on your server. If you’re using the local
server included with the SDK, the <code>web_url</code> field should look something
like <code>http://localhost:5103/my_app/my_app_main_page.html</code>.</li>
</ul>
</li>
<li>Put the CWS manifest file and the application icon(s) in the same directory
as your application’s main HTML page.</li>
<li>Load the application as an unpacked extension in Chrome:<ul>
<li>Bring up the extensions management page in Chrome by clicking the menu
icon <img alt="menu-icon" src="/docs/native-client/images/menu-icon.png"> and choosing <strong>Tools > Extensions</strong>.</li>
<li>Check the box for <strong>Developer mode</strong> and then click the <strong>Load unpacked
extension</strong> button:
<img alt="extensions" src="/docs/native-client/images/extensions-management.png"></li>
<li>In the file dialog that appears, select your application directory. Unless
you get an error dialog, you’ve now installed your app in Chrome.</li>
</ul>
</li>
<li>Open a new tab in Chrome and click the <strong>Apps</strong> link at the bottom of the
page to show your installed apps:
<img alt="new-tab-apps" src="/docs/native-client/images/new-tab-apps.png"></li>
<li>The icon for your newly installed app should appear on the New Tab page.
Click the icon to launch the app.</li>
</ol>
<p>For additional information about how to create CWS metadata and load your
application into Chrome (including troubleshooting information), see the
<a class="reference external" href="/webstore/get_started_simple">Chrome Web Store Tutorial: Getting Started</a>.</p>
<h2 id="technique-4-chrome-web-store-application-with-trusted-testers">Technique 4: Chrome Web Store application with trusted testers</h2>
<p>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:</p>
<ol>
<li>Create the Chrome Web Store metadata required to publish your application:<ul>
<li>First, create a Chrome Web Store manifest file and one or more icons for
your application, as described above under <a class="reference internal" href="#metadata"><em>Chrome Web Store metadata</em></a>. Note that packaged applications must have at least two icons
(a 16x16 icon and a 128x128 icon).</li>
<li>You also need to create the following additional assets before you can
publish your application:<ul>
<li>a screenshot (size must be 640x400 or 1280x800)</li>
<li>a promotional image called a “small tile” (size must be 440x280)</li>
</ul>
</li>
</ul>
</li>
<li>For a <strong>packaged application</strong>:<ul>
<li>Create a zip file with the CWS manifest file, the application icons, and
all your application files (.html, .nmf, .nexe, .css, .js, image files,
etc.)</li>
</ul>
</li>
<li>For a <strong>hosted application</strong>:<ul>
<li>Create a zip file with the CWS manifest file and the application icon(s).</li>
<li>Upload the application files (.html, .nmf, .nexe, .css, .js, image files,
etc.) to the server on which the application is being hosted.</li>
<li>Use <a class="reference external" href="http://www.google.com/webmasters/tools/">Google Webmaster Tools</a> to
verify ownership of the website on which the application runs.</li>
</ul>
</li>
<li>Log in to the <a class="reference external" href="https://chrome.google.com/webstore/developer/dashboard">Chrome Web Store Developer Dashboard</a>.<ul>
<li>The first time you log in, click the “Add new item” button to display the
Google Chrome Web Store Developer Agreement. Review and accept the
agreement and then return to the <a class="reference external" href="https://chrome.google.com/webstore/developer/dashboard">Developer Dashboard</a>.</li>
</ul>
</li>
<li>Click “Edit your tester accounts” at the bottom of the Developer Dashboard.</li>
<li>Enter a series of email addresses for your testers (separated by commas or
whitespace), and click the “Save Changes” button.</li>
<li>Click the “Add new item” button to add your application to the Chrome Web
Store.</li>
<li>Click the “Choose file” button and select the zip file you created earlier.</li>
<li>Click the “Upload” button; this uploads your zip file and opens the “Edit
item” page.</li>
<li>Edit the following required fields on the “Edit item” page:<ul>
<li>Upload an application icon.</li>
<li>Upload a screenshot.</li>
<li>Upload a small tile.</li>
<li>Select a category for your application (accounting application, action
game, etc.).</li>
<li>Select a language for your application.</li>
</ul>
</li>
<li>If you are an owner or manager of a Google Group, you can select that group
in the “Trusted testers” field.<ul>
<li>You may want to create a Google Group specifically for your testers. When
you add a group to the “Trusted testers” field, all group members will be
able to test the application, in addition to the individuals you added to
the “trusted tester accounts” field on the Developer Dashboard.</li>
</ul>
</li>
<li>Click the “Publish to test accounts” button at the bottom of the page and
click “OK”.</li>
<li>A page comes up that shows your application’s listing in the Chrome Web
Store. Copy the URL and mail it to your trusted testers.<ul>
<li>When you publish an application to test accounts, the application’s CWS
listing is visible only to you and to people who are logged into those
accounts. Your application won’t appear in search results, so you need to
give testers a direct link to your application’s CWS listing. Users won’t
be able to find the application by searching in the CWS.</li>
</ul>
</li>
</ol>
<p>To publish an application to the world after publishing it to test accounts,
you must first unpublish the application. For additional information see
<a class="reference external" href="/webstore/docs/publish">Publishing Your App</a>, and in particular <a class="reference external" href="/webstore/publish#testaccounts">Publishing
to test accounts</a>.</p>
</section>
</body></html>