1.1 --- /dev/null Thu Jan 01 00:00:00 1970 +0000
1.2 +++ b/build/docs/jar-manifests.rst Wed Dec 31 06:09:35 2014 +0100
1.3 @@ -0,0 +1,81 @@
1.4 +.. _jar_manifests:
1.5 +
1.6 +=============
1.7 +JAR Manifests
1.8 +=============
1.9 +
1.10 +JAR Manifests are plaintext files in the tree that are used to package chrome
1.11 +files into the correct JARs, and create
1.12 +`Chrome Registration <https://developer.mozilla.org/en-US/docs/Chrome_Registration>`_
1.13 +manifests. JAR Manifests are commonly named ``jar.mn``. They are
1.14 +declared in ``moz.build`` files using the ``JAR_MANIFESTS`` variable.
1.15 +
1.16 +``jar.mn`` files are automatically processed by the build system when building a
1.17 +source directory that contains one. The ``jar``.mn is run through the
1.18 +:ref:`preprocessor` before being passed to the manifest processor. In order to
1.19 +have ``@variables@`` expanded (such as ``@AB_CD@``) throughout the file, add
1.20 +the line ``#filter substitution`` at the top of your ``jar.mn`` file.
1.21 +
1.22 +The format of a jar.mn is fairly simple; it consists of a heading specifying
1.23 +which JAR file is being packaged, followed by indented lines listing files and
1.24 +chrome registration instructions.
1.25 +
1.26 +To see a simple ``jar.mn`` file at work, see ``toolkit/profile/jar.mn``. A much
1.27 +more complex ``jar.mn`` is at ``toolkit/locales/jar.mn``.
1.28 +
1.29 +Shipping Chrome Files
1.30 +=====================
1.31 +
1.32 +To ship chrome files in a JAR, an indented line indicates a file to be packaged::
1.33 +
1.34 + <jarfile>.jar:
1.35 + path/in/jar/file_name.xul (source/tree/location/file_name.xul)
1.36 +
1.37 +The source tree location may also be an *absolute* path (taken from the
1.38 +top of the source tree::
1.39 +
1.40 + path/in/jar/file_name.xul (/path/in/sourcetree/file_name.xul)
1.41 +
1.42 +An asterisk marker (``*``) at the beginning of the line indicates that the
1.43 +file should be processed by the :ref:`preprocessor` before being packaged::
1.44 +
1.45 + * path/in/jar/preprocessed.xul (source/tree/location/file_name.xul)
1.46 +
1.47 +A plus marker (``+``) at the beginning of the line indicates that the file
1.48 +should replace an existing file, even if the source file's timestamp isn't
1.49 +newer than the existing file::
1.50 +
1.51 + + path/in/jar/file_name.xul (source/tree/location/my_file_name.xul)
1.52 +
1.53 +Preprocessed files always replace existing files, to ensure that changes in
1.54 +``#expand`` or ``#include`` directives are picked up, so ``+`` and ``*`` are
1.55 +equivalent.
1.56 +
1.57 +There is a special source-directory format for localized files (note the
1.58 +percent sign in the source file location): this format reads ``localized.dtd``
1.59 +from the ``en-US`` directory if building an English version, and reads the
1.60 +file from the alternate localization source tree
1.61 +``/l10n/<locale>/path/localized.dtd`` if building a localized version::
1.62 +
1.63 + locale/path/localized.dtd (%localized/path/localized.dtd)
1.64 +
1.65 +Register Chrome
1.66 +===============
1.67 +
1.68 +`Chrome Registration <https://developer.mozilla.org/en-US/docs/Chrome_Registration>`_
1.69 +instructions are marked with a percent sign (``%``) at the beginning of the
1.70 +line, and must be part of the definition of a JAR file. Any additional percents
1.71 +signs are replaced with an appropriate relative URL of the JAR file being
1.72 +packaged::
1.73 +
1.74 + % content global %path/in/jar/
1.75 + % overlay chrome://blah/content/blah.xul chrome://foo/content/overlay.xul
1.76 +
1.77 +There are two possible locations for a manifest file. If the chrome is being
1.78 +built into a standalone application, the ``jar.mn`` processor creates a
1.79 +``<jarfilename>.manifest`` next to the JAR file itself. This is the default
1.80 +behavior.
1.81 +
1.82 +If the build specifies ``USE_EXTENSION_MANIFEST = 1``, the ``jar.mn`` processor
1.83 +creates a single ``chrome.manifest`` file suitable for registering chrome as
1.84 +an extension.
