| 1 |
# Cross and Native File reference |
| 2 |
|
| 3 |
Cross and native files are nearly identical, but not completely. This |
| 4 |
is the documentation on the common values used by both, for the |
| 5 |
specific values of one or the other see the [cross |
| 6 |
compilation](Cross-compilation.md) and [native |
| 7 |
environments](Native-environments.md). |
| 8 |
|
| 9 |
*Changed in 0.56.0* Keys within sections are now case sensitive. This |
| 10 |
is required to make project options work correctly. |
| 11 |
|
| 12 |
## Data Types |
| 13 |
|
| 14 |
There are four basic data types in a machine file: |
| 15 |
- strings |
| 16 |
- arrays |
| 17 |
- booleans |
| 18 |
- integers |
| 19 |
|
| 20 |
A string is specified single quoted: |
| 21 |
```ini |
| 22 |
[section] |
| 23 |
option1 = 'false' |
| 24 |
option2 = '2' |
| 25 |
``` |
| 26 |
|
| 27 |
An array is enclosed in square brackets, and must consist of strings or booleans |
| 28 |
```ini |
| 29 |
[section] |
| 30 |
option = ['value'] |
| 31 |
``` |
| 32 |
|
| 33 |
A boolean must be either `true` or `false`, and unquoted. |
| 34 |
```ini |
| 35 |
option = false |
| 36 |
``` |
| 37 |
|
| 38 |
An integer must be an unquoted numeric constant. |
| 39 |
```ini |
| 40 |
option = 42 |
| 41 |
``` |
| 42 |
|
| 43 |
## Sections |
| 44 |
|
| 45 |
The following sections are allowed: |
| 46 |
- constants |
| 47 |
- binaries |
| 48 |
- paths |
| 49 |
- properties |
| 50 |
- cmake |
| 51 |
- project options |
| 52 |
- built-in options |
| 53 |
|
| 54 |
### constants |
| 55 |
|
| 56 |
*Since 0.56.0* |
| 57 |
|
| 58 |
String and list concatenation is supported using the `+` operator, |
| 59 |
joining paths is supported using the `/` operator. Entries defined in |
| 60 |
the `[constants]` section can be used in any other section (they are |
| 61 |
always parsed first), entries in any other section can be used only |
| 62 |
within that same section and only after it has been defined. |
| 63 |
|
| 64 |
```ini |
| 65 |
[constants] |
| 66 |
toolchain = '/toolchain' |
| 67 |
common_flags = ['--sysroot=' + toolchain / 'sysroot'] |
| 68 |
|
| 69 |
[properties] |
| 70 |
c_args = common_flags + ['-DSOMETHING'] |
| 71 |
cpp_args = c_args + ['-DSOMETHING_ELSE'] |
| 72 |
|
| 73 |
[binaries] |
| 74 |
c = toolchain / 'gcc' |
| 75 |
``` |
| 76 |
|
| 77 |
This can be useful with cross file composition as well. A generic |
| 78 |
cross file could be composed with a platform specific file where |
| 79 |
constants are defined: |
| 80 |
|
| 81 |
```ini |
| 82 |
# aarch64.ini |
| 83 |
[constants] |
| 84 |
arch = 'aarch64-linux-gnu' |
| 85 |
``` |
| 86 |
|
| 87 |
```ini |
| 88 |
# cross.ini |
| 89 |
[binaries] |
| 90 |
c = arch + '-gcc' |
| 91 |
cpp = arch + '-g++' |
| 92 |
strip = arch + '-strip' |
| 93 |
pkg-config = arch + '-pkg-config' |
| 94 |
... |
| 95 |
``` |
| 96 |
|
| 97 |
This can be used as `meson setup --cross-file aarch64.ini --cross-file |
| 98 |
cross.ini builddir`. |
| 99 |
|
| 100 |
Note that file composition happens before the parsing of values. The |
| 101 |
example below results in `b` being `'HelloWorld'`: |
| 102 |
|
| 103 |
```ini |
| 104 |
# file1.ini: |
| 105 |
[constants] |
| 106 |
a = 'Foo' |
| 107 |
b = a + 'World' |
| 108 |
``` |
| 109 |
|
| 110 |
```ini |
| 111 |
#file2.ini: |
| 112 |
[constants] |
| 113 |
a = 'Hello' |
| 114 |
``` |
| 115 |
|
| 116 |
The example below results in an error when file1.ini is included |
| 117 |
before file2.ini because `b` would be defined before `a`: |
| 118 |
|
| 119 |
```ini |
| 120 |
# file1.ini: |
| 121 |
[constants] |
| 122 |
b = a + 'World' |
| 123 |
``` |
| 124 |
|
| 125 |
```ini |
| 126 |
#file2.ini: |
| 127 |
[constants] |
| 128 |
a = 'Hello' |
| 129 |
``` |
| 130 |
|
| 131 |
*Since 1.3.0* Some tokens are replaced in the machine file before parsing it: |
| 132 |
- `@GLOBAL_SOURCE_ROOT@`: the absolute path to the project's source tree |
| 133 |
- `@DIRNAME@`: the absolute path to the machine file's parent directory. |
| 134 |
|
| 135 |
It can be used, for example, to have paths relative to the source directory, or |
| 136 |
relative to toolchain's installation directory. |
| 137 |
```ini |
| 138 |
[binaries] |
| 139 |
c = '@DIRNAME@/toolchain/gcc' |
| 140 |
exe_wrapper = '@GLOBAL_SOURCE_ROOT@' / 'build-aux' / 'my-exe-wrapper.sh' |
| 141 |
``` |
| 142 |
|
| 143 |
### Binaries |
| 144 |
|
| 145 |
The binaries section contains a list of binaries. These can be used |
| 146 |
internally by Meson, or by the `find_program` function. |
| 147 |
|
| 148 |
These values must be either strings or an array of strings |
| 149 |
|
| 150 |
Compilers and linkers are defined here using `<lang>` and `<lang>_ld`. |
| 151 |
`<lang>_ld` is special because it is compiler specific. For compilers |
| 152 |
like gcc and clang which are used to invoke the linker this is a value |
| 153 |
to pass to their "choose the linker" argument (-fuse-ld= in this |
| 154 |
case). For compilers like MSVC and Clang-Cl, this is the path to a |
| 155 |
linker for Meson to invoke, such as `link.exe` or `lld-link.exe`. |
| 156 |
Support for `ld` is *new in 0.53.0* |
| 157 |
|
| 158 |
*changed in 0.53.1* the `ld` variable was replaced by `<lang>_ld`, |
| 159 |
because it regressed a large number of projects. in 0.53.0 the `ld` |
| 160 |
variable was used instead. |
| 161 |
|
| 162 |
Native example: |
| 163 |
|
| 164 |
```ini |
| 165 |
c = '/usr/bin/clang' |
| 166 |
c_ld = 'lld' |
| 167 |
sed = 'C:\\program files\\gnu\\sed.exe' |
| 168 |
llvm-config = '/usr/lib/llvm8/bin/llvm-config' |
| 169 |
``` |
| 170 |
|
| 171 |
Cross example: |
| 172 |
|
| 173 |
```ini |
| 174 |
c = ['ccache', '/usr/bin/i586-mingw32msvc-gcc'] |
| 175 |
cpp = ['ccache', '/usr/bin/i586-mingw32msvc-g++'] |
| 176 |
c_ld = 'gold' |
| 177 |
cpp_ld = 'gold' |
| 178 |
ar = '/usr/i586-mingw32msvc/bin/ar' |
| 179 |
strip = '/usr/i586-mingw32msvc/bin/strip' |
| 180 |
pkg-config = '/usr/bin/i586-mingw32msvc-pkg-config' |
| 181 |
``` |
| 182 |
|
| 183 |
An incomplete list of internally used programs that can be overridden |
| 184 |
here is: |
| 185 |
|
| 186 |
- cmake |
| 187 |
- cups-config |
| 188 |
- gnustep-config |
| 189 |
- gpgme-config |
| 190 |
- libgcrypt-config |
| 191 |
- libwmf-config |
| 192 |
- llvm-config |
| 193 |
- pcap-config |
| 194 |
- pkg-config |
| 195 |
- sdl2-config |
| 196 |
- wx-config (or wx-3.0-config or wx-config-gtk) |
| 197 |
|
| 198 |
### Paths and Directories |
| 199 |
|
| 200 |
*Deprecated in 0.56.0* use the built-in section instead. |
| 201 |
|
| 202 |
As of 0.50.0 paths and directories such as libdir can be defined in |
| 203 |
the native and cross files in a paths section. These should be |
| 204 |
strings. |
| 205 |
|
| 206 |
```ini |
| 207 |
[paths] |
| 208 |
libdir = 'mylibdir' |
| 209 |
prefix = '/my prefix' |
| 210 |
``` |
| 211 |
|
| 212 |
These values will only be loaded when not cross compiling. Any |
| 213 |
arguments on the command line will override any options in the native |
| 214 |
file. For example, passing `--libdir=otherlibdir` would result in a |
| 215 |
prefix of `/my prefix` and a libdir of `otherlibdir`. |
| 216 |
|
| 217 |
### Properties |
| 218 |
|
| 219 |
*New in native files in 0.54.0*, always in cross files. |
| 220 |
|
| 221 |
In addition to special data that may be specified in cross files, this |
| 222 |
section may contain random key value pairs accessed using the |
| 223 |
`meson.get_external_property()`, or `meson.get_cross_property()`. |
| 224 |
|
| 225 |
*Changed in 0.56.0* putting `<lang>_args` and `<lang>_link_args` in |
| 226 |
the properties section has been deprecated, and should be put in the |
| 227 |
built-in options section. |
| 228 |
|
| 229 |
#### Supported properties |
| 230 |
|
| 231 |
This is a non exhaustive list of supported variables in the `[properties]` |
| 232 |
section. |
| 233 |
|
| 234 |
- `cmake_toolchain_file` specifies an absolute path to an already existing |
| 235 |
CMake toolchain file that will be loaded with `include()` as the last |
| 236 |
instruction of the automatically generated CMake toolchain file from Meson. |
| 237 |
(*new in 0.56.0*) |
| 238 |
- `cmake_defaults` is a boolean that specifies whether Meson should automatically |
| 239 |
generate default toolchain variables from other sections (`binaries`, |
| 240 |
`host_machine`, etc.) in the machine file. Defaults are always overwritten |
| 241 |
by variables set in the `[cmake]` section. The default is `true`. (*new in 0.56.0*) |
| 242 |
- `cmake_skip_compiler_test` is an enum that specifies when Meson should |
| 243 |
automatically generate toolchain variables to skip the CMake compiler |
| 244 |
sanity checks. This only has an effect if `cmake_defaults` is `true`. |
| 245 |
Supported values are `always`, `never`, `dep_only`. The default is `dep_only`. |
| 246 |
(*new in 0.56.0*) |
| 247 |
- `cmake_use_exe_wrapper` is a boolean that controls whether to use the |
| 248 |
`exe_wrapper` specified in `[binaries]` to run generated executables in CMake |
| 249 |
subprojects. This setting has no effect if the `exe_wrapper` was not specified. |
| 250 |
The default value is `true`. (*new in 0.56.0*) |
| 251 |
- `java_home` is an absolute path pointing to the root of a Java installation. |
| 252 |
- `bindgen_clang_arguments` an array of extra arguments to pass to clang when |
| 253 |
calling bindgen |
| 254 |
|
| 255 |
### CMake variables |
| 256 |
|
| 257 |
*New in 0.56.0* |
| 258 |
|
| 259 |
All variables set in the `[cmake]` section will be added to the |
| 260 |
generate CMake toolchain file used for both CMake dependencies and |
| 261 |
CMake subprojects. The type of each entry must be either a string or a |
| 262 |
list of strings. |
| 263 |
|
| 264 |
**Note:** All occurrences of `\` in the value of all keys will be replaced with |
| 265 |
a `/` since CMake has a lot of issues with correctly escaping `\` when |
| 266 |
dealing with variables (even in cases where a path in `CMAKE_C_COMPILER` |
| 267 |
is correctly escaped, CMake will still trip up internally for instance) |
| 268 |
|
| 269 |
A custom toolchain file should be used (via the `cmake_toolchain_file` |
| 270 |
property) if `\` support is required. |
| 271 |
|
| 272 |
```ini |
| 273 |
[cmake] |
| 274 |
|
| 275 |
CMAKE_C_COMPILER = '/usr/bin/gcc' |
| 276 |
CMAKE_CXX_COMPILER = 'C:\\usr\\bin\\g++' |
| 277 |
CMAKE_SOME_VARIABLE = ['some', 'value with spaces'] |
| 278 |
``` |
| 279 |
|
| 280 |
For instance, the `[cmake]` section from above will generate the |
| 281 |
following code in the CMake toolchain file: |
| 282 |
|
| 283 |
```cmake |
| 284 |
set(CMAKE_C_COMPILER "/usr/bin/gcc") |
| 285 |
set(CMAKE_CXX_COMPILER "C:/usr/bin/g++") |
| 286 |
set(CMAKE_SOME_VARIABLE "some" "value with spaces") |
| 287 |
``` |
| 288 |
|
| 289 |
### Project specific options |
| 290 |
|
| 291 |
*New in 0.56.0* |
| 292 |
|
| 293 |
Path options are not allowed, those must be set in the `[paths]` |
| 294 |
section. |
| 295 |
|
| 296 |
Being able to set project specific options in a cross or native file |
| 297 |
can be done using the `[project options]` section of the specific file |
| 298 |
(if doing a cross build the options from the native file will be |
| 299 |
ignored) |
| 300 |
|
| 301 |
For setting options in subprojects use the `[<subproject>:project |
| 302 |
options]` section instead. |
| 303 |
|
| 304 |
```ini |
| 305 |
[project options] |
| 306 |
build-tests = true |
| 307 |
|
| 308 |
[zlib:project options] |
| 309 |
build-tests = false |
| 310 |
``` |
| 311 |
|
| 312 |
### Meson built-in options |
| 313 |
|
| 314 |
*Before 0.56.0, `<lang>_args` and `<lang>_link_args` must be put in the `properties` section instead, else they will be ignored.* |
| 315 |
|
| 316 |
Meson built-in options can be set the same way: |
| 317 |
|
| 318 |
```ini |
| 319 |
[built-in options] |
| 320 |
c_std = 'c99' |
| 321 |
``` |
| 322 |
|
| 323 |
You can set some Meson built-in options on a per-subproject basis, |
| 324 |
such as `default_library` and `werror`. The order of precedence is: |
| 325 |
|
| 326 |
1) Command line |
| 327 |
2) Machine file |
| 328 |
3) Build system definitions |
| 329 |
|
| 330 |
```ini |
| 331 |
[zlib:built-in options] |
| 332 |
default_library = 'static' |
| 333 |
werror = false |
| 334 |
``` |
| 335 |
|
| 336 |
Options set on a per-subproject basis will inherit the option from the |
| 337 |
parent if the parent has a setting but the subproject doesn't, even |
| 338 |
when there is a default set Meson language. |
| 339 |
|
| 340 |
```ini |
| 341 |
[built-in options] |
| 342 |
default_library = 'static' |
| 343 |
``` |
| 344 |
|
| 345 |
will make subprojects use default_library as static. |
| 346 |
|
| 347 |
Some options can be set on a per-machine basis (in other words, the |
| 348 |
value of the build machine can be different than the host machine in a |
| 349 |
cross compile). In these cases the values from both a cross file and a |
| 350 |
native file are used. |
| 351 |
|
| 352 |
An incomplete list of options is: |
| 353 |
- pkg_config_path |
| 354 |
- cmake_prefix_path |
| 355 |
|
| 356 |
## Loading multiple machine files |
| 357 |
|
| 358 |
Native files allow layering (cross files can be layered since Meson |
| 359 |
0.52.0). More than one file can be loaded, with values from a previous |
| 360 |
file being overridden by the next. The intention of this is not |
| 361 |
overriding, but to allow composing files. This composition is done by |
| 362 |
passing the command line argument multiple times: |
| 363 |
|
| 364 |
```console |
| 365 |
meson setup builddir/ --cross-file first.ini --cross-file second.ini --cross-file third.ini |
| 366 |
``` |
| 367 |
|
| 368 |
In this case `first.ini` will be loaded, then `second.ini`, with |
| 369 |
values from `second.ini` replacing `first.ini`, and so on. |
| 370 |
|
| 371 |
For example, if there is a project using C and C++, python 3.4-3.7, |
| 372 |
and LLVM 5-7, and it needs to build with clang 5, 6, and 7, and gcc |
| 373 |
5.x, 6.x, and 7.x; expressing all of these configurations in |
| 374 |
monolithic configurations would result in 81 different native files. |
| 375 |
By layering them, it can be expressed by just 12 native files. |