build/docs/preprocessor.rst

   1 .. _preprocessor:
   2
   3 =================
   4 Text Preprocessor
   5 =================
   6
   7 The build system contains a text preprocessor similar to the C preprocessor,
   8 meant for processing files which have no built-in preprocessor such as XUL
   9 and JavaScript documents. It is implemented at ``python/mozbuild/mozbuild/preprocessor.py`` and
  10 is typically invoked via :ref:`jar_manifests`.
  11
  12 While used to preprocess CSS files, the directives are changed to begin with
  13 ``%`` instead of ``#`` to avoid conflict of the id selectors.
  14
  15 Directives
  16 ==========
  17
  18 Variable Definition
  19 -------------------
  20
  21 define
  22 ^^^^^^
  23
  24 ::
  25
  26    #define variable
  27    #define variable value
  28
  29 Defines a preprocessor variable.
  30
  31 Note that, unlike the C preprocessor, instances of this variable later in the
  32 source are not automatically replaced (see #filter). If value is not supplied,
  33 it defaults to ``1``.
  34
  35 Note that whitespace is significant, so ``"#define foo one"`` and
  36 ``"#define foo one "`` is different (in the second case, ``foo`` is defined to
  37 be a four-character string).
  38
  39 undef
  40 ^^^^^
  41
  42 ::
  43
  44    #undef variable
  45
  46 Undefines a preprocessor variable.
  47
  48 Conditionals
  49 ------------
  50
  51 if
  52 ^^
  53
  54 ::
  55
  56    #if variable
  57    #if !variable
  58    #if variable == string
  59    #if variable != string
  60
  61 Disables output if the conditional is false. This can be nested to arbitrary
  62 depths. Note that in the equality checks, the variable must come first.
  63
  64 else
  65 ^^^^
  66
  67 ::
  68
  69    #else
  70
  71 Reverses the state of the previous conditional block; for example, if the
  72 last ``#if`` was true (output was enabled), an ``#else`` makes it off
  73 (output gets disabled).
  74
  75 endif
  76 ^^^^^
  77
  78 ::
  79
  80    #endif
  81
  82 Ends the conditional block.
  83
  84 ifdef / ifndef
  85 ^^^^^^^^^^^^^^
  86
  87 ::
  88
  89    #ifdef variable
  90    #ifndef variable
  91
  92 An ``#if`` conditional that is true only if the preprocessor variable
  93 variable is defined (in the case of ``ifdef``) or not defined (``ifndef``).
  94
  95 elif / elifdef / elifndef
  96 ^^^^^^^^^^^^^^^^^^^^^^^^^
  97
  98 ::
  99
 100    #elif variable
 101    #elif !variable
 102    #elif variable == string
 103    #elif variable != string
 104    #elifdef variable
 105    #elifndef variable
 106
 107 A shorthand to mean an ``#else`` combined with the relevant conditional.
 108 The following two blocks are equivalent::
 109
 110    #ifdef foo
 111      block 1
 112    #elifdef bar
 113      block 2
 114    #endif
 115
 116 ::
 117
 118    #ifdef foo
 119      block 1
 120    #else
 121    #ifdef bar
 122      block 2
 123    #endif
 124    #endif
 125
 126 File Inclusion
 127 --------------
 128
 129 include
 130 ^^^^^^^
 131
 132 ::
 133
 134    #include filename
 135
 136 The file specified by filename is processed as if the contents was placed
 137 at this position. This also means that preprocessor conditionals can even
 138 be started in one file and ended in another (but is highly discouraged).
 139 There is no limit on depth of inclusion, or repeated inclusion of the same
 140 file, or self inclusion; thus, care should be taken to avoid infinite loops.
 141
 142 includesubst
 143 ^^^^^^^^^^^^
 144
 145 ::
 146
 147    #includesubst @variable@filename
 148
 149 Same as a ``#include`` except that all instances of variable in the included
 150 file is also expanded as in ``#filter`` substitution
 151
 152 expand
 153 ^^^^^^
 154
 155 ::
 156
 157    #expand string
 158
 159 All variables wrapped in ``__`` are replaced with their value, for this line
 160 only. If the variable is not defined, it expands to an empty string. For
 161 example, if ``foo`` has the value ``bar``, and ``baz`` is not defined, then::
 162
 163    #expand This <__foo__> <__baz__> gets expanded
 164
 165 Is expanded to::
 166
 167    This <bar> <> gets expanded
 168
 169 filter / unfilter
 170 ^^^^^^^^^^^^^^^^^
 171
 172 ::
 173
 174    #filter filter1 filter2 ... filterN
 175    #unfilter filter1 filter2 ... filterN
 176
 177 ``#filter`` turns on the given filter.
 178
 179 Filters are run in alphabetical order on a per-line basis.
 180
 181 ``#unfilter`` turns off the given filter. Available filters are:
 182
 183 emptyLines
 184    strips blank lines from the output
 185 dumbComments
 186     dumbComments: empties out any line that consists of optional whitespace
 187     followed by a ``//``. Good for getting rid of comments that are on their
 188     own lines, and being smarter with a simple regexp filter is impossible
 189 substitution
 190    all variables wrapped in @ are replaced with their value. If the
 191    variable is not defined, it is a fatal error. Similar to ``#expand``
 192    and ``#filter``
 193 attemptSubstitution
 194    all variables wrapped in ``@`` are replaced with their value, or an
 195    empty string if the variable is not defined. Similar to ``#expand``.
 196
 197 literal
 198 ^^^^^^^
 199
 200 ::
 201
 202    #literal string
 203
 204 Output the string (i.e. the rest of the line) literally, with no other fixups.
 205 This is useful to output lines starting with ``#``, or to temporarily
 206 disable filters.
 207
 208 Other
 209 -----
 210
 211 #error
 212 ^^^^^^
 213
 214 ::
 215
 216    #error string
 217
 218 Cause a fatal error at this point, with the error message being the
 219 given string.