| 1 |
--- |
| 2 |
short-description: Syntax and structure of Meson files |
| 3 |
... |
| 4 |
|
| 5 |
# Syntax |
| 6 |
|
| 7 |
The syntax of Meson's specification language has been kept as simple |
| 8 |
as possible. It is *strongly typed* so no object is ever converted to |
| 9 |
another under the covers. Variables have no visible type which makes |
| 10 |
Meson *dynamically typed* (also known as *duck typed*). |
| 11 |
|
| 12 |
The main building blocks of the language are *variables*, *numbers*, |
| 13 |
*booleans*, *strings*, *arrays*, *function calls*, *method calls*, *if |
| 14 |
statements* and *includes*. |
| 15 |
|
| 16 |
Usually one Meson statement takes just one line. There is no way to |
| 17 |
have multiple statements on one line as in e.g. *C*. Function and |
| 18 |
method calls' argument lists can be split over multiple lines. Meson |
| 19 |
will autodetect this case and do the right thing. |
| 20 |
|
| 21 |
In other cases, *(added 0.50)* you can get multi-line statements by |
| 22 |
ending the line with a `\`. Apart from line ending whitespace has no |
| 23 |
syntactic meaning. |
| 24 |
|
| 25 |
## Variables |
| 26 |
|
| 27 |
Variables in Meson work just like in other high level programming |
| 28 |
languages. A variable can contain a value of any type, such as an |
| 29 |
integer or a string. Variables don't need to be predeclared, you can |
| 30 |
just assign to them and they appear. Here's how you would assign |
| 31 |
values to two different variables. |
| 32 |
|
| 33 |
```meson |
| 34 |
var1 = 'hello' |
| 35 |
var2 = 102 |
| 36 |
``` |
| 37 |
|
| 38 |
One important difference in how variables work in Meson is that all |
| 39 |
objects are immutable. When you see an operation which appears like |
| 40 |
a mutation, actually a new object is created and assigned to the |
| 41 |
name. This is different from, for example, how Python works for |
| 42 |
objects, but similar to e.g. Python strings. |
| 43 |
|
| 44 |
```meson |
| 45 |
var1 = [1, 2, 3] |
| 46 |
var2 = var1 |
| 47 |
var2 += [4] |
| 48 |
# var2 is now [1, 2, 3, 4] |
| 49 |
# var1 is still [1, 2, 3] |
| 50 |
``` |
| 51 |
|
| 52 |
## Numbers |
| 53 |
|
| 54 |
Meson supports only integer numbers. They are declared simply by |
| 55 |
writing them out. Basic arithmetic operations are supported. |
| 56 |
|
| 57 |
```meson |
| 58 |
x = 1 + 2 |
| 59 |
y = 3 * 4 |
| 60 |
d = 5 % 3 # Yields 2. |
| 61 |
``` |
| 62 |
|
| 63 |
Hexadecimal literals are supported since version 0.45.0: |
| 64 |
|
| 65 |
```meson |
| 66 |
int_255 = 0xFF |
| 67 |
``` |
| 68 |
|
| 69 |
Octal and binary literals are supported since version 0.47.0: |
| 70 |
|
| 71 |
```meson |
| 72 |
int_493 = 0o755 |
| 73 |
int_1365 = 0b10101010101 |
| 74 |
``` |
| 75 |
|
| 76 |
Strings can be converted to a number like this: |
| 77 |
|
| 78 |
```meson |
| 79 |
string_var = '42' |
| 80 |
num = string_var.to_int() |
| 81 |
``` |
| 82 |
|
| 83 |
Numbers can be converted to a string: |
| 84 |
|
| 85 |
```meson |
| 86 |
int_var = 42 |
| 87 |
string_var = int_var.to_string() |
| 88 |
``` |
| 89 |
|
| 90 |
## Booleans |
| 91 |
|
| 92 |
A boolean is either `true` or `false`. |
| 93 |
|
| 94 |
```meson |
| 95 |
truth = true |
| 96 |
``` |
| 97 |
|
| 98 |
Booleans can be converted to a string or to a number: |
| 99 |
|
| 100 |
```meson |
| 101 |
bool_var = true |
| 102 |
string_var = bool_var.to_string() |
| 103 |
int_var = bool_var.to_int() |
| 104 |
``` |
| 105 |
|
| 106 |
## Strings |
| 107 |
|
| 108 |
Strings in Meson are declared with single quotes. To enter a literal |
| 109 |
single quote do it like this: |
| 110 |
|
| 111 |
```meson |
| 112 |
single_quote = 'contains a \' character' |
| 113 |
``` |
| 114 |
|
| 115 |
The full list of escape sequences is: |
| 116 |
|
| 117 |
* `\\` Backslash |
| 118 |
* `\'` Single quote |
| 119 |
* `\a` Bell |
| 120 |
* `\b` Backspace |
| 121 |
* `\f` Formfeed |
| 122 |
* `\n` Newline |
| 123 |
* `\r` Carriage Return |
| 124 |
* `\t` Horizontal Tab |
| 125 |
* `\v` Vertical Tab |
| 126 |
* `\ooo` Character with octal value ooo |
| 127 |
* `\xhh` Character with hex value hh |
| 128 |
* `\uxxxx` Character with 16-bit hex value xxxx |
| 129 |
* `\Uxxxxxxxx` Character with 32-bit hex value xxxxxxxx |
| 130 |
* `\N{name}` Character named name in Unicode database |
| 131 |
|
| 132 |
As in python and C, up to three octal digits are accepted in `\ooo`. |
| 133 |
|
| 134 |
Unrecognized escape sequences are left in the string unchanged, i.e., the |
| 135 |
backslash is left in the string. |
| 136 |
|
| 137 |
### String concatenation |
| 138 |
|
| 139 |
Strings can be concatenated to form a new string using the `+` symbol. |
| 140 |
|
| 141 |
```meson |
| 142 |
str1 = 'abc' |
| 143 |
str2 = 'xyz' |
| 144 |
combined = str1 + '_' + str2 # combined is now abc_xyz |
| 145 |
``` |
| 146 |
|
| 147 |
### String path building |
| 148 |
|
| 149 |
*(Added 0.49)* |
| 150 |
|
| 151 |
You can concatenate any two strings using `/` as an operator to build paths. |
| 152 |
This will always use `/` as the path separator on all platforms. |
| 153 |
|
| 154 |
```meson |
| 155 |
joined = '/usr/share' / 'projectname' # => /usr/share/projectname |
| 156 |
joined = '/usr/local' / '/etc/name' # => /etc/name |
| 157 |
|
| 158 |
joined = 'C:\\foo\\bar' / 'builddir' # => C:/foo/bar/builddir |
| 159 |
joined = 'C:\\foo\\bar' / 'D:\\builddir' # => D:/builddir |
| 160 |
``` |
| 161 |
|
| 162 |
Note that this is equivalent to using [[join_paths]], |
| 163 |
which was obsoleted by this operator. |
| 164 |
|
| 165 |
### Strings running over multiple lines |
| 166 |
|
| 167 |
Strings running over multiple lines can be declared with three single |
| 168 |
quotes, like this: |
| 169 |
|
| 170 |
```meson |
| 171 |
multiline_string = '''#include <foo.h> |
| 172 |
int main (int argc, char ** argv) { |
| 173 |
return FOO_SUCCESS; |
| 174 |
}''' |
| 175 |
``` |
| 176 |
|
| 177 |
These are raw strings that do not support the escape sequences listed |
| 178 |
above. These strings can also be combined with the string formatting |
| 179 |
functionality via `.format()` described below. |
| 180 |
|
| 181 |
Note that multiline f-string support was added in version 0.63. |
| 182 |
|
| 183 |
### String index |
| 184 |
|
| 185 |
Strings support the indexing (`[<num>]`) operator. This operator allows (read |
| 186 |
only) accessing a specific character. The returned value is guaranteed to be |
| 187 |
a string of length 1. |
| 188 |
|
| 189 |
```meson |
| 190 |
foo = 'abcd' |
| 191 |
message(foo[1]) # Will print 'b' |
| 192 |
foo[2] = 'C' # ERROR: Meson objects are immutable! |
| 193 |
``` |
| 194 |
|
| 195 |
### String formatting |
| 196 |
|
| 197 |
#### .format() |
| 198 |
|
| 199 |
Strings can be built using the string formatting functionality. |
| 200 |
|
| 201 |
```meson |
| 202 |
template = 'string: @0@, number: @1@, bool: @2@' |
| 203 |
res = template.format('text', 1, true) |
| 204 |
# res now has value 'string: text, number: 1, bool: true' |
| 205 |
``` |
| 206 |
|
| 207 |
As can be seen, the formatting works by replacing placeholders of type |
| 208 |
`@number@` with the corresponding argument. |
| 209 |
|
| 210 |
#### Format strings |
| 211 |
*(Added 0.58)* |
| 212 |
|
| 213 |
Format strings can be used as a non-positional alternative to the |
| 214 |
string formatting functionality described above. Note that multiline f-string |
| 215 |
support was added in version 0.63. |
| 216 |
|
| 217 |
```meson |
| 218 |
n = 10 |
| 219 |
m = 'hi' |
| 220 |
|
| 221 |
s = f'int: @n@, string: @m@' |
| 222 |
# s now has the value 'int: 10, string: hi' |
| 223 |
``` |
| 224 |
|
| 225 |
Currently only identity-expressions are supported inside of format |
| 226 |
strings, meaning you cannot use arbitrary Meson expressions inside of them. |
| 227 |
|
| 228 |
```meson |
| 229 |
n = 10 |
| 230 |
m = 5 |
| 231 |
|
| 232 |
# The following is not a valid format string |
| 233 |
s = f'result: @n + m@' |
| 234 |
``` |
| 235 |
|
| 236 |
### String methods |
| 237 |
|
| 238 |
Strings also support a number of other methods that return transformed |
| 239 |
copies. |
| 240 |
|
| 241 |
#### .replace() |
| 242 |
|
| 243 |
Since 0.58.0, you can replace a substring from a string. |
| 244 |
|
| 245 |
```meson |
| 246 |
# Replaces all instances of one substring with another |
| 247 |
s = 'semicolons;as;separators' |
| 248 |
s = s.replace('as', 'are') |
| 249 |
# 's' now has the value of 'semicolons;are;separators' |
| 250 |
``` |
| 251 |
|
| 252 |
#### .strip() |
| 253 |
|
| 254 |
```meson |
| 255 |
# Similar to the Python str.strip(). Removes leading/ending spaces and newlines. |
| 256 |
define = ' -Dsomedefine ' |
| 257 |
stripped_define = define.strip() |
| 258 |
# 'stripped_define' now has the value '-Dsomedefine' |
| 259 |
|
| 260 |
# You may also pass a string to strip, which specifies the set of characters to |
| 261 |
# be removed instead of the default whitespace. |
| 262 |
string = 'xyxHelloxyx'.strip('xy') |
| 263 |
# 'string' now has the value 'Hello' |
| 264 |
``` |
| 265 |
|
| 266 |
Since 0.43.0, you can specify one positional string argument, |
| 267 |
and all characters in that string will be stripped. |
| 268 |
|
| 269 |
#### .to_upper(), .to_lower() |
| 270 |
|
| 271 |
```meson |
| 272 |
target = 'x86_FreeBSD' |
| 273 |
upper = target.to_upper() # t now has the value 'X86_FREEBSD' |
| 274 |
lower = target.to_lower() # t now has the value 'x86_freebsd' |
| 275 |
``` |
| 276 |
|
| 277 |
#### .to_int() |
| 278 |
|
| 279 |
```meson |
| 280 |
version = '1' |
| 281 |
# Converts the string to an int and throws an error if it can't be |
| 282 |
ver_int = version.to_int() |
| 283 |
``` |
| 284 |
|
| 285 |
#### .contains(), .startswith(), .endswith() |
| 286 |
|
| 287 |
```meson |
| 288 |
target = 'x86_FreeBSD' |
| 289 |
is_fbsd = target.to_lower().contains('freebsd') |
| 290 |
# is_fbsd now has the boolean value 'true' |
| 291 |
is_x86 = target.startswith('x86') # boolean value 'true' |
| 292 |
is_bsd = target.to_lower().endswith('bsd') # boolean value 'true' |
| 293 |
``` |
| 294 |
|
| 295 |
#### .substring() |
| 296 |
|
| 297 |
Since 0.56.0, you can extract a substring from a string. |
| 298 |
|
| 299 |
```meson |
| 300 |
# Similar to the Python str[start:end] syntax |
| 301 |
target = 'x86_FreeBSD' |
| 302 |
platform = target.substring(0, 3) # prefix string value 'x86' |
| 303 |
system = target.substring(4) # suffix string value 'FreeBSD' |
| 304 |
``` |
| 305 |
|
| 306 |
The method accepts negative values where negative `start` is relative to the end of |
| 307 |
string `len(string) - start` as well as negative `end`. |
| 308 |
|
| 309 |
```meson |
| 310 |
string = 'foobar' |
| 311 |
string.substring(-5, -3) # => 'oo' |
| 312 |
string.substring(1, -1) # => 'ooba' |
| 313 |
``` |
| 314 |
|
| 315 |
#### .split(), .join() |
| 316 |
|
| 317 |
```meson |
| 318 |
# Similar to the Python str.split() |
| 319 |
components = 'a b c d '.split() |
| 320 |
# components now has the value ['a', 'b', 'c', 'd'] |
| 321 |
components = 'a b c d '.split(' ') |
| 322 |
# components now has the value ['a', 'b', '', '', 'c', 'd', ''] |
| 323 |
|
| 324 |
# Similar to the Python str.join() |
| 325 |
output = ' '.join(['foo', 'bar']) |
| 326 |
# Output value is 'foo bar' |
| 327 |
pathsep = ':' |
| 328 |
path = pathsep.join(['/usr/bin', '/bin', '/usr/local/bin']) |
| 329 |
# path now has the value '/usr/bin:/bin:/usr/local/bin' |
| 330 |
|
| 331 |
# For joining path elements, you should use path1 / path2 |
| 332 |
# This has the advantage of being cross-platform |
| 333 |
path = '/usr' / 'local' / 'bin' |
| 334 |
# path now has the value '/usr/local/bin' |
| 335 |
|
| 336 |
# For sources files, use files(): |
| 337 |
my_sources = files('foo.c') |
| 338 |
... |
| 339 |
my_sources += files('bar.c') |
| 340 |
# This has the advantage of always calculating the correct relative path, even |
| 341 |
# if you add files in another directory or use them in a different directory |
| 342 |
# than they're defined in |
| 343 |
|
| 344 |
# Example to set an API version for use in library(), install_header(), etc |
| 345 |
project('project', 'c', version: '0.2.3') |
| 346 |
version_array = meson.project_version().split('.') |
| 347 |
# version_array now has the value ['0', '2', '3'] |
| 348 |
api_version = '.'.join([version_array[0], version_array[1]]) |
| 349 |
# api_version now has the value '0.2' |
| 350 |
|
| 351 |
# We can do the same with .format() too: |
| 352 |
api_version = '@0@.@1@'.format(version_array[0], version_array[1]) |
| 353 |
# api_version now (again) has the value '0.2' |
| 354 |
``` |
| 355 |
|
| 356 |
#### .underscorify() |
| 357 |
|
| 358 |
```meson |
| 359 |
name = 'Meson Docs.txt#Reference-manual' |
| 360 |
# Replaces all characters other than `a-zA-Z0-9` with `_` (underscore) |
| 361 |
# Useful for substituting into #defines, filenames, etc. |
| 362 |
underscored = name.underscorify() |
| 363 |
# underscored now has the value 'Meson_Docs_txt_Reference_manual' |
| 364 |
``` |
| 365 |
|
| 366 |
#### .version_compare() |
| 367 |
|
| 368 |
```meson |
| 369 |
version = '1.2.3' |
| 370 |
# Compare version numbers semantically |
| 371 |
is_new = version.version_compare('>=2.0') |
| 372 |
# is_new now has the boolean value false |
| 373 |
# Supports the following operators: '>', '<', '>=', '<=', '!=', '==', '=' |
| 374 |
``` |
| 375 |
|
| 376 |
Meson version comparison conventions include: |
| 377 |
|
| 378 |
```meson |
| 379 |
'3.6'.version_compare('>=3.6.0') == false |
| 380 |
``` |
| 381 |
|
| 382 |
It is best to be unambiguous and specify the full revision level to compare. |
| 383 |
|
| 384 |
## Arrays |
| 385 |
|
| 386 |
Arrays are delimited by brackets. An array can contain an arbitrary number of objects of any type. |
| 387 |
|
| 388 |
```meson |
| 389 |
my_array = [1, 2, 'string', some_obj] |
| 390 |
``` |
| 391 |
|
| 392 |
Accessing elements of an array can be done via array indexing: |
| 393 |
|
| 394 |
```meson |
| 395 |
my_array = [1, 2, 'string', some_obj] |
| 396 |
second_element = my_array[1] |
| 397 |
last_element = my_array[-1] |
| 398 |
``` |
| 399 |
|
| 400 |
You can add more items to an array like this: |
| 401 |
|
| 402 |
```meson |
| 403 |
my_array += ['foo', 3, 4, another_obj] |
| 404 |
``` |
| 405 |
|
| 406 |
When adding a single item, you do not need to enclose it in an array: |
| 407 |
|
| 408 |
```meson |
| 409 |
my_array += ['something'] |
| 410 |
# This also works |
| 411 |
my_array += 'else' |
| 412 |
``` |
| 413 |
|
| 414 |
Note appending to an array will always create a new array object and |
| 415 |
assign it to `my_array` instead of modifying the original since all |
| 416 |
objects in Meson are immutable. |
| 417 |
|
| 418 |
Since 0.49.0, you can check if an array contains an element like this: |
| 419 |
|
| 420 |
```meson |
| 421 |
my_array = [1, 2] |
| 422 |
if 1 in my_array |
| 423 |
# This condition is true |
| 424 |
endif |
| 425 |
if 1 not in my_array |
| 426 |
# This condition is false |
| 427 |
endif |
| 428 |
``` |
| 429 |
|
| 430 |
### Array methods |
| 431 |
|
| 432 |
The following methods are defined for all arrays: |
| 433 |
|
| 434 |
- `length`, the size of the array |
| 435 |
- `contains`, returns `true` if the array contains the object given as argument, `false` otherwise |
| 436 |
- `get`, returns the object at the given index, negative indices count from the back of the array, indexing out of bounds is a fatal error. Provided for backwards-compatibility, it is identical to array indexing. |
| 437 |
|
| 438 |
## Dictionaries |
| 439 |
|
| 440 |
Dictionaries are delimited by curly braces. A dictionary can contain |
| 441 |
an arbitrary number of key: value pairs. Keys are required to be |
| 442 |
strings, but values can be objects of any type. Prior to *0.53.0* keys |
| 443 |
were required to be literal strings, i.e., you could not use a |
| 444 |
variable containing a string value as a key. |
| 445 |
|
| 446 |
```meson |
| 447 |
my_dict = {'foo': 42, 'bar': 'baz'} |
| 448 |
``` |
| 449 |
|
| 450 |
Keys must be unique: |
| 451 |
|
| 452 |
```meson |
| 453 |
# This will fail |
| 454 |
my_dict = {'foo': 42, 'foo': 43} |
| 455 |
``` |
| 456 |
|
| 457 |
Accessing elements of a dictionary works similarly to array indexing: |
| 458 |
|
| 459 |
```meson |
| 460 |
my_dict = {'foo': 42, 'bar': 'baz'} |
| 461 |
forty_two = my_dict['foo'] |
| 462 |
# This will fail |
| 463 |
my_dict['does_not_exist'] |
| 464 |
``` |
| 465 |
|
| 466 |
Dictionaries are immutable and do not have a guaranteed order. |
| 467 |
|
| 468 |
Dictionaries are available since 0.47.0. |
| 469 |
|
| 470 |
Visit the [[@dict]] objects page in the Reference Manual to read |
| 471 |
about the methods exposed by dictionaries. |
| 472 |
|
| 473 |
Since 0.49.0, you can check if a dictionary contains a key like this: |
| 474 |
|
| 475 |
```meson |
| 476 |
my_dict = {'foo': 42, 'bar': 43} |
| 477 |
if 'foo' in my_dict |
| 478 |
# This condition is true |
| 479 |
endif |
| 480 |
if 42 in my_dict |
| 481 |
# This condition is false |
| 482 |
endif |
| 483 |
if 'foo' not in my_dict |
| 484 |
# This condition is false |
| 485 |
endif |
| 486 |
``` |
| 487 |
|
| 488 |
*Since 0.53.0* Keys can be any expression evaluating to a string |
| 489 |
value, not limited to string literals any more. |
| 490 |
|
| 491 |
```meson |
| 492 |
d = {'a' + 'b' : 42} |
| 493 |
k = 'cd' |
| 494 |
d += {k : 43} |
| 495 |
``` |
| 496 |
|
| 497 |
## Function calls |
| 498 |
|
| 499 |
Meson provides a set of usable functions. The most common use case is |
| 500 |
creating build objects. |
| 501 |
|
| 502 |
```meson |
| 503 |
executable('progname', 'prog.c') |
| 504 |
``` |
| 505 |
|
| 506 |
Most functions take only few positional arguments but several keyword |
| 507 |
arguments, which are specified like this: |
| 508 |
|
| 509 |
```meson |
| 510 |
executable('progname', |
| 511 |
sources: 'prog.c', |
| 512 |
c_args: '-DFOO=1') |
| 513 |
``` |
| 514 |
|
| 515 |
Starting with version 0.49.0 keyword arguments can be specified |
| 516 |
dynamically. This is done by passing dictionary representing the |
| 517 |
keywords to set in the `kwargs` keyword. The previous example would be |
| 518 |
specified like this: |
| 519 |
|
| 520 |
```meson |
| 521 |
d = {'sources': 'prog.c', |
| 522 |
'c_args': '-DFOO=1'} |
| 523 |
|
| 524 |
executable('progname', |
| 525 |
kwargs: d) |
| 526 |
``` |
| 527 |
|
| 528 |
A single function can take keyword arguments both directly in the |
| 529 |
function call and indirectly via the `kwargs` keyword argument. The |
| 530 |
only limitation is that it is a hard error to pass any particular key |
| 531 |
both as a direct and indirect argument. |
| 532 |
|
| 533 |
```meson |
| 534 |
d = {'c_args': '-DFOO'} |
| 535 |
executable('progname', 'prog.c', |
| 536 |
c_args: '-DBAZ=1', |
| 537 |
kwargs: d) # This is an error! |
| 538 |
``` |
| 539 |
|
| 540 |
Attempting to do this causes Meson to immediately exit with an error. |
| 541 |
|
| 542 |
### Argument flattening |
| 543 |
|
| 544 |
Argument flattening is a Meson feature that aims to simplify using |
| 545 |
methods and functions. For functions where this feature is active, |
| 546 |
Meson takes the list of arguments and flattens all nested lists into |
| 547 |
one big list. |
| 548 |
|
| 549 |
For instance the following function calls to [[executable]] are |
| 550 |
identical in Meson: |
| 551 |
|
| 552 |
```meson |
| 553 |
# A normal example: |
| 554 |
executable('exe1', ['foo.c', 'bar.c', 'foobar.c']) |
| 555 |
|
| 556 |
# A more contrived example that also works but certainly |
| 557 |
# isn't good Meson code: |
| 558 |
l1 = ['bar.c'] |
| 559 |
executable('exe1', [[['foo.c', l1]], ['foobar.c']]) |
| 560 |
|
| 561 |
# How meson will treat all the previous calls internally: |
| 562 |
executable('exe1', 'foo.c', 'bar.c', 'foobar.c') |
| 563 |
``` |
| 564 |
|
| 565 |
Because of an internal implementation detail, the following syntax |
| 566 |
is currently also supported, even though the first argument of |
| 567 |
[[executable]] is a single [[@str]] and not a [[@list]]: |
| 568 |
|
| 569 |
```meson |
| 570 |
# WARNING: This example is only valid because of an internal |
| 571 |
# implementation detail and not because it is intended |
| 572 |
# |
| 573 |
# PLEASE DO NOT DO SOMETHING LIKE THIS! |
| 574 |
# |
| 575 |
executable(['exe1', 'foo.c'], 'bar.c', 'foobar.c') |
| 576 |
``` |
| 577 |
|
| 578 |
This code is currently accepted because argument flattening *currently* |
| 579 |
happens before the parameters are evaluated. "Support" for |
| 580 |
such constructs will likely be removed in future Meson releases! |
| 581 |
|
| 582 |
Argument flattening is supported by *most* but not *all* Meson |
| 583 |
functions and methods. As a general rule, it can be assumed that a |
| 584 |
function or method supports argument flattening if the exact list |
| 585 |
structure is irrelevant to a function. |
| 586 |
|
| 587 |
Whether a function supports argument flattening is documented in the |
| 588 |
[Reference Manual](Reference-manual.md). |
| 589 |
|
| 590 |
## Method calls |
| 591 |
|
| 592 |
Objects can have methods, which are called with the dot operator. The |
| 593 |
exact methods it provides depends on the object. |
| 594 |
|
| 595 |
```meson |
| 596 |
myobj = some_function() |
| 597 |
myobj.do_something('now') |
| 598 |
``` |
| 599 |
|
| 600 |
## If statements |
| 601 |
|
| 602 |
If statements work just like in other languages. |
| 603 |
|
| 604 |
```meson |
| 605 |
var1 = 1 |
| 606 |
var2 = 2 |
| 607 |
if var1 == var2 # Evaluates to false |
| 608 |
something_broke() |
| 609 |
elif var3 == var2 |
| 610 |
something_else_broke() |
| 611 |
else |
| 612 |
everything_ok() |
| 613 |
endif |
| 614 |
|
| 615 |
opt = get_option('someoption') |
| 616 |
if opt != 'foo' |
| 617 |
do_something() |
| 618 |
endif |
| 619 |
``` |
| 620 |
|
| 621 |
## Logical operations |
| 622 |
|
| 623 |
Meson has the standard range of logical operations which can be used in |
| 624 |
`if` statements. |
| 625 |
|
| 626 |
```meson |
| 627 |
if a and b |
| 628 |
# do something |
| 629 |
endif |
| 630 |
if c or d |
| 631 |
# do something |
| 632 |
endif |
| 633 |
if not e |
| 634 |
# do something |
| 635 |
endif |
| 636 |
if not (f or g) |
| 637 |
# do something |
| 638 |
endif |
| 639 |
``` |
| 640 |
|
| 641 |
Logical operations work only on boolean values. |
| 642 |
|
| 643 |
## Foreach statements |
| 644 |
|
| 645 |
To do an operation on all elements of an iterable, use the `foreach` |
| 646 |
command. |
| 647 |
|
| 648 |
> Note that Meson variables are immutable. Trying to assign a new value |
| 649 |
> to the iterated object inside a foreach loop will not affect foreach's |
| 650 |
> control flow. |
| 651 |
|
| 652 |
### Foreach with an array |
| 653 |
|
| 654 |
Here's an example of how you could define two executables |
| 655 |
with corresponding tests using arrays and foreach. |
| 656 |
|
| 657 |
```meson |
| 658 |
progs = [['prog1', ['prog1.c', 'foo.c']], |
| 659 |
['prog2', ['prog2.c', 'bar.c']]] |
| 660 |
|
| 661 |
foreach p : progs |
| 662 |
exe = executable(p[0], p[1]) |
| 663 |
test(p[0], exe) |
| 664 |
endforeach |
| 665 |
``` |
| 666 |
|
| 667 |
### Foreach with a dictionary |
| 668 |
|
| 669 |
Here's an example of you could iterate a set of components that |
| 670 |
should be compiled in according to some configuration. This uses |
| 671 |
a [dictionary][dictionaries], which is available since 0.47.0. |
| 672 |
|
| 673 |
```meson |
| 674 |
components = { |
| 675 |
'foo': ['foo.c'], |
| 676 |
'bar': ['bar.c'], |
| 677 |
'baz': ['baz.c'], |
| 678 |
} |
| 679 |
|
| 680 |
# compute a configuration based on system dependencies, custom logic |
| 681 |
conf = configuration_data() |
| 682 |
conf.set('USE_FOO', 1) |
| 683 |
|
| 684 |
# Determine the sources to compile |
| 685 |
sources_to_compile = [] |
| 686 |
foreach name, sources : components |
| 687 |
if conf.get('USE_@0@'.format(name.to_upper()), 0) == 1 |
| 688 |
sources_to_compile += sources |
| 689 |
endif |
| 690 |
endforeach |
| 691 |
``` |
| 692 |
|
| 693 |
### Foreach `break` and `continue` |
| 694 |
|
| 695 |
Since 0.49.0 `break` and `continue` keywords can be used inside foreach loops. |
| 696 |
|
| 697 |
```meson |
| 698 |
items = ['a', 'continue', 'b', 'break', 'c'] |
| 699 |
result = [] |
| 700 |
foreach i : items |
| 701 |
if i == 'continue' |
| 702 |
continue |
| 703 |
elif i == 'break' |
| 704 |
break |
| 705 |
endif |
| 706 |
result += i |
| 707 |
endforeach |
| 708 |
# result is ['a', 'b'] |
| 709 |
``` |
| 710 |
|
| 711 |
## Comments |
| 712 |
|
| 713 |
A comment starts with the `#` character and extends until the end of the line. |
| 714 |
|
| 715 |
```meson |
| 716 |
some_function() # This is a comment |
| 717 |
some_other_function() |
| 718 |
``` |
| 719 |
|
| 720 |
## Ternary operator |
| 721 |
|
| 722 |
The ternary operator works just like in other languages. |
| 723 |
|
| 724 |
```meson |
| 725 |
x = condition ? true_value : false_value |
| 726 |
``` |
| 727 |
|
| 728 |
The only exception is that nested ternary operators are forbidden to |
| 729 |
improve legibility. If your branching needs are more complex than this |
| 730 |
you need to write an `if/else` construct. |
| 731 |
|
| 732 |
## Includes |
| 733 |
|
| 734 |
Most source trees have multiple subdirectories to process. These can |
| 735 |
be handled by Meson's `subdir` command. It changes to the given |
| 736 |
subdirectory and executes the contents of `meson.build` in that |
| 737 |
subdirectory. All state (variables etc) are passed to and from the |
| 738 |
subdirectory. The effect is roughly the same as if the contents of the |
| 739 |
subdirectory's Meson file would have been written where the include |
| 740 |
command is. |
| 741 |
|
| 742 |
```meson |
| 743 |
test_data_dir = 'data' |
| 744 |
subdir('tests') |
| 745 |
``` |
| 746 |
|
| 747 |
## User-defined functions and methods |
| 748 |
|
| 749 |
Meson does not currently support user-defined functions or methods. |
| 750 |
The addition of user-defined functions would make Meson |
| 751 |
Turing-complete which would make it harder to reason about and more |
| 752 |
difficult to integrate with tools like IDEs. More details about this |
| 753 |
are [in the |
| 754 |
FAQ](FAQ.md#why-is-meson-not-just-a-python-module-so-i-could-code-my-build-setup-in-python). |
| 755 |
If because of this limitation you find yourself copying and pasting |
| 756 |
code a lot you may be able to use a [`foreach` loop |
| 757 |
instead](#foreach-statements). |
| 758 |
|
| 759 |
## Stability Promises |
| 760 |
|
| 761 |
Meson is very actively developed and continuously improved. There is a |
| 762 |
possibility that future enhancements to the Meson build system will |
| 763 |
require changes to the syntax. Such changes might be the addition of |
| 764 |
new reserved keywords, changing the meaning of existing keywords or |
| 765 |
additions around the basic building blocks like statements and |
| 766 |
fundamental types. It is planned to stabilize the syntax with the 1.0 |
| 767 |
release. |
| 768 |
|
| 769 |
## Grammar |
| 770 |
|
| 771 |
This is the full Meson grammar, as it is used to parse Meson build definition files: |
| 772 |
|
| 773 |
``` |
| 774 |
additive_expression: multiplicative_expression | (additive_expression additive_operator multiplicative_expression) |
| 775 |
additive_operator: "+" | "-" |
| 776 |
argument_list: positional_arguments ["," keyword_arguments] | keyword_arguments |
| 777 |
array_literal: "[" [expression_list] "]" |
| 778 |
assignment_statement: expression assignment_operator expression |
| 779 |
assignment_operator: "=" | "+=" |
| 780 |
binary_literal: "0b" BINARY_NUMBER |
| 781 |
BINARY_NUMBER: /[01]+/ |
| 782 |
boolean_literal: "true" | "false" |
| 783 |
build_definition: (NEWLINE | statement)* |
| 784 |
condition: expression |
| 785 |
conditional_expression: logical_or_expression | (logical_or_expression "?" expression ":" assignment_expression |
| 786 |
decimal_literal: DECIMAL_NUMBER |
| 787 |
DECIMAL_NUMBER: /[1-9][0-9]*/ |
| 788 |
dictionary_literal: "{" [key_value_list] "}" |
| 789 |
equality_expression: relational_expression | (equality_expression equality_operator relational_expression) |
| 790 |
equality_operator: "==" | "!=" |
| 791 |
expression: conditional_expression | logical_or_expression |
| 792 |
expression_list: expression ("," expression)* |
| 793 |
expression_statement: expression |
| 794 |
function_expression: id_expression "(" [argument_list] ")" |
| 795 |
hex_literal: "0x" HEX_NUMBER |
| 796 |
HEX_NUMBER: /[a-fA-F0-9]+/ |
| 797 |
id_expression: IDENTIFIER |
| 798 |
IDENTIFIER: /[a-zA-Z_][a-zA-Z_0-9]*/ |
| 799 |
identifier_list: id_expression ("," id_expression)* |
| 800 |
integer_literal: decimal_literal | octal_literal | hex_literal |
| 801 |
iteration_statement: "foreach" identifier_list ":" id_expression NEWLINE (statement | jump_statement)* "endforeach" |
| 802 |
jump_statement: ("break" | "continue") NEWLINE |
| 803 |
key_value_item: expression ":" expression |
| 804 |
key_value_list: key_value_item ("," key_value_item)* |
| 805 |
keyword_item: id_expression ":" expression |
| 806 |
keyword_arguments: keyword_item ("," keyword_item)* |
| 807 |
literal: integer_literal | string_literal | boolean_literal | array_literal | dictionary_literal |
| 808 |
logical_and_expression: equality_expression | (logical_and_expression "and" equality_expression) |
| 809 |
logical_or_expression: logical_and_expression | (logical_or_expression "or" logical_and_expression) |
| 810 |
method_expression: postfix_expression "." function_expression |
| 811 |
multiplicative_expression: unary_expression | (multiplicative_expression multiplicative_operator unary_expression) |
| 812 |
multiplicative_operator: "*" | "/" | "%" |
| 813 |
octal_literal: "0o" OCTAL_NUMBER |
| 814 |
OCTAL_NUMBER: /[0-7]+/ |
| 815 |
positional_arguments: expression ("," expression)* |
| 816 |
postfix_expression: primary_expression | subscript_expression | function_expression | method_expression |
| 817 |
primary_expression: literal | ("(" expression ")") | id_expression |
| 818 |
relational_expression: additive_expression | (relational_expression relational_operator additive_expression) |
| 819 |
relational_operator: ">" | "<" | ">=" | "<=" | "in" | ("not" "in") |
| 820 |
selection_statement: "if" condition NEWLINE (statement)* ("elif" condition NEWLINE (statement)*)* ["else" (statement)*] "endif" |
| 821 |
statement: (expression_statement | selection_statement | iteration_statement | assignment_statement) NEWLINE |
| 822 |
string_literal: ("'" STRING_SIMPLE_VALUE "'") | ("'''" STRING_MULTILINE_VALUE "'''") |
| 823 |
STRING_MULTILINE_VALUE: \.*?(''')\ |
| 824 |
STRING_SIMPLE_VALUE: \.*?(?<!\\)(\\\\)*?'\ |
| 825 |
subscript_expression: postfix_expression "[" expression "]" |
| 826 |
unary_expression: postfix_expression | (unary_operator unary_expression) |
| 827 |
unary_operator: "not" | "-" |
| 828 |
``` |