| 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. |