gecko-dev/build/docs/jar-manifests.rst
Gregory Szorc 40438af67c Bug 774572 - Part 1: Support for defining JAR manifests in moz.build; r=glandium
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
2013-12-13 00:47:02 +09:00

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.