Debian Codegraph @

subprojects/meson-docs/docs/markdown/Machine-files.md

raw
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.