| Index: native_client_sdk/src/doc/_developer.chrome.com_generated/reference/nacl-manifest-format.html
|
| diff --git a/native_client_sdk/src/doc/_developer.chrome.com_generated/reference/nacl-manifest-format.html b/native_client_sdk/src/doc/_developer.chrome.com_generated/reference/nacl-manifest-format.html
|
| new file mode 100644
|
| index 0000000000000000000000000000000000000000..109e86c9221074c3f503abd0c87faebd48df8ca6
|
| --- /dev/null
|
| +++ b/native_client_sdk/src/doc/_developer.chrome.com_generated/reference/nacl-manifest-format.html
|
| @@ -0,0 +1,237 @@
|
| +{{+bindTo:partials.standard_nacl_article}}
|
| +
|
| +<section id="native-client-manifest-nmf-format">
|
| +<h1 id="native-client-manifest-nmf-format">Native Client Manifest (nmf) Format</h1>
|
| +<div class="contents local topic" id="contents">
|
| +<ul class="small-gap">
|
| +<li><a class="reference internal" href="#overview" id="id1">Overview</a></li>
|
| +<li><a class="reference internal" href="#field-summary" id="id2">Field summary</a></li>
|
| +<li><p class="first"><a class="reference internal" href="#field-details" id="id3">Field details</a></p>
|
| +<ul class="small-gap">
|
| +<li><a class="reference internal" href="#program" id="id4">program</a></li>
|
| +<li><a class="reference internal" href="#files" id="id5">files</a></li>
|
| +</ul>
|
| +</li>
|
| +<li><p class="first"><a class="reference internal" href="#semantics" id="id6">Semantics</a></p>
|
| +<ul class="small-gap">
|
| +<li><a class="reference internal" href="#schema-validation" id="id7">Schema validation</a></li>
|
| +<li><a class="reference internal" href="#nexe-matching" id="id8">Nexe matching</a></li>
|
| +<li><a class="reference internal" href="#file-matching" id="id9">File matching</a></li>
|
| +<li><a class="reference internal" href="#url-of-the-nmf-file-from-embed-src-and-data-uri" id="id10">URL of the nmf file, from <code><embed></code> src, and data URI</a></li>
|
| +<li><a class="reference internal" href="#url-resolution" id="id11">URL resolution</a></li>
|
| +</ul>
|
| +</li>
|
| +</ul>
|
| +</div>
|
| +<section id="overview">
|
| +<h2 id="overview">Overview</h2>
|
| +<p>Every Native Client application has a <a class="reference external" href="http://www.json.org/">JSON-formatted</a>
|
| +NaCl Manifest File (<code>nmf</code>). The <code>nmf</code> tells the browser where to
|
| +download and load your Native Client application files and libraries.
|
| +The file can also contain configuration options.</p>
|
| +</section><section id="field-summary">
|
| +<h2 id="field-summary">Field summary</h2>
|
| +<p>The following shows the supported top-level manifest fields. There is one
|
| +section that discusses each field in detail. The only field that is required
|
| +is the <code>program</code> field.</p>
|
| +<pre class="prettyprint">
|
| +{
|
| + // Required
|
| + "program": { ... }
|
| +
|
| + // Only required for glibc
|
| + "files": { ... }
|
| +}
|
| +</pre>
|
| +</section><section id="field-details">
|
| +<h2 id="field-details">Field details</h2>
|
| +<section id="program">
|
| +<h3 id="program">program</h3>
|
| +<p>The <code>program</code> field specifies the main program that will be loaded
|
| +in the Native Client runtime environment. For a Portable Native Client
|
| +application, this is a URL for the statically linked bitcode <code>pexe</code> file.
|
| +For architecture-specific Native Client applications, this is a list
|
| +of URLs, one URL for each supported architecture (currently the choices
|
| +are “arm”, “x86-32”, and “x86-64”). For a dynamically linked executable,
|
| +<code>program</code> is the dynamic loader used to load the dynamic executable
|
| +and its dynamic libraries. See the <a class="reference internal" href="#nmf-url-resolution"><em>semantics</em></a>
|
| +section for the rules on URL resolution.</p>
|
| +<section id="example-of-a-program-for-portable-native-client">
|
| +<h4 id="example-of-a-program-for-portable-native-client">Example of a <code>program</code> for Portable Native Client:</h4>
|
| +<pre class="prettyprint">
|
| +{
|
| + "program": {
|
| + "pnacl-translate": {
|
| + // url is required
|
| + "url": "url_to_my_pexe"
|
| +
|
| + // optlevel is optional
|
| + "optlevel": 0
|
| + }
|
| + }
|
| +}
|
| +</pre>
|
| +<p>Portable Native Client applications can also specify an <code>optlevel</code> field.
|
| +The <code>optlevel</code> field is an optimization level <em>hint</em>, which is a number
|
| +(zero and higher). Higher numbers indicate more optimization effort.
|
| +Setting a higher optimization level will improve the application’s
|
| +performance, but it will also slow down the first load experience.
|
| +The default is <code>optlevel</code> is currently <code>2</code>, and values higher
|
| +than 2 are no different than 2. If compute speed is not as important
|
| +as first load speed, an application could specify an <code>optlevel</code>
|
| +of <code>0</code>. Note that <code>optlevel</code> is only a <em>hint</em>. In the future, the
|
| +Portable Native Client translator and runtime may <em>automatically</em> choose
|
| +an <code>optlevel</code> to best balance load time and application performance.</p>
|
| +</section><section id="example-of-a-program-for-statically-linked-native-client-executables">
|
| +<h4 id="example-of-a-program-for-statically-linked-native-client-executables">Example of a <code>program</code> for statically linked Native Client executables</h4>
|
| +<pre class="prettyprint">
|
| +{
|
| + "program": {
|
| + // Required: at least one entry
|
| + // Add one of these for each architecture supported by the application.
|
| + "arm": { "url": "url_to_arm_nexe" },
|
| + "x86-32": { "url": "url_to_x86_32_nexe" },
|
| + "x86-64": { "url": "url_to_x86_64_nexe" }
|
| + }
|
| +}
|
| +</pre>
|
| +</section><section id="example-of-a-program-for-dynamically-linked-native-client-executables">
|
| +<h4 id="example-of-a-program-for-dynamically-linked-native-client-executables">Example of a <code>program</code> for dynamically linked Native Client executables</h4>
|
| +<pre class="prettyprint">
|
| +{
|
| + "program": {
|
| + // Required: at least one entry
|
| + // Add one of these for each architecture supported by the application.
|
| + "x86-32": { "url": "lib32/runnable-ld.so" },
|
| + "x86-64": { "url": "lib64/runnable-ld.so" }
|
| + },
|
| + // discussed in next section
|
| + "files": {
|
| + "main.nexe": {
|
| + "x86-32": { "url": "url_to_x86_32_nexe" },
|
| + "x86-64": { "url": "url_to_x86_64_nexe" }
|
| + },
|
| + // ...
|
| + }
|
| +}
|
| +</pre>
|
| +</section></section><section id="files">
|
| +<h3 id="files">files</h3>
|
| +<p>The <code>files</code> field specifies a dictionary of file resources to be
|
| +used by a Native Client application. This is not supported and
|
| +not needed by Portable Native Client applications (use the PPAPI
|
| +<a class="reference external" href="https://developers.google.com/native-client/peppercpp/classpp_1_1_u_r_l_loader">URL Loader interfaces</a>
|
| +to load resources instead). However, the <code>files</code> manifest field
|
| +is important for dynamically linked executables, which must
|
| +load files before PPAPI is initialized. The <code>files</code> dictionary
|
| +should include the main dynamic program and its dynamic libraries.
|
| +There should be one file entry that corresponds to each a
|
| +dynamic library. Each file entry is a dictionary of supported architectures
|
| +and the URLs where the appropriate Native Client shared object
|
| +(<code>.so</code>) for that architecture may be found.</p>
|
| +<p>Since <code>program</code> is used to refer to the dynamic linker that comes
|
| +with the NaCl port of glibc, the main program is specified in the
|
| +<code>files</code> dictionary. The main program is specified under the
|
| +<code>"main.nexe"</code> field of the <code>files</code> dictionary.</p>
|
| +<pre class="prettyprint">
|
| +{
|
| + "program": {
|
| + "x86-64": {"url": "lib64/runnable-ld.so"},
|
| + "x86-32": {"url": "lib32/runnable-ld.so"}
|
| + },
|
| + "files": {
|
| + "main.nexe" : {
|
| + "x86-64": {"url": "pi_generator_x86_64.nexe"},
|
| + "x86-32": {"url": "pi_generator_x86_32.nexe"}
|
| + },
|
| + "libpthread.so.5055067a" : {
|
| + "x86-64": {"url": "lib64/libpthread.so.5055067a"},
|
| + "x86-32": {"url": "lib32/libpthread.so.5055067a"}
|
| + },
|
| + "libppapi_cpp.so" : {
|
| + "x86-64": {"url": "lib64/libppapi_cpp.so"},
|
| + "x86-32": {"url": "lib32/libppapi_cpp.so"}
|
| + },
|
| + "libstdc++.so.6" : {
|
| + "x86-64": {"url": "lib64/libstdc++.so.6"},
|
| + "x86-32": {"url": "lib32/libstdc++.so.6"}
|
| + },
|
| + "libm.so.5055067a" : {
|
| + "x86-64": {"url": "lib64/libm.so.5055067a"},
|
| + "x86-32": {"url": "lib32/libm.so.5055067a"}
|
| + },
|
| + "libgcc_s.so.1" : {
|
| + "x86-64": {"url": "lib64/libgcc_s.so.1"},
|
| + "x86-32": {"url": "lib32/libgcc_s.so.1"}
|
| + },
|
| + "libc.so.5055067a" : {
|
| + "x86-64": {"url": "lib64/libc.so.5055067a"},
|
| + "x86-32": {"url": "lib32/libc.so.5055067a"}
|
| + }
|
| + }
|
| +}
|
| +</pre>
|
| +<p>Dynamic libraries that the dynamic program depends upon and links in at program
|
| +startup must be listed in the <code>files</code> dictionary. Library files that are
|
| +loaded after startup using <code>dlopen()</code> should either be listed in the <code>files</code>
|
| +dictionary, or should be made accessible by the <code>nacl_io</code> library. The
|
| +<code>nacl_io</code> library provides various file system <em>mounts</em> such as HTTP-based
|
| +file systems and memory-based file systems. The Native Client SDK includes
|
| +helpful tools for determining library dependencies and generating NaCl manifest
|
| +files for programs that that use dynamic linking. See
|
| +<a class="reference internal" href="/native-client/devguide/devcycle/dynamic-loading.html#dynamic-loading-manifest"><em>Generating a Native Client manifest file for a dynamically linked application</em></a>.</p>
|
| +</section></section><section id="semantics">
|
| +<h2 id="semantics">Semantics</h2>
|
| +<section id="schema-validation">
|
| +<h3 id="schema-validation">Schema validation</h3>
|
| +<p>Manifests are validated before the program files are downloaded.
|
| +Schema validation checks the following properties:</p>
|
| +<ul class="small-gap">
|
| +<li>The schema must be valid JSON.</li>
|
| +<li>The schema must conform to the grammar given above.</li>
|
| +<li>If the program is not a PNaCl program, then the manifest
|
| +must contain at least one applicable match for the current ISA
|
| +in “program” and in every entry within “files”.</li>
|
| +</ul>
|
| +<p>If the manifest contains a field that is not in the official
|
| +set of supported fields, it is ignored. This allows the grammar to be
|
| +extended without breaking compatibility with older browsers.</p>
|
| +</section><section id="nexe-matching">
|
| +<h3 id="nexe-matching">Nexe matching</h3>
|
| +<p>For Portable Native Client, there are no architecture variations, so
|
| +matching is simple.</p>
|
| +<p>For Native Client, the main nexe for the application is determined by
|
| +looking up the browser’s current architecture in the <code>"program"</code>
|
| +dictionary. Failure to provide an entry for the browser’s architecture
|
| +will result in a load error.</p>
|
| +</section><section id="file-matching">
|
| +<h3 id="file-matching">File matching</h3>
|
| +<p>All files (shared objects and other assets, typically) are looked up
|
| +by a UTF8 string that is the file name. To load a library with a certain
|
| +file name, the browser searches the <code>"files"</code> dictionary for an entry
|
| +corresponding to that file name. Failure to find that name in the
|
| +<code>"files"</code> dictionary is a run-time error. The architecture matching
|
| +rule for all files is from most to least specific. That is, if there
|
| +is an exact match for the current architecture (e.g., “x86-32”) it is
|
| +used in preference to more general “portable”. This is useful for
|
| +non-architecture-specific asset files. Note that <code>"files"</code> is only
|
| +useful for files that must be loaded early in application startup
|
| +(before PPAPI interfaces are initialized to provide the standard
|
| +file loading mechanisms).</p>
|
| +</section><section id="url-of-the-nmf-file-from-embed-src-and-data-uri">
|
| +<h3 id="url-of-the-nmf-file-from-embed-src-and-data-uri">URL of the nmf file, from <code><embed></code> src, and data URI</h3>
|
| +<p>The URL for the manifest file should be specified by the <code>src</code> attribute
|
| +of the <code><embed></code> tag for a Native Client module instance. The URL for
|
| +a manifest file can refer to an actual file, or it can be a
|
| +<a class="reference external" href="http://en.wikipedia.org/wiki/Data_URI_scheme">data URI</a>
|
| +representing the contents of the file. Specifying the <code>nmf</code> contents
|
| +inline with a data URI can help reduce the amount of network traffic
|
| +required to load the Native Client application.</p>
|
| +</section><section id="url-resolution">
|
| +<span id="nmf-url-resolution"></span><h3 id="url-resolution"><span id="nmf-url-resolution"></span>URL resolution</h3>
|
| +<p>All URLs contained in a manifest are resolved relative to the URL of
|
| +the manifest. If the manifest was specified as a data URI, the URLs must
|
| +all be absolute.</p>
|
| +</section></section></section>
|
| +
|
| +{{/partials.standard_nacl_article}}
|
|
|
Chromium Code Reviews
Issue 140993006:
[NaCl SDK Docs] Check in the generated NaCl SDK Documentation. (Closed)
Base URL: svn://svn.chromium.org/chrome/trunk/src