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