1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
|
.. _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 JAR location may be preceded with a base path between square brackets::
[base/path] <jarfile>.jar:
path/in/jar/file_name.xul (source/tree/location/file_name.xul)
In this case, the jar will be directly located under the given ``base/path``,
while without a base path, it will be under a ``chrome`` directory.
If the JAR manifest and packaged file live in the same directory, the path and
parenthesis can be omitted. In other words, the following two lines are
equivalent::
path/in/jar/same_place.xhtml (same_place.xhtml)
path/in/jar/same_place.xhtml
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)
Preprocessed files always replace existing files, to ensure that changes in
``#expand`` or ``#include`` directives are picked up.
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)
The source tree location can also use wildcards, in which case the path in
jar is expected to be a base directory. Paths before the wildcard are not
made part of the destination path::
path/in/jar/ (source/tree/location/*.xul)
The above will install all xul files under ``source/tree/location`` as
``path/in/jar/*.xul``.
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.
|
