Debian Codegraph @

subprojects/meson-docs/docs/markdown/Contributing.md

raw
1 ---
2 short-description: Contributing to Meson
3 ...
4
5 # Contributing to Meson
6
7 A large fraction of Meson is contributed by people outside the core
8 team. This documentation explains some of the design rationales of
9 Meson as well as how to create and submit your patches for inclusion
10 to Meson.
11
12 Thank you for your interest in participating to the development.
13
14 ## Submitting patches
15
16 All changes must be submitted as [pull requests to
17 GitHub](https://github.com/mesonbuild/meson/pulls). This causes them
18 to be run through the CI system. All submissions must pass a full CI
19 test run before they are even considered for submission.
20
21 ## Keeping pull requests up to date
22
23 It is possible that while your pull request is being reviewed, other
24 changes are committed to master that cause merge conflicts that must
25 be resolved. The basic rule for this is very simple: keep your pull
26 request up to date using rebase _only_.
27
28 Do not merge head back to your branch. Any merge commits in your pull
29 request make it not acceptable for merging into master and you must
30 remove them.
31
32 ## Special procedure for new features
33
34 Every new feature requires some extra steps, namely:
35
36 - Must include a project test under `test cases/`, or if that's not
37 possible or if the test requires a special environment, it must go
38 into `run_unittests.py`.
39 - Must be registered with the [FeatureChecks
40 framework](Release-notes-for-0.47.0.md#feature-detection-based-on-meson_version-in-project)
41 that will warn the user if they try to use a new feature while
42 targeting an older Meson version.
43 - Needs a release note snippet inside `docs/markdown/snippets/` with
44 a heading and a brief paragraph explaining what the feature does
45 with an example.
46
47 ## Acceptance and merging
48
49 The kind of review and acceptance any merge proposal gets depends on
50 the changes it contains. All pull requests must be reviewed and
51 accepted by someone with commit rights who is not the original
52 submitter. Merge requests can be roughly split into three different
53 categories.
54
55 The first one consists of MRs that only change the markdown
56 documentation under `docs/markdown`. Anyone with access rights can
57 push changes to these directly to master. For major changes it is
58 still recommended to create a MR so other people can comment on it.
59
60 The second group consists of merges that don't change any
61 functionality, fixes to the CI system and bug fixes that have added
62 regression tests (see below) and don't change existing
63 functionality. Once successfully reviewed anyone with merge rights can
64 merge these to master.
65
66 The final kind of merges are those that add new functionality or
67 change existing functionality in a backwards incompatible way. These
68 require the approval of the project lead.
69
70 In a simplified list form the split would look like the following:
71
72 - members with commit access can do:
73 - documentation changes (directly to master if warranted)
74 - bug fixes that don't change functionality
75 - refactorings
76 - new dependency types
77 - new tool support (e.g. a new Doxygen-kind of tool)
78 - support for new compilers to existing languages
79 - project leader decision is needed for:
80 - new modules
81 - new functions in the Meson language
82 - syntax changes for Meson files
83 - changes breaking backwards compatibility
84 - support for new languages
85
86 ## A green CI run is mandatory for merging
87
88 No merge request may be merged until it has a fully green CI run. It
89 does not matter why CI fails, it is a hard blocker. Even if the MR
90 could possibly not have anything to do with the failure and clearly
91 should be permitted, it may not be merged. Only MRs that fix the CI
92 issue are allowed to land in trunk.
93
94 There is one, and only one, exception to this. At the time of writing
95 the Apple CI is unreliable and sometimes fails with clock skew errors.
96
97 If a merge causes CI failure any developer can revert it out of
98 master. It is then the responsibility of the original submitter to
99 resubmit a fixed version.
100
101 ## Strategy for merging pull requests to trunk
102
103 Meson's merge strategy should fulfill the following guidelines:
104
105 - preserve as much history as possible
106
107 - have as little junk in the repo as possible
108
109 - everything in the "master lineage" should always pass all tests
110
111 These goals are slightly contradictory so the correct thing to do
112 often requires some judgement on part of the person doing the
113 merge. GitHub provides three different merge options, The rules of
114 thumb for choosing between them goes like this:
115
116 - single commit pull requests should always be rebased
117
118 - a pull request with one commit and one "fixup" commit (such as
119 testing something to see if it passes CI) should be squashed
120
121 - large branches with many commits should be merged with a merge
122 commit, especially if one of the commits does not pass all tests
123 (which happens in e.g. large and difficult refactorings)
124
125 If in doubt, ask for guidance on IRC.
126
127 ## Tests
128
129 All new features must come with automatic tests that thoroughly prove
130 that the feature is working as expected. Similarly bug fixes must come
131 with a unit test that demonstrates the bug, proves that it has been
132 fixed and prevents the feature from breaking in the future.
133
134 Sometimes it is difficult to create a unit test for a given bug. If
135 this is the case, note this in your pull request. We may permit bug
136 fix merge requests in these cases. This is done on a case by case
137 basis. Sometimes it may be easier to write the test than convince the
138 maintainers that one is not needed. Exercise judgment and ask for help
139 in problematic cases.
140
141 The tests are split into two different parts: unit tests and full
142 project tests. To run all tests, execute `./run_tests.py`. Unit tests
143 can be run with `./run_unittests.py` and project tests with
144 `./run_project_tests.py`.
145
146 ### Project tests
147
148 Subsets of project tests can be selected with
149 `./run_project_tests.py --only` option. This can save a great deal of
150 time when only a certain part of Meson is being tested.
151 For example, a useful and easy contribution to Meson is making
152 sure the full set of compilers is supported. One could for example test
153 various Fortran compilers by setting `FC=ifort`, `FC=flang` or
154 `FC=flang-new` or similar with `./run_project_test.py --only fortran`.
155 Some families of tests require a particular backend to run.
156 For example, all the CUDA project tests run and pass on Windows via
157 `./run_project_tests.py --only cuda --backend ninja`
158
159 Each project test is a standalone project that can be compiled on its
160 own. They are all in the `test cases` subdirectory. The simplest way to
161 run a single project test is to do something like `./meson.py test\
162 cases/common/1\ trivial builddir`. The one exception to this is `test
163 cases/unit` directory discussed below.
164
165 The test cases in the `common` subdirectory are meant to be run always
166 for all backends. They should only depend on C and C++, without any
167 external dependencies such as libraries. Tests that require those are
168 in the `test cases/frameworks` directory. If there is a need for an
169 external program in the common directory, such as a code generator, it
170 should be implemented as a Python script. The goal of test projects is
171 also to provide sample projects that end users can use as a base for
172 their own projects.
173
174 All project tests follow the same pattern: they are configured,
175 compiled, tests are run and finally install is run. Passing means that
176 configuring, building and tests succeed and that installed files match
177 those expected.
178
179 Any tests that require more thorough analysis, such as checking that
180 certain compiler arguments can be found in the command line or that
181 the generated pkg-config files actually work should be done with a
182 unit test.
183
184 Additionally:
185
186 * `crossfile.ini` and `nativefile.ini` are passed to the configure step with
187 `--cross-file` and `--native-file` options, respectively.
188
189 * `mlog.cmd_ci_include()` can be called from anywhere inside Meson to
190 capture the contents of an additional file into the CI log on failure.
191
192 Projects needed by unit tests are in the `test cases/unit`
193 subdirectory. They are not run as part of `./run_project_tests.py`.
194
195 ### Configuring project tests
196
197 The (optional) `test.json` file, in the root of a test case, is used
198 for configuring the test. All of the following root entries in the `test.json`
199 are independent of each other and can be combined as needed.
200
201 Example `test.json`:
202
203 ```json
204 {
205 "env": {
206 "VAR": "VAL"
207 },
208 "installed": [
209 { "type": "exe", "file": "usr/bin/testexe" },
210 { "type": "pdb", "file": "usr/bin/testexe" },
211 { "type": "shared_lib", "file": "usr/lib/z", "version": "1.2.3" },
212 ],
213 "matrix": {
214 "options": {
215 "opt1": [
216 { "val": "abc" },
217 { "val": "qwert" },
218 { "val": "bad" }
219 ],
220 "opt2": [
221 { "val": null },
222 { "val": "true" },
223 { "val": "false" },
224 ]
225 },
226 "exclude": [
227 { "opt1": "qwert", "opt2": "false" },
228 { "opt1": "bad" }
229 ]
230 },
231 "tools": {
232 "cmake": ">=3.11"
233 }
234 }
235 ```
236
237 #### env
238
239 The `env` key contains a dictionary which specifies additional
240 environment variables to be set during the configure step of the test.
241
242 There is some basic support for configuring the string with the `@<VAR>@` syntax:
243
244 - `@ROOT@`: absolute path of the source directory
245 - `@PATH@`: current value of the `PATH` env variable
246
247 #### installed
248
249 The `installed` dict contains a list of dicts, describing which files are expected
250 to be installed. Each dict contains the following keys:
251
252 - `file`
253 - `type`
254 - `platform` (optional)
255 - `version` (optional)
256 - `language` (optional)
257
258 The `file` entry contains the relative path (from the install root) to the
259 actually installed file.
260
261 The `type` entry specifies how the `file` path should be interpreted based on the
262 current platform. The following values are currently supported:
263
264 | type | Description |
265 | ------------- | ------------------------------------------------------------------------------------------------------- |
266 | `file` | No postprocessing, just use the provided path |
267 | `python_file` | Use the provided path while replacing the python directory. |
268 | `dir` | To include all files inside the directory (for generated docs, etc). The path must be a valid directory |
269 | `exe` | For executables. On Windows the `.exe` suffix is added to the path in `file` |
270 | `shared_lib` | For shared libraries, always written as `name`. The appropriate suffix and prefix are added by platform |
271 | `python_lib` | For python libraries, while replacing the python directory. The appropriate suffix is added by platform |
272 | `pdb` | For Windows PDB files. PDB entries are ignored on non Windows platforms |
273 | `implib` | For Windows import libraries. These entries are ignored on non Windows platforms |
274 | `py_implib` | For Windows import libraries. These entries are ignored on non Windows platforms |
275 | `implibempty` | Like `implib`, but no symbols are exported in the library |
276 | `expr` | `file` is an expression. This type should be avoided and removed if possible |
277
278 Except for the `file`, `python_file` and `expr` types, all paths should be provided *without* a suffix.
279
280 | Argument | Applies to | Description |
281 | -----------|----------------------------|-------------------------------------------------------------------------------|
282 | `version` | `shared_lib`, `pdb` | Sets the version to look for appropriately per-platform |
283 | `language` | `pdb` | Determines which compiler/linker determines the existence of this file |
284
285 The `shared_lib` and `pdb` types takes an optional additional
286 parameter, `version`, this is us a string in `X.Y.Z` format that will
287 be applied to the library. Each version to be tested must have a
288 single version. The harness will apply this correctly per platform:
289
290 The `python_file`, `python_lib`, and `py_implib` types have basic support for configuring the string with the `@<VAR>@` syntax:
291
292 - `@PYTHON_PLATLIB@`: python `get_install_dir` directory relative to prefix
293 - `@PYTHON_PURELIB@`: python `get_install_dir(pure: true)` directory relative to prefix
294
295 `pdb` takes an optional `language` argument. This determines which
296 compiler/linker should generate the pdb file. Because it's possible to
297 mix compilers that do and don't generate pdb files (dmd's optlink
298 doesn't). Currently this is only needed when mixing D and C code.
299
300 ```json
301 {
302 "type": "shared_lib", "file": "usr/lib/lib",
303 "type": "shared_lib", "file": "usr/lib/lib", "version": "1",
304 "type": "shared_lib", "file": "usr/lib/lib", "version": "1.2.3.",
305 }
306 ```
307
308 This will be applied appropriately per platform. On windows this
309 expects `lib.dll` and `lib-1.dll`. on MacOS it expects `liblib.dylib`
310 and `liblib.1.dylib`. On other Unices it expects `liblib.so`,
311 `liblib.so.1`, and `liblib.so.1.2.3`.
312
313 If the `platform` key is present, the installed file entry is only
314 considered if the platform matches. The following values for
315 `platform` are currently supported:
316
317 | platform | Description |
318 | ---------- | -------------------------------------------------------------------- |
319 | `msvc` | Matches when a msvc like compiler is used (`msvc`, `clang-cl`, etc.) |
320 | `gcc` | Not `msvc` |
321 | `cygwin` | Matches when the platform is cygwin |
322 | `!cygwin` | Not `cygwin` |
323
324 #### matrix
325
326 The `matrix` section can be used to define a test matrix to run
327 project tests with different Meson options.
328
329 In the `options` dict, all possible options and their values are
330 specified. Each key in the `options` dict is a Meson option. It stores
331 a list of all potential values in a dict format.
332
333 Each value must contain the `val` key for the value of the option.
334 `null` can be used for adding matrix entries without the current
335 option.
336
337 The `skip_on_env` key (as described below) may be used in the value to skip that
338 matrix entry, based on the current environment.
339
340 The `expect_skip_on_jobname` and `expect_skip_on_os` keys (as described below)
341 may be used to expect that the test will be skipped, based on the current environment.
342
343 Similarly, the `compilers` key can be used to define a mapping of
344 compilers to languages that are required for this value.
345
346 ```json
347 {
348 "compilers": {
349 "c": "gcc",
350 "cpp": "gcc",
351 "d": "gdc"
352 }
353 }
354 ```
355
356 Specific option combinations can be excluded with the `exclude`
357 section. It should be noted that `exclude` does not require exact
358 matches. Instead, any matrix entry containing all option value
359 combinations in `exclude` will be excluded. Thus an empty dict (`{}`)
360 to will match **all** elements in the test matrix.
361
362 The above example will produce the following matrix entries:
363 - `opt1=abc`
364 - `opt1=abc opt2=true`
365 - `opt1=abc opt2=false`
366 - `opt1=qwert`
367 - `opt1=qwert opt2=true`
368
369 #### do_not_set_opts
370
371 Currently supported values are:
372 - `prefix`
373 - `libdir`
374
375 #### tools
376
377 This section specifies a dict of tool requirements in a simple
378 key-value format. If a tool is specified, it has to be present in the
379 environment, and the version requirement must be fulfilled. Otherwise,
380 the entire test is skipped (including every element in the test
381 matrix).
382
383 #### stdout
384
385 The `stdout` key contains a list of dicts, describing the expected
386 stdout.
387
388 Each dict contains the following keys:
389
390 - `line`
391 - `match` (optional)
392 - `count` (optional)
393
394 Each item in the list is matched, in order, against the remaining
395 actual stdout lines, after any previous matches. If the actual stdout
396 is exhausted before every item in the list is matched, the expected
397 output has not been seen, and the test has failed.
398
399 The `match` element of the dict determines how the `line` element is
400 matched:
401
402 | Type | Description |
403 | -------- | ----------------------- |
404 | `literal` | Literal match (default) |
405 | `re` | regex match |
406
407 The `count` element determines how many times the line is expected, and allowed,
408 to be in the output. If unspecified, it must appear "any number of times, but at
409 least once".
410
411 #### skip_on_env
412
413 The `skip_on_env` key can be used to specify a list of environment variables. If
414 at least one environment variable in the `skip_on_env` list is present, the test
415 is skipped.
416
417 #### expect_skip_on_jobname
418
419 The `expect_skip_on_jobname` key contains a list of strings. If the `MESON_CI_JOBNAME`
420 environment variable is set, and any of them are a sub-string of it, the test is
421 expected to be skipped (that is, it is expected that the test will output
422 `MESON_SKIP_TEST`, because the CI environment is not one in which it can run,
423 for whatever reason).
424
425 The test is failed if it either skips unexpectedly or runs unexpectedly.
426
427 #### expect_skip_on_os
428
429 The `expect_skip_on_os` key can be used to specify a list of OS names (or their
430 negations, prefixed with a `!`). If at least one item in the `expect_skip_on_os` list
431 is matched, the test is expected to be skipped.
432
433 The test is failed if it either skips unexpectedly or runs unexpectedly.
434
435 ### Skipping integration tests
436
437 Meson uses several continuous integration testing systems that have
438 slightly different interfaces for indicating a commit should be
439 skipped.
440
441 Continuous integration systems currently used:
442 - [Azure Pipelines](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)
443 allows `***NO_CI***` in the commit message.
444 - [Sider](https://sider.review)
445 runs Flake8 ([see below](#python-coding-style))
446
447 To promote consistent naming policy, use:
448
449 - `[skip ci]` in the commit title if you want to disable all
450 integration tests
451
452 ## Documentation
453
454 The `docs` directory contains the full documentation that will be used
455 to generate [the Meson web site](https://mesonbuild.com). Line length
456 in most cases should not exceed 70 characters (lines containing links
457 or examples are usually exempt). Every change in functionality must
458 change the documentation pages. In most cases this means updating the
459 reference documentation page but bigger changes might need changes in
460 other documentation, too.
461
462 All new functionality needs to have a mention in the release
463 notes. These features should be written in standalone files in the
464 `docs/markdown/snippets` directory. The release manager will combine
465 them into one page when doing the release.
466
467 ## Python Coding style
468
469 Meson follows the basic Python coding style. Additional rules are the
470 following:
471
472 - indent 4 spaces, no tabs ever
473 - indent meson.build files with two spaces
474 - try to keep the code as simple as possible
475 - contact the mailing list before embarking on large scale projects
476 to avoid wasted effort
477
478 Meson uses Flake8 for style guide enforcement. The Flake8 options for
479 the project are contained in .flake8.
480
481 To run Flake8 on your local clone of Meson:
482
483 ```console
484 $ python3 -m pip install flake8
485 $ cd meson
486 $ flake8
487 ```
488
489 To run it automatically before committing:
490
491 ```console
492 $ flake8 --install-hook=git
493 $ git config --bool flake8.strict true
494 ```
495
496 ## C/C++ coding style
497
498 Meson has a bunch of test code in several languages. The rules for
499 those are simple.
500
501 - indent 4 spaces, no tabs ever
502 - brace always on the same line as if/for/else/function definition
503
504 ## External dependencies
505
506 The goal of Meson is to be as easily usable as possible. The user
507 experience should be "get Python3 and Ninja, run", even on
508 Windows. Unfortunately this means that we can't have dependencies on
509 projects outside of Python's standard library. This applies only to
510 core functionality, though. For additional helper programs etc the use
511 of external dependencies may be ok. If you feel that you are dealing
512 with this kind of case, please contact the developers first with your
513 use case.
514
515 ## Turing completeness
516
517 The main design principle of Meson is that the definition language is
518 not Turing complete. Any change that would make Meson Turing complete
519 is automatically rejected. In practice this means that defining your
520 own functions inside `meson.build` files and generalised loops will
521 not be added to the language.
522
523 ## Do I need to sign a CLA in order to contribute?
524
525 No you don't. All contributions are welcome.
526
527 ## No lingering state
528
529 Meson operates in much the same way as functional programming
530 languages. It has inputs, which include `meson.build` files, values of
531 options, compilers and so on. These are passed to a function, which
532 generates output build definition. This function is pure, which means that:
533
534 - for any given input the output is always the same
535 - running Meson twice in a row _always_ produce the same output in both runs
536
537 The latter one is important, because it enforces that there is no way
538 for "secret state" to pass between consecutive invocations of
539 Meson. This is the reason why, for example, there is no `set_option`
540 function even though there is a `get_option` one.
541
542 If this were not the case, we could never know if the build output is
543 "stable". For example suppose there were a `set_option` function and a
544 boolean variable `flipflop`. Then you could do this:
545
546 ```meson
547 set_option('flipflop', not get_option('flipflop'))
548 ```
549
550 This piece of code would never converge. Every Meson run would change
551 the value of the option and thus the output you get out of this build
552 definition would be random.
553
554 Meson does not permit this by forbidding these sorts of covert
555 channels.
556
557 There is one exception to this rule. Users can call into external
558 commands with `run_command`. If the output of that command does not
559 behave like a pure function, this problem arises. Meson does not try
560 to guard against this case, it is the responsibility of the user to
561 make sure the commands they run behave like pure functions.
562
563 ## Environment variables
564
565 Environment variables are like global variables, except that they are
566 also hidden by default. Envvars should be avoided whenever possible,
567 all functionality should be exposed in better ways such as command
568 line switches.
569
570 ## Random design points that fit nowhere else
571
572 - All features should follow the 90/9/1 rule. 90% of all use cases
573 should be easy, 9% should be possible and it is totally fine to not
574 support the final 1% if it would make things too complicated.
575
576 - Any build directory will have at most two toolchains: one native and
577 one cross.
578
579 - Prefer specific solutions to generic frameworks. Solve the end
580 user's problems rather than providing them tools to do it
581 themselves.
582
583 - Never use features of the Unix shell (or Windows shell for that
584 matter). Doing things like forwarding output with `>` or invoking
585 multiple commands with `&&` are not permitted. Whenever these sorts
586 of requirements show up, write an internal Python script with the
587 desired functionality and use that instead.