| ################################### |
| Native Client Manifest (nmf) Format |
| ################################### |
| |
| .. contents:: |
| :local: |
| :backlinks: none |
| :depth: 2 |
| |
| Overview |
| ======== |
| |
| Every Native Client application has a `JSON-formatted <http://www.json.org/>`_ |
| NaCl Manifest File (``nmf``). The ``nmf`` tells the browser where to |
| download and load your Native Client application files and libraries. |
| The file can also contain configuration options. |
| |
| |
| Field summary |
| ============= |
| |
| The following shows the supported top-level manifest fields. There is one |
| section that discusses each field in detail. The only field that is required |
| is the ``program`` field. |
| |
| .. naclcode:: |
| |
| { |
| // Required |
| "program": { ... } |
| |
| // Only required for glibc |
| "files": { ... } |
| } |
| |
| Field details |
| ============= |
| |
| program |
| ------- |
| |
| The ``program`` field specifies the main program that will be loaded |
| in the Native Client runtime environment. For a Portable Native Client |
| application, this is a URL for the statically linked bitcode ``pexe`` file. |
| For architecture-specific Native Client applications, this is a list |
| of URLs, one URL for each supported architecture (currently the choices |
| are "arm", "x86-32", and "x86-64"). For a dynamically linked executable, |
| ``program`` is the dynamic loader used to load the dynamic executable |
| and its dynamic libraries. See the :ref:`semantics <nmf_url_resolution>` |
| section for the rules on URL resolution. |
| |
| Example of a ``program`` for Portable Native Client: |
| ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ |
| |
| .. naclcode:: |
| |
| { |
| "program": { |
| "pnacl-translate": { |
| // url is required |
| "url": "url_to_my_pexe" |
| |
| // optlevel is optional |
| "optlevel": 0 |
| } |
| } |
| } |
| |
| Portable Native Client applications can also specify an ``optlevel`` field. |
| The ``optlevel`` field is an optimization level *hint*, which is a number |
| (zero and higher). Higher numbers indicate more optimization effort. |
| Setting a higher optimization level will improve the application's |
| performance, but it will also slow down the first load experience. |
| The default is ``optlevel`` is currently ``2``, and values higher |
| than 2 are no different than 2. If compute speed is not as important |
| as first load speed, an application could specify an ``optlevel`` |
| of ``0``. Note that ``optlevel`` is only a *hint*. In the future, the |
| Portable Native Client translator and runtime may *automatically* choose |
| an ``optlevel`` to best balance load time and application performance. |
| |
| |
| Example of a ``program`` for statically linked Native Client executables |
| ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ |
| |
| .. naclcode:: |
| |
| { |
| "program": { |
| // Required: at least one entry |
| // Add one of these for each architecture supported by the application. |
| "arm": { "url": "url_to_arm_nexe" }, |
| "x86-32": { "url": "url_to_x86_32_nexe" }, |
| "x86-64": { "url": "url_to_x86_64_nexe" } |
| } |
| } |
| |
| Example of a ``program`` for dynamically linked Native Client executables |
| ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ |
| |
| .. naclcode:: |
| |
| { |
| "program": { |
| // Required: at least one entry |
| // Add one of these for each architecture supported by the application. |
| "x86-32": { "url": "lib32/runnable-ld.so" }, |
| "x86-64": { "url": "lib64/runnable-ld.so" } |
| }, |
| // discussed in next section |
| "files": { |
| "main.nexe": { |
| "x86-32": { "url": "url_to_x86_32_nexe" }, |
| "x86-64": { "url": "url_to_x86_64_nexe" } |
| }, |
| // ... |
| } |
| } |
| |
| |
| files |
| ----- |
| |
| The ``files`` field specifies a dictionary of file resources to be |
| used by a Native Client application. This is not supported and |
| not needed by Portable Native Client applications (use the PPAPI |
| `URL Loader interfaces |
| <https://developers.google.com/native-client/peppercpp/classpp_1_1_u_r_l_loader>`_ |
| to load resources instead). However, the ``files`` manifest field |
| is important for dynamically linked executables, which must |
| load files before PPAPI is initialized. The ``files`` dictionary |
| should include the main dynamic program and its dynamic libraries. |
| There should be one file entry that corresponds to each a |
| dynamic library. Each file entry is a dictionary of supported architectures |
| and the URLs where the appropriate Native Client shared object |
| (``.so``) for that architecture may be found. |
| |
| Since ``program`` is used to refer to the dynamic linker that comes |
| with the NaCl port of glibc, the main program is specified in the |
| ``files`` dictionary. The main program is specified under the |
| ``"main.nexe"`` field of the ``files`` dictionary. |
| |
| |
| .. naclcode:: |
| |
| { |
| "program": { |
| "x86-64": {"url": "lib64/runnable-ld.so"}, |
| "x86-32": {"url": "lib32/runnable-ld.so"} |
| }, |
| "files": { |
| "main.nexe" : { |
| "x86-64": {"url": "pi_generator_x86_64.nexe"}, |
| "x86-32": {"url": "pi_generator_x86_32.nexe"} |
| }, |
| "libpthread.so.5055067a" : { |
| "x86-64": {"url": "lib64/libpthread.so.5055067a"}, |
| "x86-32": {"url": "lib32/libpthread.so.5055067a"} |
| }, |
| "libppapi_cpp.so" : { |
| "x86-64": {"url": "lib64/libppapi_cpp.so"}, |
| "x86-32": {"url": "lib32/libppapi_cpp.so"} |
| }, |
| "libstdc++.so.6" : { |
| "x86-64": {"url": "lib64/libstdc++.so.6"}, |
| "x86-32": {"url": "lib32/libstdc++.so.6"} |
| }, |
| "libm.so.5055067a" : { |
| "x86-64": {"url": "lib64/libm.so.5055067a"}, |
| "x86-32": {"url": "lib32/libm.so.5055067a"} |
| }, |
| "libgcc_s.so.1" : { |
| "x86-64": {"url": "lib64/libgcc_s.so.1"}, |
| "x86-32": {"url": "lib32/libgcc_s.so.1"} |
| }, |
| "libc.so.5055067a" : { |
| "x86-64": {"url": "lib64/libc.so.5055067a"}, |
| "x86-32": {"url": "lib32/libc.so.5055067a"} |
| } |
| } |
| } |
| |
| |
| Dynamic libraries that the dynamic program depends upon and links in |
| at program startup must be listed in the ``files`` dictionary. |
| Library files that are loaded after startup using ``dlopen()`` should either |
| be listed in the ``files`` dictionary, or should be made accessible |
| by the ``nacl_io`` library. The ``nacl_io`` library provides various |
| file system *mounts* such as HTTP-based file systems and memory-based |
| file systems. The Native Client SDK includes helpful tools for |
| determining library dependencies and generating NaCl manifest files |
| for programs that that use dynamic linking. See |
| `Generating a Native Client manifest file for a dynamically linked application |
| <https://developers.google.com/native-client/devguide/devcycle/dynamic-loading#manifest>`_. |
| |
| .. TODO(jvoung) update the link when glibc document is linkable. |
| |
| |
| Semantics |
| ========= |
| |
| Schema validation |
| ----------------- |
| |
| Manifests are validated before the program files are downloaded. |
| Schema validation checks the following properties: |
| |
| * The schema must be valid JSON. |
| * The schema must conform to the grammar given above. |
| * If the program is not a PNaCl program, then the manifest |
| must contain at least one applicable match for the current ISA |
| in "program" and in every entry within "files". |
| |
| If the manifest contains a field that is not in the official |
| set of supported fields, it is ignored. This allows the grammar to be |
| extended without breaking compatibility with older browsers. |
| |
| |
| Nexe matching |
| ------------- |
| |
| For Portable Native Client, there are no architecture variations, so |
| matching is simple. |
| |
| For Native Client, the main nexe for the application is determined by |
| looking up the browser's current architecture in the ``"program"`` |
| dictionary. Failure to provide an entry for the browser's architecture |
| will result in a load error. |
| |
| |
| File matching |
| ------------- |
| |
| All files (shared objects and other assets, typically) are looked up |
| by a UTF8 string that is the file name. To load a library with a certain |
| file name, the browser searches the ``"files"`` dictionary for an entry |
| corresponding to that file name. Failure to find that name in the |
| ``"files"`` dictionary is a run-time error. The architecture matching |
| rule for all files is from most to least specific. That is, if there |
| is an exact match for the current architecture (e.g., "x86-32") it is |
| used in preference to more general "portable". This is useful for |
| non-architecture-specific asset files. Note that ``"files"`` is only |
| useful for files that must be loaded early in application startup |
| (before PPAPI interfaces are initialized to provide the standard |
| file loading mechanisms). |
| |
| |
| URL of the nmf file, from ``<embed>`` src, and data URI |
| ------------------------------------------------------- |
| |
| The URL for the manifest file should be specified by the ``src`` attribute |
| of the ``<embed>`` tag for a Native Client module instance. The URL for |
| a manifest file can refer to an actual file, or it can be a |
| `data URI <http://en.wikipedia.org/wiki/Data_URI_scheme>`_ |
| representing the contents of the file. Specifying the ``nmf`` contents |
| inline with a data URI can help reduce the amount of network traffic |
| required to load the Native Client application. |
| |
| .. _nmf_url_resolution: |
| |
| URL resolution |
| -------------- |
| |
| All URLs contained in a manifest are resolved relative to the URL of |
| the manifest. If the manifest was specified as a data URI, the URLs must |
| all be absolute. |