build/docs/jar-manifests.rst

   1 .. _jar_manifests:
   2
   3 =============
   4 JAR Manifests
   5 =============
   6
   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.
  11
  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.
  17
  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.
  21
  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.
  24
  25 Shipping Chrome Files
  26 ======================
  27 General Format
  28 ^^^^^^^^^^^^^^
  29 To ship chrome files in a JAR, an indented line indicates a file to be packaged::
  30
  31    <jarfile>.jar:
  32      path/in/jar/file_name.xul     (source/tree/location/file_name.xul)
  33
  34 Note that file path mappings are listed by destination (left) followed by source (right).
  35
  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>`_::
  40
  41    browser.jar:
  42      content/browser/colorwaycloset.html
  43      content/browser/colorwaycloset.css
  44      content/browser/colorwaycloset.js
  45
  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``::
  47
  48    browser.jar:
  49      content/browser/colorwaycloset.html (colorwaycloset.html)
  50      content/browser/colorwaycloset.css  (colorwaycloset.css)
  51      content/browser/colorwaycloset.js   (colorwaycloset.js)
  52
  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.
  56
  57 Absolute Paths
  58 ^^^^^^^^^^^^^^
  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>`_::
  61
  62    toolkit.jar:
  63      * content/global/pictureinpicture/player.xhtml   (content/player.xhtml)
  64      content/global/pictureinpicture/player.js      (content/player.js)
  65
  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::
  71
  72    * content/mozapps/profile/profileDowngrade.xhtml  (content/profileDowngrade.xhtml)
  73
  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>`_.
  79
  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::
  81
  82    #filter substitution
  83
  84    ...
  85
  86    [localization] @AB_CD@.jar:
  87      crashreporter                                    (%crashreporter/**/*.ftl)
  88      toolkit                                          (%toolkit/**/*.ftl)
  89
  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.
  93
  94 Registering Chrome
  95 ==================
  96
  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
 100 packaged.
 101
 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
 105 behavior.
 106
 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
 109 an extension.
 110
 111 Example
 112 ^^^^^^^
 113
 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/``::
 115
 116    browser.jar:
 117      %  resource builtin-themes %content/builtin-themes/
 118
 119      content/builtin-themes/alpenglow                 (alpenglow/*.svg)
 120      content/builtin-themes/alpenglow/manifest.json   (alpenglow/manifest.json)
 121
 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.