NO BUG - Build docs for text preprocessor and jar manifests

DONTBUILD (NPOTB)

build/docs/index.rst

@@ -25,6 +25,8 @@ Important Concepts
    python
    test_manifests
    mozinfo
+   preprocessor
+   jar-manifests
 
 mozbuild
 ========

build/docs/jar-manifests.rst

@@ -0,0 +1,80 @@
+.. _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 named ``jar.mn``.
+
+``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 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)
+
+A plus marker (``+``) at the beginning of the line indicates that the file
+should replace an existing file, even if the source file's timestamp isn't
+newer than the existing file::
+
+   + path/in/jar/file_name.xul     (source/tree/location/my_file_name.xul)
+
+Preprocessed files always replace existing files, to ensure that changes in
+``#expand`` or ``#include`` directives are picked up, so ``+`` and ``*`` are
+equivalent.
+
+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)
+
+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.

build/docs/preprocessor.rst

@@ -0,0 +1,244 @@
+.. _preprocessor:
+
+=================
+Text Preprocessor
+=================
+
+The build system contains a text preprocessor similar to the C preprocessor,
+meant for processing files which have no built-in preprocessor such as XUL
+and JavaScript documents. It is implemented at ``config/Preprocessor.py`` and
+is typically invoked via :ref:`jar_manifests`.
+
+While used to preprocess CSS files, the directives are changed to begin with
+``%`` instead of ``#`` to avoid conflict of the id selectors.
+
+Directives
+==========
+
+Variable Definition
+-------------------
+
+define
+^^^^^^
+
+::
+
+   #define variable
+   #define variable value
+
+Defines a preprocessor variable.
+
+Note that, unlike the C preprocessor, instances of this variable later in the
+source are not automatically replaced (see #filter). If value is not supplied,
+it defaults to ``1``.
+
+Note that whitespace is significant, so ``"#define foo one"`` and
+``"#define foo one "`` is different (in the second case, ``foo`` is defined to
+be a four-character string).
+
+undef
+^^^^^
+
+::
+
+   #undef variable
+
+Undefines a preprocessor variable.
+
+Conditionals
+------------
+
+if
+^^
+
+::
+
+   #if variable
+   #if !variable
+   #if variable==string
+   #if variable!=string
+
+Disables output if the conditional is false. This can be nested to arbitrary
+depths. Note that in the equality checks, the variable must come first, and
+the comparison operator must not be surrounded by any whitespace.
+
+else
+^^^^
+
+::
+
+   #else
+
+Reverses the state of the previous conditional block; for example, if the
+last ``#if`` was true (output was enabled), an ``#else`` makes it off
+(output gets disabled).
+
+.. warning:: An ``#else`` is relative to the last conditional block only,
+   unlike the C preprocessor.
+
+   It does not matter whether any blocks before it were true. This behavior
+   changed on trunk (Gecko 1.9) on 2006-12-07; see Bug 277122 for details.
+
+::
+
+   #if 1
+     always included
+   #elif 1
+     never included
+   #else
+     always included
+   #endif
+
+endif
+^^^^^
+
+::
+
+   #endif
+
+Ends the conditional block.
+
+ifdef / ifndef
+^^^^^^^^^^^^^^
+
+::
+
+   #ifdef variable
+   #ifndef variable
+
+An ``#if`` conditional that is true only if the preprocessor variable
+variable is defined (in the case of ``ifdef``) or not defined (``ifndef``).
+
+elif / elifdef / elifndef
+^^^^^^^^^^^^^^^^^^^^^^^^^
+
+::
+
+   #elif variable
+   #elif !variable
+   #elif variable == string
+   #elif variable != string
+   #elifdef variable
+   #elifndef variable
+
+A shorthand to mean an ``#else`` combined with the relevant conditional.
+The following two blocks are equivalent::
+
+   #ifdef foo
+     block 1
+   #elifdef bar
+     block 2
+   #endif
+
+::
+
+   #ifdef foo
+     block 1
+   #else
+   #ifdef bar
+     block 2
+   #endif
+   #endif
+
+.. warning:: An ``#elif``, ``#elifdef``, or ``#elifndef`` is relative to
+   the last conditional block only (as well as the condition it implies),
+   unlike the C preprocessor. It does not matter whether any blocks before
+   it were true. This behavior changed on trunk (Gecko 1.9) on 2006-12-07.
+   See Bug 277122 for details.
+
+File Inclusion
+--------------
+
+include
+^^^^^^^
+
+::
+
+   #include filename
+
+The file specified by filename is processed as if the contents was placed
+at this position. This also means that preprocessor conditionals can even
+be started in one file and ended in another (but is highly discouraged).
+There is no limit on depth of inclusion, or repeated inclusion of the same
+file, or self inclusion; thus, care should be taken to avoid infinite loops.
+
+includesubst
+^^^^^^^^^^^^
+
+::
+
+   #includesubst @variable@filename
+
+Same as a ``#include`` except that all instances of variable in the included
+file is also expanded as in ``#filter`` substitution
+
+expand
+^^^^^^
+
+::
+
+   #expand string
+
+All variables wrapped in ``__`` are replaced with their value, for this line
+only. If the variable is not defined, it expands to an empty string. For
+example, if ``foo`` has the value ``bar``, and ``baz`` is not defined, then::
+
+   #expand This <__foo__> <__baz__> gets expanded
+
+Is expanded to::
+
+   This <bar> <> gets expanded
+
+filter / unfilter
+^^^^^^^^^^^^^^^^^
+
+::
+
+   #filter filter1 filter2 ... filterN
+   #unfilter filter1 filter2 ... filterN
+
+``#filter`` turns on the given filter.
+
+Filters are run in alphabetical order on a per-line basis.
+
+``#unfilter`` turns off the given filter. Available filters are:
+
+emptyLines
+   strips blank lines from the output
+slashslash
+   strips everything from the first two consecutive slash (``/``)
+   characters until the end of the line
+spaces
+   collapses consecutive sequences of spaces into a single space,
+   and strips leading and trailing spaces
+substitution
+   all variables wrapped in @ are replaced with their value. If the
+   variable is not defined, it is a fatal error. Similar to ``#expand``
+   and ``#filter``
+attemptSubstitution
+   all variables wrapped in ``@`` are replaced with their value, or an
+   empty string if the variable is not defined. Similar to ``#expand``.
+
+literal
+^^^^^^^
+
+::
+
+   #literal string
+
+Output the string (i.e. the rest of the line) literally, with no other fixups.
+This is useful to output lines starting with ``#``, or to temporarily
+disable filters.
+
+Other
+-----
+
+#error
+^^^^^^
+
+::
+
+   #error string
+
+Cause a fatal error at this point, with the error message being the
+given string.