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