nacl-manifest-format.html revision 116680a4aac90f2aa7413d9095a592090648e557
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" id="contents" style="display: none"> 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">Semantics</a></p> 16<ul class="small-gap"> 17<li><a class="reference internal" href="#schema-validation" id="id7">Schema validation</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, and data URI</a></li> 21<li><a class="reference internal" href="#url-resolution" id="id11">URL resolution</a></li> 22</ul> 23</li> 24</ul> 25 26</div><section id="overview"> 27<h2 id="overview">Overview</h2> 28<p>Every Native Client application has a <a class="reference external" href="http://www.json.org/">JSON-formatted</a> 29NaCl Manifest File (<code>nmf</code>). The <code>nmf</code> tells the browser where to 30download and load your Native Client application files and libraries. 31The 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 35section that discusses each field in detail. The only field that is required 36is 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 51in the Native Client runtime environment. For a Portable Native Client 52application, this is a URL for the statically linked bitcode <code>pexe</code> file. 53For architecture-specific Native Client applications, this is a list 54of URLs, one URL for each supported architecture (currently the choices 55are “arm”, “x86-32”, and “x86-64”). For a dynamically linked executable, 56<code>program</code> is the dynamic loader used to load the dynamic executable 57and its dynamic libraries. See the <a class="reference internal" href="#nmf-url-resolution"><em>semantics</em></a> 58section 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>program</code> for Portable Native Client:</h4> 61<pre class="prettyprint"> 62{ 63 "program": { 64 "portable": { 65 // Required 66 "pnacl-translate": { 67 // url is required 68 "url": "url_to_my_pexe", 69 70 // optlevel is optional 71 "optlevel": 2 72 }, 73 // pnacl-debug is optional 74 "pnacl-debug": { 75 // url is required 76 "url": "url_to_my_bitcode_bc", 77 78 // optlevel is optional 79 "optlevel": 0 80 } 81 } 82 } 83} 84</pre> 85<p>Portable Native Client applications can also specify an <code>optlevel</code> field. 86The <code>optlevel</code> field is an optimization level <em>hint</em>, which is a number 87(zero and higher). Higher numbers indicate more optimization effort. 88Setting a higher optimization level will improve the application’s 89performance, but it will also slow down the first load experience. 90The default is <code>optlevel</code> is currently <code>2</code>, and values higher 91than 2 are no different than 2. If compute speed is not as important 92as first load speed, an application could specify an <code>optlevel</code> 93of <code>0</code>. Note that <code>optlevel</code> is only a <em>hint</em>. In the future, the 94Portable Native Client translator and runtime may <em>automatically</em> choose 95an <code>optlevel</code> to best balance load time and application performance.</p> 96<p>A <code>pnacl-debug</code> section can specify an unfinalized pnacl llvm bitcode file 97for debugging. The <code>url</code> provided in this section will be used when Native 98Client debugging is enabled with either the <code>--enable-nacl-debug</code> Chrome 99command line switch, or via <code>about://flags</code>.</p> 100</section><section id="example-of-a-program-for-statically-linked-native-client-executables"> 101<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> 102<pre class="prettyprint"> 103{ 104 "program": { 105 // Required: at least one entry 106 // Add one of these for each architecture supported by the application. 107 "arm": { "url": "url_to_arm_nexe" }, 108 "x86-32": { "url": "url_to_x86_32_nexe" }, 109 "x86-64": { "url": "url_to_x86_64_nexe" } 110 } 111} 112</pre> 113</section><section id="example-of-a-program-for-dynamically-linked-native-client-executables"> 114<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> 115<pre class="prettyprint"> 116{ 117 "program": { 118 // Required: at least one entry 119 // Add one of these for each architecture supported by the application. 120 "x86-32": { "url": "lib32/runnable-ld.so" }, 121 "x86-64": { "url": "lib64/runnable-ld.so" } 122 }, 123 // discussed in next section 124 "files": { 125 "main.nexe": { 126 "x86-32": { "url": "url_to_x86_32_nexe" }, 127 "x86-64": { "url": "url_to_x86_64_nexe" } 128 }, 129 // ... 130 } 131} 132</pre> 133</section></section><section id="files"> 134<h3 id="files">files</h3> 135<p>The <code>files</code> field specifies a dictionary of file resources to be used by a 136Native Client application. This is not supported and not needed by Portable 137Native 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 138instead). However, the <code>files</code> manifest field is important for dynamically 139linked executables, which must load files before PPAPI is initialized. The 140<code>files</code> dictionary should include the main dynamic program and its dynamic 141libraries. There should be one file entry that corresponds to each a dynamic 142library. Each file entry is a dictionary of supported architectures and the 143URLs where the appropriate Native Client shared object (<code>.so</code>) for that 144architecture may be found.</p> 145<p>Since <code>program</code> is used to refer to the dynamic linker that comes 146with the NaCl port of glibc, the main program is specified in the 147<code>files</code> dictionary. The main program is specified under the 148<code>"main.nexe"</code> field of the <code>files</code> dictionary.</p> 149<pre class="prettyprint"> 150{ 151 "program": { 152 "x86-64": {"url": "lib64/runnable-ld.so"}, 153 "x86-32": {"url": "lib32/runnable-ld.so"} 154 }, 155 "files": { 156 "main.nexe" : { 157 "x86-64": {"url": "pi_generator_x86_64.nexe"}, 158 "x86-32": {"url": "pi_generator_x86_32.nexe"} 159 }, 160 "libpthread.so.5055067a" : { 161 "x86-64": {"url": "lib64/libpthread.so.5055067a"}, 162 "x86-32": {"url": "lib32/libpthread.so.5055067a"} 163 }, 164 "libppapi_cpp.so" : { 165 "x86-64": {"url": "lib64/libppapi_cpp.so"}, 166 "x86-32": {"url": "lib32/libppapi_cpp.so"} 167 }, 168 "libstdc++.so.6" : { 169 "x86-64": {"url": "lib64/libstdc++.so.6"}, 170 "x86-32": {"url": "lib32/libstdc++.so.6"} 171 }, 172 "libm.so.5055067a" : { 173 "x86-64": {"url": "lib64/libm.so.5055067a"}, 174 "x86-32": {"url": "lib32/libm.so.5055067a"} 175 }, 176 "libgcc_s.so.1" : { 177 "x86-64": {"url": "lib64/libgcc_s.so.1"}, 178 "x86-32": {"url": "lib32/libgcc_s.so.1"} 179 }, 180 "libc.so.5055067a" : { 181 "x86-64": {"url": "lib64/libc.so.5055067a"}, 182 "x86-32": {"url": "lib32/libc.so.5055067a"} 183 } 184 } 185} 186</pre> 187<p>Dynamic libraries that the dynamic program depends upon and links in at program 188startup must be listed in the <code>files</code> dictionary. Library files that are 189loaded after startup using <code>dlopen()</code> should either be listed in the <code>files</code> 190dictionary, or should be made accessible by the <code>nacl_io</code> library. The 191<code>nacl_io</code> library provides various file system <em>mounts</em> such as HTTP-based 192file systems and memory-based file systems. The Native Client SDK includes 193helpful tools for determining library dependencies and generating NaCl manifest 194files for programs that that use dynamic linking. See 195<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> 196</section></section><section id="semantics"> 197<h2 id="semantics">Semantics</h2> 198<section id="schema-validation"> 199<h3 id="schema-validation">Schema validation</h3> 200<p>Manifests are validated before the program files are downloaded. 201Schema validation checks the following properties:</p> 202<ul class="small-gap"> 203<li>The schema must be valid JSON.</li> 204<li>The schema must conform to the grammar given above.</li> 205<li>If the program is not a PNaCl program, then the manifest 206must contain at least one applicable match for the current ISA 207in “program” and in every entry within “files”.</li> 208</ul> 209<p>If the manifest contains a field that is not in the official 210set of supported fields, it is ignored. This allows the grammar to be 211extended without breaking compatibility with older browsers.</p> 212</section><section id="nexe-matching"> 213<h3 id="nexe-matching">Nexe matching</h3> 214<p>For Portable Native Client, there are no architecture variations, so 215matching is simple.</p> 216<p>For Native Client, the main nexe for the application is determined by 217looking up the browser’s current architecture in the <code>"program"</code> 218dictionary. Failure to provide an entry for the browser’s architecture 219will result in a load error.</p> 220</section><section id="file-matching"> 221<h3 id="file-matching">File matching</h3> 222<p>All files (shared objects and other assets, typically) are looked up 223by a UTF8 string that is the file name. To load a library with a certain 224file name, the browser searches the <code>"files"</code> dictionary for an entry 225corresponding to that file name. Failure to find that name in the 226<code>"files"</code> dictionary is a run-time error. The architecture matching 227rule for all files is from most to least specific. That is, if there 228is an exact match for the current architecture (e.g., “x86-32”) it is 229used in preference to more general “portable”. This is useful for 230non-architecture-specific asset files. Note that <code>"files"</code> is only 231useful for files that must be loaded early in application startup 232(before PPAPI interfaces are initialized to provide the standard 233file loading mechanisms).</p> 234</section><section id="url-of-the-nmf-file-from-embed-src-and-data-uri"> 235<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> 236<p>The URL for the manifest file should be specified by the <code>src</code> attribute 237of the <code><embed></code> tag for a Native Client module instance. The URL for 238a manifest file can refer to an actual file, or it can be a 239<a class="reference external" href="http://en.wikipedia.org/wiki/Data_URI_scheme">data URI</a> 240representing the contents of the file. Specifying the <code>nmf</code> contents 241inline with a data URI can help reduce the amount of network traffic 242required to load the Native Client application.</p> 243</section><section id="url-resolution"> 244<span id="nmf-url-resolution"></span><h3 id="url-resolution"><span id="nmf-url-resolution"></span>URL resolution</h3> 245<p>All URLs contained in a manifest are resolved relative to the URL of 246the manifest. If the manifest was specified as a data URI, the URLs must 247all be absolute.</p> 248</section></section></section> 249 250{{/partials.standard_nacl_article}} 251