preprocessor.rst (4583B)
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.