.\" Generated by scdoc 1.11.2
.\" Complete documentation for this program is not available as a GNU info page
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.nh
.ad l
.\" Begin generated content:
.TH "meson.build" "5" "2023-01-22"
.P
.SH NAME
.P
meson.\&build - a build system dsl
.P
.SH DESCRIPTION
.P
The meson dsl is a dynamically typed language, similar to other interpreted
languages like python and ruby.\&  All objects are immutable.\& Functions cannot be
defined, only built-in functions are available.\&
.P
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.IP \(bu 4
.\}
\fBSTRUCTURE\fR - overview of source and project layout
.RE
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.IP \(bu 4
.\}
\fBTYPES\fR - information on all primitive types
.RE
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.IP \(bu 4
.\}
\fBSYNTAX\fR - description of syntax and keywords

.RE
.P
.SH STRUCTURE
.P
All meson projects must have a file called `meson.\&build` at the project root.\&
This is the root build file.\&  This file must have a call to the `project()`
function as its first statement.\&  Additional `meson.\&build` files may reside in
any subdirectories of the project.\&  These build files are then executed with
the `subdir()` function.\&
.P
.SH TYPES
.P
The meson build system dsl contains most of the common types that would be
expected:
.P
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.IP \(bu 4
.\}
booleans (written as `true` and `false`)
.RE
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.IP \(bu 4
.\}
integers
.RE
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.IP \(bu 4
.\}
strings
.RE
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.IP \(bu 4
.\}
arrays
.RE
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.IP \(bu 4
.\}
dictionaries

.RE
.P
.SS Booleans
.P
Booleans are either `true` or `false`.\&
.P
\fBOPERATORS\fR
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.IP \(bu 4
.\}
`and` - logical and
.RE
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.IP \(bu 4
.\}
`or` - logical or
.RE
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.IP \(bu 4
.\}
`not` - logical and

.RE
.P
.SS Integers
.P
You can specify an integer literal using decimal, hexadecimal, octal, and
binary.\&
.P
.nf
.RS 4
int_1 = 1
int_42 = 42
int_255 = 0xFF
int_493 = 0o755
int_1365 = 0b10101010101
.fi
.RE
.P
All common arithmetic operations are implemented for integers: addition,
subtraction, division, multiplication, and modulo.\&
.P
\fBOPERATORS\fR
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.IP \(bu 4
.\}
`*` - multiplication
.RE
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.IP \(bu 4
.\}
`/` - integer division
.RE
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.IP \(bu 4
.\}
`%` - modulo (remainder)
.RE
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.IP \(bu 4
.\}
`+` - addition
.RE
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.IP \(bu 4
.\}
`-` - subtraction
.RE
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.IP \(bu 4
.\}
`==` - equal to
.RE
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.IP \(bu 4
.\}
`!\&=` - not equal to
.RE
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.IP \(bu 4
.\}
`<` - less than
.RE
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.IP \(bu 4
.\}
`>` - greater than
.RE
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.IP \(bu 4
.\}
`<=` - less than or equal to
.RE
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.IP \(bu 4
.\}
`>=` - greater than or equal to

.RE
.P
.SS Strings
.P
Strings in Meson are declared with single quotes.\&  `` is the escape character.\&
.P
The full list of escape sequences is:
.P
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.IP \(bu 4
.\}
`\\` Backslash
.RE
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.IP \(bu 4
.\}
`'` Single quote
.RE
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.IP \(bu 4
.\}
`a` Bell
.RE
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.IP \(bu 4
.\}
`b` Backspace
.RE
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.IP \(bu 4
.\}
`f` Formfeed
.RE
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.IP \(bu 4
.\}
`n` Newline
.RE
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.IP \(bu 4
.\}
`r` Carriage Return
.RE
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.IP \(bu 4
.\}
`t` Horizontal Tab
.RE
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.IP \(bu 4
.\}
`v` Vertical Tab
.RE
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.IP \(bu 4
.\}
`ooo` Character with octal value ooo, up to 3 digits long
.RE
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.IP \(bu 4
.\}
`xhh` Character with hex value hh
.RE
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.IP \(bu 4
.\}
`uxxxx` Character with 16-bit hex value xxxx
.RE
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.IP \(bu 4
.\}
`Uxxxxxxxx` Character with 32-bit hex value xxxxxxxx
.RE
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.IP \(bu 4
.\}
`N{name}` Character named name in Unicode database

.RE
.P
Multi-line strings are surrounded by 3 consecutive quotes.\&  These are raw
strings that do not support the escape sequences listed above.\&
.P
Format strings are expressed by a placing leading `f` before the first opening
quote.\&  Inside of a format string, sequences of the form `@[a-z_]+@` will be
substituted with the value of the matching variable.\&
.P
.nf
.RS 4
name = \&'Alice\&'

