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 the correct JARs, and create :ref:`Chrome Registration <Chrome Registration>`
   9 manifests. JAR Manifests are commonly named ``jar.mn``. They are
  10 declared in ``moz.build`` files using the ``JAR_MANIFESTS`` variable.
  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 To see a simple ``jar.mn`` file at work, see ``toolkit/profile/jar.mn``. A much
  23 more complex ``jar.mn`` is at ``toolkit/locales/jar.mn``.
  24
  25 Shipping Chrome Files
  26 =====================
  27
  28 To ship chrome files in a JAR, an indented line indicates a file to be packaged::
  29
  30    <jarfile>.jar:
  31      path/in/jar/file_name.xul     (source/tree/location/file_name.xul)
  32
  33 The JAR location may be preceded with a base path between square brackets::
  34    [base/path] <jarfile>.jar:
  35      path/in/jar/file_name.xul     (source/tree/location/file_name.xul)
  36
  37 In this case, the jar will be directly located under the given ``base/path``,
  38 while without a base path, it will be under a ``chrome`` directory.
  39
  40 If the JAR manifest and packaged file live in the same directory, the path and
  41 parenthesis can be omitted. In other words, the following two lines are
  42 equivalent::
  43
  44    path/in/jar/same_place.xhtml     (same_place.xhtml)
  45    path/in/jar/same_place.xhtml
  46
  47 The source tree location may also be an *absolute* path (taken from the
  48 top of the source tree::
  49
  50    path/in/jar/file_name.xul     (/path/in/sourcetree/file_name.xul)
  51
  52 An asterisk marker (``*``) at the beginning of the line indicates that the
  53 file should be processed by the :ref:`preprocessor` before being packaged::
  54
  55    * path/in/jar/preprocessed.xul  (source/tree/location/file_name.xul)
  56
  57 Preprocessed files always replace existing files, to ensure that changes in
  58 ``#expand`` or ``#include`` directives are picked up.
  59
  60 There is a special source-directory format for localized files (note the
  61 percent sign in the source file location): this format reads ``localized.dtd``
  62 from the ``en-US`` directory if building an English version, and reads the
  63 file from the alternate localization source tree
  64 ``/l10n/<locale>/path/localized.dtd`` if building a localized version::
  65
  66    locale/path/localized.dtd     (%localized/path/localized.dtd)
  67
  68 The source tree location can also use wildcards, in which case the path in
  69 jar is expected to be a base directory. Paths before the wildcard are not
  70 made part of the destination path::
  71
  72      path/in/jar/                (source/tree/location/*.xul)
  73
  74 The above will install all xul files under ``source/tree/location`` as
  75 ``path/in/jar/*.xul``.
  76
  77 Register Chrome
  78 ===============
  79
  80 :ref:`Chrome Registration <Chrome Registration>` instructions are marked with a percent sign (``%``) at the beginning of the
  81 line, and must be part of the definition of a JAR file. Any additional percents
  82 signs are replaced with an appropriate relative URL of the JAR file being
  83 packaged::
  84
  85    % content global %path/in/jar/
  86    % overlay chrome://blah/content/blah.xul chrome://foo/content/overlay.xul
  87
  88 There are two possible locations for a manifest file. If the chrome is being
  89 built into a standalone application, the ``jar.mn`` processor creates a
  90 ``<jarfilename>.manifest`` next to the JAR file itself. This is the default
  91 behavior.
  92
  93 If the build specifies ``USE_EXTENSION_MANIFEST = 1``, the ``jar.mn`` processor
  94 creates a single ``chrome.manifest`` file suitable for registering chrome as
  95 an extension.