mirror of
https://github.com/mozilla/gecko-dev.git
synced 2024-11-05 08:35:26 +00:00
40438af67c
JAR_MANIFESTS can now be defined in moz.build files. However, due to limitations in rules.mk, only 1 file may be defined at a time. In the future, this restriction will be lifted. But first, better support for JAR manifests in the build config must be built. rules.mk will be updated in the subsequent conversion patch so this patch applied alone doesn't break the build. --HG-- extra : rebase_source : 2521d49a1731b659dd720769e4685715925be590
82 lines
3.4 KiB
ReStructuredText
82 lines
3.4 KiB
ReStructuredText
.. _jar_manifests:
|
|
|
|
=============
|
|
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 <https://developer.mozilla.org/en-US/docs/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
|
|
: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 ``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 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 :ref:`preprocessor` before being packaged::
|
|
|
|
* path/in/jar/preprocessed.xul (source/tree/location/file_name.xul)
|
|
|
|
A plus marker (``+``) at the beginning of the line indicates that the file
|
|
should replace an existing file, even if the source file's timestamp isn't
|
|
newer than the existing file::
|
|
|
|
+ path/in/jar/file_name.xul (source/tree/location/my_file_name.xul)
|
|
|
|
Preprocessed files always replace existing files, to ensure that changes in
|
|
``#expand`` or ``#include`` directives are picked up, so ``+`` and ``*`` are
|
|
equivalent.
|
|
|
|
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 <https://developer.mozilla.org/en-US/docs/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.
|