JAR Manifests

JAR Manifests are plaintext files in the tree that are used to package chrome files into the correct JARs, and create Chrome Registration manifests. JAR Manifests are commonly named jar.mn. They are declared in moz.build files using the JAR_MANIFESTS variable.

jar.mn files are automatically processed by the build system when building a source directory that contains one. The jar.mn is run through the Text Preprocessor before being passed to the manifest processor. In order to have @variables@ expanded (such as @AB_CD@) throughout the file, add the line #filter substitution at the top of your jar.mn file.

The format of a jar.mn is fairly simple; it consists of a heading specifying which JAR file is being packaged, followed by indented lines listing files and chrome registration instructions.

To see a simple jar.mn file at work, see toolkit/profile/jar.mn. A much more complex jar.mn is at toolkit/locales/jar.mn.

Shipping Chrome Files

To ship chrome files in a JAR, an indented line indicates a file to be packaged:

<jarfile>.jar:
  path/in/jar/file_name.xul     (source/tree/location/file_name.xul)

The JAR location may be preceded with a base path between square brackets::

[base/path] <jarfile>.jar:

path/in/jar/file_name.xul (source/tree/location/file_name.xul)

In this case, the jar will be directly located under the given base/bath, while without a base path, it will be under a chrome directory.

If the JAR manifest and packaged file live in the same directory, the path and parenthesis can be omitted. In other words, the following two lines are equivalent:

path/in/jar/same_place.xhtml     (same_place.xhtml)
path/in/jar/same_place.xhtml

The source tree location may also be an absolute path (taken from the top of the source tree:

path/in/jar/file_name.xul     (/path/in/sourcetree/file_name.xul)

An asterisk marker (*) at the beginning of the line indicates that the file should be processed by the Text Preprocessor before being packaged:

* path/in/jar/preprocessed.xul  (source/tree/location/file_name.xul)

Preprocessed files always replace existing files, to ensure that changes in #expand or #include directives are picked up.

There is a special source-directory format for localized files (note the percent sign in the source file location): this format reads localized.dtd from the en-US directory if building an English version, and reads the file from the alternate localization source tree /l10n/<locale>/path/localized.dtd if building a localized version:

locale/path/localized.dtd     (%localized/path/localized.dtd)

The source tree location can also use wildcards, in which case the path in jar is expected to be a base directory. Paths before the wildcard are not made part of the destination path:

path/in/jar/                (source/tree/location/*.xul)

The above will install all xul files under source/tree/location as path/in/jar/*.xul.

Register Chrome

Chrome Registration instructions are marked with a percent sign (%) at the beginning of the line, and must be part of the definition of a JAR file. Any additional percents signs are replaced with an appropriate relative URL of the JAR file being packaged:

% content global %path/in/jar/
% overlay chrome://blah/content/blah.xul chrome://foo/content/overlay.xul

There are two possible locations for a manifest file. If the chrome is being built into a standalone application, the jar.mn processor creates a <jarfilename>.manifest next to the JAR file itself. This is the default behavior.

If the build specifies USE_EXTENSION_MANIFEST = 1, the jar.mn processor creates a single chrome.manifest file suitable for registering chrome as an extension.