native_client_sdk/src/doc/reference/nacl-manifest-format.rst

   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.