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