nacl-manifest-format.rst revision 5c02ac1a9c1b504631c0a3d2b6e737b5d738bae1
1################################### 2Native Client Manifest (nmf) Format 3################################### 4 5.. contents:: 6 :local: 7 :backlinks: none 8 :depth: 2 9 10Overview 11======== 12 13Every Native Client application has a `JSON-formatted <http://www.json.org/>`_ 14NaCl Manifest File (``nmf``). The ``nmf`` tells the browser where to 15download and load your Native Client application files and libraries. 16The file can also contain configuration options. 17 18 19Field summary 20============= 21 22The following shows the supported top-level manifest fields. There is one 23section that discusses each field in detail. The only field that is required 24is the ``program`` field. 25 26.. naclcode:: 27 28 { 29 // Required 30 "program": { ... } 31 32 // Only required for glibc 33 "files": { ... } 34 } 35 36Field details 37============= 38 39program 40------- 41 42The ``program`` field specifies the main program that will be loaded 43in the Native Client runtime environment. For a Portable Native Client 44application, this is a URL for the statically linked bitcode ``pexe`` file. 45For architecture-specific Native Client applications, this is a list 46of URLs, one URL for each supported architecture (currently the choices 47are "arm", "x86-32", and "x86-64"). For a dynamically linked executable, 48``program`` is the dynamic loader used to load the dynamic executable 49and its dynamic libraries. See the :ref:`semantics <nmf_url_resolution>` 50section for the rules on URL resolution. 51 52Example 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 77Portable Native Client applications can also specify an ``optlevel`` field. 78The ``optlevel`` field is an optimization level *hint*, which is a number 79(zero and higher). Higher numbers indicate more optimization effort. 80Setting a higher optimization level will improve the application's 81performance, but it will also slow down the first load experience. 82The default is ``optlevel`` is currently ``2``, and values higher 83than 2 are no different than 2. If compute speed is not as important 84as first load speed, an application could specify an ``optlevel`` 85of ``0``. Note that ``optlevel`` is only a *hint*. In the future, the 86Portable Native Client translator and runtime may *automatically* choose 87an ``optlevel`` to best balance load time and application performance. 88 89A ``pnacl-debug`` section can specify an unfinalized pnacl llvm bitcode file 90for debugging. The ``url`` provided in this section will be used when Native 91Client debugging is enabled with either the ``--enable-nacl-debug`` Chrome 92command line switch, or via ``about://flags``. 93 94 95Example 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 110Example 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 133files 134----- 135 136The ``files`` field specifies a dictionary of file resources to be used by a 137Native Client application. This is not supported and not needed by Portable 138Native Client applications (use the PPAPI `URL Loader interfaces 139</native-client/pepper_stable/cpp/classpp_1_1_u_r_l_loader>`_ to load resources 140instead). However, the ``files`` manifest field is important for dynamically 141linked executables, which must load files before PPAPI is initialized. The 142``files`` dictionary should include the main dynamic program and its dynamic 143libraries. There should be one file entry that corresponds to each a dynamic 144library. Each file entry is a dictionary of supported architectures and the 145URLs where the appropriate Native Client shared object (``.so``) for that 146architecture may be found. 147 148Since ``program`` is used to refer to the dynamic linker that comes 149with 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 194Dynamic libraries that the dynamic program depends upon and links in at program 195startup must be listed in the ``files`` dictionary. Library files that are 196loaded after startup using ``dlopen()`` should either be listed in the ``files`` 197dictionary, or should be made accessible by the ``nacl_io`` library. The 198``nacl_io`` library provides various file system *mounts* such as HTTP-based 199file systems and memory-based file systems. The Native Client SDK includes 200helpful tools for determining library dependencies and generating NaCl manifest 201files for programs that that use dynamic linking. See 202:ref:`dynamic_loading_manifest`. 203 204Semantics 205========= 206 207Schema validation 208----------------- 209 210Manifests are validated before the program files are downloaded. 211Schema 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 219If the manifest contains a field that is not in the official 220set of supported fields, it is ignored. This allows the grammar to be 221extended without breaking compatibility with older browsers. 222 223 224Nexe matching 225------------- 226 227For Portable Native Client, there are no architecture variations, so 228matching is simple. 229 230For Native Client, the main nexe for the application is determined by 231looking up the browser's current architecture in the ``"program"`` 232dictionary. Failure to provide an entry for the browser's architecture 233will result in a load error. 234 235 236File matching 237------------- 238 239All files (shared objects and other assets, typically) are looked up 240by a UTF8 string that is the file name. To load a library with a certain 241file name, the browser searches the ``"files"`` dictionary for an entry 242corresponding to that file name. Failure to find that name in the 243``"files"`` dictionary is a run-time error. The architecture matching 244rule for all files is from most to least specific. That is, if there 245is an exact match for the current architecture (e.g., "x86-32") it is 246used in preference to more general "portable". This is useful for 247non-architecture-specific asset files. Note that ``"files"`` is only 248useful for files that must be loaded early in application startup 249(before PPAPI interfaces are initialized to provide the standard 250file loading mechanisms). 251 252 253URL of the nmf file, from ``<embed>`` src, and data URI 254------------------------------------------------------- 255 256The URL for the manifest file should be specified by the ``src`` attribute 257of the ``<embed>`` tag for a Native Client module instance. The URL for 258a manifest file can refer to an actual file, or it can be a 259`data URI <http://en.wikipedia.org/wiki/Data_URI_scheme>`_ 260representing the contents of the file. Specifying the ``nmf`` contents 261inline with a data URI can help reduce the amount of network traffic 262required to load the Native Client application. 263 264.. _nmf_url_resolution: 265 266URL resolution 267-------------- 268 269All URLs contained in a manifest are resolved relative to the URL of 270the manifest. If the manifest was specified as a data URI, the URLs must 271all be absolute. 272