-
Notifications
You must be signed in to change notification settings - Fork 4
/
Copy pathContributing.html
936 lines (900 loc) · 36.7 KB
/
Contributing.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
<!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>Contributing to Meson</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="Contributing.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="contributing-to-meson">Contributing to Meson</h1>
<p>A large fraction of Meson is contributed by people outside the core
team. This documentation explains some of the design rationales of
Meson as well as how to create and submit your patches for inclusion
to Meson.</p>
<p>Thank you for your interest in participating to the development.</p>
<h2 id="submitting-patches">Submitting patches</h2>
<p>All changes must be submitted as <a href="https://github.com/mesonbuild/meson/pulls">pull requests to
GitHub</a>. This causes them
to be run through the CI system. All submissions must pass a full CI
test run before they are even considered for submission.</p>
<h2 id="keeping-pull-requests-up-to-date">Keeping pull requests up to date</h2>
<p>It is possible that while your pull request is being reviewed, other
changes are committed to master that cause merge conflicts that must
be resolved. The basic rule for this is very simple: keep your pull
request up to date using rebase <em>only</em>.</p>
<p>Do not merge head back to your branch. Any merge commits in your pull
request make it not acceptable for merging into master and you must
remove them.</p>
<h2 id="special-procedure-for-new-features">Special procedure for new features</h2>
<p>Every new feature requires some extra steps, namely:</p>
<ul>
<li>Must include a project test under <code>test cases/</code>, or if that's not
possible or if the test requires a special environment, it must go
into <code>run_unittests.py</code>.</li>
<li>Must be registered with the <a href="Release-notes-for-0-47-0.html#feature-detection-based-on-meson_version-in-project">FeatureChecks
framework</a>
that will warn the user if they try to use a new feature while
targeting an older Meson version.</li>
<li>Needs a release note snippet inside <code>docs/markdown/snippets/</code> with
a heading and a brief paragraph explaining what the feature does
with an example.</li>
</ul>
<h2 id="acceptance-and-merging">Acceptance and merging</h2>
<p>The kind of review and acceptance any merge proposal gets depends on
the changes it contains. All pull requests must be reviewed and
accepted by someone with commit rights who is not the original
submitter. Merge requests can be roughly split into three different
categories.</p>
<p>The first one consists of MRs that only change the markdown
documentation under <code>docs/markdown</code>. Anyone with access rights can
push changes to these directly to master. For major changes it is
still recommended to create a MR so other people can comment on it.</p>
<p>The second group consists of merges that don't change any
functionality, fixes to the CI system and bug fixes that have added
regression tests (see below) and don't change existing
functionality. Once successfully reviewed anyone with merge rights can
merge these to master.</p>
<p>The final kind of merges are those that add new functionality or
change existing functionality in a backwards incompatible way. These
require the approval of the project lead.</p>
<p>In a simplified list form the split would look like the following:</p>
<ul>
<li>members with commit access can do:
<ul>
<li>documentation changes (directly to master if warranted)</li>
<li>bug fixes that don't change functionality</li>
<li>refactorings</li>
<li>new dependency types</li>
<li>new tool support (e.g. a new Doxygen-kind of tool)</li>
<li>support for new compilers to existing languages</li>
</ul>
</li>
<li>project leader decision is needed for:
<ul>
<li>new modules</li>
<li>new functions in the Meson language</li>
<li>syntax changes for Meson files</li>
<li>changes breaking backwards compatibility</li>
<li>support for new languages</li>
</ul>
</li>
</ul>
<h2 id="a-green-ci-run-is-mandatory-for-merging">A green CI run is mandatory for merging</h2>
<p>No merge request may be merged until it has a fully green CI run. It
does not matter why CI fails, it is a hard blocker. Even if the MR
could possibly not have anything to do with the failure and clearly
should be permitted, it may not be merged. Only MRs that fix the CI
issue are allowed to land in trunk.</p>
<p>There is one, and only one, exception to this. At the time of writing
the Apple CI is unreliable and sometimes fails with clock skew errors.</p>
<p>If a merge causes CI failure any developer can revert it out of
master. It is then the responsibility of the original submitter to
resubmit a fixed version.</p>
<h2 id="strategy-for-merging-pull-requests-to-trunk">Strategy for merging pull requests to trunk</h2>
<p>Meson's merge strategy should fulfill the following guidelines:</p>
<ul>
<li>
<p>preserve as much history as possible</p>
</li>
<li>
<p>have as little junk in the repo as possible</p>
</li>
<li>
<p>everything in the "master lineage" should always pass all tests</p>
</li>
</ul>
<p>These goals are slightly contradictory so the correct thing to do
often requires some judgement on part of the person doing the
merge. GitHub provides three different merge options, The rules of
thumb for choosing between them goes like this:</p>
<ul>
<li>
<p>single commit pull requests should always be rebased</p>
</li>
<li>
<p>a pull request with one commit and one "fixup" commit (such as
testing something to see if it passes CI) should be squashed</p>
</li>
<li>
<p>large branches with many commits should be merged with a merge
commit, especially if one of the commits does not pass all tests
(which happens in e.g. large and difficult refactorings)</p>
</li>
</ul>
<p>If in doubt, ask for guidance on IRC.</p>
<h2 id="tests">Tests</h2>
<p>All new features must come with automatic tests that thoroughly prove
that the feature is working as expected. Similarly bug fixes must come
with a unit test that demonstrates the bug, proves that it has been
fixed and prevents the feature from breaking in the future.</p>
<p>Sometimes it is difficult to create a unit test for a given bug. If
this is the case, note this in your pull request. We may permit bug
fix merge requests in these cases. This is done on a case by case
basis. Sometimes it may be easier to write the test than convince the
maintainers that one is not needed. Exercise judgment and ask for help
in problematic cases.</p>
<p>The tests are split into two different parts: unit tests and full
project tests. To run all tests, execute <code>./run_tests.py</code>. Unit tests
can be run with <code>./run_unittests.py</code> and project tests with
<code>./run_project_tests.py</code>.</p>
<h3 id="project-tests">Project tests</h3>
<p>Subsets of project tests can be selected with
<code>./run_project_tests.py --only</code> option. This can save a great deal of
time when only a certain part of Meson is being tested.
For example, a useful and easy contribution to Meson is making
sure the full set of compilers is supported. One could for example test
various Fortran compilers by setting <code>FC=ifort</code>, <code>FC=flang</code> or
<code>FC=flang-new</code> or similar with <code>./run_project_test.py --only fortran</code>.
Some families of tests require a particular backend to run.
For example, all the CUDA project tests run and pass on Windows via
<code>./run_project_tests.py --only cuda --backend ninja</code></p>
<p>Each project test is a standalone project that can be compiled on its
own. They are all in the <code>test cases</code> subdirectory. The simplest way to
run a single project test is to do something like <code>./meson.py test\ cases/common/1\ trivial builddir</code>. The one exception to this is <code>test cases/unit</code> directory discussed below.</p>
<p>The test cases in the <code>common</code> subdirectory are meant to be run always
for all backends. They should only depend on C and C++, without any
external dependencies such as libraries. Tests that require those are
in the <code>test cases/frameworks</code> directory. If there is a need for an
external program in the common directory, such as a code generator, it
should be implemented as a Python script. The goal of test projects is
also to provide sample projects that end users can use as a base for
their own projects.</p>
<p>All project tests follow the same pattern: they are configured,
compiled, tests are run and finally install is run. Passing means that
configuring, building and tests succeed and that installed files match
those expected.</p>
<p>Any tests that require more thorough analysis, such as checking that
certain compiler arguments can be found in the command line or that
the generated pkg-config files actually work should be done with a
unit test.</p>
<p>Additionally:</p>
<ul>
<li>
<p><code>crossfile.ini</code> and <code>nativefile.ini</code> are passed to the configure step with
<code>--cross-file</code> and <code>--native-file</code> options, respectively.</p>
</li>
<li>
<p><code>mlog.cmd_ci_include()</code> can be called from anywhere inside Meson to
capture the contents of an additional file into the CI log on failure.</p>
</li>
</ul>
<p>Projects needed by unit tests are in the <code>test cases/unit</code>
subdirectory. They are not run as part of <code>./run_project_tests.py</code>.</p>
<h3 id="configuring-project-tests">Configuring project tests</h3>
<p>The (optional) <code>test.json</code> file, in the root of a test case, is used
for configuring the test. All of the following root entries in the <code>test.json</code>
are independent of each other and can be combined as needed.</p>
<p>Example <code>test.json</code>:</p>
<pre><code class="language-json">{
"env": {
"VAR": "VAL"
},
"installed": [
{ "type": "exe", "file": "usr/bin/testexe" },
{ "type": "pdb", "file": "usr/bin/testexe" },
{ "type": "shared_lib", "file": "usr/lib/z", "version": "1.2.3" },
],
"matrix": {
"options": {
"opt1": [
{ "val": "abc" },
{ "val": "qwert" },
{ "val": "bad" }
],
"opt2": [
{ "val": null },
{ "val": "true" },
{ "val": "false" },
]
},
"exclude": [
{ "opt1": "qwert", "opt2": "false" },
{ "opt1": "bad" }
]
},
"tools": {
"cmake": ">=3.11"
}
}
</code></pre>
<h4 id="env">env</h4>
<p>The <code>env</code> key contains a dictionary which specifies additional
environment variables to be set during the configure step of the test.</p>
<p>There is some basic support for configuring the string with the <code>@<VAR>@</code> syntax:</p>
<ul>
<li>
<code>@ROOT@</code>: absolute path of the source directory</li>
<li>
<code>@PATH@</code>: current value of the <code>PATH</code> env variable</li>
</ul>
<h4 id="installed">installed</h4>
<p>The <code>installed</code> dict contains a list of dicts, describing which files are expected
to be installed. Each dict contains the following keys:</p>
<ul>
<li><code>file</code></li>
<li><code>type</code></li>
<li>
<code>platform</code> (optional)</li>
<li>
<code>version</code> (optional)</li>
<li>
<code>language</code> (optional)</li>
</ul>
<p>The <code>file</code> entry contains the relative path (from the install root) to the
actually installed file.</p>
<p>The <code>type</code> entry specifies how the <code>file</code> path should be interpreted based on the
current platform. The following values are currently supported:</p>
<table>
<thead>
<tr>
<th> type</th>
<th> Description</th>
</tr>
</thead>
<tbody>
<tr>
<td> <code>file</code>
</td>
<td> No postprocessing, just use the provided path</td>
</tr>
<tr>
<td> <code>python_file</code>
</td>
<td> Use the provided path while replacing the python directory.</td>
</tr>
<tr>
<td> <code>dir</code>
</td>
<td> To include all files inside the directory (for generated docs, etc). The path must be a valid directory</td>
</tr>
<tr>
<td> <code>exe</code>
</td>
<td> For executables. On Windows the <code>.exe</code> suffix is added to the path in <code>file</code>
</td>
</tr>
<tr>
<td> <code>shared_lib</code>
</td>
<td> For shared libraries, always written as <code>name</code>. The appropriate suffix and prefix are added by platform</td>
</tr>
<tr>
<td> <code>python_lib</code>
</td>
<td> For python libraries, while replacing the python directory. The appropriate suffix is added by platform</td>
</tr>
<tr>
<td> <code>pdb</code>
</td>
<td> For Windows PDB files. PDB entries are ignored on non Windows platforms</td>
</tr>
<tr>
<td> <code>implib</code>
</td>
<td> For Windows import libraries. These entries are ignored on non Windows platforms</td>
</tr>
<tr>
<td> <code>py_implib</code>
</td>
<td> For Windows import libraries. These entries are ignored on non Windows platforms</td>
</tr>
<tr>
<td> <code>implibempty</code>
</td>
<td> Like <code>implib</code>, but no symbols are exported in the library</td>
</tr>
<tr>
<td> <code>expr</code>
</td>
<td> <code>file</code> is an expression. This type should be avoided and removed if possible</td>
</tr>
</tbody>
</table>
<p>Except for the <code>file</code>, <code>python_file</code> and <code>expr</code> types, all paths should be provided <em>without</em> a suffix.</p>
<table>
<thead>
<tr>
<th> Argument</th>
<th> Applies to</th>
<th> Description</th>
</tr>
</thead>
<tbody>
<tr>
<td> <code>version</code>
</td>
<td> <code>shared_lib</code>, <code>pdb</code>
</td>
<td> Sets the version to look for appropriately per-platform</td>
</tr>
<tr>
<td> <code>language</code>
</td>
<td> <code>pdb</code>
</td>
<td> Determines which compiler/linker determines the existence of this file</td>
</tr>
</tbody>
</table>
<p>The <code>shared_lib</code> and <code>pdb</code> types takes an optional additional
parameter, <code>version</code>, this is us a string in <code>X.Y.Z</code> format that will
be applied to the library. Each version to be tested must have a
single version. The harness will apply this correctly per platform:</p>
<p>The <code>python_file</code>, <code>python_lib</code>, and <code>py_implib</code> types have basic support for configuring the string with the <code>@<VAR>@</code> syntax:</p>
<ul>
<li>
<code>@PYTHON_PLATLIB@</code>: python <code>get_install_dir</code> directory relative to prefix</li>
<li>
<code>@PYTHON_PURELIB@</code>: python <code>get_install_dir(pure: true)</code> directory relative to prefix</li>
</ul>
<p><code>pdb</code> takes an optional <code>language</code> argument. This determines which
compiler/linker should generate the pdb file. Because it's possible to
mix compilers that do and don't generate pdb files (dmd's optlink
doesn't). Currently this is only needed when mixing D and C code.</p>
<pre><code class="language-json">{
"type": "shared_lib", "file": "usr/lib/lib",
"type": "shared_lib", "file": "usr/lib/lib", "version": "1",
"type": "shared_lib", "file": "usr/lib/lib", "version": "1.2.3.",
}
</code></pre>
<p>This will be applied appropriately per platform. On windows this
expects <code>lib.dll</code> and <code>lib-1.dll</code>. on MacOS it expects <code>liblib.dylib</code>
and <code>liblib.1.dylib</code>. On other Unices it expects <code>liblib.so</code>,
<code>liblib.so.1</code>, and <code>liblib.so.1.2.3</code>.</p>
<p>If the <code>platform</code> key is present, the installed file entry is only
considered if the platform matches. The following values for
<code>platform</code> are currently supported:</p>
<table>
<thead>
<tr>
<th> platform</th>
<th> Description</th>
</tr>
</thead>
<tbody>
<tr>
<td> <code>msvc</code>
</td>
<td> Matches when a msvc like compiler is used (<code>msvc</code>, <code>clang-cl</code>, etc.)</td>
</tr>
<tr>
<td> <code>gcc</code>
</td>
<td> Not <code>msvc</code>
</td>
</tr>
<tr>
<td> <code>cygwin</code>
</td>
<td> Matches when the platform is cygwin</td>
</tr>
<tr>
<td> <code>!cygwin</code>
</td>
<td> Not <code>cygwin</code>
</td>
</tr>
</tbody>
</table>
<h4 id="matrix">matrix</h4>
<p>The <code>matrix</code> section can be used to define a test matrix to run
project tests with different Meson options.</p>
<p>In the <code>options</code> dict, all possible options and their values are
specified. Each key in the <code>options</code> dict is a Meson option. It stores
a list of all potential values in a dict format.</p>
<p>Each value must contain the <code>val</code> key for the value of the option.
<code>null</code> can be used for adding matrix entries without the current
option.</p>
<p>The <code>skip_on_env</code> key (as described below) may be used in the value to skip that
matrix entry, based on the current environment.</p>
<p>The <code>expect_skip_on_jobname</code> and <code>expect_skip_on_os</code> keys (as described below)
may be used to expect that the test will be skipped, based on the current environment.</p>
<p>Similarly, the <code>compilers</code> key can be used to define a mapping of
compilers to languages that are required for this value.</p>
<pre><code class="language-json">{
"compilers": {
"c": "gcc",
"cpp": "gcc",
"d": "gdc"
}
}
</code></pre>
<p>Specific option combinations can be excluded with the <code>exclude</code>
section. It should be noted that <code>exclude</code> does not require exact
matches. Instead, any matrix entry containing all option value
combinations in <code>exclude</code> will be excluded. Thus an empty dict (<code>{}</code>)
to will match <strong>all</strong> elements in the test matrix.</p>
<p>The above example will produce the following matrix entries:</p>
<ul>
<li><code>opt1=abc</code></li>
<li><code>opt1=abc opt2=true</code></li>
<li><code>opt1=abc opt2=false</code></li>
<li><code>opt1=qwert</code></li>
<li><code>opt1=qwert opt2=true</code></li>
</ul>
<h4 id="do_not_set_opts">do_not_set_opts</h4>
<p>Currently supported values are:</p>
<ul>
<li><code>prefix</code></li>
<li><code>libdir</code></li>
</ul>
<h4 id="tools">tools</h4>
<p>This section specifies a dict of tool requirements in a simple
key-value format. If a tool is specified, it has to be present in the
environment, and the version requirement must be fulfilled. Otherwise,
the entire test is skipped (including every element in the test
matrix).</p>
<h4 id="stdout">stdout</h4>
<p>The <code>stdout</code> key contains a list of dicts, describing the expected
stdout.</p>
<p>Each dict contains the following keys:</p>
<ul>
<li><code>line</code></li>
<li>
<code>match</code> (optional)</li>
<li>
<code>count</code> (optional)</li>
</ul>
<p>Each item in the list is matched, in order, against the remaining
actual stdout lines, after any previous matches. If the actual stdout
is exhausted before every item in the list is matched, the expected
output has not been seen, and the test has failed.</p>
<p>The <code>match</code> element of the dict determines how the <code>line</code> element is
matched:</p>
<table>
<thead>
<tr>
<th> Type</th>
<th> Description</th>
</tr>
</thead>
<tbody>
<tr>
<td> <code>literal</code>
</td>
<td> Literal match (default)</td>
</tr>
<tr>
<td> <code>re</code>
</td>
<td> regex match</td>
</tr>
</tbody>
</table>
<p>The <code>count</code> element determines how many times the line is expected, and allowed,
to be in the output. If unspecified, it must appear "any number of times, but at
least once".</p>
<h4 id="skip_on_env">skip_on_env</h4>
<p>The <code>skip_on_env</code> key can be used to specify a list of environment variables. If
at least one environment variable in the <code>skip_on_env</code> list is present, the test
is skipped.</p>
<h4 id="expect_skip_on_jobname">expect_skip_on_jobname</h4>
<p>The <code>expect_skip_on_jobname</code> key contains a list of strings. If the <code>MESON_CI_JOBNAME</code>
environment variable is set, and any of them are a sub-string of it, the test is
expected to be skipped (that is, it is expected that the test will output
<code>MESON_SKIP_TEST</code>, because the CI environment is not one in which it can run,
for whatever reason).</p>
<p>The test is failed if it either skips unexpectedly or runs unexpectedly.</p>
<h4 id="expect_skip_on_os">expect_skip_on_os</h4>
<p>The <code>expect_skip_on_os</code> key can be used to specify a list of OS names (or their
negations, prefixed with a <code>!</code>). If at least one item in the <code>expect_skip_on_os</code> list
is matched, the test is expected to be skipped.</p>
<p>The test is failed if it either skips unexpectedly or runs unexpectedly.</p>
<h3 id="skipping-integration-tests">Skipping integration tests</h3>
<p>Meson uses several continuous integration testing systems that have
slightly different interfaces for indicating a commit should be
skipped.</p>
<p>Continuous integration systems currently used:</p>
<ul>
<li>
<a href="https://docs.microsoft.com/en-us/azure/devops/pipelines/scripts/git-commands?view=vsts&tabs=yaml#how-do-i-avoid-triggering-a-ci-build-when-the-script-pushes">Azure Pipelines</a>
allows <code>***NO_CI***</code> in the commit message.</li>
<li>
<a href="https://sider.review">Sider</a>
runs Flake8 (<a href="Contributing.html#python-coding-style">see below</a>)</li>
</ul>
<p>To promote consistent naming policy, use:</p>
<ul>
<li>
<code>[skip ci]</code> in the commit title if you want to disable all
integration tests</li>
</ul>
<h2 id="documentation">Documentation</h2>
<p>The <code>docs</code> directory contains the full documentation that will be used
to generate <a href="https://mesonbuild.com">the Meson web site</a>. Line length
in most cases should not exceed 70 characters (lines containing links
or examples are usually exempt). Every change in functionality must
change the documentation pages. In most cases this means updating the
reference documentation page but bigger changes might need changes in
other documentation, too.</p>
<p>All new functionality needs to have a mention in the release
notes. These features should be written in standalone files in the
<code>docs/markdown/snippets</code> directory. The release manager will combine
them into one page when doing the release.</p>
<h2 id="python-coding-style">Python Coding style</h2>
<p>Meson follows the basic Python coding style. Additional rules are the
following:</p>
<ul>
<li>indent 4 spaces, no tabs ever</li>
<li>indent meson.build files with two spaces</li>
<li>try to keep the code as simple as possible</li>
<li>contact the mailing list before embarking on large scale projects
to avoid wasted effort</li>
</ul>
<p>Meson uses Flake8 for style guide enforcement. The Flake8 options for
the project are contained in .flake8.</p>
<p>To run Flake8 on your local clone of Meson:</p>
<pre><code class="language-console">$ python3 -m pip install flake8
$ cd meson
$ flake8
</code></pre>
<p>To run it automatically before committing:</p>
<pre><code class="language-console">$ flake8 --install-hook=git
$ git config --bool flake8.strict true
</code></pre>
<h2 id="cc-coding-style">C/C++ coding style</h2>
<p>Meson has a bunch of test code in several languages. The rules for
those are simple.</p>
<ul>
<li>indent 4 spaces, no tabs ever</li>
<li>brace always on the same line as if/for/else/function definition</li>
</ul>
<h2 id="dependency-support-policy">Dependency support policy</h2>
<p>The goal of Meson is to be as easily usable as possible. The user
experience should be "get Python3 and Ninja, run", even on
Windows.</p>
<p>Additionally, Meson is popularly used in many core infrastructure packages in a
Unix (and particularly, Linux) userland. This includes:</p>
<ul>
<li>package managers, such as pacman (Arch Linux) and portage (Gentoo)</li>
<li>init systems (systemd, openrc, dinit)</li>
<li>graphics stacks (xorg, wayland, libdrm, Mesa, gtk)</li>
</ul>
<p>As such it needs to be able to run early on when bootstrapping a system from
scratch.</p>
<h3 id="python">Python</h3>
<p>We will always support all non EOL versions of CPython. Yes, there are people
out there using and depending on every old version of python. In fact, there
are people using and depending on systems that had a brand new python at the
time of release, but with a much longer support cycle than Python itself. We
need to balance the tradeoff between supporting those systems and being able to
improve our own codebase and code quality.</p>
<p>Meson will also be <em>honest</em> about what versions of python it supports. When a
version of CPython becomes EOL, it becomes eligible to be removed from our
support policy. We cannot guarantee continued support forever for software that
is not supported by its own developers, even if some deprecated LTS systems out
there still ship it. However, that doesn't mean we will drop support for those
versions simply because they are old. If we are not using new functionality
from new python versions, we will continue to mark Meson as compatible with the
older version -- and test it in CI!</p>
<p>(Note that contrary to popular belief, it is actually easier to test support
for very old versions of python than it is to drop support for it. We already
have the CI setup necessary for testing. Upgrading the CI to use newer versions
of python, on the other hand, represents mildly painful administrative work
that has to be done.)</p>
<p>So, in order to start requiring a newer version of python, one should check a
few factors:</p>
<ul>
<li>are the older versions being dropped, already EOL? <a href="https://endoflife.date/python">Python EOL chart</a>
</li>
<li>document the new minimum version of corresponding OSes</li>
<li>rationalize the benefit of the change in terms of improvements to development
and maintenance of Meson. What new language features will be unlocked by the
upgrade, that Meson will be able to make good use of? Not every version has
new features requiring an upgrade, and not every new feature is so great we
need to drop everything to use it</li>
</ul>
<h3 id="external-dependencies">External dependencies</h3>
<p>Unfortunately this also means that we can't have dependencies on
projects outside of Python's standard library. This applies only to
core functionality, though. For additional helper programs etc the use
of external dependencies may be ok. If you feel that you are dealing
with this kind of case, please contact the developers first with your
use case.</p>
<h2 id="turing-completeness">Turing completeness</h2>
<p>The main design principle of Meson is that the definition language is
not Turing complete. Any change that would make Meson Turing complete
is automatically rejected. In practice this means that defining your
own functions inside <code>meson.build</code> files and generalised loops will
not be added to the language.</p>
<h2 id="do-i-need-to-sign-a-cla-in-order-to-contribute">Do I need to sign a CLA in order to contribute?</h2>
<p>No you don't. All contributions are welcome.</p>
<h2 id="no-lingering-state">No lingering state</h2>
<p>Meson operates in much the same way as functional programming
languages. It has inputs, which include <code>meson.build</code> files, values of
options, compilers and so on. These are passed to a function, which
generates output build definition. This function is pure, which means that:</p>
<ul>
<li>for any given input the output is always the same</li>
<li>running Meson twice in a row <em>always</em> produce the same output in both runs</li>
</ul>
<p>The latter one is important, because it enforces that there is no way
for "secret state" to pass between consecutive invocations of
Meson. This is the reason why, for example, there is no <code>set_option</code>
function even though there is a <code>get_option</code> one.</p>
<p>If this were not the case, we could never know if the build output is
"stable". For example suppose there were a <code>set_option</code> function and a
boolean variable <code>flipflop</code>. Then you could do this:</p>
<pre><code class="language-meson">set_option('flipflop', not get_option('flipflop'))
</code></pre>
<p>This piece of code would never converge. Every Meson run would change
the value of the option and thus the output you get out of this build
definition would be random.</p>
<p>Meson does not permit this by forbidding these sorts of covert
channels.</p>
<p>There is one exception to this rule. Users can call into external
commands with <code>run_command</code>. If the output of that command does not
behave like a pure function, this problem arises. Meson does not try
to guard against this case, it is the responsibility of the user to
make sure the commands they run behave like pure functions.</p>
<h2 id="environment-variables">Environment variables</h2>
<p>Environment variables are like global variables, except that they are
also hidden by default. Envvars should be avoided whenever possible,
all functionality should be exposed in better ways such as command
line switches.</p>
<h2 id="random-design-points-that-fit-nowhere-else">Random design points that fit nowhere else</h2>
<ul>
<li>
<p>All features should follow the 90/9/1 rule. 90% of all use cases
should be easy, 9% should be possible and it is totally fine to not
support the final 1% if it would make things too complicated.</p>
</li>
<li>
<p>Any build directory will have at most two toolchains: one native and
one cross.</p>
</li>
<li>
<p>Prefer specific solutions to generic frameworks. Solve the end
user's problems rather than providing them tools to do it
themselves.</p>
</li>
<li>
<p>Never use features of the Unix shell (or Windows shell for that
matter). Doing things like forwarding output with <code>></code> or invoking
multiple commands with <code>&&</code> are not permitted. Whenever these sorts
of requirements show up, write an internal Python script with the
desired functionality and use that instead.</p>
</li>
</ul>
</div>
<div id="subpages">
<p><b>Subpages:</b></p>
<div class="thumb-subpages">
</div>
<p>
<a href="Yaml-RefMan.html">YAML Reference manual</a>
– Editing and maintaining the Reference manual
</p>
<p>
<a href="MesonCI.html">Meson CI setup</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/Contributing.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>