JAR Manifests

  • Revision slug: JAR_Manifests
  • Revision title: JAR Manifests
  • Revision id: 113419
  • Created:
  • Creator: Waldo
  • Is current revision? No
  • Comment Convert last remaining source link to use 'named-source'

Revision Content


JAR Manifests are plaintext files in the mozilla build tree that are used to package chrome files into the correct JARs, and create Chrome Registration manifests. JAR Manifests are named "jar.mn".

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 Build:Text Preprocessor before being passed to the {{wiki.template('Named-source', [ "config/make-jars.pl", "make-jars script" ])}} which processes the manifest. 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 {{template.Source("toolkit/profile/jar.mn")}}. A much more complex jar.mn is at {{template.Source("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 source tree location may also be an "absolute" path (taken from the top of the mozilla/ 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 Build:Text Preprocessor before being packaged:

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

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)

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 Makefile specifies USE_EXTENSION_MANIFEST = 1, the jar.mn processor creates a single chrome.manifest file suitable for registering chrome as an extension.

Finally, in order to be backwards-compatible with the old contents.rdf chrome registration scheme, whenever the jar.mn processor encounters a contents.rdf file, it will automatically add the path of that contents.rdf to the chrome/installed-chrome.txt file. If this behavior is undesirable (for instance, when packaging an extension XPI), set NO_JAR_AUTO_REG = 1 in the makefile to suppress this default behavior.

Revision Source

<p><br>
JAR Manifests are plaintext files in the mozilla build tree that are used to package chrome files into the correct JARs, and create <a href="en/Chrome_Registration">Chrome Registration</a> manifests. JAR Manifests are named "jar.mn".
</p><p>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 <a href="en/Build/Text_Preprocessor">Build:Text Preprocessor</a> before being passed to the {{wiki.template('Named-source', [ "config/make-jars.pl", "make-jars script" ])}} which processes the manifest. 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.
</p><p>To see a simple jar.mn file at work, see {{template.Source("toolkit/profile/jar.mn")}}. A much more complex jar.mn is at {{template.Source("toolkit/locales/jar.mn")}}.
</p>
<h3 name="Shipping_Chrome_Files"> Shipping Chrome Files </h3>
<p>To ship chrome files in a JAR, an indented line indicates a file to be packaged:
</p>
<pre class="eval">&lt;jarfile&gt;.jar:
  path/in/jar/file_name.xul     (source/tree/location/file_name.xul)
</pre>
<p>The source tree location may also be an "absolute" path (taken from the top of the mozilla/ source tree:
</p>
<pre class="eval">  path/in/jar/file_name.xul     (/path/in/sourcetree/file_name.xul)
</pre>
<p>An asterisk marker at the beginning of the line indicates that the file should be processed by the <a href="en/Build/Text_Preprocessor">Build:Text Preprocessor</a> before being packaged:
</p>
<pre class="eval">* path/in/jar/preprocessed.xul  (source/tree/location/file_name.xul)
</pre>
<p>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/&lt;locale&gt;/path/localized.dtd if building a localized version.
</p>
<pre class="eval">  locale/path/localized.dtd     (%localized/path/localized.dtd)
</pre>
<h3 name="Register_Chrome"> Register Chrome </h3>
<p><a href="en/Chrome_Registration">Chrome Registration</a> 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.
</p>
<pre class="eval">% content global %path/in/jar/
% overlay chrome://blah/content/blah.xul chrome://foo/content/overlay.xul
</pre>
<p>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 &lt;jarfilename&gt;.manifest next to the JAR file itself. This is the default behavior.
</p><p>If the build Makefile specifies USE_EXTENSION_MANIFEST = 1, the jar.mn processor creates a single chrome.manifest file suitable for registering chrome as an extension.
</p><p>Finally, in order to be backwards-compatible with the old contents.rdf chrome registration scheme, whenever the jar.mn processor encounters a contents.rdf file, it will automatically add the path of that contents.rdf to the chrome/installed-chrome.txt file. If this behavior is undesirable (for instance, when packaging an extension XPI), set NO_JAR_AUTO_REG = 1 in the makefile to suppress this default behavior.
</p>
Revert to this revision