-
Notifications
You must be signed in to change notification settings - Fork 4
/
Copy pathCommands.html
1185 lines (1135 loc) · 61.2 KB
/
Commands.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
814
815
816
817
818
819
820
821
822
823
824
825
826
827
828
829
830
831
832
833
834
835
836
837
838
839
840
841
842
843
844
845
846
847
848
849
850
851
852
853
854
855
856
857
858
859
860
861
862
863
864
865
866
867
868
869
870
871
872
873
874
875
876
877
878
879
880
881
882
883
884
885
886
887
888
889
890
891
892
893
894
895
896
897
898
899
900
901
902
903
904
905
906
907
908
909
910
911
912
913
914
915
916
917
918
919
920
921
922
923
924
925
926
927
928
929
930
931
932
933
934
935
936
937
938
939
940
941
942
943
944
945
946
947
948
949
950
951
952
953
954
955
956
957
958
959
960
961
962
963
964
965
966
967
968
969
970
971
972
973
974
975
976
977
978
979
980
981
982
983
984
985
986
987
988
989
990
991
992
993
994
995
996
997
998
999
1000
<!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>Command-line commands</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/notes.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="Commands.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="commandline-commands">Command-line commands</h1>
<p>There are two different ways of invoking Meson. First, you can run it
directly from the source tree with the command
<code>/path/to/source/meson.py</code>. Meson may also be installed in which case
the command is simply <code>meson</code>. In this manual we only use the latter
format for simplicity.</p>
<p>Meson is invoked using the following syntax:
<code>meson [COMMAND] [COMMAND_OPTIONS]</code></p>
<p>This section describes all available commands and some of their
Optional arguments. The most common workflow is to run
<a href="Commands.html#setup"><code>setup</code></a>, followed by <a href="Commands.html#compile"><code>compile</code></a>, and then
<a href="Commands.html#install"><code>install</code></a>.</p>
<p>For the full list of all available options for a specific command use
the following syntax: <code>meson COMMAND --help</code></p>
<h3 id="configure">configure</h3>
<pre><code class="language-inc">$ meson configure [-h] [--prefix PREFIX] [--bindir BINDIR]
[--datadir DATADIR] [--includedir INCLUDEDIR]
[--infodir INFODIR] [--libdir LIBDIR]
[--licensedir LICENSEDIR] [--libexecdir LIBEXECDIR]
[--localedir LOCALEDIR] [--localstatedir LOCALSTATEDIR]
[--mandir MANDIR] [--sbindir SBINDIR]
[--sharedstatedir SHAREDSTATEDIR]
[--sysconfdir SYSCONFDIR]
[--auto-features {enabled,disabled,auto}]
[--backend {ninja,vs,vs2010,vs2012,vs2013,vs2015,vs2017,vs2019,vs2022,xcode,none}]
[--genvslite {vs2022}]
[--buildtype {plain,debug,debugoptimized,release,minsize,custom}]
[--debug] [--default-library {shared,static,both}]
[--default-both-libraries {shared,static,auto}]
[--errorlogs] [--install-umask INSTALL_UMASK]
[--layout {mirror,flat}]
[--optimization {plain,0,g,1,2,3,s}] [--prefer-static]
[--stdsplit] [--strip] [--unity {on,off,subprojects}]
[--unity-size UNITY_SIZE]
[--warnlevel {0,1,2,3,everything}] [--werror]
[--wrap-mode {default,nofallback,nodownload,forcefallback,nopromote}]
[--force-fallback-for FORCE_FALLBACK_FOR] [--vsenv]
[--pkgconfig.relocatable]
[--python.bytecompile PYTHON.BYTECOMPILE]
[--python.install-env {auto,prefix,system,venv}]
[--python.platlibdir PYTHON.PLATLIBDIR]
[--python.purelibdir PYTHON.PURELIBDIR]
[--python.allow-limited-api]
[--pkg-config-path PKG_CONFIG_PATH]
[--build.pkg-config-path BUILD.PKG_CONFIG_PATH]
[--cmake-prefix-path CMAKE_PREFIX_PATH]
[--build.cmake-prefix-path BUILD.CMAKE_PREFIX_PATH]
[-D option] [--clearcache] [--no-pager] [-U UNSET_OPTS]
[builddir]
</code></pre>
<p>Changes options of a configured meson project.</p>
<pre><code class="language-inc">positional arguments:
builddir
options:
-h, --help show this help message and exit
--prefix PREFIX Installation prefix.
--bindir BINDIR Executable directory.
--datadir DATADIR Data file directory.
--includedir INCLUDEDIR Header file directory.
--infodir INFODIR Info page directory.
--libdir LIBDIR Library directory.
--licensedir LICENSEDIR Licenses directory (default: ).
--libexecdir LIBEXECDIR Library executable directory.
--localedir LOCALEDIR Locale data directory.
--localstatedir LOCALSTATEDIR Localstate data directory.
--mandir MANDIR Manual page directory.
--sbindir SBINDIR System executable directory.
--sharedstatedir SHAREDSTATEDIR Architecture-independent data directory.
--sysconfdir SYSCONFDIR Sysconf data directory.
--auto-features {enabled,disabled,auto}
Override value of all 'auto' features
(default: auto).
--backend {ninja,vs,vs2010,vs2012,vs2013,vs2015,vs2017,vs2019,vs2022,xcode,none}
Backend to use (default: ninja).
--genvslite {vs2022} Setup multiple buildtype-suffixed ninja-
backend build directories, and a
[builddir]_vs containing a Visual Studio
meta-backend with multiple
configurations that calls into them
(default: vs2022).
--buildtype {plain,debug,debugoptimized,release,minsize,custom}
Build type to use (default: debug).
--debug Enable debug symbols and other
information
--default-library {shared,static,both}
Default library type (default: shared).
--default-both-libraries {shared,static,auto}
Default library type for both_libraries
(default: shared).
--errorlogs Whether to print the logs from failing
tests
--install-umask INSTALL_UMASK Default umask to apply on permissions of
installed files (default: 0o22).
--layout {mirror,flat} Build directory layout (default:
mirror).
--optimization {plain,0,g,1,2,3,s} Optimization level (default: 0).
--prefer-static Whether to try static linking before
shared linking
--stdsplit Split stdout and stderr in test logs
--strip Strip targets on install
--unity {on,off,subprojects} Unity build (default: off).
--unity-size UNITY_SIZE Unity block size (default: 4).
--warnlevel {0,1,2,3,everything} Compiler warning level to use (default:
1).
--werror Treat warnings as errors
--wrap-mode {default,nofallback,nodownload,forcefallback,nopromote}
Wrap mode (default: default).
--force-fallback-for FORCE_FALLBACK_FOR
Force fallback for those subprojects
(default: []).
--vsenv Activate Visual Studio environment
--pkgconfig.relocatable Generate pkgconfig files as relocatable
--python.bytecompile PYTHON.BYTECOMPILE
Whether to compile bytecode (default:
0).
--python.install-env {auto,prefix,system,venv}
Which python environment to install to
(default: prefix).
--python.platlibdir PYTHON.PLATLIBDIR
Directory for site-specific, platform-
specific files (default: ).
--python.purelibdir PYTHON.PURELIBDIR
Directory for site-specific, non-
platform-specific files (default: ).
--python.allow-limited-api Whether to allow use of the Python
Limited API
--pkg-config-path PKG_CONFIG_PATH List of additional paths for pkg-config
to search (default: []). (just for host
machine)
--build.pkg-config-path BUILD.PKG_CONFIG_PATH
List of additional paths for pkg-config
to search (default: []). (just for build
machine)
--cmake-prefix-path CMAKE_PREFIX_PATH
List of additional prefixes for cmake to
search (default: []). (just for host
machine)
--build.cmake-prefix-path BUILD.CMAKE_PREFIX_PATH
List of additional prefixes for cmake to
search (default: []). (just for build
machine)
-D option Set the value of an option, can be used
several times to set multiple options.
--clearcache Clear cached state (e.g. found
dependencies)
--no-pager Do not redirect output to a pager
-U UNSET_OPTS Remove a subproject option.
</code></pre>
<p>Most arguments are the same as in <a href="Commands.html#setup"><code>setup</code></a>.</p>
<p>Note: reconfiguring project will not reset options to their default
values (even if they were changed in <code>meson.build</code>).</p>
<h4 id="examples">Examples:</h4>
<p>List all available options:</p>
<pre><code>meson configure builddir
</code></pre>
<p>Change value of a single option:</p>
<pre><code>meson configure builddir -Doption=new_value
</code></pre>
<h3 id="compile">compile</h3>
<p><em>(since 0.54.0)</em></p>
<pre><code class="language-inc">$ meson compile [-h] [--clean] [-C WD] [-j JOBS] [-l LOAD_AVERAGE] [-v]
[--ninja-args NINJA_ARGS] [--vs-args VS_ARGS]
[--xcode-args XCODE_ARGS]
[TARGET ...]
</code></pre>
<p>Builds a default or a specified target of a configured Meson project.</p>
<pre><code class="language-inc">positional arguments:
TARGET Targets to build. Target has the
following format: [PATH_TO_TARGET/]TARGE
T_NAME.TARGET_SUFFIX[:TARGET_TYPE].
options:
-h, --help show this help message and exit
--clean Clean the build directory.
-C WD directory to cd into before running
-j JOBS, --jobs JOBS The number of worker jobs to run (if
supported). If the value is less than 1
the build program will guess.
-l LOAD_AVERAGE, --load-average LOAD_AVERAGE
The system load average to try to
maintain (if supported).
-v, --verbose Show more verbose output.
--ninja-args NINJA_ARGS Arguments to pass to `ninja` (applied
only on `ninja` backend).
--vs-args VS_ARGS Arguments to pass to `msbuild` (applied
only on `vs` backend).
--xcode-args XCODE_ARGS Arguments to pass to `xcodebuild`
(applied only on `xcode` backend).
</code></pre>
<p><code>--verbose</code> argument is available since 0.55.0.</p>
<h4 id="targets">Targets</h4>
<p><em>(since 0.55.0)</em></p>
<p><code>TARGET</code> has the following syntax <code>[PATH/]NAME.SUFFIX[:TYPE]</code>, where:</p>
<ul>
<li>
<code>NAME</code>: name of the target from <code>meson.build</code> (e.g. <code>foo</code> from <code>executable('foo', ...)</code>).</li>
<li>
<code>SUFFIX</code>: name of the suffix of the target from <code>meson.build</code> (e.g. <code>exe</code> from <code>executable('foo', suffix: 'exe', ...)</code>).</li>
<li>
<code>PATH</code>: path to the target relative to the root <code>meson.build</code> file. Note: relative path for a target specified in the root <code>meson.build</code> is <code>./</code>.</li>
<li>
<code>TYPE</code>: type of the target. Can be one of the following: 'executable', 'static_library', 'shared_library', 'shared_module', 'custom', 'alias', 'run', 'jar'.</li>
</ul>
<p><code>PATH</code>, <code>SUFFIX</code>, and <code>TYPE</code> can all be omitted if the resulting <code>TARGET</code> can be
used to uniquely identify the target in <code>meson.build</code>.</p>
<p>Note that <code>SUFFIX</code> did not exist prior to 1.3.0.</p>
<h4 id="backend-specific-arguments">Backend specific arguments</h4>
<p><em>(since 0.55.0)</em></p>
<p><code>BACKEND-args</code> use the following syntax:</p>
<p>If you only pass a single string, then it is considered to have all
values separated by commas. Thus invoking the following command:</p>
<pre><code>$ meson compile --ninja-args=-n,-d,explain
</code></pre>
<p>would add <code>-n</code>, <code>-d</code> and <code>explain</code> arguments to ninja invocation.</p>
<p>If you need to have commas or spaces in your string values, then you
need to pass the value with proper shell quoting like this:</p>
<pre><code>$ meson compile "--ninja-args=['a,b', 'c d']"
</code></pre>
<h4 id="examples1">Examples:</h4>
<p>Build the project:</p>
<pre><code>meson compile -C builddir
</code></pre>
<p>Execute a dry run on ninja backend with additional debug info:</p>
<pre><code>meson compile --ninja-args=-n,-d,explain
</code></pre>
<p>Build three targets: two targets that have the same <code>foo</code> name, but
different type, and a <code>bar</code> target:</p>
<pre><code>meson compile foo:shared_library foo:static_library bar
</code></pre>
<p>Produce a coverage html report (if available):</p>
<pre><code>ninja coverage-html
</code></pre>
<h3 id="dist">dist</h3>
<p><em>(since 0.52.0)</em></p>
<pre><code class="language-inc">$ meson dist [-h] [-C WD] [--allow-dirty] [--formats FORMATS]
[--include-subprojects] [--no-tests]
</code></pre>
<p>Generates a release archive from the current source tree.</p>
<pre><code class="language-inc">options:
-h, --help show this help message and exit
-C WD directory to cd into before running
--allow-dirty Allow even when repository contains uncommitted
changes.
--formats FORMATS Comma separated list of archive types to create.
Supports xztar (default), bztar, gztar, and zip.
--include-subprojects Include source code of subprojects that have been used
for the build.
--no-tests Do not build and test generated packages.
</code></pre>
<p>See <a href="Creating-releases.html">notes about creating releases</a> for more info.</p>
<h4 id="examples2">Examples:</h4>
<p>Create a release archive:</p>
<pre><code>meson dist -C builddir
</code></pre>
<h3 id="init">init</h3>
<p><em>(since 0.45.0)</em></p>
<pre><code class="language-inc">$ meson init [-h] [-C WD] [-n NAME] [-e EXECUTABLE] [-d DEPS]
[-l {c,cpp,cs,cuda,d,fortran,java,objc,objcpp,rust,vala}] [-b]
[--builddir BUILDDIR] [-f] [--type {executable,library}]
[--version VERSION]
[sourcefile ...]
</code></pre>
<p>Creates a basic set of build files based on a template.</p>
<pre><code class="language-inc">positional arguments:
sourcefile source files. default: all recognized
files in current directory
options:
-h, --help show this help message and exit
-C WD directory to cd into before running
-n NAME, --name NAME project name. default: name of current
directory
-e EXECUTABLE, --executable EXECUTABLE
executable name. default: project name
-d DEPS, --deps DEPS dependencies, comma-separated
-l {c,cpp,cs,cuda,d,fortran,java,objc,objcpp,rust,vala}, --language {c,cpp,cs,cuda,d,fortran,java,objc,objcpp,rust,vala}
project language. default: autodetected
based on source files
-b, --build build after generation
--builddir BUILDDIR directory for build
-f, --force force overwrite of existing files and
directories.
--type {executable,library} project type. default: executable based
project
--version VERSION project version. default: 0.1
</code></pre>
<h4 id="examples3">Examples:</h4>
<p>Create a project in <code>sourcedir</code>:</p>
<pre><code>meson init -C sourcedir
</code></pre>
<h3 id="env2mfile">env2mfile</h3>
<p><em>This command is experimental and subject to change.</em></p>
<p><em>{Since 0.62.0}</em></p>
<pre><code class="language-inc">$ meson env2mfile [-h] [--debarch DEBARCH] [--gccsuffix GCCSUFFIX] -o
OUTFILE [--cross] [--native] [--use-for-build]
[--system SYSTEM] [--subsystem SUBSYSTEM]
[--kernel KERNEL] [--cpu CPU] [--cpu-family CPU_FAMILY]
[--endian {big,little}]
</code></pre>
<p>Create native and cross files from the current environment, typically
by sniffing environment variables like <code>CC</code> and <code>CFLAGS</code>.</p>
<pre><code class="language-inc">options:
-h, --help show this help message and exit
--debarch DEBARCH The dpkg architecture to generate.
--gccsuffix GCCSUFFIX A particular gcc version suffix if necessary.
-o OUTFILE The output file.
--cross Generate a cross compilation file.
--native Generate a native compilation file.
--use-for-build Use _FOR_BUILD envvars.
--system SYSTEM Define system for cross compilation.
--subsystem SUBSYSTEM Define subsystem for cross compilation.
--kernel KERNEL Define kernel for cross compilation.
--cpu CPU Define cpu for cross compilation.
--cpu-family CPU_FAMILY Define cpu family for cross compilation.
--endian {big,little} Define endianness for cross compilation.
</code></pre>
<h4 id="examples4">Examples:</h4>
<p>Autodetect the current cross build environment:</p>
<pre><code>meson env2mfile --cross -o current_cross.txt --cpu=arm7a --cpu-family=arm --system=linux
</code></pre>
<p>Generate a cross build using Debian system information:</p>
<pre><code>meson env2mfile --cross --debarch=armhf -o deb_arm_cross.txt
</code></pre>
<h3 id="introspect">introspect</h3>
<pre><code class="language-inc">$ meson introspect [-h] [--ast] [--benchmarks] [--buildoptions]
[--buildsystem-files] [--compilers] [--dependencies]
[--scan-dependencies] [--installed] [--install-plan]
[--machines] [--projectinfo] [--targets] [--tests]
[--backend {ninja,none,vs,vs2010,vs2012,vs2013,vs2015,vs2017,vs2019,vs2022,xcode}]
[-a] [-i] [-f]
[builddir]
</code></pre>
<p>Displays information about a configured Meson project.</p>
<pre><code class="language-inc">positional arguments:
builddir The build directory
options:
-h, --help show this help message and exit
--ast Dump the AST of the meson file.
--benchmarks List all benchmarks.
--buildoptions List all build options.
--buildsystem-files List files that make up the build
system.
--compilers List used compilers.
--dependencies List external dependencies.
--scan-dependencies Scan for dependencies used in the
meson.build file.
--installed List all installed files and
directories.
--install-plan List all installed files and directories
with their details.
--machines Information about host, build, and
target machines.
--projectinfo Information about projects.
--targets List top level targets.
--tests List all unit tests.
--backend {ninja,none,vs,vs2010,vs2012,vs2013,vs2015,vs2017,vs2019,vs2022,xcode}
The backend to use for the
--buildoptions introspection.
-a, --all Print all available information.
-i, --indent Enable pretty printed JSON.
-f, --force-object-output Always use the new JSON format for
multiple entries (even for 0 and 1
introspection commands)
</code></pre>
<h4 id="examples5">Examples:</h4>
<p>Display basic information about a configured project in <code>builddir</code>:</p>
<pre><code>meson introspect builddir --projectinfo
</code></pre>
<h3 id="install">install</h3>
<p><em>(since 0.47.0)</em></p>
<pre><code class="language-inc">$ meson install [-h] [-C WD] [--no-rebuild] [--only-changed] [-q]
[--destdir DESTDIR] [-n]
[--skip-subprojects [SKIP_SUBPROJECTS]] [--tags TAGS]
[--strip]
</code></pre>
<p>Installs the project to the prefix specified in <a href="Commands.html#setup"><code>setup</code></a>.</p>
<pre><code class="language-inc">options:
-h, --help show this help message and exit
-C WD directory to cd into before running
--no-rebuild Do not rebuild before installing.
--only-changed Only overwrite files that are older than
the copied file.
-q, --quiet Do not print every file that was
installed.
--destdir DESTDIR Sets or overrides DESTDIR environment.
(Since 0.57.0)
-n, --dry-run Doesn't actually install, but print
logs. (Since 0.57.0)
--skip-subprojects [SKIP_SUBPROJECTS]
Do not install files from given
subprojects. (Since 0.58.0)
--tags TAGS Install only targets having one of the
given tags. (Since 0.60.0)
--strip Strip targets even if strip option was
not set during configure. (Since 0.62.0)
</code></pre>
<p>See <a href="Installing.html">the installation documentation</a> for more info.</p>
<h4 id="examples6">Examples:</h4>
<p>Install project to <code>prefix</code>:</p>
<pre><code>meson install -C builddir
</code></pre>
<p>Install project to <code>$DESTDIR/prefix</code>:</p>
<pre><code>DESTDIR=/path/to/staging/area meson install -C builddir
</code></pre>
<p>Since <em>0.60.0</em> <code>DESTDIR</code> and <code>--destdir</code> can be a path relative to build
directory. An absolute path will be set into environment when executing scripts.</p>
<h3 id="reprotest">reprotest</h3>
<p><em>(since 1.6.0)</em></p>
<pre><code class="language-inc">$ meson reprotest [-h] [--intermediaries] [mesonargs ...]
</code></pre>
<p>Simple reproducible build tester that compiles the project twice and
checks whether the end results are identical.</p>
<p>This command must be run in the source root of the project you want to
test.</p>
<pre><code class="language-inc">positional arguments:
mesonargs Arguments to pass to "meson setup".
options:
-h, --help show this help message and exit
--intermediaries Check intermediate files.
</code></pre>
<h4 id="examples7">Examples</h4>
<pre><code>meson reprotest
</code></pre>
<p>Builds the current project with its default settings.</p>
<pre><code>meson reprotest --intermediaries -- --buildtype=debugoptimized
</code></pre>
<p>Builds the target and also checks that all intermediate files like
object files are also identical. All command line arguments after the
<code>--</code> are passed directly to the underlying <code>meson</code> invocation. Only
use option arguments, i.e. those that start with a dash, Meson sets
directory arguments automatically.</p>
<h3 id="rewrite">rewrite</h3>
<p><em>(since 0.50.0)</em></p>
<pre><code class="language-inc">$ meson rewrite [-h] [-s SRCDIR] [-V] [-S]
{target,tgt,kwargs,default-options,def,command,cmd} ...
</code></pre>
<p>Modifies the Meson project.</p>
<pre><code class="language-inc">options:
-h, --help show this help message and exit
-s SRCDIR, --sourcedir SRCDIR Path to source directory.
-V, --verbose Enable verbose output
-S, --skip-errors Skip errors instead of aborting
Rewriter commands:
Rewrite command to execute
{target,tgt,kwargs,default-options,def,command,cmd}
target (tgt) Modify a target
kwargs Modify keyword arguments
default-options (def) Modify the project default options
command (cmd) Execute a JSON array of commands
</code></pre>
<p>See <a href="Rewriter.html">the Meson file rewriter documentation</a> for more info.</p>
<h3 id="setup">setup</h3>
<pre><code class="language-inc">$ meson setup [-h] [--prefix PREFIX] [--bindir BINDIR] [--datadir DATADIR]
[--includedir INCLUDEDIR] [--infodir INFODIR]
[--libdir LIBDIR] [--licensedir LICENSEDIR]
[--libexecdir LIBEXECDIR] [--localedir LOCALEDIR]
[--localstatedir LOCALSTATEDIR] [--mandir MANDIR]
[--sbindir SBINDIR] [--sharedstatedir SHAREDSTATEDIR]
[--sysconfdir SYSCONFDIR]
[--auto-features {enabled,disabled,auto}]
[--backend {ninja,vs,vs2010,vs2012,vs2013,vs2015,vs2017,vs2019,vs2022,xcode,none}]
[--genvslite {vs2022}]
[--buildtype {plain,debug,debugoptimized,release,minsize,custom}]
[--debug] [--default-library {shared,static,both}]
[--default-both-libraries {shared,static,auto}] [--errorlogs]
[--install-umask INSTALL_UMASK] [--layout {mirror,flat}]
[--optimization {plain,0,g,1,2,3,s}] [--prefer-static]
[--stdsplit] [--strip] [--unity {on,off,subprojects}]
[--unity-size UNITY_SIZE] [--warnlevel {0,1,2,3,everything}]
[--werror]
[--wrap-mode {default,nofallback,nodownload,forcefallback,nopromote}]
[--force-fallback-for FORCE_FALLBACK_FOR] [--vsenv]
[--pkgconfig.relocatable]
[--python.bytecompile PYTHON.BYTECOMPILE]
[--python.install-env {auto,prefix,system,venv}]
[--python.platlibdir PYTHON.PLATLIBDIR]
[--python.purelibdir PYTHON.PURELIBDIR]
[--python.allow-limited-api]
[--pkg-config-path PKG_CONFIG_PATH]
[--build.pkg-config-path BUILD.PKG_CONFIG_PATH]
[--cmake-prefix-path CMAKE_PREFIX_PATH]
[--build.cmake-prefix-path BUILD.CMAKE_PREFIX_PATH]
[-D option] [--native-file NATIVE_FILE]
[--cross-file CROSS_FILE] [-v] [--fatal-meson-warnings]
[--reconfigure] [--wipe] [--clearcache]
[builddir] [sourcedir]
</code></pre>
<p>Configures a build directory for the Meson project.</p>
<p><em>Deprecated since 0.64.0</em>: This is the default Meson command (invoked if there
was no COMMAND supplied). However, supplying the command is necessary to avoid
clashes with future added commands, so "setup" should be used explicitly.</p>
<p><em>Since 1.1.0</em> <code>--reconfigure</code> is allowed even if the build directory does not
already exist, that argument is ignored in that case.</p>
<p><em>Since 1.3.0</em> If the build directory already exists, options are updated with
their new value given on the command line (<code>-Dopt=value</code>). Unless <code>--reconfigure</code>
is also specified, this won't reconfigure immediately. This has the same behaviour
as <code>meson configure <builddir> -Dopt=value</code>.</p>
<p><em>Since 1.3.0</em> It is possible to clear the cache and reconfigure in a single command
with <code>meson setup --clearcache --reconfigure <builddir></code>.</p>
<pre><code class="language-inc">positional arguments:
builddir
sourcedir
options:
-h, --help show this help message and exit
--prefix PREFIX Installation prefix.
--bindir BINDIR Executable directory.
--datadir DATADIR Data file directory.
--includedir INCLUDEDIR Header file directory.
--infodir INFODIR Info page directory.
--libdir LIBDIR Library directory.
--licensedir LICENSEDIR Licenses directory (default: ).
--libexecdir LIBEXECDIR Library executable directory.
--localedir LOCALEDIR Locale data directory.
--localstatedir LOCALSTATEDIR Localstate data directory.
--mandir MANDIR Manual page directory.
--sbindir SBINDIR System executable directory.
--sharedstatedir SHAREDSTATEDIR Architecture-independent data directory.
--sysconfdir SYSCONFDIR Sysconf data directory.
--auto-features {enabled,disabled,auto}
Override value of all 'auto' features
(default: auto).
--backend {ninja,vs,vs2010,vs2012,vs2013,vs2015,vs2017,vs2019,vs2022,xcode,none}
Backend to use (default: ninja).
--genvslite {vs2022} Setup multiple buildtype-suffixed ninja-
backend build directories, and a
[builddir]_vs containing a Visual Studio
meta-backend with multiple
configurations that calls into them
(default: vs2022).
--buildtype {plain,debug,debugoptimized,release,minsize,custom}
Build type to use (default: debug).
--debug Enable debug symbols and other
information
--default-library {shared,static,both}
Default library type (default: shared).
--default-both-libraries {shared,static,auto}
Default library type for both_libraries
(default: shared).
--errorlogs Whether to print the logs from failing
tests
--install-umask INSTALL_UMASK Default umask to apply on permissions of
installed files (default: 0o22).
--layout {mirror,flat} Build directory layout (default:
mirror).
--optimization {plain,0,g,1,2,3,s} Optimization level (default: 0).
--prefer-static Whether to try static linking before
shared linking
--stdsplit Split stdout and stderr in test logs
--strip Strip targets on install
--unity {on,off,subprojects} Unity build (default: off).
--unity-size UNITY_SIZE Unity block size (default: 4).
--warnlevel {0,1,2,3,everything} Compiler warning level to use (default:
1).
--werror Treat warnings as errors
--wrap-mode {default,nofallback,nodownload,forcefallback,nopromote}
Wrap mode (default: default).
--force-fallback-for FORCE_FALLBACK_FOR
Force fallback for those subprojects
(default: []).
--vsenv Activate Visual Studio environment
--pkgconfig.relocatable Generate pkgconfig files as relocatable
--python.bytecompile PYTHON.BYTECOMPILE
Whether to compile bytecode (default:
0).
--python.install-env {auto,prefix,system,venv}
Which python environment to install to
(default: prefix).
--python.platlibdir PYTHON.PLATLIBDIR
Directory for site-specific, platform-
specific files (default: ).
--python.purelibdir PYTHON.PURELIBDIR
Directory for site-specific, non-
platform-specific files (default: ).
--python.allow-limited-api Whether to allow use of the Python
Limited API
--pkg-config-path PKG_CONFIG_PATH List of additional paths for pkg-config
to search (default: []). (just for host
machine)
--build.pkg-config-path BUILD.PKG_CONFIG_PATH
List of additional paths for pkg-config
to search (default: []). (just for build
machine)
--cmake-prefix-path CMAKE_PREFIX_PATH
List of additional prefixes for cmake to
search (default: []). (just for host
machine)
--build.cmake-prefix-path BUILD.CMAKE_PREFIX_PATH
List of additional prefixes for cmake to
search (default: []). (just for build
machine)
-D option Set the value of an option, can be used
several times to set multiple options.
--native-file NATIVE_FILE File containing overrides for native
compilation environment.
--cross-file CROSS_FILE File describing cross compilation
environment.
-v, --version show program's version number and exit
--fatal-meson-warnings Make all Meson warnings fatal
--reconfigure Set options and reconfigure the project.
Useful when new options have been added
to the project and the default value is
not working.
--wipe Wipe build directory and reconfigure
using previous command line options.
Useful when build directory got
corrupted, or when rebuilding with a
newer version of meson.
--clearcache Clear cached state (e.g. found
dependencies). Since 1.3.0.
</code></pre>
<p>See <a href="Running-Meson.html#configuring-the-build-directory">Meson introduction
page</a> for more info.</p>
<h4 id="examples8">Examples:</h4>
<p>Configures <code>builddir</code> with default values:</p>
<pre><code>meson setup builddir
</code></pre>
<h3 id="subprojects">subprojects</h3>
<p><em>(since 0.49.0)</em></p>
<pre><code class="language-inc">$ meson subprojects [-h]
{update,checkout,download,foreach,purge,packagefiles}
...
</code></pre>
<p>Manages subprojects of the Meson project. <em>Since 0.59.0</em> commands are run on
multiple subprojects in parallel by default, use <code>--num-processes=1</code> if it is
not desired.</p>
<p>Since <em>0.64.0</em> the <code>update</code> subcommand will not download new wrap files
from WrapDB any more. Use <code>meson wrap update</code> command for that instead.</p>
<pre><code class="language-inc">options:
-h, --help show this help message and exit
Commands:
{update,checkout,download,foreach,purge,packagefiles}
update Update all subprojects from wrap files
checkout Checkout a branch (git only)
download Ensure subprojects are fetched, even if
not in use. Already downloaded
subprojects are not modified. This can
be used to pre-fetch all subprojects and
avoid downloads during configure.
foreach Execute a command in each subproject
directory.
purge Remove all wrap-based subproject
artifacts
packagefiles Manage the packagefiles overlay
</code></pre>
<h3 id="test">test</h3>
<pre><code class="language-inc">$ meson test [-h] [--maxfail MAXFAIL] [--repeat REPEAT] [--no-rebuild]
[--gdb] [--gdb-path GDB_PATH] [-i] [--list]
[--wrapper WRAPPER] [-C WD] [--suite SUITE] [--no-suite SUITE]
[--no-stdsplit] [--print-errorlogs] [--benchmark]
[--logbase LOGBASE] [-j NUM_PROCESSES] [-v] [-q]
[-t TIMEOUT_MULTIPLIER] [--setup SETUP]
[--test-args TEST_ARGS] [--max-lines MAX_LINES]
[--slice SLICE/NUM_SLICES]
[args ...]
</code></pre>
<p>Run tests for the configure Meson project.</p>
<pre><code class="language-inc">positional arguments:
args Optional list of test names to run.
"testname" to run all tests with that
name, "subprojname:testname" to
specifically run "testname" from
"subprojname", "subprojname:" to run all
tests defined by "subprojname".
options:
-h, --help show this help message and exit
--maxfail MAXFAIL Number of failing tests before aborting
the test run. (default: 0, to disable
aborting on failure)
--repeat REPEAT Number of times to run the tests.
--no-rebuild Do not rebuild before running tests.
--gdb Run test under gdb.
--gdb-path GDB_PATH Path to the gdb binary (default: gdb).
-i, --interactive Run tests with interactive input/output.
--list List available tests.
--wrapper WRAPPER wrapper to run tests with (e.g.
Valgrind)
-C WD directory to cd into before running
--suite SUITE Only run tests belonging to the given
suite.
--no-suite SUITE Do not run tests belonging to the given
suite.
--no-stdsplit Do not split stderr and stdout in test
logs.
--print-errorlogs Whether to print failing tests' logs.
--benchmark Run benchmarks instead of tests.
--logbase LOGBASE Base name for log file.
-j NUM_PROCESSES, --num-processes NUM_PROCESSES
How many parallel processes to use.
-v, --verbose Do not redirect stdout and stderr
-q, --quiet Produce less output to the terminal.
-t TIMEOUT_MULTIPLIER, --timeout-multiplier TIMEOUT_MULTIPLIER
Define a multiplier for test timeout,
for example when running tests in
particular conditions they might take
more time to execute. (<= 0 to disable
timeout)
--setup SETUP Which test setup to use.
--test-args TEST_ARGS Arguments to pass to the specified
test(s) or all tests
--max-lines MAX_LINES Maximum number of lines to show from a
long test log. Since 1.5.0.
--slice SLICE/NUM_SLICES Split tests into NUM_SLICES slices and
execute slice SLICE. Since 1.8.0.
</code></pre>
<p>See <a href="Unit-tests.html">the unit test documentation</a> for more info.</p>
<p>Since <em>1.2.0</em> you can use wildcards in <em>args</em> for test names.
For example, "bas*" will match all test with names beginning with "bas".</p>
<p>Since <em>1.2.0</em> it is an error to provide a test name or wildcard that
does not match any test.</p>
<h4 id="examples9">Examples:</h4>
<p>Run tests for the project:</p>
<pre><code>meson test -C builddir
</code></pre>
<p>Run only <code>specific_test_1</code> and <code>specific_test_2</code>:</p>
<pre><code>meson test -C builddir specific_test_1 specific_test_2
</code></pre>
<h3 id="wrap">wrap</h3>
<pre><code class="language-inc">$ meson wrap [-h]
{list,search,install,update,info,status,promote,update-db} ...
</code></pre>
<p>An utility to manage WrapDB dependencies.</p>
<pre><code class="language-inc">options:
-h, --help show this help message and exit
Commands:
{list,search,install,update,info,status,promote,update-db}
list show all available projects
search search the db by name
install install the specified project
update Update wrap files from WrapDB (Since
0.63.0)
info show available versions of a project
status show installed and available versions of
your projects
promote bring a subsubproject up to the master
project
update-db Update list of projects available in
WrapDB (Since 0.61.0)
</code></pre>
<p>See <a href="Using-wraptool.html">the WrapDB tool documentation</a> for more info.</p>
<h3 id="devenv">devenv</h3>
<p><em>(since 0.58.0)</em></p>
<pre><code class="language-inc">$ meson devenv [-h] [-C BUILDDIR] [--workdir WORKDIR] [--dump [DUMP]]
[--dump-format {sh,export,vscode}]
...
</code></pre>
<p>Runs a command, or open interactive shell if no command is provided, with
environment setup to run project from the build directory, without installation.</p>
<p>We automatically handle <code>bash</code> and set <code>$PS1</code> accordingly. If the automatic <code>$PS1</code>
override is not desired (maybe you have a fancy custom prompt), set the
<code>$MESON_DISABLE_PS1_OVERRIDE</code> environment variable and use <code>$MESON_PROJECT_NAME</code>
when setting the custom prompt, for example with a snippet like the following:</p>
<pre><code class="language-bash">...
if [[ -n "${MESON_PROJECT_NAME-}" ]];
then
PS1+="[ ${MESON_PROJECT_NAME} ]"
fi
...
</code></pre>
<p>These variables are set in environment in addition to those set using <a href="Reference-manual_builtin_meson.html#mesonadd_devenv"><ins><code>meson.add_devenv()</code></ins></a>:</p>
<ul>
<li>
<code>MESON_DEVENV</code> is defined to <code>'1'</code>.</li>
<li>
<code>MESON_PROJECT_NAME</code> is defined to the main project's name.</li>
<li>
<code>PKG_CONFIG_PATH</code> includes the directory where Meson generates <code>-uninstalled.pc</code>
files.</li>
<li>
<code>PATH</code> includes every directory where there is an executable that would be
installed into <code>bindir</code>. On windows it also includes every directory where there
is a DLL needed to run those executables.</li>
<li>
<code>LD_LIBRARY_PATH</code> includes every directory where there is a shared library that
would be installed into <code>libdir</code>. This allows to run system application using
custom build of some libraries. For example running system GEdit when building
GTK from git. On OSX the environment variable is <code>DYLD_LIBRARY_PATH</code> and
<code>PATH</code> on Windows.</li>
<li>