-
Notifications
You must be signed in to change notification settings - Fork 4
/
Copy pathFAQ.html
813 lines (769 loc) · 40.7 KB
/
FAQ.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
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
795
796
797
798
799
800
801
802
803
804
805
806
807
808
809
810
811
812
813
<!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>FAQ</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="FAQ.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="meson-frequently-asked-questions">Meson Frequently Asked Questions</h1>
<p>See also <a href="howtox.html">How do I do X in Meson</a>.</p>
<h2 id="why-is-it-called-meson">Why is it called Meson?</h2>
<p>When the name was originally chosen, there were two main limitations:
there must not exist either a Debian package or a Sourceforge project
of the given name. This ruled out tens of potential project names. At
some point the name Gluon was considered. Gluons are elementary
particles that hold protons and neutrons together, much like a build
system's job is to take pieces of source code and a compiler and bind
them to a complete whole.</p>
<p>Unfortunately this name was taken, too. Then the rest of subatomic
particles were examined and Meson was found to be available.</p>
<h2 id="what-is-the-correct-way-to-use-threads-such-as-pthreads">What is the correct way to use threads (such as pthreads)?</h2>
<pre><code class="language-meson">thread_dep = dependency('threads')
</code></pre>
<p>This will set up everything on your behalf. People coming from
Autotools or CMake want to do this by looking for <code>libpthread.so</code>
manually. Don't do that, it has tricky corner cases especially when
cross compiling.</p>
<h2 id="how-to-use-meson-on-a-host-where-it-is-not-available-in-system-packages">How to use Meson on a host where it is not available in system packages?</h2>
<p>Starting from version 0.29.0, Meson is available from the <a href="https://pypi.python.org/pypi/meson/">Python
Package Index</a>, so installing it
simply a matter of running this command:</p>
<pre><code class="language-console">$ pip3 install <your options here> meson
</code></pre>
<p>If you don't have access to PyPI, that is not a problem either. Meson
has been designed to be easily runnable from an extracted source
tarball or even a git checkout. First you need to download Meson. Then
use this command to set up you build instead of plain <code>meson</code>.</p>
<pre><code class="language-console">$ /path/to/meson.py <options>
</code></pre>
<p>After this you don't have to care about invoking Meson any more. It
remembers where it was originally invoked from and calls itself
appropriately. As a user the only thing you need to do is to <code>cd</code> into
your build directory and invoke <code>meson compile</code>.</p>
<h2 id="why-cant-i-specify-target-files-with-a-wildcard">Why can't I specify target files with a wildcard?</h2>
<p>Instead of specifying files explicitly, people seem to want to do this:</p>
<pre><code class="language-meson">executable('myprog', sources : '*.cpp') # This does NOT work!
</code></pre>
<p>Meson does not support this syntax and the reason for this is simple.
This cannot be made both reliable and fast. By reliable we mean that
if the user adds a new source file to the subdirectory, Meson should
detect that and make it part of the build automatically.</p>
<p>One of the main requirements of Meson is that it must be fast. This
means that a no-op build in a tree of 10 000 source files must take no
more than a fraction of a second. This is only possible because Meson
knows the exact list of files to check. If any target is specified as
a wildcard glob, this is no longer possible. Meson would need to
re-evaluate the glob every time and compare the list of files produced
against the previous list. This means inspecting the entire source
tree (because the glob pattern could be <code>src/\*/\*/\*/\*.cpp</code> or
something like that). This is impossible to do efficiently.</p>
<p>The main backend of Meson is Ninja, which does not support wildcard
matches either, and for the same reasons.</p>
<p>Because of this, all source files must be specified explicitly.</p>
<h2 id="but-i-really-want-to-use-wildcards">But I really want to use wildcards!</h2>
<p>If the tradeoff between reliability and convenience is acceptable to
you, then Meson gives you all the tools necessary to do wildcard
globbing. You are allowed to run arbitrary commands during
configuration. First you need to write a script that locates the files
to compile. Here's a simple shell script that writes all <code>.c</code> files in
the current directory, one per line.</p>
<pre><code class="language-bash">#!/bin/sh
for i in *.c; do
echo $i
done
</code></pre>
<p>Then you need to run this script in your Meson file, convert the
output into a string array and use the result in a target.</p>
<pre><code class="language-meson">c = run_command('grabber.sh', check: true)
sources = c.stdout().strip().split('\n')
e = executable('prog', sources)
</code></pre>
<p>The script can be any executable, so it can be written in shell,
Python, Lua, Perl or whatever you wish.</p>
<p>As mentioned above, the tradeoff is that just adding new files to the
source directory does <em>not</em> add them to the build automatically. To
add them you need to tell Meson to reinitialize itself. The simplest
way is to touch the <code>meson.build</code> file in your source root. Then Meson
will reconfigure itself next time the build command is run. Advanced
users can even write a small background script that utilizes a
filesystem event queue, such as
<a href="https://en.wikipedia.org/wiki/Inotify">inotify</a>, to do this
automatically.</p>
<h2 id="should-i-use-subdir-or-subproject">Should I use <code>subdir</code> or <code>subproject</code>?</h2>
<p>The answer is almost always <code>subdir</code>. Subproject exists for a very
specific use case: embedding external dependencies into your build
process. As an example, suppose we are writing a game and wish to use
SDL. Let us further suppose that SDL comes with a Meson build
definition. Let us suppose even further that we don't want to use
prebuilt binaries but want to compile SDL for ourselves.</p>
<p>In this case you would use <code>subproject</code>. The way to do it would be to
grab the source code of SDL and put it inside your own source
tree. Then you would do <code>sdl = subproject('sdl')</code>, which would cause
Meson to build SDL as part of your build and would then allow you to
link against it or do whatever else you may prefer.</p>
<p>For every other use you would use <code>subdir</code>. As an example, if you
wanted to build a shared library in one dir and link tests against it
in another dir, you would do something like this:</p>
<pre><code class="language-meson">project('simple', 'c')
subdir('src') # library is built here
subdir('tests') # test binaries would link against the library here
</code></pre>
<h2 id="why-is-there-not-a-make-backend">Why is there not a Make backend?</h2>
<p>Because Make is slow. This is not an implementation issue, Make simply
cannot be made fast. For further info we recommend you read <a href="http://neugierig.org/software/chromium/notes/2011/02/ninja.html">this
post</a>
by Evan Martin, the author of Ninja. Makefiles also have a syntax that
is very unpleasant to write which makes them a big maintenance burden.</p>
<p>The only reason why one would use Make instead of Ninja is working on
a platform that does not have a Ninja port. Even in this case it is an
order of magnitude less work to port Ninja than it is to write a Make
backend for Meson.</p>
<p>Just use Ninja, you'll be happier that way. I guarantee it.</p>
<h2 id="why-is-meson-not-just-a-python-module-so-i-could-code-my-build-setup-in-python">Why is Meson not just a Python module so I could code my build setup in Python?</h2>
<p>A related question to this is <em>Why is Meson's configuration language
not Turing-complete?</em></p>
<p>There are many good reasons for this, most of which are summarized on
this web page: <a href="https://taint.org/2011/02/18/001527a.html">Against The Use Of Programming Languages in
Configuration Files</a>.</p>
<p>In addition to those reasons, not exposing Python or any other "real"
programming language makes it possible to port Meson's implementation
to a different language. This might become necessary if, for example,
Python turns out to be a performance bottleneck. This is an actual
problem that has caused complications for GNU Autotools and SCons.</p>
<h2 id="how-do-i-do-the-equivalent-of-libtools-exportsymbol-and-exportregex">How do I do the equivalent of Libtools export-symbol and export-regex?</h2>
<p>Either by using <a href="https://gcc.gnu.org/wiki/Visibility">GCC symbol
visibility</a> or by writing a
<a href="https://sourceware.org/binutils/docs/ld.html">linker
script</a>. This
has the added benefit that your symbol definitions are in a standalone
file instead of being buried inside your build definitions. An example
can be found
<a href="https://github.com/jpakkane/meson/tree/master/test%20cases/linuxlike/3%20linker%20script">here</a>.</p>
<h2 id="my-project-works-fine-on-linux-and-mingw-but-fails-to-link-with-msvc-due-to-a-missing-lib-file-fatal-error-lnk1181-why">My project works fine on Linux and MinGW but fails to link with MSVC due to a missing .lib file (fatal error LNK1181). Why?</h2>
<p>With GCC, all symbols on shared libraries are exported automatically
unless you specify otherwise. With MSVC no symbols are exported by
default. If your shared library exports no symbols, MSVC will silently
not produce an import library file leading to failures. The solution
is to add symbol visibility definitions <a href="https://gcc.gnu.org/wiki/Visibility">as specified in GCC
wiki</a>.</p>
<h2 id="i-added-some-compiler-flags-and-now-the-build-fails-with-weird-errors-what-is-happening">I added some compiler flags and now the build fails with weird errors. What is happening?</h2>
<p>You probably did the equivalent to this:</p>
<pre><code class="language-meson">executable('foobar', ...
c_args : '-some_arg -other_arg')
</code></pre>
<p>Meson is <em>explicit</em>. In this particular case it will <strong>not</strong>
automatically split your strings at whitespaces, instead it will take
it as is and work extra hard to pass it to the compiler unchanged,
including quoting it properly over shell invocations. This is
mandatory to make e.g. files with spaces in them work flawlessly. To
pass multiple command line arguments, you need to explicitly put them
in an array like this:</p>
<pre><code class="language-meson">executable('foobar', ...
c_args : ['-some_arg', '-other_arg'])
</code></pre>
<h2 id="why-are-changes-to-default-project-options-ignored">Why are changes to default project options ignored?</h2>
<p>You probably had a project that looked something like this:</p>
<pre><code class="language-meson">project('foobar', 'cpp')
</code></pre>
<p>This defaults to <code>c++11</code> on GCC compilers. Suppose you want to use
<code>c++14</code> instead, so you change the definition to this:</p>
<pre><code class="language-meson">project('foobar', 'cpp', default_options : ['cpp_std=c++14'])
</code></pre>
<p>But when you recompile, it still uses <code>c++11</code>. The reason for this is
that default options are only looked at when you are setting up a
build directory for the very first time. After that the setting is
considered to have a value and thus the default value is ignored. To
change an existing build dir to <code>c++14</code>, either reconfigure your build
dir with <code>meson configure</code> or delete the build dir and recreate it
from scratch.</p>
<p>The reason we don't automatically change the option value when the
default is changed is that it is impossible to know to do that
reliably. The actual question that we need to solve is "if the
option's value is foo and the default value is bar, should we change
the option value to bar also". There are many choices:</p>
<ul>
<li>
<p>if the user has changed the value themselves from the default, then
we must not change it back</p>
</li>
<li>
<p>if the user has not changed the value, but changes the default
value, then this section's premise would seem to indicate that the
value should be changed</p>
</li>
<li>
<p>suppose the user changes the value from the default to foo, then
back to bar and then changes the default value to bar, the correct
step to take is ambiguous by itself</p>
</li>
</ul>
<p>In order to solve the latter question we would need to remember not
only the current and old value, but also all the times the user has
changed the value and from which value to which other value. Since
people don't remember their own actions that far back, toggling
between states based on long history would be confusing.</p>
<p>Because of this we do the simple and understandable thing: default
values are only defaults and will never affect the value of an option
once set.</p>
<h2 id="does-wrap-download-sources-behind-my-back">Does wrap download sources behind my back?</h2>
<p>It does not. In order for Meson to download anything from the net
while building, two conditions must be met.</p>
<p>First of all there needs to be a <code>.wrap</code> file with a download URL in
the <code>subprojects</code> directory. If one does not exist, Meson will not
download anything.</p>
<p>The second requirement is that there needs to be an explicit
subproject invocation in your <code>meson.build</code> files. Either
<code>subproject('foobar')</code> or <code>dependency('foobar', fallback : ['foobar', 'foo_dep'])</code>. If these declarations either are not in any build file
or they are not called (due to e.g. <code>if/else</code>) then nothing is
downloaded.</p>
<p>If this is not sufficient for you, starting from release 0.40.0 Meson
has a option called <code>wrap-mode</code> which can be used to disable wrap
downloads altogether with <code>--wrap-mode=nodownload</code>. You can also
disable dependency fallbacks altogether with <code>--wrap-mode=nofallback</code>,
which also implies the <code>nodownload</code> option.</p>
<p>If on the other hand, you want Meson to always use the fallback
for dependencies, even when an external dependency exists and could
satisfy the version requirements, for example in order to make
sure your project builds when fallbacks are used, you can use
<code>--wrap-mode=forcefallback</code> since 0.46.0.</p>
<h2 id="why-is-meson-implemented-in-python-rather-than-programming-language-x">Why is Meson implemented in Python rather than [programming language X]?</h2>
<p>Because build systems are special in ways normal applications aren't.</p>
<p>Perhaps the biggest limitation is that because Meson is used to build
software at the very lowest levels of the OS, it is part of the core
bootstrap for new systems. Whenever support for a new CPU architecture
is added, Meson must run on the system before software using it can be
compiled natively. This requirement adds two hard limitations.</p>
<p>The first one is that Meson must have the minimal amount of
dependencies, because they must all be built during the bootstrap to
get Meson to work.</p>
<p>The second is that Meson must support all CPU architectures, both
existing and future ones. As an example many new programming languages
have only an LLVM based compiler available. LLVM has limited CPU
support compared to, say, GCC, and thus bootstrapping Meson on such
platforms would first require adding new processor support to
LLVM. This is in most cases unfeasible.</p>
<p>A further limitation is that we want developers on as many platforms
as possible to submit to Meson development using the default tools
provided by their operating system. In practice what this means is
that Windows developers should be able to contribute using nothing but
Visual Studio.</p>
<p>At the time of writing (April 2018) there are only three languages
that could fulfill these requirements:</p>
<ul>
<li>C</li>
<li>C++</li>
<li>Python</li>
</ul>
<p>Out of these we have chosen Python because it is the best fit for our
needs.</p>
<h2 id="but-i-really-want-a-version-of-meson-that-doesnt-use-python">But I really want a version of Meson that doesn't use python!</h2>
<p>Ecosystem diversity is good. We encourage interested users to write this
competing implementation of Meson themselves. As of September 2021, there are 3
projects attempting to do just this:</p>
<ul>
<li><a href="https://git.sr.ht/%7Elattis/muon">muon</a></li>
<li><a href="https://github.com/dcbaker/meson-plus-plus">Meson++</a></li>
<li><a href="https://git.sr.ht/%7Ebl4ckb0ne/boson">boson</a></li>
</ul>
<h2 id="i-have-proprietary-compiler-toolchain-x-that-does-not-work-with-meson-how-can-i-make-it-work">I have proprietary compiler toolchain X that does not work with Meson, how can I make it work?</h2>
<p>Meson needs to know several details about each compiler in order to
compile code with it. These include things such as which compiler
flags to use for each option and how to detect the compiler from its
output. This information cannot be input via a configuration file,
instead it requires changes to Meson's source code that need to be
submitted to Meson master repository. In theory you can run your own
forked version with custom patches, but that's not good use of your
time. Please submit the code upstream so everyone can use the
toolchain.</p>
<p>The steps for adding a new compiler for an existing language are
roughly the following. For simplicity we're going to assume a C
compiler.</p>
<ul>
<li>
<p>Create a new class with a proper name in
<code>mesonbuild/compilers/c.py</code>. Look at the methods that other
compilers for the same language have and duplicate what they do.</p>
</li>
<li>
<p>If the compiler can only be used for cross compilation, make sure to
flag it as such (see existing compiler classes for examples).</p>
</li>
<li>
<p>Add detection logic to <code>mesonbuild/environment.py</code>, look for a
method called <code>detect_c_compiler</code>.</p>
</li>
<li>
<p>Run the test suite and fix issues until the tests pass.</p>
</li>
<li>
<p>Submit a pull request, add the result of the test suite to your MR
(linking an existing page is fine).</p>
</li>
<li>
<p>If the compiler is freely available, consider adding it to the CI
system.</p>
</li>
</ul>
<h2 id="why-does-building-my-project-with-msvc-output-static-libraries-called-libfooa">Why does building my project with MSVC output static libraries called <code>libfoo.a</code>?</h2>
<p>The naming convention for static libraries on Windows is usually
<code>foo.lib</code>. Unfortunately, import libraries are also called <code>foo.lib</code>.</p>
<p>This causes filename collisions with the default library type where we
build both shared and static libraries, and also causes collisions
during installation since all libraries are installed to the same
directory by default.</p>
<p>To resolve this, we decided to default to creating static libraries of
the form <code>libfoo.a</code> when building with MSVC. This has the following
advantages:</p>
<ol>
<li>Filename collisions are completely avoided.</li>
<li>The format for MSVC static libraries is <code>ar</code>, which is the same as the GNU
static library format, so using this extension is semantically correct.</li>
<li>The static library filename format is now the same on all platforms and with
all toolchains.</li>
<li>Both Clang and GNU compilers can search for <code>libfoo.a</code> when specifying
a library as <code>-lfoo</code>. This does not work for alternative naming schemes for
static libraries such as <code>libfoo.lib</code>.</li>
<li>Since <code>-lfoo</code> works out of the box, pkgconfig files will work correctly for
projects built with both MSVC, GCC, and Clang on Windows.</li>
<li>MSVC does not have arguments to search for library filenames, and <a href="https://docs.microsoft.com/en-us/cpp/build/reference/link-input-files?view=vs-2019">it does
not care what the extension is</a>,
so specifying <code>libfoo.a</code> instead of <code>foo.lib</code> does not change the workflow,
and is an improvement since it's less ambiguous.</li>
<li>Projects built with the MinGW compiler are fully compatible with
MSVC as long as they use the same CRT (e.g. UCRT with MSYS2).
These projects also name their static libraries <code>libfoo.a</code>.</li>
</ol>
<p>If, for some reason, you really need your project to output static
libraries of the form <code>foo.lib</code> when building with MSVC, you can set
the
<a href="https://mesonbuild.com/Reference-manual.html#library"><code>name_prefix:</code></a>
kwarg to <code>''</code> and the
<a href="https://mesonbuild.com/Reference-manual.html#library"><code>name_suffix:</code></a>
kwarg to <code>'lib'</code>. To get the default behaviour for each, you can
either not specify the kwarg, or pass <code>[]</code> (an empty array) to it.</p>
<h2 id="do-i-need-to-add-my-headers-to-the-sources-list-like-in-autotools">Do I need to add my headers to the sources list like in Autotools?</h2>
<p>Autotools requires you to add private and public headers to the sources list so
that it knows what files to include in the tarball generated by <code>make dist</code>.
Meson's <code>dist</code> command simply gathers everything committed to your git/hg
repository and adds it to the tarball, so adding headers to the sources list is
pointless.</p>
<p>Meson uses Ninja which uses compiler dependency information to automatically
figure out dependencies between C sources and headers, so it will rebuild
things correctly when a header changes.</p>
<p>The only exception to this are generated headers, for which you must <a href="FAQ.html#how-do-i-tell-meson-that-my-sources-use-generated-headers">declare
dependencies correctly</a>.</p>
<p>If, for whatever reason, you do add non-generated headers to the sources list
of a target, Meson will simply ignore them.</p>
<h2 id="how-do-i-tell-meson-that-my-sources-use-generated-headers">How do I tell Meson that my sources use generated headers?</h2>
<p>Let's say you use a <a href="https://mesonbuild.com/Reference-manual.html#custom_target"><code>custom_target()</code></a>
to generate the headers, and then <code>#include</code> them in your C code. Here's how
you ensure that Meson generates the headers before trying to compile any
sources in the build target:</p>
<pre><code class="language-meson">libfoo_gen_headers = custom_target('gen-headers', ..., output: 'foo-gen.h')
libfoo_sources = files('foo-utils.c', 'foo-lib.c')
# Add generated headers to the list of sources for the build target
libfoo = library('foo', sources: [libfoo_sources + libfoo_gen_headers])
</code></pre>
<p>Now let's say you have a new target that links to <code>libfoo</code>:</p>
<pre><code class="language-meson">libbar_sources = files('bar-lib.c')
libbar = library('bar', sources: libbar_sources, link_with: libfoo)
</code></pre>
<p>This adds a <strong>link-time</strong> dependency between the two targets, but note that the
sources of the targets have <strong>no compile-time</strong> dependencies and can be built
in any order; which improves parallelism and speeds up builds.</p>
<p>If the sources in <code>libbar</code> <em>also</em> use <code>foo-gen.h</code>, that's a <em>compile-time</em>
dependency, and you'll have to add <code>libfoo_gen_headers</code> to <code>sources:</code> for
<code>libbar</code> too:</p>
<pre><code class="language-meson">libbar_sources = files('bar-lib.c')
libbar = library('bar', sources: libbar_sources + libfoo_gen_headers, link_with: libfoo)
</code></pre>
<p>Alternatively, if you have multiple libraries with sources that link to
a library and also use its generated headers, this code is equivalent to above:</p>
<pre><code class="language-meson"># Add generated headers to the list of sources for the build target
libfoo = library('foo', sources: libfoo_sources + libfoo_gen_headers)
# Declare a dependency that will add the generated headers to sources
libfoo_dep = declare_dependency(link_with: libfoo, sources: libfoo_gen_headers)
...
libbar = library('bar', sources: libbar_sources, dependencies: libfoo_dep)
</code></pre>
<p><strong>Note:</strong> You should only add <em>headers</em> to <code>sources:</code> while declaring
a dependency. If your custom target outputs both sources and headers, you can
use the subscript notation to get only the header(s):</p>
<pre><code class="language-meson">libfoo_gen_sources = custom_target('gen-headers', ..., output: ['foo-gen.h', 'foo-gen.c'])
libfoo_gen_headers = libfoo_gen_sources[0]
# Add static and generated sources to the target
libfoo = library('foo', sources: libfoo_sources + libfoo_gen_sources)
# Declare a dependency that will add the generated *headers* to sources
libfoo_dep = declare_dependency(link_with: libfoo, sources: libfoo_gen_headers)
...
libbar = library('bar', sources: libbar_sources, dependencies: libfoo_dep)
</code></pre>
<p>A good example of a generator that outputs both sources and headers is
<a href="https://mesonbuild.com/Gnome-module.html#gnomemkenums"><code>gnome.mkenums()</code></a>.</p>
<h2 id="how-do-i-disable-exceptions-and-rtti-in-my-c-project">How do I disable exceptions and RTTI in my C++ project?</h2>
<p>With the <code>cpp_eh</code> and <code>cpp_rtti</code> options. A typical invocation would
look like this:</p>
<pre><code>meson -Dcpp_eh=none -Dcpp_rtti=false <other options>
</code></pre>
<p>The RTTI option is only available since Meson version 0.53.0.</p>
<h2 id="should-i-check-for-buildtype-or-individual-options-like-debug-in-my-build-files">Should I check for <code>buildtype</code> or individual options like <code>debug</code> in my build files?</h2>
<p>This depends highly on what you actually need to happen. The
´buildtype` option is meant do describe the current build's
<em>intent</em>. That is, what it will be used for. Individual options are
for determining what the exact state is. This becomes clearer with a
few examples.</p>
<p>Suppose you have a source file that is known to miscompile when using
<code>-O3</code> and requires a workaround. Then you'd write something like this:</p>
<pre><code class="language-meson">if get_option('optimization') == '3'
add_project_arguments('-DOPTIMIZATION_WORKAROUND', ...)
endif
</code></pre>
<p>On the other hand if your project has extra logging and sanity checks
that you would like to be enabled during the day to day development
work (which uses the <code>debug</code> buildtype), you'd do this instead:</p>
<pre><code class="language-meson">if get_option('buildtype') == 'debug'
add_project_arguments('-DENABLE_EXTRA_CHECKS', ...)
endif
</code></pre>
<p>In this way the extra options are automatically used during
development but are not compiled in release builds. Note that (since
Meson 0.57.0) you can set optimization to, say, 2 in your debug builds
if you want to. If you tried to set this flag based on optimization
level, it would fail in this case.</p>
<h2 id="how-do-i-use-a-library-before-declaring-it">How do I use a library before declaring it?</h2>
<p>This is valid (and good) code:</p>
<pre><code>libA = library('libA', 'fileA.cpp', link_with : [])
libB = library('libB', 'fileB.cpp', link_with : [libA])
</code></pre>
<p>But there is currently no way to get something like this to work:</p>
<pre><code>libB = library('libB', 'fileB.cpp', link_with : [libA])
libA = library('libA', 'fileA.cpp', link_with : [])
</code></pre>
<p>This means that you HAVE to write your <code>library(...)</code> calls in the order that the
dependencies flow. While ideas to make arbitrary orders possible exist, they were
rejected because reordering the <code>library(...)</code> calls was considered the "proper"
way. See <a href="https://github.com/mesonbuild/meson/issues/8178">here</a> for the discussion.</p>
<h2 id="why-doesnt-meson-have-user-defined-functionsmacros">Why doesn't meson have user defined functions/macros?</h2>
<p>The tl;dr answer to this is that meson's design is focused on solving specific
problems rather than providing a general purpose language to write complex
code solutions in build files. Build systems should be quick to write and
quick to understand, functions muddle this simplicity.</p>
<p>The long answer is twofold:</p>
<p>First, Meson aims to provide a rich set of tools that solve specific problems
simply out of the box. This is similar to the "batteries included" mentality of
Python. By providing tools that solve common problems in the simplest way
possible <em>in</em> Meson we are solving that problem for everyone instead of forcing
everyone to solve that problem for themselves over and over again, often
badly. One example of this are Meson's dependency wrappers around various
config-tool executables (sdl-config, llvm-config, etc). In other build
systems each user of that dependency writes a wrapper and deals with the
corner cases (or doesn't, as is often the case), in Meson we handle them
internally, everyone gets fixes and the corner cases are ironed out for
<em>everyone</em>. Providing user defined functions or macros goes directly against
this design goal.</p>
<p>Second, functions and macros makes the build system more difficult to reason
about. When you encounter some function call, you can refer to the reference
manual to see that function and its signature. Instead of spending
frustrating hours trying to interpret some bit of m4 or follow long include
paths to figure out what <code>function1</code> (which calls <code>function2</code>, which calls
<code>function3</code>, ad infinitum), you know what the build system is doing. Unless
you're actively developing Meson itself, it's just a tool to orchestrate
building the thing you actually care about. We want you to spend as little
time worrying about build systems as possible so you can spend more time on
<em>your code</em>.</p>
<p>Many times user defined functions are used due to a lack of loops or
because loops are tedious to use in the language. Meson has both arrays/lists
and hashes/dicts natively. Compare the following pseudo code:</p>
<pre><code class="language-meson">func(name, sources, extra_args)
executable(
name,
sources,
c_args : extra_args
)
endfunc
func(exe1, ['1.c', 'common.c'], [])
func(exe2, ['2.c', 'common.c'], [])
func(exe2_a, ['2.c', 'common.c'], ['-arg'])
</code></pre>
<pre><code class="language-meson">foreach e : [['1', '1.c', []],
['2', '2.c', []],
['2', '2.c', ['-arg']]]
executable(
'exe' + e[0],
e[1],
c_args : e[2],
)
endforeach
</code></pre>
<p>The loop is both less code and is much easier to reason about than the function
version is, especially if the function were to live in a separate file, as is
common in other popular build systems.</p>
<p>Build system DSLs also tend to be badly thought out as generic programming
languages, Meson tries to make it easy to use external scripts or programs
for handling complex problems. While one can't always convert build logic
into a scripting language (or compiled language), when it can be done this is
often a better solution. External languages tend to be well-thought-out and
tested, generally don't regress, and users are more likely to have domain
knowledge about them. They also tend to have better tooling (such as
autocompletion, linting, testing solutions), which make them a lower
maintenance burden over time.</p>
<h2 id="why-dont-the-arguments-passed-to-add_project_link_arguments-affect-anything">Why don't the arguments passed to <code>add_project_link_arguments</code> affect anything?</h2>
<p>Given code like this:</p>
<pre><code class="language-meson">add_project_link_arguments(['-Wl,-foo'], language : ['c'])
executable(
'main',
'main.c',
'helper.cpp',
)
</code></pre>
<p>One might be surprised to find that <code>-Wl,-foo</code> is <em>not</em> applied to the linkage
of the <code>main</code> executable. In this Meson is working as expected, since meson will
attempt to determine the correct linker to use automatically. This avoids
situations like in autotools where dummy C++ sources have to be added to some
compilation targets to get correct linkage. So in the above case the C++ linker
is used, instead of the C linker, as <code>helper.cpp</code> likely cannot be linked using
the C linker.</p>
<p>Generally the best way to resolve this is to add the <code>cpp</code> language to the
<code>add_project_link_arguments</code> call.</p>
<pre><code class="language-meson">add_project_link_arguments(['-Wl,-foo'], language : ['c', 'cpp'])
executable(
'main',
'main.c',
'helper.cpp',
)
</code></pre>
<p>To force the use of the C linker anyway the <code>link_language</code> keyword argument can
be used. Note that this can result in a compilation failure if there are symbols
that the C linker cannot resolve.</p>
<pre><code class="language-meson">add_project_link_arguments(['-Wl,-foo'], language : ['c'])
executable(
'main',
'main.c',
'helper.cpp',
link_language : 'c',
)
</code></pre>
<h2 id="how-do-i-ignore-the-build-directory-in-my-vcs">How do I ignore the build directory in my VCS?</h2>
<p>You don't need to, assuming you use git or mercurial! Meson >=0.57.0 will
create a <code>.gitignore</code> and <code>.hgignore</code> file for you, inside each build
directory. It glob ignores <code>"*"</code>, since all generated files should not be
checked into git.</p>
<p>Users of older versions of Meson may need to set up ignore files themselves.</p>
<h2 id="how-to-add-preprocessor-defines-to-a-target">How to add preprocessor defines to a target?</h2>
<p>Just add <code>-DFOO</code> to <code>c_args</code> or <code>cpp_args</code>. This works for all known compilers.</p>
<pre><code class="language-meson">mylib = library('mylib', 'mysource.c', c_args: ['-DFOO'])
</code></pre>
<p>Even though <a href="https://learn.microsoft.com/en-us/cpp/build/reference/d-preprocessor-definitions">MSVC documentation</a>
uses <code>/D</code> for preprocessor defines, its <a href="https://learn.microsoft.com/en-us/cpp/build/reference/compiler-command-line-syntax">command-line syntax</a>
accepts <code>-</code> instead of <code>/</code>.
It's not necessary to treat preprocessor defines specially in Meson (<a href="https://github.com/mesonbuild/meson/issues/6269#issuecomment-560003922">GH-6269</a>).</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/FAQ.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>