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