7 JAR Manifests are plaintext files in the tree that are used to package chrome
8 files into ``.jar`` files and create :ref:`Chrome Registration <Chrome Registration>`
9 manifests. JAR Manifests are commonly named ``jar.mn``. They are declared in ``moz.build`` files using the ``JAR_MANIFESTS`` variable, which makes up a collection of ``jar.mn`` files.
10 All files declared in JAR Manifests are processed and installed into ``omni.ja`` files in ``browser/`` and ``toolkit/`` when building Firefox.
12 ``jar.mn`` files are automatically processed by the build system when building a
13 source directory that contains one. The ``jar.mn`` is run through the
14 :ref:`preprocessor` before being passed to the manifest processor. In order to
15 have ``@variables@`` expanded (such as ``@AB_CD@``) throughout the file, add
16 the line ``#filter substitution`` at the top of your ``jar.mn`` file.
18 The format of a jar.mn is fairly simple; it consists of a heading specifying
19 which JAR file is being packaged, followed by indented lines listing files and
20 chrome registration instructions.
22 For a simple ``jar.mn`` file, see `toolkit/profile/jar.mn <https://searchfox.org/mozilla-central/rev/5b2d2863bd315f232a3f769f76e0eb16cdca7cb0/toolkit/profile/jar.mn>`_. For a much
23 more complex ``jar.mn`` file, see `toolkit/locales/jar.mn <https://searchfox.org/mozilla-central/rev/5b2d2863bd315f232a3f769f76e0eb16cdca7cb0/toolkit/locales/jar.mn>`_. More examples with specific formats and uses are available below.
26 ======================
29 To ship chrome files in a JAR, an indented line indicates a file to be packaged::
32 path/in/jar/file_name.xul (source/tree/location/file_name.xul)
34 Note that file path mappings are listed by destination (left) followed by source (right).
36 Same Directory Omission
37 ^^^^^^^^^^^^^^^^^^^^^^^
38 If the JAR manifest and packaged files live in the same directory, the source path and parentheses can be omitted.
39 A sample of a ``jar.mn`` file with omitted source paths and parentheses is `this revision of browser/components/colorways/jar.mn <https://searchfox.org/mozilla-central/rev/5b2d2863bd315f232a3f769f76e0eb16cdca7cb0/browser/components/colorways/jar.mn>`_::
42 content/browser/colorwaycloset.html
43 content/browser/colorwaycloset.css
44 content/browser/colorwaycloset.js
46 Writing the following is equivalent, given that the aforementioned files exist in the same directory as the ``jar.mn``. Notice the ``.jar`` file is named ``browser.jar``::
49 content/browser/colorwaycloset.html (colorwaycloset.html)
50 content/browser/colorwaycloset.css (colorwaycloset.css)
51 content/browser/colorwaycloset.js (colorwaycloset.js)
53 This manifest is responsible for packaging files needed by Colorway Closet, including
54 JS scripts, localization files, images (ex. PNGs, AVIFs), and CSS styling. Look at `browser/components/colorways/colorwaycloset.html <https://searchfox.org/mozilla-central/rev/5b2d2863bd315f232a3f769f76e0eb16cdca7cb0/browser/components/colorways/colorwaycloset.html#18>`_
55 to see how a file may be referenced using its chrome URL.
59 The source tree location may also be an absolute path (taken from the top of the source tree).
60 One such example can be found in `toolkit/components/pictureinpicture/jar.mn <https://searchfox.org/mozilla-central/rev/2005e8d87ee045f19dac58e5bff32eff7d01bc9b/toolkit/components/pictureinpicture/jar.mn>`_::
63 * content/global/pictureinpicture/player.xhtml (content/player.xhtml)
64 content/global/pictureinpicture/player.js (content/player.js)
66 Asterisk Marker (Preprocessing)
67 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
68 An asterisk marker (``*``) at the beginning of the line indicates that the file should be processed by the :ref:`preprocessor` before being packaged.
69 The file `toolkit/profile/jar.mn <https://searchfox.org/mozilla-central/rev/5b2d2863bd315f232a3f769f76e0eb16cdca7cb0/toolkit/profile/jar.mn>`_ indicates that the file `toolkit/profile/content/profileDowngrade.xhtml <https://searchfox.org/mozilla-central/rev/2005e8d87ee045f19dac58e5bff32eff7d01bc9b/toolkit/profile/content/profileDowngrade.xhtml#34,36>`_ should be
70 run through the preprocessor, since it contains ``#ifdef`` and ``#endif`` statements that need to be interpreted::
72 * content/mozapps/profile/profileDowngrade.xhtml (content/profileDowngrade.xhtml)
74 Base Path, Variables, Wildcards and Localized Files
75 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
76 The ``.jar`` file location may be preceded with a base path between square brackets.
77 The file `toolkit/locales/jar.mn <https://searchfox.org/mozilla-central/rev/5b2d2863bd315f232a3f769f76e0eb16cdca7cb0/toolkit/locales/jar.mn>`_ uses a base path so that the ``.jar`` file is under a ``localization`` directory,
78 which is a `special directory parsed by mozbuild <https://searchfox.org/mozilla-central/rev/2005e8d87ee045f19dac58e5bff32eff7d01bc9b/python/mozbuild/mozpack/packager/l10n.py#260-265>`_.
80 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::
86 [localization] @AB_CD@.jar:
87 crashreporter (%crashreporter/**/*.ftl)
88 toolkit (%toolkit/**/*.ftl)
90 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 <https://searchfox.org/mozilla-central/source/toolkit/locales/en-US>`_ would be targeted.
91 Otherwise, the file from an alternate localization source tree ``/l10n/<locale>/toolkit/`` is read if building a localized version.
92 The wildcards in ``**/*.ftl`` tell the processor to install all Fluent files within the ``crashreporter`` and ``toolkit`` directories, as well as their subdirectories.
97 :ref:`Chrome Registration <Chrome Registration>` instructions are marked with a percent sign (``%``) at the beginning of the
98 line, and must be part of the definition of a JAR file. Any additional percents
99 signs are replaced with an appropriate relative URL of the JAR file being
102 There are two possible locations for a manifest file. If the chrome is being
103 built into a standalone application, the ``jar.mn`` processor creates a
104 ``<jarfilename>.manifest`` next to the JAR file itself. This is the default
107 If the ``moz.build`` specifies ``USE_EXTENSION_MANIFEST = 1``, the ``jar.mn`` processor
108 creates a single ``chrome.manifest`` file suitable for registering chrome as
114 The file `browser/themes/addons/jar.mn <https://searchfox.org/mozilla-central/rev/5b2d2863bd315f232a3f769f76e0eb16cdca7cb0/browser/themes/addons/jar.mn>`_ registers a ``resource`` chrome package under the name ``builtin-themes``. Its source files are in ``%content/builtin-themes/``::
117 % resource builtin-themes %content/builtin-themes/
119 content/builtin-themes/alpenglow (alpenglow/*.svg)
120 content/builtin-themes/alpenglow/manifest.json (alpenglow/manifest.json)
122 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``
123 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.