1.1 --- /dev/null Thu Jan 01 00:00:00 1970 +0000
1.2 +++ b/build/docs/preprocessor.rst Wed Dec 31 06:09:35 2014 +0100
1.3 @@ -0,0 +1,244 @@
1.4 +.. _preprocessor:
1.5 +
1.6 +=================
1.7 +Text Preprocessor
1.8 +=================
1.9 +
1.10 +The build system contains a text preprocessor similar to the C preprocessor,
1.11 +meant for processing files which have no built-in preprocessor such as XUL
1.12 +and JavaScript documents. It is implemented at ``python/mozbuild/mozbuild/preprocessor.py`` and
1.13 +is typically invoked via :ref:`jar_manifests`.
1.14 +
1.15 +While used to preprocess CSS files, the directives are changed to begin with
1.16 +``%`` instead of ``#`` to avoid conflict of the id selectors.
1.17 +
1.18 +Directives
1.19 +==========
1.20 +
1.21 +Variable Definition
1.22 +-------------------
1.23 +
1.24 +define
1.25 +^^^^^^
1.26 +
1.27 +::
1.28 +
1.29 + #define variable
1.30 + #define variable value
1.31 +
1.32 +Defines a preprocessor variable.
1.33 +
1.34 +Note that, unlike the C preprocessor, instances of this variable later in the
1.35 +source are not automatically replaced (see #filter). If value is not supplied,
1.36 +it defaults to ``1``.
1.37 +
1.38 +Note that whitespace is significant, so ``"#define foo one"`` and
1.39 +``"#define foo one "`` is different (in the second case, ``foo`` is defined to
1.40 +be a four-character string).
1.41 +
1.42 +undef
1.43 +^^^^^
1.44 +
1.45 +::
1.46 +
1.47 + #undef variable
1.48 +
1.49 +Undefines a preprocessor variable.
1.50 +
1.51 +Conditionals
1.52 +------------
1.53 +
1.54 +if
1.55 +^^
1.56 +
1.57 +::
1.58 +
1.59 + #if variable
1.60 + #if !variable
1.61 + #if variable==string
1.62 + #if variable!=string
1.63 +
1.64 +Disables output if the conditional is false. This can be nested to arbitrary
1.65 +depths. Note that in the equality checks, the variable must come first, and
1.66 +the comparison operator must not be surrounded by any whitespace.
1.67 +
1.68 +else
1.69 +^^^^
1.70 +
1.71 +::
1.72 +
1.73 + #else
1.74 +
1.75 +Reverses the state of the previous conditional block; for example, if the
1.76 +last ``#if`` was true (output was enabled), an ``#else`` makes it off
1.77 +(output gets disabled).
1.78 +
1.79 +.. warning:: An ``#else`` is relative to the last conditional block only,
1.80 + unlike the C preprocessor.
1.81 +
1.82 + It does not matter whether any blocks before it were true. This behavior
1.83 + changed on trunk (Gecko 1.9) on 2006-12-07; see Bug 277122 for details.
1.84 +
1.85 +::
1.86 +
1.87 + #if 1
1.88 + always included
1.89 + #elif 1
1.90 + never included
1.91 + #else
1.92 + always included
1.93 + #endif
1.94 +
1.95 +endif
1.96 +^^^^^
1.97 +
1.98 +::
1.99 +
1.100 + #endif
1.101 +
1.102 +Ends the conditional block.
1.103 +
1.104 +ifdef / ifndef
1.105 +^^^^^^^^^^^^^^
1.106 +
1.107 +::
1.108 +
1.109 + #ifdef variable
1.110 + #ifndef variable
1.111 +
1.112 +An ``#if`` conditional that is true only if the preprocessor variable
1.113 +variable is defined (in the case of ``ifdef``) or not defined (``ifndef``).
1.114 +
1.115 +elif / elifdef / elifndef
1.116 +^^^^^^^^^^^^^^^^^^^^^^^^^
1.117 +
1.118 +::
1.119 +
1.120 + #elif variable
1.121 + #elif !variable
1.122 + #elif variable == string
1.123 + #elif variable != string
1.124 + #elifdef variable
1.125 + #elifndef variable
1.126 +
1.127 +A shorthand to mean an ``#else`` combined with the relevant conditional.
1.128 +The following two blocks are equivalent::
1.129 +
1.130 + #ifdef foo
1.131 + block 1
1.132 + #elifdef bar
1.133 + block 2
1.134 + #endif
1.135 +
1.136 +::
1.137 +
1.138 + #ifdef foo
1.139 + block 1
1.140 + #else
1.141 + #ifdef bar
1.142 + block 2
1.143 + #endif
1.144 + #endif
1.145 +
1.146 +.. warning:: An ``#elif``, ``#elifdef``, or ``#elifndef`` is relative to
1.147 + the last conditional block only (as well as the condition it implies),
1.148 + unlike the C preprocessor. It does not matter whether any blocks before
1.149 + it were true. This behavior changed on trunk (Gecko 1.9) on 2006-12-07.
1.150 + See Bug 277122 for details.
1.151 +
1.152 +File Inclusion
1.153 +--------------
1.154 +
1.155 +include
1.156 +^^^^^^^
1.157 +
1.158 +::
1.159 +
1.160 + #include filename
1.161 +
1.162 +The file specified by filename is processed as if the contents was placed
1.163 +at this position. This also means that preprocessor conditionals can even
1.164 +be started in one file and ended in another (but is highly discouraged).
1.165 +There is no limit on depth of inclusion, or repeated inclusion of the same
1.166 +file, or self inclusion; thus, care should be taken to avoid infinite loops.
1.167 +
1.168 +includesubst
1.169 +^^^^^^^^^^^^
1.170 +
1.171 +::
1.172 +
1.173 + #includesubst @variable@filename
1.174 +
1.175 +Same as a ``#include`` except that all instances of variable in the included
1.176 +file is also expanded as in ``#filter`` substitution
1.177 +
1.178 +expand
1.179 +^^^^^^
1.180 +
1.181 +::
1.182 +
1.183 + #expand string
1.184 +
1.185 +All variables wrapped in ``__`` are replaced with their value, for this line
1.186 +only. If the variable is not defined, it expands to an empty string. For
1.187 +example, if ``foo`` has the value ``bar``, and ``baz`` is not defined, then::
1.188 +
1.189 + #expand This <__foo__> <__baz__> gets expanded
1.190 +
1.191 +Is expanded to::
1.192 +
1.193 + This <bar> <> gets expanded
1.194 +
1.195 +filter / unfilter
1.196 +^^^^^^^^^^^^^^^^^
1.197 +
1.198 +::
1.199 +
1.200 + #filter filter1 filter2 ... filterN
1.201 + #unfilter filter1 filter2 ... filterN
1.202 +
1.203 +``#filter`` turns on the given filter.
1.204 +
1.205 +Filters are run in alphabetical order on a per-line basis.
1.206 +
1.207 +``#unfilter`` turns off the given filter. Available filters are:
1.208 +
1.209 +emptyLines
1.210 + strips blank lines from the output
1.211 +slashslash
1.212 + strips everything from the first two consecutive slash (``/``)
1.213 + characters until the end of the line
1.214 +spaces
1.215 + collapses consecutive sequences of spaces into a single space,
1.216 + and strips leading and trailing spaces
1.217 +substitution
1.218 + all variables wrapped in @ are replaced with their value. If the
1.219 + variable is not defined, it is a fatal error. Similar to ``#expand``
1.220 + and ``#filter``
1.221 +attemptSubstitution
1.222 + all variables wrapped in ``@`` are replaced with their value, or an
1.223 + empty string if the variable is not defined. Similar to ``#expand``.
1.224 +
1.225 +literal
1.226 +^^^^^^^
1.227 +
1.228 +::
1.229 +
1.230 + #literal string
1.231 +
1.232 +Output the string (i.e. the rest of the line) literally, with no other fixups.
1.233 +This is useful to output lines starting with ``#``, or to temporarily
1.234 +disable filters.
1.235 +
1.236 +Other
1.237 +-----
1.238 +
1.239 +#error
1.240 +^^^^^^
1.241 +
1.242 +::
1.243 +
1.244 + #error string
1.245 +
1.246 +Cause a fatal error at this point, with the error message being the
1.247 +given string.
