3d71a3cd45
Bug: 750830 Change-Id: I30baf7f3042d318e1d460b0af8628369c4fdfe10 Reviewed-on: https://chromium-review.googlesource.com/602246 Commit-Queue: Julien Brianceau <jbriance@cisco.com> Reviewed-by: Sam Clegg <sbc@chromium.org> Cr-Commit-Position: refs/heads/master@{#492085}
320 lines
16 KiB
HTML
320 lines
16 KiB
HTML
{{+bindTo:partials.standard_nacl_article}}
|
|
|
|
<b><font color="#cc0000">
|
|
NOTE:
|
|
Deprecation of the technologies described here has been announced
|
|
for platforms other than ChromeOS.<br/>
|
|
Please visit our
|
|
<a href="/native-client/migration">migration guide</a>
|
|
for details.
|
|
</font></b>
|
|
<hr/><section id="distributing-your-application">
|
|
<h1 id="distributing-your-application">Distributing Your Application</h1>
|
|
<div class="contents local" id="contents" style="display: none">
|
|
<ul class="small-gap">
|
|
<li><a class="reference internal" href="#portable-native-client" id="id2">Portable Native Client</a></li>
|
|
<li><p class="first"><a class="reference internal" href="#non-portable-native-client" id="id3">Non-portable Native Client</a></p>
|
|
<ul class="small-gap">
|
|
<li><a class="reference internal" href="#chrome-apps" id="id4">Chrome apps</a></li>
|
|
<li><a class="reference internal" href="#extension" id="id5">Extension</a></li>
|
|
<li><a class="reference internal" href="#hosted-application" id="id6">Hosted application</a></li>
|
|
<li><a class="reference internal" href="#registering-native-client-modules-to-handle-mime-types" id="id7">Registering Native Client modules to handle MIME types</a></li>
|
|
</ul>
|
|
</li>
|
|
</ul>
|
|
|
|
</div><p>This document describes how to distribute Portable Native Client applications
|
|
on the web, and Native Client applications through the
|
|
<a class="reference external" href="/webstore">Chrome Web Store</a> (CWS).</p>
|
|
<h2 id="portable-native-client">Portable Native Client</h2>
|
|
<p>Portable Native Client is enabled by default for web pages, so no separate
|
|
distribution step is required. Making PNaCl a part of your web application is as
|
|
simple as embedding a manifest file that points to a <strong>pexe</strong>. See the
|
|
<a class="reference internal" href="/native-client/overview.html"><em>technical overview</em></a> for more details.</p>
|
|
<img alt="/native-client/images/nacl-in-a-web-app.png" src="/native-client/images/nacl-in-a-web-app.png" />
|
|
<p>The only constraint for distributing PNaCl modules with a web application is
|
|
abiding by the <a class="reference external" href="http://en.wikipedia.org/wiki/Same_origin_policy">Same-origin policy</a>. The PNaCl manifest and
|
|
<strong>pexe</strong> must either be served from the same domain with the HTML, or the <a class="reference external" href="http://en.wikipedia.org/wiki/Cross-origin_resource_sharing">CORS
|
|
mechanism</a> should
|
|
be used to safely host them on a different domain.</p>
|
|
<h2 id="non-portable-native-client">Non-portable Native Client</h2>
|
|
<p>NaCl modules are only allowed for applications distributed through the <a class="reference external" href="https://chrome.google.com/webstore/category/apps">Chrome
|
|
Web Store (CWS)</a>
|
|
The CWS requirement is in place to prevent the proliferation of Native Client
|
|
executables (<strong>nexe</strong>s) compiled for specific architecures (e.g., x86-32,
|
|
x86-64, or ARM).</p>
|
|
<p>In general, the considerations and guidelines for distributing applications
|
|
through the Chrome Web Store apply to applications that contain NaCl modules as
|
|
well. Here are a few pointers to relevant documentation:</p>
|
|
<ul class="small-gap">
|
|
<li><a class="reference external" href="/webstore">CWS Overview</a></li>
|
|
<li><a class="reference external" href="/webstore/choosing">Choosing an App Type</a></li>
|
|
<li><a class="reference external" href="/apps">Getting started with Chrome apps</a></li>
|
|
<li><a class="reference external" href="/extensions">Chrome extensions</a></li>
|
|
</ul>
|
|
<p>In this document, we’ll focus only on distribution issues specific to
|
|
applications that contain NaCl modules.</p>
|
|
<h3 id="chrome-apps"><span id="distributing-packaged"></span>Chrome apps</h3>
|
|
<p>A Chrome app is a special zip file (with a .crx extension) hosted in the Chrome
|
|
Web Store. This file contains all of the application parts: A Chrome Web Store
|
|
manifest file (manifest.json), an icon, and all of the regular Native Client
|
|
application files. Refer to <a class="reference external" href="/apps">Chrome Apps</a> for more information about
|
|
creating a Chrome app.</p>
|
|
<h4 id="reducing-the-size-of-the-user-download-package">Reducing the size of the user download package</h4>
|
|
<aside class="note">
|
|
<strong>Tip:</strong>
|
|
Packaging an app in a multi-platform zip file can significantly reduce the
|
|
download and storage requirements for the app.
|
|
</aside>
|
|
<p>As described above, to upload a Chrome app to the CWS you have to create a zip
|
|
file with all the resources that your app needs, including .nexe files for
|
|
multiple architectures (x86-64, x86-32, and ARM). Prior to Chrome 28, when users
|
|
installed your app they had to download a .crx file from the CWS with all the
|
|
included .nexe files.</p>
|
|
<p>Starting with Chrome 28, the Chrome Web Store includes a feature called
|
|
<strong>multi-platform zip files.</strong> This feature lets you structure your application
|
|
directory and zip file in a way that reduces the size of the user download
|
|
package. Here’s how this feature works:</p>
|
|
<ul class="small-gap">
|
|
<li>You still include all the .nexe files in the zip file that you upload to
|
|
the CWS, but you designate specific .nexe files (and other files if
|
|
appropriate) for specific architectures.</li>
|
|
<li>The Chrome Web Store re-packages your app, so that users only download
|
|
the files that they need for their specific architecture.</li>
|
|
</ul>
|
|
<p>Here is how to use this feature:</p>
|
|
<ol class="arabic">
|
|
<li><p class="first">Create a directory called <code>_platform_specific</code>.
|
|
Put this directory at the same level where your CWS manifest file,
|
|
<code>manifest.json</code>, is located.</p>
|
|
</li>
|
|
<li><p class="first">Create a subdirectory for each specific architecture that you support,
|
|
and add the files for each architecture in the relevant subdirectory.</p>
|
|
<p>Here is a sample app directory structure:</p>
|
|
<pre>
|
|
|-- my_app_directory/
|
|
| |-- manifest.json
|
|
| |-- my_app.html
|
|
| |-- my_module.nmf
|
|
| +-- css/
|
|
| +-- images/
|
|
| +-- scripts/
|
|
| |-- _platform_specific/
|
|
| | |-- x86-64/
|
|
| | | |-- my_module_x86_64.nexe
|
|
| | |-- x86-32/
|
|
| | | |-- my_module_x86_32.nexe
|
|
| | |-- arm/
|
|
| | | |-- my_module_arm.nexe
|
|
| | |-- all/
|
|
| | | |-- my_module_x86_64.nexe
|
|
| | | |-- my_module_x86_64.nexe
|
|
| | | |-- my_module_x86_32.nexe
|
|
</pre>
|
|
<p>Please note a few important points about the app directory structure:</p>
|
|
<ul class="small-gap">
|
|
<li><p class="first">The architecture-specific subdirectories:</p>
|
|
<ul class="small-gap">
|
|
<li><p class="first">can have arbitrary names;</p>
|
|
</li>
|
|
<li><p class="first">must be directly under the <code>_platform_specific</code> directory; and</p>
|
|
</li>
|
|
<li><p class="first">must be listed in the CWS manifest file (see step 3 below).</p>
|
|
</li>
|
|
</ul>
|
|
</li>
|
|
<li><p class="first">You can include a fallback subdirectory that provides a download package
|
|
with all the architecture-specific files. (In the example above this
|
|
is the <code>all/</code> subdirectory.) This folder is used if the user has an
|
|
earlier version of Chrome (prior to Chrome 28) that does not support
|
|
multi-platform zip files.</p>
|
|
</li>
|
|
<li><p class="first">You cannot include any files directly in the folder
|
|
<code>_platform_specific</code>. All architecture-specific files
|
|
must be under one of the architecture-specific subdirectories.</p>
|
|
</li>
|
|
<li><p class="first">Files that are not under the <code>_platform_specific</code> directory are
|
|
included in all download packages. (In the example above, that
|
|
includes <code>my_app.html</code>, <code>my_module.nmf</code>,
|
|
and the <code>css/</code>, <code>images/</code>, and <code>scripts/</code> directories.)</p>
|
|
</li>
|
|
</ul>
|
|
</li>
|
|
<li><p class="first">Modify the CWS manifest file, <code>manifest.json</code>, so that it specifies which
|
|
subdirectory under <code>_platform_specific</code> corresponds to which architecture.</p>
|
|
<p>The CWS manifest file must include a new name/value pair, where the name
|
|
is <code>platforms</code> and the value is an array. The array has an object for
|
|
each Native Client architecture with two name/value pairs:</p>
|
|
<table border="1" class="docutils">
|
|
<colgroup>
|
|
</colgroup>
|
|
<thead valign="bottom">
|
|
<tr class="row-odd"><th class="head">Name</th>
|
|
<th class="head">Value</th>
|
|
</tr>
|
|
</thead>
|
|
<tbody valign="top">
|
|
<tr class="row-even"><td><code>nacl_arch</code></td>
|
|
<td><code>x86-64</code>, <code>x86-32</code>, or <code>arm</code></td>
|
|
</tr>
|
|
<tr class="row-odd"><td><code>sub_package_path</code></td>
|
|
<td>the path of the directory (starting
|
|
with <code>_platform_specific</code>) that
|
|
contains the files for the designated
|
|
NaCl architecture</td>
|
|
</tr>
|
|
</tbody>
|
|
</table>
|
|
<p>Here is a sample <code>manifest.json</code> file:</p>
|
|
<pre>
|
|
{
|
|
"name": "My Reminder App",
|
|
"description": "A reminder app that syncs across Chrome browsers.",
|
|
"manifest_version": 2,
|
|
"minimum_chrome_version": "28",
|
|
"offline_enabled": true,
|
|
"version": "0.3",
|
|
"permissions": [
|
|
{"fileSystem": ["write"]},
|
|
"alarms",
|
|
"storage"
|
|
],
|
|
"app": {
|
|
"background": {
|
|
"scripts": ["scripts/background.js"]
|
|
}
|
|
},
|
|
"icons": {
|
|
"16": "images/icon-16x16.png",
|
|
"128": "images/icon-128x128.png"
|
|
},
|
|
"platforms": [
|
|
{
|
|
"nacl_arch": "x86-64",
|
|
"sub_package_path": "_platform_specific/x86-64/"
|
|
},
|
|
{
|
|
"nacl_arch": "x86-32",
|
|
"sub_package_path": "_platform_specific/x86-32/"
|
|
},
|
|
{
|
|
"nacl_arch": "arm",
|
|
"sub_package_path": "_platform_specific/arm/"
|
|
},
|
|
{
|
|
"sub_package_path": "_platform_specific/all/"
|
|
}
|
|
]
|
|
}
|
|
</pre>
|
|
<p>Note the last entry in the CWS manifest file above, which specifies a
|
|
<code>sub_package_path</code> without a corresponding <code>nacl_arch</code>. This entry
|
|
identifies the fallback directory, which is included in the download
|
|
package if the user architecture does not match any of the listed NaCl
|
|
architectures, or if the user is using an older version of Chrome that
|
|
does not support multi-platform zip files.</p>
|
|
</li>
|
|
<li><p class="first">Modify your application as necessary so that it uses the files for the
|
|
correct user architecture.</p>
|
|
<p>To reference architecture-specific files, use the JavaScript API
|
|
<a class="reference external" href="/extensions/runtime.html#method-getPlatformInfo">chrome.runtime.getPlatformInfo()</a>.
|
|
As an example, if you have architecture-specific files in the directories
|
|
<code>x86-64</code>, <code>x86-32</code>, and <code>arm</code>, you can use the following JavaScript
|
|
code to create a path for the files:</p>
|
|
<pre class="prettyprint">
|
|
function getPath(name) {
|
|
return '_platform_specific/' +
|
|
chrome.runtime.getPlatformInfo().nacl_arch +
|
|
'/' + name;
|
|
}
|
|
</pre>
|
|
</li>
|
|
<li><p class="first">Test your app, create a zip file, and upload the app to the CWS as before.</p>
|
|
</li>
|
|
</ol>
|
|
<h4 id="additional-considerations-for-a-chrome-app"><span id="additional-considerations-packaged"></span>Additional considerations for a Chrome app</h4>
|
|
<ul class="small-gap">
|
|
<li>In the description of your application in the CWS, make sure to mention that
|
|
your application is a Native Client application that only works with the
|
|
Chrome browser. Also make sure to identify the minimum version of Chrome
|
|
that your application requires.</li>
|
|
<li><p class="first">Hosted and packaged applications have a “launch” parameter in the CWS
|
|
manifest. This parameter is present only in apps (not extensions), and it
|
|
tells Google Chrome what to show when a user starts an installed app. For
|
|
example:</p>
|
|
<pre>
|
|
"launch": {
|
|
"web_url": "http://mail.google.com/mail/"
|
|
}
|
|
</pre>
|
|
</li>
|
|
<li>If you want to write local data using the Pepper
|
|
<a class="reference external" href="/native-client/peppercpp/classpp_1_1_file_i_o">FileIO</a>
|
|
API, you must set the ‘unlimitedStorage’ permission in your Chrome Web
|
|
Store manifest file, just as you would for a JavaScript application that
|
|
uses the HTML5 File API.</li>
|
|
<li>For Chrome apps, you can only use in-app purchases.</li>
|
|
<li>You can place your application in the Google Web Store with access only to
|
|
certain people for testing. See <a class="reference external" href="/webstore/publish">Publishing to test accounts</a> for more information.</li>
|
|
</ul>
|
|
<h3 id="extension">Extension</h3>
|
|
<p>The NaCl-specific notes for a <a class="reference internal" href="#distributing-packaged"><em>package application</em></a>
|
|
apply to extensions as well.</p>
|
|
<h3 id="hosted-application">Hosted application</h3>
|
|
<p>The .html file, .nmf file (Native Client manifest file), and .nexe files must
|
|
be served from the same domain, and the Chrome Web Store manifest file must
|
|
specify the correct, verified domain. Other files can be served from the same
|
|
or another domain.</p>
|
|
<p>In addition, see <a class="reference internal" href="#additional-considerations-packaged"><em>Additional considerations for a Chrome apps</em></a>.</p>
|
|
<h3 id="registering-native-client-modules-to-handle-mime-types">Registering Native Client modules to handle MIME types</h3>
|
|
<p>If you want Chrome to use a Native Client module to display a particular type
|
|
of content, you can associate the MIME type of that content with the Native
|
|
Client module. Use the <code>nacl_modules</code> attribute in the Chrome Web Store
|
|
manifest file to register a Native Client module as the handler for one or more
|
|
specific MIME types. For example, the bold code in the snippet below registers
|
|
a Native Client module as the content handler for the OpenOffice spreadsheet
|
|
MIME type:</p>
|
|
<pre>
|
|
{
|
|
"name": "My Native Client Spreadsheet Viewer",
|
|
"version": "0.1",
|
|
"description": "Open spreadsheets right in your browser.",
|
|
"nacl_modules": [{
|
|
"path": "SpreadsheetViewer.nmf",
|
|
"mime_type": "application/vnd.oasis.opendocument.spreadsheet"
|
|
}]
|
|
}
|
|
</pre>
|
|
<p>The value of “path” is the location of a Native Client manifest file (.nmf)
|
|
within the application directory. For more information on Native Client
|
|
manifest files, see <a class="reference internal" href="/native-client/devguide/coding/application-structure.html#manifest-file"><em>Manifest Files</em></a>.</p>
|
|
<p>The value of “mime_type” is a specific MIME type that you want the Native
|
|
Client module to handle. Each MIME type can be associated with only one .nmf
|
|
file, but a single .nmf file might handle multiple MIME types. The following
|
|
example shows an extension with two .nmf files that handle three MIME types.</p>
|
|
<pre>
|
|
{
|
|
"name": "My Native Client Spreadsheet and Document Viewer",
|
|
"version": "0.1",
|
|
"description": "Open spreadsheets and documents right in your browser.",
|
|
"nacl_modules": [{
|
|
"path": "SpreadsheetViewer.nmf",
|
|
"mime_type": "application/vnd.oasis.opendocument.spreadsheet"
|
|
},
|
|
{
|
|
"path": "SpreadsheetViewer.nmf",
|
|
"mime_type": "application/vnd.oasis.opendocument.spreadsheet-template"
|
|
},
|
|
{
|
|
"path": "DocumentViewer.nmf",
|
|
"mime_type": "application/vnd.oasis.opendocument.text"
|
|
}]
|
|
}
|
|
</pre>
|
|
<p>The <code>nacl_modules</code> attribute is optional—specify this attribute only if
|
|
you want Chrome to use a Native Client module to display a particular type of
|
|
content.</p>
|
|
</section>
|
|
|
|
{{/partials.standard_nacl_article}}
|