-
Notifications
You must be signed in to change notification settings - Fork 4
/
Machine-files.html
548 lines (507 loc) · 20.6 KB
/
Machine-files.html
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
<!DOCTYPE html>
<html lang="en">
<head>
<base href=".">
<meta http-equiv="Content-Type" content="text/html; charset=utf-8">
<meta http-equiv="X-UA-Compatible" content="IE=edge">
<meta name="viewport" content="width=device-width, initial-scale=1">
<title>Cross and Native File reference</title>
<link rel="stylesheet" href="assets/css/dark-frontend.css" type="text/css" title="dark">
<link rel="alternate stylesheet" href="assets/css/light-frontend.css" type="text/css" title="light">
<link rel="stylesheet" href="assets/css/bootstrap-toc.min.css" type="text/css">
<link rel="stylesheet" href="assets/css/jquery.mCustomScrollbar.min.css">
<link rel="stylesheet" href="assets/js/search/enable_search.css" type="text/css">
<link rel="stylesheet" href="assets/css/prism-tomorrow.css" type="text/css" title="dark">
<link rel="alternate stylesheet" href="assets/css/prism.css" type="text/css" title="light">
<script src="assets/js/mustache.min.js"></script>
<script src="assets/js/jquery.js"></script>
<script src="assets/js/bootstrap.js"></script>
<script src="assets/js/scrollspy.js"></script>
<script src="assets/js/typeahead.jquery.min.js"></script>
<script src="assets/js/search.js"></script>
<script src="assets/js/compare-versions.js"></script>
<script src="assets/js/jquery.mCustomScrollbar.concat.min.js"></script>
<script src="assets/js/bootstrap-toc.min.js"></script>
<script src="assets/js/jquery.touchSwipe.min.js"></script>
<script src="assets/js/anchor.min.js"></script>
<script src="assets/js/tag_filtering.js"></script>
<script src="assets/js/language_switching.js"></script>
<script src="assets/js/styleswitcher.js"></script>
<script src="assets/js/lines_around_headings.js"></script>
<script src="assets/js/prism-core.js"></script>
<script src="assets/js/prism-autoloader.js"></script>
<script src="assets/js/prism_autoloader_path_override.js"></script>
<script src="assets/js/prism-keep-markup.js"></script>
<script src="assets/js/trie.js"></script>
<link rel="icon" type="image/png" href="assets/images/favicon.png">
<link rel="shortcut icon" href="assets/images/favicon.png">
</head>
<body class="no-script
">
<script>
$('body').removeClass('no-script');
</script>
<nav class="navbar navbar-fixed-top navbar-default" id="topnav">
<div class="container-fluid">
<div class="navbar-right">
<a id="toc-toggle">
<span class="glyphicon glyphicon-menu-right"></span>
<span class="glyphicon glyphicon-menu-left"></span>
</a>
<button type="button" class="navbar-toggle collapsed" data-toggle="collapse" data-target="#navbar-wrapper" aria-expanded="false">
<span class="sr-only">Toggle navigation</span>
<span class="icon-bar"></span>
<span class="icon-bar"></span>
<span class="icon-bar"></span>
</button>
<span title="light mode switch" class="glyphicon glyphicon-sunglasses pull-right" id="lightmode-icon"></span>
<form class="navbar-form pull-right" id="navbar-search-form">
<div class="form-group has-feedback">
<input type="text" class="form-control input-sm" name="search" id="sidenav-lookup-field" placeholder="search" disabled>
<span class="glyphicon glyphicon-search form-control-feedback" id="search-mgn-glass"></span>
</div>
</form>
</div>
<div class="navbar-header">
<a id="sidenav-toggle">
<span class="glyphicon glyphicon-menu-right"></span>
<span class="glyphicon glyphicon-menu-left"></span>
</a>
<a id="home-link" href="index.html" class="hotdoc-navbar-brand">
<img src="assets/images/meson_logo.png" alt="Home">
</a>
</div>
<div class="navbar-collapse collapse" id="navbar-wrapper">
<ul class="nav navbar-nav" id="menu">
<li class="dropdown">
<a class="dropdown-toggle" role="button" data-toggle="dropdown" aria-haspopup="true" aria-expanded="false">
Modules <span class="caret"></span>
</a>
<ul class="dropdown-menu" id="modules-menu">
<li>
<a href="CMake-module.html">CMake</a>
</li>
<li>
<a href="Cuda-module.html">CUDA</a>
</li>
<li>
<a href="Dlang-module.html">Dlang</a>
</li>
<li>
<a href="External-Project-module.html">External Project</a>
</li>
<li>
<a href="Fs-module.html">Filesystem</a>
</li>
<li>
<a href="Gnome-module.html">GNOME</a>
</li>
<li>
<a href="Hotdoc-module.html">Hotdoc</a>
</li>
<li>
<a href="i18n-module.html">i18n</a>
</li>
<li>
<a href="Icestorm-module.html">Icestorm</a>
</li>
<li>
<a href="Java-module.html">Java</a>
</li>
<li>
<a href="Keyval-module.html">Keyval</a>
</li>
<li>
<a href="Pkgconfig-module.html">Pkgconfig</a>
</li>
<li>
<a href="Python-3-module.html">Python 3</a>
</li>
<li>
<a href="Python-module.html">Python</a>
</li>
<li>
<a href="Qt4-module.html">Qt4</a>
</li>
<li>
<a href="Qt5-module.html">Qt5</a>
</li>
<li>
<a href="Qt6-module.html">Qt6</a>
</li>
<li>
<a href="Rust-module.html">Rust</a>
</li>
<li>
<a href="Simd-module.html">Simd</a>
</li>
<li>
<a href="SourceSet-module.html">SourceSet</a>
</li>
<li>
<a href="Wayland-module.html">Wayland</a>
</li>
<li>
<a href="Windows-module.html">Windows</a>
</li>
</ul>
</li>
<li class="dropdown">
<a class="dropdown-toggle" role="button" data-toggle="dropdown" aria-haspopup="true" aria-expanded="false">
Quick References <span class="caret"></span>
</a>
<ul class="dropdown-menu" id="quick-refs-menu">
<li>
<a href="Reference-manual.html">Functions</a>
</li>
<li>
<a href="Build-options.html">Options</a>
</li>
<li>
<a href="Configuration.html">Configuration</a>
</li>
<li>
<a href="Dependencies.html">Dependencies</a>
</li>
<li>
<a href="Unit-tests.html">Tests</a>
</li>
<li>
<a href="Syntax.html">Syntax</a>
</li>
</ul>
</li>
</ul>
<div class="hidden-xs hidden-sm navbar-text navbar-center">
<p><b>The Meson Build System</b></p>
</div>
</div>
</div>
</nav>
<main>
<div data-extension="core" data-hotdoc-in-toplevel="True" data-hotdoc-project="Meson-documentation" data-hotdoc-ref="Machine-files.html" class="page_container" id="page-wrapper">
<script src="assets/js/utils.js"></script>
<div class="panel panel-collapse oc-collapsed" id="sidenav" data-hotdoc-role="navigation">
<script src="assets/js/full-width.js"></script>
<div id="sitenav-wrapper">
<iframe src="hotdoc-sitemap.html" id="sitenav-frame"></iframe>
</div>
</div>
<div id="body">
<div id="main">
<div id="page-description" data-hotdoc-role="main">
<h1 id="cross-and-native-file-reference">Cross and Native File reference</h1>
<p>Cross and native files are nearly identical, but not completely. This
is the documentation on the common values used by both, for the
specific values of one or the other see the <a href="Cross-compilation.html">cross
compilation</a> and <a href="Native-environments.html">native
environments</a>.</p>
<p><em>Changed in 0.56.0</em> Keys within sections are now case sensitive. This
is required to make project options work correctly.</p>
<h2 id="data-types">Data Types</h2>
<p>There are four basic data types in a machine file:</p>
<ul>
<li>strings</li>
<li>arrays</li>
<li>booleans</li>
<li>integers</li>
</ul>
<p>A string is specified single quoted:</p>
<pre><code class="language-ini">[section]
option1 = 'false'
option2 = '2'
</code></pre>
<p>An array is enclosed in square brackets, and must consist of strings or booleans</p>
<pre><code class="language-ini">[section]
option = ['value']
</code></pre>
<p>A boolean must be either <code>true</code> or <code>false</code>, and unquoted.</p>
<pre><code class="language-ini">option = false
</code></pre>
<p>An integer must be an unquoted numeric constant.</p>
<pre><code class="language-ini">option = 42
</code></pre>
<h2 id="sections">Sections</h2>
<p>The following sections are allowed:</p>
<ul>
<li>constants</li>
<li>binaries</li>
<li>paths</li>
<li>properties</li>
<li>cmake</li>
<li>project options</li>
<li>built-in options</li>
</ul>
<h3 id="constants">constants</h3>
<p><em>Since 0.56.0</em></p>
<p>String and list concatenation is supported using the <code>+</code> operator,
joining paths is supported using the <code>/</code> operator. Entries defined in
the <code>[constants]</code> section can be used in any other section (they are
always parsed first), entries in any other section can be used only
within that same section and only after it has been defined.</p>
<pre><code class="language-ini">[constants]
toolchain = '/toolchain'
common_flags = ['--sysroot=' + toolchain / 'sysroot']
[properties]
c_args = common_flags + ['-DSOMETHING']
cpp_args = c_args + ['-DSOMETHING_ELSE']
[binaries]
c = toolchain / 'gcc'
</code></pre>
<p>This can be useful with cross file composition as well. A generic
cross file could be composed with a platform specific file where
constants are defined:</p>
<pre><code class="language-ini"># aarch64.ini
[constants]
arch = 'aarch64-linux-gnu'
</code></pre>
<pre><code class="language-ini"># cross.ini
[binaries]
c = arch + '-gcc'
cpp = arch + '-g++'
strip = arch + '-strip'
pkg-config = arch + '-pkg-config'
...
</code></pre>
<p>This can be used as <code>meson setup --cross-file aarch64.ini --cross-file cross.ini builddir</code>.</p>
<p>Note that file composition happens before the parsing of values. The
example below results in <code>b</code> being <code>'HelloWorld'</code>:</p>
<pre><code class="language-ini"># file1.ini:
[constants]
a = 'Foo'
b = a + 'World'
</code></pre>
<pre><code class="language-ini">#file2.ini:
[constants]
a = 'Hello'
</code></pre>
<p>The example below results in an error when file1.ini is included
before file2.ini because <code>b</code> would be defined before <code>a</code>:</p>
<pre><code class="language-ini"># file1.ini:
[constants]
b = a + 'World'
</code></pre>
<pre><code class="language-ini">#file2.ini:
[constants]
a = 'Hello'
</code></pre>
<p><em>Since 1.3.0</em> Some tokens are replaced in the machine file before parsing it:</p>
<ul>
<li>
<code>@GLOBAL_SOURCE_ROOT@</code>: the absolute path to the project's source tree</li>
<li>
<code>@DIRNAME@</code>: the absolute path to the machine file's parent directory.</li>
</ul>
<p>It can be used, for example, to have paths relative to the source directory, or
relative to toolchain's installation directory.</p>
<pre><code class="language-ini">[binaries]
c = '@DIRNAME@/toolchain/gcc'
exe_wrapper = '@GLOBAL_SOURCE_ROOT@' / 'build-aux' / 'my-exe-wrapper.sh'
</code></pre>
<h3 id="binaries">Binaries</h3>
<p>The binaries section contains a list of binaries. These can be used
internally by Meson, or by the <code>find_program</code> function.</p>
<p>These values must be either strings or an array of strings</p>
<p>Compilers and linkers are defined here using <code><lang></code> and <code><lang>_ld</code>.
<code><lang>_ld</code> is special because it is compiler specific. For compilers
like gcc and clang which are used to invoke the linker this is a value
to pass to their "choose the linker" argument (-fuse-ld= in this
case). For compilers like MSVC and Clang-Cl, this is the path to a
linker for Meson to invoke, such as <code>link.exe</code> or <code>lld-link.exe</code>.
Support for <code>ld</code> is <em>new in 0.53.0</em></p>
<p><em>changed in 0.53.1</em> the <code>ld</code> variable was replaced by <code><lang>_ld</code>,
because it regressed a large number of projects. in 0.53.0 the <code>ld</code>
variable was used instead.</p>
<p>Native example:</p>
<pre><code class="language-ini">c = '/usr/bin/clang'
c_ld = 'lld'
sed = 'C:\\program files\\gnu\\sed.exe'
llvm-config = '/usr/lib/llvm8/bin/llvm-config'
</code></pre>
<p>Cross example:</p>
<pre><code class="language-ini">c = ['ccache', '/usr/bin/i586-mingw32msvc-gcc']
cpp = ['ccache', '/usr/bin/i586-mingw32msvc-g++']
c_ld = 'gold'
cpp_ld = 'gold'
ar = '/usr/i586-mingw32msvc/bin/ar'
strip = '/usr/i586-mingw32msvc/bin/strip'
pkg-config = '/usr/bin/i586-mingw32msvc-pkg-config'
</code></pre>
<p>An incomplete list of internally used programs that can be overridden
here is:</p>
<ul>
<li>cmake</li>
<li>cups-config</li>
<li>gnustep-config</li>
<li>gpgme-config</li>
<li>libgcrypt-config</li>
<li>libwmf-config</li>
<li>llvm-config</li>
<li>pcap-config</li>
<li>pkg-config</li>
<li>sdl2-config</li>
<li>wx-config (or wx-3.0-config or wx-config-gtk)</li>
</ul>
<h3 id="paths-and-directories">Paths and Directories</h3>
<p><em>Deprecated in 0.56.0</em> use the built-in section instead.</p>
<p>As of 0.50.0 paths and directories such as libdir can be defined in
the native and cross files in a paths section. These should be
strings.</p>
<pre><code class="language-ini">[paths]
libdir = 'mylibdir'
prefix = '/my prefix'
</code></pre>
<p>These values will only be loaded when not cross compiling. Any
arguments on the command line will override any options in the native
file. For example, passing <code>--libdir=otherlibdir</code> would result in a
prefix of <code>/my prefix</code> and a libdir of <code>otherlibdir</code>.</p>
<h3 id="properties">Properties</h3>
<p><em>New in native files in 0.54.0</em>, always in cross files.</p>
<p>In addition to special data that may be specified in cross files, this
section may contain random key value pairs accessed using the
<code>meson.get_external_property()</code>, or <code>meson.get_cross_property()</code>.</p>
<p><em>Changed in 0.56.0</em> putting <code><lang>_args</code> and <code><lang>_link_args</code> in
the properties section has been deprecated, and should be put in the
built-in options section.</p>
<h4 id="supported-properties">Supported properties</h4>
<p>This is a non exhaustive list of supported variables in the <code>[properties]</code>
section.</p>
<ul>
<li>
<code>cmake_toolchain_file</code> specifies an absolute path to an already existing
CMake toolchain file that will be loaded with <code>include()</code> as the last
instruction of the automatically generated CMake toolchain file from Meson.
(<em>new in 0.56.0</em>)</li>
<li>
<code>cmake_defaults</code> is a boolean that specifies whether Meson should automatically
generate default toolchain variables from other sections (<code>binaries</code>,
<code>host_machine</code>, etc.) in the machine file. Defaults are always overwritten
by variables set in the <code>[cmake]</code> section. The default is <code>true</code>. (<em>new in 0.56.0</em>)</li>
<li>
<code>cmake_skip_compiler_test</code> is an enum that specifies when Meson should
automatically generate toolchain variables to skip the CMake compiler
sanity checks. This only has an effect if <code>cmake_defaults</code> is <code>true</code>.
Supported values are <code>always</code>, <code>never</code>, <code>dep_only</code>. The default is <code>dep_only</code>.
(<em>new in 0.56.0</em>)</li>
<li>
<code>cmake_use_exe_wrapper</code> is a boolean that controls whether to use the
<code>exe_wrapper</code> specified in <code>[binaries]</code> to run generated executables in CMake
subprojects. This setting has no effect if the <code>exe_wrapper</code> was not specified.
The default value is <code>true</code>. (<em>new in 0.56.0</em>)</li>
<li>
<code>java_home</code> is an absolute path pointing to the root of a Java installation.</li>
<li>
<code>bindgen_clang_arguments</code> an array of extra arguments to pass to clang when
calling bindgen</li>
</ul>
<h3 id="cmake-variables">CMake variables</h3>
<p><em>New in 0.56.0</em></p>
<p>All variables set in the <code>[cmake]</code> section will be added to the
generate CMake toolchain file used for both CMake dependencies and
CMake subprojects. The type of each entry must be either a string or a
list of strings.</p>
<p><strong>Note:</strong> All occurrences of <code>\</code> in the value of all keys will be replaced with
a <code>/</code> since CMake has a lot of issues with correctly escaping <code>\</code> when
dealing with variables (even in cases where a path in <code>CMAKE_C_COMPILER</code>
is correctly escaped, CMake will still trip up internally for instance)</p>
<pre><code> A custom toolchain file should be used (via the `cmake_toolchain_file`
property) if `\` support is required.
</code></pre>
<pre><code class="language-ini">[cmake]
CMAKE_C_COMPILER = '/usr/bin/gcc'
CMAKE_CXX_COMPILER = 'C:\\usr\\bin\\g++'
CMAKE_SOME_VARIABLE = ['some', 'value with spaces']
</code></pre>
<p>For instance, the <code>[cmake]</code> section from above will generate the
following code in the CMake toolchain file:</p>
<pre><code class="language-cmake">set(CMAKE_C_COMPILER "/usr/bin/gcc")
set(CMAKE_CXX_COMPILER "C:/usr/bin/g++")
set(CMAKE_SOME_VARIABLE "some" "value with spaces")
</code></pre>
<h3 id="project-specific-options">Project specific options</h3>
<p><em>New in 0.56.0</em></p>
<p>Path options are not allowed, those must be set in the <code>[paths]</code>
section.</p>
<p>Being able to set project specific options in a cross or native file
can be done using the <code>[project options]</code> section of the specific file
(if doing a cross build the options from the native file will be
ignored)</p>
<p>For setting options in subprojects use the <code>[<subproject>:project options]</code> section instead.</p>
<pre><code class="language-ini">[project options]
build-tests = true
[zlib:project options]
build-tests = false
</code></pre>
<h3 id="meson-builtin-options">Meson built-in options</h3>
<p><em>Before 0.56.0, <code><lang>_args</code> and <code><lang>_link_args</code> must be put in the <code>properties</code> section instead, else they will be ignored.</em></p>
<p>Meson built-in options can be set the same way:</p>
<pre><code class="language-ini">[built-in options]
c_std = 'c99'
</code></pre>
<p>You can set some Meson built-in options on a per-subproject basis,
such as <code>default_library</code> and <code>werror</code>. The order of precedence is:</p>
<ol>
<li>Command line</li>
<li>Machine file</li>
<li>Build system definitions</li>
</ol>
<pre><code class="language-ini">[zlib:built-in options]
default_library = 'static'
werror = false
</code></pre>
<p>Options set on a per-subproject basis will inherit the option from the
parent if the parent has a setting but the subproject doesn't, even
when there is a default set Meson language.</p>
<pre><code class="language-ini">[built-in options]
default_library = 'static'
</code></pre>
<p>will make subprojects use default_library as static.</p>
<p>Some options can be set on a per-machine basis (in other words, the
value of the build machine can be different than the host machine in a
cross compile). In these cases the values from both a cross file and a
native file are used.</p>
<p>An incomplete list of options is:</p>
<ul>
<li>pkg_config_path</li>
<li>cmake_prefix_path</li>
</ul>
<h2 id="loading-multiple-machine-files">Loading multiple machine files</h2>
<p>Native files allow layering (cross files can be layered since Meson
0.52.0). More than one file can be loaded, with values from a previous
file being overridden by the next. The intention of this is not
overriding, but to allow composing files. This composition is done by
passing the command line argument multiple times:</p>
<pre><code class="language-console">meson setup builddir/ --cross-file first.ini --cross-file second.ini --cross-file third.ini
</code></pre>
<p>In this case <code>first.ini</code> will be loaded, then <code>second.ini</code>, with
values from <code>second.ini</code> replacing <code>first.ini</code>, and so on.</p>
<p>For example, if there is a project using C and C++, python 3.4-3.7,
and LLVM 5-7, and it needs to build with clang 5, 6, and 7, and gcc
5.x, 6.x, and 7.x; expressing all of these configurations in
monolithic configurations would result in 81 different native files.
By layering them, it can be expressed by just 12 native files.</p>
</div>
</div>
<div id="search_results">
<p>The results of the search are</p>
</div>
<div id="footer">
<hr>
<div class="license-description">
Website licensing information are available on the <a href="legal.html">Legal</a> page.
</div>
</div>
</div>
<div id="toc-column">
<div class="edit-button">
<a href="https://github.com/mesonbuild/meson/edit/master/docs/markdown/Machine-files.md" data-hotdoc-role="edit-button">Edit on GitHub</a>
</div>
<div id="toc-wrapper">
<nav id="toc"></nav>
</div>
</div>
</div>
</main>
<script src="assets/js/navbar_offset_scroller.js"></script>
</body>
</html>