Source code

Revision control

Copy as Markdown

Other Tools

.. _jar_manifests:
JAR Manifests
JAR Manifests are plaintext files in the tree that are used to package chrome
files into ``.jar`` files and create :ref:`Chrome Registration <Chrome Registration>`
manifests. JAR Manifests are commonly named ````. They are declared in ```` files using the ``JAR_MANIFESTS`` variable, which makes up a collection of ```` files.
All files declared in JAR Manifests are processed and installed into ``omni.ja`` files in ``browser/`` and ``toolkit/`` when building Firefox.
```` files are automatically processed by the build system when building a
source directory that contains one. The ```` is run through the
:ref:`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 ```` file.
The format of a 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.
For a simple ```` file, see `toolkit/profile/ <>`_. For a much
more complex ```` file, see `toolkit/locales/ <>`_. More examples with specific formats and uses are available below.
Shipping Chrome Files
General Format
To ship chrome files in a JAR, an indented line indicates a file to be packaged::
path/in/jar/file_name.xul (source/tree/location/file_name.xul)
Note that file path mappings are listed by destination (left) followed by source (right).
Same Directory Omission
If the JAR manifest and packaged files live in the same directory, the source path and parentheses can be omitted.
A sample of a ```` file with omitted source paths and parentheses is `this revision of browser/components/colorways/ <>`_::
Writing the following is equivalent, given that the aforementioned files exist in the same directory as the ````. Notice the ``.jar`` file is named ``browser.jar``::
content/browser/colorwaycloset.html (colorwaycloset.html)
content/browser/colorwaycloset.css (colorwaycloset.css)
content/browser/colorwaycloset.js (colorwaycloset.js)
This manifest is responsible for packaging files needed by Colorway Closet, including
JS scripts, localization files, images (ex. PNGs, AVIFs), and CSS styling. Look at `browser/components/colorways/colorwaycloset.html <>`_
to see how a file may be referenced using its chrome URL.
Absolute Paths
The source tree location may also be an absolute path (taken from the top of the source tree).
One such example can be found in `toolkit/components/pictureinpicture/ <>`_::
* content/global/pictureinpicture/player.xhtml (content/player.xhtml)
content/global/pictureinpicture/player.js (content/player.js)
Asterisk Marker (Preprocessing)
An asterisk marker (``*``) at the beginning of the line indicates that the file should be processed by the :ref:`preprocessor` before being packaged.
run through the preprocessor, since it contains ``#ifdef`` and ``#endif`` statements that need to be interpreted::
* content/mozapps/profile/profileDowngrade.xhtml (content/profileDowngrade.xhtml)
Base Path, Variables, Wildcards and Localized Files
The ``.jar`` file location may be preceded with a base path between square brackets.
The file `toolkit/locales/ <>`_ uses a base path so that the ``.jar`` file is under a ``localization`` directory,
It is also named according to the value passed by the variable ``@AB_CD@``, normally a locale. Note the use of the preprocessor directive ``#filter substitution`` at the top of the file for replacing the variable with the value::
#filter substitution
[localization] @AB_CD@.jar:
crashreporter (%crashreporter/**/*.ftl)
toolkit (%toolkit/**/*.ftl)
The percentage sign in front of the source paths designates the locale to target as a source. By default, this is ``en-US``. With this specific example, `/toolkit/locales/en-US <>`_ would be targeted.
Otherwise, the file from an alternate localization source tree ``/l10n/<locale>/toolkit/`` is read if building a localized version.
The wildcards in ``**/*.ftl`` tell the processor to install all Fluent files within the ``crashreporter`` and ``toolkit`` directories, as well as their subdirectories.
Registering Chrome
:ref:`Chrome Registration <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
There are two possible locations for a manifest file. If the chrome is being
built into a standalone application, the ```` processor creates a
``<jarfilename>.manifest`` next to the JAR file itself. This is the default
If the ```` specifies ``USE_EXTENSION_MANIFEST = 1``, the ```` processor
creates a single ``chrome.manifest`` file suitable for registering chrome as
an extension.
The file `browser/themes/addons/ <>`_ registers a ``resource`` chrome package under the name ``builtin-themes``. Its source files are in ``%content/builtin-themes/``::
% resource builtin-themes %content/builtin-themes/
content/builtin-themes/alpenglow (alpenglow/*.svg)
content/builtin-themes/alpenglow/manifest.json (alpenglow/manifest.json)
Notice how other files declare an installation destination using the ``builtin-themes`` resource that is defined. As such, a SVG file ``preview.svg`` for a theme ``Alpenglow`` may be loaded using the resource URL ``resource://builtin-themes/alpenglow/preview.svg``
so that a preview of the theme is available on ``about:addons``. See :ref:`Chrome Registration <Chrome Registration>` for more details on ``resource`` and other manifest instructions.