| OLD | NEW |
|---|
| (Empty) | |
| 1 {{+bindTo:partials.standard_nacl_article}} |
| 2 |
| 3 <section id="native-client-manifest-nmf-format"> |
| 4 <h1 id="native-client-manifest-nmf-format">Native Client Manifest (nmf) Format</
h1> |
| 5 <div class="contents local topic" id="contents"> |
| 6 <ul class="small-gap"> |
| 7 <li><a class="reference internal" href="#overview" id="id1">Overview</a></li> |
| 8 <li><a class="reference internal" href="#field-summary" id="id2">Field summary</
a></li> |
| 9 <li><p class="first"><a class="reference internal" href="#field-details" id="id3
">Field details</a></p> |
| 10 <ul class="small-gap"> |
| 11 <li><a class="reference internal" href="#program" id="id4">program</a></li> |
| 12 <li><a class="reference internal" href="#files" id="id5">files</a></li> |
| 13 </ul> |
| 14 </li> |
| 15 <li><p class="first"><a class="reference internal" href="#semantics" id="id6">Se
mantics</a></p> |
| 16 <ul class="small-gap"> |
| 17 <li><a class="reference internal" href="#schema-validation" id="id7">Schema vali
dation</a></li> |
| 18 <li><a class="reference internal" href="#nexe-matching" id="id8">Nexe matching</
a></li> |
| 19 <li><a class="reference internal" href="#file-matching" id="id9">File matching</
a></li> |
| 20 <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, an
d data URI</a></li> |
| 21 <li><a class="reference internal" href="#url-resolution" id="id11">URL resolutio
n</a></li> |
| 22 </ul> |
| 23 </li> |
| 24 </ul> |
| 25 </div> |
| 26 <section id="overview"> |
| 27 <h2 id="overview">Overview</h2> |
| 28 <p>Every Native Client application has a <a class="reference external" href="htt
p://www.json.org/">JSON-formatted</a> |
| 29 NaCl Manifest File (<code>nmf</code>). The <code>nmf</code> tells the browser wh
ere to |
| 30 download and load your Native Client application files and libraries. |
| 31 The file can also contain configuration options.</p> |
| 32 </section><section id="field-summary"> |
| 33 <h2 id="field-summary">Field summary</h2> |
| 34 <p>The following shows the supported top-level manifest fields. There is one |
| 35 section that discusses each field in detail. The only field that is required |
| 36 is the <code>program</code> field.</p> |
| 37 <pre class="prettyprint"> |
| 38 { |
| 39 // Required |
| 40 "program": { ... } |
| 41 |
| 42 // Only required for glibc |
| 43 "files": { ... } |
| 44 } |
| 45 </pre> |
| 46 </section><section id="field-details"> |
| 47 <h2 id="field-details">Field details</h2> |
| 48 <section id="program"> |
| 49 <h3 id="program">program</h3> |
| 50 <p>The <code>program</code> field specifies the main program that will be loaded |
| 51 in the Native Client runtime environment. For a Portable Native Client |
| 52 application, this is a URL for the statically linked bitcode <code>pexe</code> f
ile. |
| 53 For architecture-specific Native Client applications, this is a list |
| 54 of URLs, one URL for each supported architecture (currently the choices |
| 55 are “arm”, “x86-32”, and “x86-64”). For a dy
namically linked executable, |
| 56 <code>program</code> is the dynamic loader used to load the dynamic executable |
| 57 and its dynamic libraries. See the <a class="reference internal" href="#nmf-url
-resolution"><em>semantics</em></a> |
| 58 section for the rules on URL resolution.</p> |
| 59 <section id="example-of-a-program-for-portable-native-client"> |
| 60 <h4 id="example-of-a-program-for-portable-native-client">Example of a <code>prog
ram</code> for Portable Native Client:</h4> |
| 61 <pre class="prettyprint"> |
| 62 { |
| 63 "program": { |
| 64 "pnacl-translate": { |
| 65 // url is required |
| 66 "url": "url_to_my_pexe" |
| 67 |
| 68 // optlevel is optional |
| 69 "optlevel": 0 |
| 70 } |
| 71 } |
| 72 } |
| 73 </pre> |
| 74 <p>Portable Native Client applications can also specify an <code>optlevel</code>
field. |
| 75 The <code>optlevel</code> field is an optimization level <em>hint</em>, which is
a number |
| 76 (zero and higher). Higher numbers indicate more optimization effort. |
| 77 Setting a higher optimization level will improve the application’s |
| 78 performance, but it will also slow down the first load experience. |
| 79 The default is <code>optlevel</code> is currently <code>2</code>, and values hig
her |
| 80 than 2 are no different than 2. If compute speed is not as important |
| 81 as first load speed, an application could specify an <code>optlevel</code> |
| 82 of <code>0</code>. Note that <code>optlevel</code> is only a <em>hint</em>. In t
he future, the |
| 83 Portable Native Client translator and runtime may <em>automatically</em> choose |
| 84 an <code>optlevel</code> to best balance load time and application performance.<
/p> |
| 85 </section><section id="example-of-a-program-for-statically-linked-native-client-
executables"> |
| 86 <h4 id="example-of-a-program-for-statically-linked-native-client-executables">Ex
ample of a <code>program</code> for statically linked Native Client executables<
/h4> |
| 87 <pre class="prettyprint"> |
| 88 { |
| 89 "program": { |
| 90 // Required: at least one entry |
| 91 // Add one of these for each architecture supported by the application. |
| 92 "arm": { "url": "url_to_arm_nexe" }, |
| 93 "x86-32": { "url": "url_to_x86_32_nexe" }, |
| 94 "x86-64": { "url": "url_to_x86_64_nexe" } |
| 95 } |
| 96 } |
| 97 </pre> |
| 98 </section><section id="example-of-a-program-for-dynamically-linked-native-client
-executables"> |
| 99 <h4 id="example-of-a-program-for-dynamically-linked-native-client-executables">E
xample of a <code>program</code> for dynamically linked Native Client executable
s</h4> |
| 100 <pre class="prettyprint"> |
| 101 { |
| 102 "program": { |
| 103 // Required: at least one entry |
| 104 // Add one of these for each architecture supported by the application. |
| 105 "x86-32": { "url": "lib32/runnable-ld.so" }, |
| 106 "x86-64": { "url": "lib64/runnable-ld.so" } |
| 107 }, |
| 108 // discussed in next section |
| 109 "files": { |
| 110 "main.nexe": { |
| 111 "x86-32": { "url": "url_to_x86_32_nexe" }, |
| 112 "x86-64": { "url": "url_to_x86_64_nexe" } |
| 113 }, |
| 114 // ... |
| 115 } |
| 116 } |
| 117 </pre> |
| 118 </section></section><section id="files"> |
| 119 <h3 id="files">files</h3> |
| 120 <p>The <code>files</code> field specifies a dictionary of file resources to be |
| 121 used by a Native Client application. This is not supported and |
| 122 not needed by Portable Native Client applications (use the PPAPI |
| 123 <a class="reference external" href="https://developers.google.com/native-client/
peppercpp/classpp_1_1_u_r_l_loader">URL Loader interfaces</a> |
| 124 to load resources instead). However, the <code>files</code> manifest field |
| 125 is important for dynamically linked executables, which must |
| 126 load files before PPAPI is initialized. The <code>files</code> dictionary |
| 127 should include the main dynamic program and its dynamic libraries. |
| 128 There should be one file entry that corresponds to each a |
| 129 dynamic library. Each file entry is a dictionary of supported architectures |
| 130 and the URLs where the appropriate Native Client shared object |
| 131 (<code>.so</code>) for that architecture may be found.</p> |
| 132 <p>Since <code>program</code> is used to refer to the dynamic linker that comes |
| 133 with the NaCl port of glibc, the main program is specified in the |
| 134 <code>files</code> dictionary. The main program is specified under the |
| 135 <code>"main.nexe"</code> field of the <code>files</code> dictionary.</
p> |
| 136 <pre class="prettyprint"> |
| 137 { |
| 138 "program": { |
| 139 "x86-64": {"url": "lib64/runnable-ld.so"}, |
| 140 "x86-32": {"url": "lib32/runnable-ld.so"} |
| 141 }, |
| 142 "files": { |
| 143 "main.nexe" : { |
| 144 "x86-64": {"url": "pi_generator_x86_64.nexe"
}, |
| 145 "x86-32": {"url": "pi_generator_x86_32.nexe"
} |
| 146 }, |
| 147 "libpthread.so.5055067a" : { |
| 148 "x86-64": {"url": "lib64/libpthread.so.5055067a&q
uot;}, |
| 149 "x86-32": {"url": "lib32/libpthread.so.5055067a&q
uot;} |
| 150 }, |
| 151 "libppapi_cpp.so" : { |
| 152 "x86-64": {"url": "lib64/libppapi_cpp.so"}, |
| 153 "x86-32": {"url": "lib32/libppapi_cpp.so"} |
| 154 }, |
| 155 "libstdc++.so.6" : { |
| 156 "x86-64": {"url": "lib64/libstdc++.so.6"}, |
| 157 "x86-32": {"url": "lib32/libstdc++.so.6"} |
| 158 }, |
| 159 "libm.so.5055067a" : { |
| 160 "x86-64": {"url": "lib64/libm.so.5055067a"}, |
| 161 "x86-32": {"url": "lib32/libm.so.5055067a"} |
| 162 }, |
| 163 "libgcc_s.so.1" : { |
| 164 "x86-64": {"url": "lib64/libgcc_s.so.1"}, |
| 165 "x86-32": {"url": "lib32/libgcc_s.so.1"} |
| 166 }, |
| 167 "libc.so.5055067a" : { |
| 168 "x86-64": {"url": "lib64/libc.so.5055067a"}, |
| 169 "x86-32": {"url": "lib32/libc.so.5055067a"} |
| 170 } |
| 171 } |
| 172 } |
| 173 </pre> |
| 174 <p>Dynamic libraries that the dynamic program depends upon and links in at progr
am |
| 175 startup must be listed in the <code>files</code> dictionary. Library files that
are |
| 176 loaded after startup using <code>dlopen()</code> should either be listed in the
<code>files</code> |
| 177 dictionary, or should be made accessible by the <code>nacl_io</code> library. T
he |
| 178 <code>nacl_io</code> library provides various file system <em>mounts</em> such a
s HTTP-based |
| 179 file systems and memory-based file systems. The Native Client SDK includes |
| 180 helpful tools for determining library dependencies and generating NaCl manifest |
| 181 files for programs that that use dynamic linking. See |
| 182 <a class="reference internal" href="/native-client/devguide/devcycle/dynamic-loa
ding.html#dynamic-loading-manifest"><em>Generating a Native Client manifest file
for a dynamically linked application</em></a>.</p> |
| 183 </section></section><section id="semantics"> |
| 184 <h2 id="semantics">Semantics</h2> |
| 185 <section id="schema-validation"> |
| 186 <h3 id="schema-validation">Schema validation</h3> |
| 187 <p>Manifests are validated before the program files are downloaded. |
| 188 Schema validation checks the following properties:</p> |
| 189 <ul class="small-gap"> |
| 190 <li>The schema must be valid JSON.</li> |
| 191 <li>The schema must conform to the grammar given above.</li> |
| 192 <li>If the program is not a PNaCl program, then the manifest |
| 193 must contain at least one applicable match for the current ISA |
| 194 in “program” and in every entry within “files”.</li> |
| 195 </ul> |
| 196 <p>If the manifest contains a field that is not in the official |
| 197 set of supported fields, it is ignored. This allows the grammar to be |
| 198 extended without breaking compatibility with older browsers.</p> |
| 199 </section><section id="nexe-matching"> |
| 200 <h3 id="nexe-matching">Nexe matching</h3> |
| 201 <p>For Portable Native Client, there are no architecture variations, so |
| 202 matching is simple.</p> |
| 203 <p>For Native Client, the main nexe for the application is determined by |
| 204 looking up the browser’s current architecture in the <code>"program&q
uot;</code> |
| 205 dictionary. Failure to provide an entry for the browser’s architecture |
| 206 will result in a load error.</p> |
| 207 </section><section id="file-matching"> |
| 208 <h3 id="file-matching">File matching</h3> |
| 209 <p>All files (shared objects and other assets, typically) are looked up |
| 210 by a UTF8 string that is the file name. To load a library with a certain |
| 211 file name, the browser searches the <code>"files"</code> dictionary fo
r an entry |
| 212 corresponding to that file name. Failure to find that name in the |
| 213 <code>"files"</code> dictionary is a run-time error. The architecture
matching |
| 214 rule for all files is from most to least specific. That is, if there |
| 215 is an exact match for the current architecture (e.g., “x86-32”) it i
s |
| 216 used in preference to more general “portable”. This is useful for |
| 217 non-architecture-specific asset files. Note that <code>"files"</code>
is only |
| 218 useful for files that must be loaded early in application startup |
| 219 (before PPAPI interfaces are initialized to provide the standard |
| 220 file loading mechanisms).</p> |
| 221 </section><section id="url-of-the-nmf-file-from-embed-src-and-data-uri"> |
| 222 <h3 id="url-of-the-nmf-file-from-embed-src-and-data-uri">URL of the nmf file, fr
om <code><embed></code> src, and data URI</h3> |
| 223 <p>The URL for the manifest file should be specified by the <code>src</code> att
ribute |
| 224 of the <code><embed></code> tag for a Native Client module instance. The U
RL for |
| 225 a manifest file can refer to an actual file, or it can be a |
| 226 <a class="reference external" href="http://en.wikipedia.org/wiki/Data_URI_scheme
">data URI</a> |
| 227 representing the contents of the file. Specifying the <code>nmf</code> contents |
| 228 inline with a data URI can help reduce the amount of network traffic |
| 229 required to load the Native Client application.</p> |
| 230 </section><section id="url-resolution"> |
| 231 <span id="nmf-url-resolution"></span><h3 id="url-resolution"><span id="nmf-url-r
esolution"></span>URL resolution</h3> |
| 232 <p>All URLs contained in a manifest are resolved relative to the URL of |
| 233 the manifest. If the manifest was specified as a data URI, the URLs must |
| 234 all be absolute.</p> |
| 235 </section></section></section> |
| 236 |
| 237 {{/partials.standard_nacl_article}} |
| OLD | NEW |
|---|
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