Native Client Manifest (nmf) Format

Overview

Every Native Client application has a JSON-formatted 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.

{
  // 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 semantics section for the rules on URL resolution.

Example of a program for Portable Native Client:

{
  "program": {
    "portable": {
      // Required
      "pnacl-translate": {
        // url is required
        "url": "url_to_my_pexe",

        // optlevel is optional
        "optlevel": 2
      },
      // pnacl-debug is optional
      "pnacl-debug": {
        // url is required
        "url": "url_to_my_bitcode_bc",

        // 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.

A pnacl-debug section can specify an unfinalized pnacl llvm bitcode file for debugging. The url provided in this section will be used when Native Client debugging is enabled with either the --enable-nacl-debug Chrome command line switch, or via about://flags.

Example of a program for statically linked Native Client executables

{
  "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

{
  "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 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.

{
  "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.

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 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.

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.