# prints "Hello Alice"
message(f\&'Hello @name@\&')
.fi
.RE
.P
\fBOPERATORS\fR
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.IP \(bu 4
.\}
`+` - concatenate two strings
.RE
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.IP \(bu 4
.\}
`/` - concatenate two strings as if `join_paths()` was called
.RE
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.IP \(bu 4
.\}
`[n]` -  access the character at index `n`
.RE
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.IP \(bu 4
.\}
`==` - equal to
.RE
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.IP \(bu 4
.\}
`!\&=` - not equal to

.RE
.P
.SS Arrays
.P
Arrays are delimited by brackets.\& An array can contain an arbitrary number of objects of any type.\&
.P
\fBOPERATORS\fR
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.IP \(bu 4
.\}
`+` -  If the rhs operand is an array, it will be joined to the lhs
array.\& If it is a scalar, it will be appended to the lhs array.\&
.RE
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.IP \(bu 4
.\}
`[n]` - access the object at index `n`
.RE
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.IP \(bu 4
.\}
`<obj> in <array>` - check if object `obj` is in `array`
.RE
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.IP \(bu 4
.\}
`<obj> in <array>` - check if object `obj` is not in `array`
.RE
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.IP \(bu 4
.\}
`==` - equal to
.RE
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.IP \(bu 4
.\}
`!\&=` - not equal to

.RE
.P
.SS Dictionaries
.P
Dictionaries are delimited by curly braces.\& A dictionary can contain an
arbitrary number of key: value pairs.\& Keys are required to be strings, but
values can be objects of any type.\&  Dictionaries are immutable and do not have
a guaranteed order.\&
.P
\fBOPERATORS\fR
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.IP \(bu 4
.\}
`+` - merge two dictionaries.\&  In case of a conflicting key, the value from
the rhs dictionary will be taken.\&
.RE
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.IP \(bu 4
.\}
`[key]` - access the object with key `key`
.RE
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.IP \(bu 4
.\}
`<key> in <dict>` - check if key `key` is in `dict`
.RE
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.IP \(bu 4
.\}
`<key> not in <dict>` - check if key `key` is not in `dict`
.RE
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.IP \(bu 4
.\}
`==` - equal to
.RE
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.IP \(bu 4
.\}
`!\&=` - not equal to

.RE
.P
.SH SYNTAX
.P
A meson build file is composed of statements, which are terminated by newlines.\&
Other than the statement-terminating newline, white space has no syntactic
meaning.\&
.P
.SS Comments
.P
A comment starts with the `#` character and extends until the end of the line.\&
.P
.SS Variables
.P
A variable can contain a value of any type, and does not need to be
predeclared.\&
.P
.nf
.RS 4
var1 = \&'hello\&'
var2 = 102
.fi
.RE
.P
One important difference in how variables work in the dsl is that all objects
are immutable.\& When you see an operation which appears like a mutation,
actually a new object is created and assigned to the name.\&
.P
.nf
.RS 4
var1 = [1, 2, 3]
var2 = var1
var2 += [4]
# var2 is now [1, 2, 3, 4]
# var1 is still [1, 2, 3]
.fi
.RE
.P
.SS Function and method calls
.P
Builtin functions are called by their name followed by parenthesis containing
optional, comma-separated arguments.\&  Arguments are either positional or
keyword.\&  Keyword arguments are expressed using the keyword without quotes,
followed by a colon.\&
.P
.nf
.RS 4
foo()
foo(\&'bar\&')
foo(\&'bar\&', baz: true)
.fi
.RE
.P
Method calls are expressed by a `.\&` followed by the same function call syntax as above.\&
.P
.nf
.RS 4
foo\&.bar()
foo\&.bar(\&'baz\&', qux: false)
.fi
.RE
.P
For a complete list of functions and methods, please see `meson-reference(3)`.\&
.P
.SS If statements
.P
Start an if statement with the `if` keyword followed by a boolean expression.\&
Further conditions can be expressed using the `elif` keyword followed by a
boolean expression.\&  The `else` keyword can be used to handle the case when no
conditions are matched.\&  An if statement is terminated with the `endif`
keyword.\&
.P
.nf
.RS 4
if conditon1
elif condition2
else condition3
endif
.fi
.RE
.P
.SS Foreach statements
.P
To loop over values in an iterable, use the `foreach` keyword followed by a
comma separated list of names to assign the values of the iterable to, a colon,
and an iterable expression.\&  Only arrays and dictionaries are iterable.\&  A
foreach statement is terminated with the `endforeach` keyword.\&
.P
Arrays have one value to assign to.\&
.P
.nf
.RS 4
foreach value : array
	foo(value)
endforeach
.fi
.RE
.P
Dictionaries have one two values to assign to.\&
.P
.nf
.RS 4
foreach key, value : dictionary
	foo(key)
	bar(value)
endforeach
.fi
.RE
.P
Inside a `foreach` block you may use the `break` and `continue` keywords.\&
`break` exits the loop immediately.\&  `continue` skips the rest of the current
iteration.\&
.P
.SH SEE ALSO
.P
meson-reference(3) meson(1) muon(1)