Roll src/third_party/WebKit e0eac24:489c548 (svn 193311:193320)

[chromium-blink-merge.git] / native_client_sdk / doc_generated / reference / nacl-manifest-format.html

{{+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" id="contents" style="display: none">
<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>&lt;embed&gt;</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><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>
<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
  &quot;program&quot;: { ... }

  // Only required for glibc
  &quot;files&quot;: { ... }
}
</pre>
<h2 id="field-details">Field details</h2>
<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 &#8220;arm&#8221;, &#8220;x86-32&#8221;, and &#8220;x86-64&#8221;). 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>
<h4 id="example-of-a-program-for-portable-native-client">Example of a <code>program</code> for Portable Native Client:</h4>
<pre class="prettyprint">
{
  &quot;program&quot;: {
    &quot;portable&quot;: {
      // Required
      &quot;pnacl-translate&quot;: {
        // url is required
        &quot;url&quot;: &quot;url_to_my_pexe&quot;,

        // optlevel is optional
        &quot;optlevel&quot;: 2
      },
      // pnacl-debug is optional
      &quot;pnacl-debug&quot;: {
        // url is required
        &quot;url&quot;: &quot;url_to_my_bitcode_bc&quot;,

        // optlevel is optional
        &quot;optlevel&quot;: 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&#8217;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>
<p>A <code>pnacl-debug</code> section can specify an unfinalized pnacl llvm bitcode file
for debugging. The <code>url</code> provided in this section will be used when Native
Client debugging is enabled with either the <code>--enable-nacl-debug</code> Chrome
command line switch, or via <code>about://flags</code>.</p>
<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">
{
  &quot;program&quot;: {
    // Required: at least one entry
    // Add one of these for each architecture supported by the application.
    &quot;arm&quot;: { &quot;url&quot;: &quot;url_to_arm_nexe&quot; },
    &quot;x86-32&quot;: { &quot;url&quot;: &quot;url_to_x86_32_nexe&quot; },
    &quot;x86-64&quot;: { &quot;url&quot;: &quot;url_to_x86_64_nexe&quot; }
  }
}
</pre>
<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">
{
  &quot;program&quot;: {
    // Required: at least one entry
    // Add one of these for each architecture supported by the application.
    &quot;x86-32&quot;: { &quot;url&quot;: &quot;lib32/runnable-ld.so&quot; },
    &quot;x86-64&quot;: { &quot;url&quot;: &quot;lib64/runnable-ld.so&quot; }
  },
  // discussed in next section
  &quot;files&quot;: {
    &quot;main.nexe&quot;: {
      &quot;x86-32&quot;: { &quot;url&quot;: &quot;url_to_x86_32_nexe&quot; },
      &quot;x86-64&quot;: { &quot;url&quot;: &quot;url_to_x86_64_nexe&quot; }
    },
    // ...
  }
}
</pre>
<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="/native-client/pepper_stable/cpp/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>&quot;main.nexe&quot;</code> field of the <code>files</code> dictionary.</p>
<pre class="prettyprint">
{
  &quot;program&quot;: {
    &quot;x86-64&quot;: {&quot;url&quot;: &quot;lib64/runnable-ld.so&quot;},
    &quot;x86-32&quot;: {&quot;url&quot;: &quot;lib32/runnable-ld.so&quot;}
  },
  &quot;files&quot;: {
    &quot;main.nexe&quot; : {
      &quot;x86-64&quot;: {&quot;url&quot;: &quot;pi_generator_x86_64.nexe&quot;},
      &quot;x86-32&quot;: {&quot;url&quot;: &quot;pi_generator_x86_32.nexe&quot;}
    },
    &quot;libpthread.so.5055067a&quot; : {
      &quot;x86-64&quot;: {&quot;url&quot;: &quot;lib64/libpthread.so.5055067a&quot;},
      &quot;x86-32&quot;: {&quot;url&quot;: &quot;lib32/libpthread.so.5055067a&quot;}
    },
    &quot;libppapi_cpp.so&quot; : {
      &quot;x86-64&quot;: {&quot;url&quot;: &quot;lib64/libppapi_cpp.so&quot;},
      &quot;x86-32&quot;: {&quot;url&quot;: &quot;lib32/libppapi_cpp.so&quot;}
    },
    &quot;libstdc++.so.6&quot; : {
      &quot;x86-64&quot;: {&quot;url&quot;: &quot;lib64/libstdc++.so.6&quot;},
      &quot;x86-32&quot;: {&quot;url&quot;: &quot;lib32/libstdc++.so.6&quot;}
    },
    &quot;libm.so.5055067a&quot; : {
      &quot;x86-64&quot;: {&quot;url&quot;: &quot;lib64/libm.so.5055067a&quot;},
      &quot;x86-32&quot;: {&quot;url&quot;: &quot;lib32/libm.so.5055067a&quot;}
    },
    &quot;libgcc_s.so.1&quot; : {
      &quot;x86-64&quot;: {&quot;url&quot;: &quot;lib64/libgcc_s.so.1&quot;},
      &quot;x86-32&quot;: {&quot;url&quot;: &quot;lib32/libgcc_s.so.1&quot;}
    },
    &quot;libc.so.5055067a&quot; : {
      &quot;x86-64&quot;: {&quot;url&quot;: &quot;lib64/libc.so.5055067a&quot;},
      &quot;x86-32&quot;: {&quot;url&quot;: &quot;lib32/libc.so.5055067a&quot;}
    }
  }
}
</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>
<h2 id="semantics">Semantics</h2>
<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 &#8220;program&#8221; and in every entry within &#8220;files&#8221;.</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>
<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&#8217;s current architecture in the <code>&quot;program&quot;</code>
dictionary. Failure to provide an entry for the browser&#8217;s architecture
will result in a load error.</p>
<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>&quot;files&quot;</code> dictionary for an entry
corresponding to that file name. Failure to find that name in the
<code>&quot;files&quot;</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., &#8220;x86-32&#8221;) it is
used in preference to more general &#8220;portable&#8221;. This is useful for
non-architecture-specific asset files. Note that <code>&quot;files&quot;</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>
<h3 id="url-of-the-nmf-file-from-embed-src-and-data-uri">URL of the nmf file, from <code>&lt;embed&gt;</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>&lt;embed&gt;</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>
<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>

{{/partials.standard_nacl_article}}