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