1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
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}}
|
