The Tor Browser / file comparison
comparison: build/docs/jar-manifests.rst
build/docs/jar-manifests.rst
- branch
- TOR_BUG_9701
- changeset 8
- 97036ab72558
equal
deleted
inserted
replaced
| -1:000000000000 | 0:64096286e999 |
|---|---|
| 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 | |
| 9 `Chrome Registration <https://developer.mozilla.org/en-US/docs/Chrome_Registration>`_ | |
| 10 manifests. JAR Manifests are commonly named ``jar.mn``. They are | |
| 11 declared in ``moz.build`` files using the ``JAR_MANIFESTS`` variable. | |
| 12 | |
| 13 ``jar.mn`` files are automatically processed by the build system when building a | |
| 14 source directory that contains one. The ``jar``.mn is run through the | |
| 15 :ref:`preprocessor` before being passed to the manifest processor. In order to | |
| 16 have ``@variables@`` expanded (such as ``@AB_CD@``) throughout the file, add | |
| 17 the line ``#filter substitution`` at the top of your ``jar.mn`` file. | |
| 18 | |
| 19 The format of a jar.mn is fairly simple; it consists of a heading specifying | |
| 20 which JAR file is being packaged, followed by indented lines listing files and | |
| 21 chrome registration instructions. | |
| 22 | |
| 23 To see a simple ``jar.mn`` file at work, see ``toolkit/profile/jar.mn``. A much | |
| 24 more complex ``jar.mn`` is at ``toolkit/locales/jar.mn``. | |
| 25 | |
| 26 Shipping Chrome Files | |
| 27 ===================== | |
| 28 | |
| 29 To ship chrome files in a JAR, an indented line indicates a file to be packaged:: | |
| 30 | |
| 31 <jarfile>.jar: | |
| 32 path/in/jar/file_name.xul (source/tree/location/file_name.xul) | |
| 33 | |
| 34 The source tree location may also be an *absolute* path (taken from the | |
| 35 top of the source tree:: | |
| 36 | |
| 37 path/in/jar/file_name.xul (/path/in/sourcetree/file_name.xul) | |
| 38 | |
| 39 An asterisk marker (``*``) at the beginning of the line indicates that the | |
| 40 file should be processed by the :ref:`preprocessor` before being packaged:: | |
| 41 | |
| 42 * path/in/jar/preprocessed.xul (source/tree/location/file_name.xul) | |
| 43 | |
| 44 A plus marker (``+``) at the beginning of the line indicates that the file | |
| 45 should replace an existing file, even if the source file's timestamp isn't | |
| 46 newer than the existing file:: | |
| 47 | |
| 48 + path/in/jar/file_name.xul (source/tree/location/my_file_name.xul) | |
| 49 | |
| 50 Preprocessed files always replace existing files, to ensure that changes in | |
| 51 ``#expand`` or ``#include`` directives are picked up, so ``+`` and ``*`` are | |
| 52 equivalent. | |
| 53 | |
| 54 There is a special source-directory format for localized files (note the | |
| 55 percent sign in the source file location): this format reads ``localized.dtd`` | |
| 56 from the ``en-US`` directory if building an English version, and reads the | |
| 57 file from the alternate localization source tree | |
| 58 ``/l10n/<locale>/path/localized.dtd`` if building a localized version:: | |
| 59 | |
| 60 locale/path/localized.dtd (%localized/path/localized.dtd) | |
| 61 | |
| 62 Register Chrome | |
| 63 =============== | |
| 64 | |
| 65 `Chrome Registration <https://developer.mozilla.org/en-US/docs/Chrome_Registration>`_ | |
| 66 instructions are marked with a percent sign (``%``) at the beginning of the | |
| 67 line, and must be part of the definition of a JAR file. Any additional percents | |
| 68 signs are replaced with an appropriate relative URL of the JAR file being | |
| 69 packaged:: | |
| 70 | |
| 71 % content global %path/in/jar/ | |
| 72 % overlay chrome://blah/content/blah.xul chrome://foo/content/overlay.xul | |
| 73 | |
| 74 There are two possible locations for a manifest file. If the chrome is being | |
| 75 built into a standalone application, the ``jar.mn`` processor creates a | |
| 76 ``<jarfilename>.manifest`` next to the JAR file itself. This is the default | |
| 77 behavior. | |
| 78 | |
| 79 If the build specifies ``USE_EXTENSION_MANIFEST = 1``, the ``jar.mn`` processor | |
| 80 creates a single ``chrome.manifest`` file suitable for registering chrome as | |
| 81 an extension. |
