diff options
Diffstat (limited to 'docs/markdown/Contributing.md')
| -rw-r--r-- | docs/markdown/Contributing.md | 111 |
1 files changed, 67 insertions, 44 deletions
diff --git a/docs/markdown/Contributing.md b/docs/markdown/Contributing.md index 3e5bcca..fe5bd0d 100644 --- a/docs/markdown/Contributing.md +++ b/docs/markdown/Contributing.md @@ -36,7 +36,8 @@ Every new feature requires some extra steps, namely: - Must include a project test under `test cases/`, or if that's not possible or if the test requires a special environment, it must go into `run_unittests.py`. -- Must be registered with the [FeatureChecks framework](Release-notes-for-0.47.0.md#feature-detection-based-on-meson_version-in-project) +- Must be registered with the [FeatureChecks + framework](Release-notes-for-0.47.0.md#feature-detection-based-on-meson_version-in-project) that will warn the user if they try to use a new feature while targeting an older meson version. - Needs a release note snippet inside `docs/markdown/snippets/` with @@ -155,21 +156,23 @@ 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. -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. +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. -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. +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. Additionally: * `crossfile.ini` and `nativefile.ini` are passed to the configure step with `--cross-file` and `--native-file` options, respectively. -* `mlog.cmd_ci_include()` can be called from anywhere inside meson to capture the -contents of an additional file into the CI log on failure. +* `mlog.cmd_ci_include()` can be called from anywhere inside meson to +capture the contents of an additional file into the CI log on failure. Projects needed by unit tests are in the `test cases/unit` subdirectory. They are not run as part of `./run_project_tests.py`. @@ -261,9 +264,15 @@ Except for the `file` and `expr` types, all paths should be provided *without* a | `version` | `shared_lib`, `pdb` | Sets the version to look for appropriately per-platform | | `language` | `pdb` | Determines which compiler/linker determines the existence of this file | -The `shared_lib` and `pdb` types takes an optional additional parameter, `version`, this is us a string in `X.Y.Z` 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: +The `shared_lib` and `pdb` types takes an optional additional +parameter, `version`, this is us a string in `X.Y.Z` 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: -`pdb` takes an optional `language` 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. +`pdb` takes an optional `language` 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. ```json { @@ -273,10 +282,14 @@ The `shared_lib` and `pdb` types takes an optional additional parameter, `versio } ``` -This will be applied appropriately per platform. On windows this expects `lib.dll` and `lib-1.dll`. on MacOS it expects `liblib.dylib` and `liblib.1.dylib`. On other Unices it expects `liblib.so`, `liblib.so.1`, and `liblib.so.1.2.3`. +This will be applied appropriately per platform. On windows this +expects `lib.dll` and `lib-1.dll`. on MacOS it expects `liblib.dylib` +and `liblib.1.dylib`. On other Unices it expects `liblib.so`, +`liblib.so.1`, and `liblib.so.1.2.3`. -If the `platform` key is present, the installed file entry is only considered if -the platform matches. The following values for `platform` are currently supported: +If the `platform` key is present, the installed file entry is only +considered if the platform matches. The following values for +`platform` are currently supported: | platform | Description | | ---------- | -------------------------------------------------------------------- | @@ -287,22 +300,25 @@ the platform matches. The following values for `platform` are currently supporte #### matrix -The `matrix` section can be used to define a test matrix to run project tests -with different meson options. +The `matrix` section can be used to define a test matrix to run +project tests with different meson options. -In the `options` dict, all possible options and their values are specified. Each -key in the `options` dict is a meson option. It stores a list of all potential -values in a dict format, which allows to skip specific values based on the current -environment. +In the `options` dict, all possible options and their values are +specified. Each key in the `options` dict is a meson option. It stores +a list of all potential values in a dict format, which allows to skip +specific values based on the current environment. -Each value must contain the `val` key for the value of the option. `null` can be -used for adding matrix entries without the current option. +Each value must contain the `val` key for the value of the option. +`null` can be used for adding matrix entries without the current +option. -Additionally, the `skip_on_env` key can be used to specify a list of environment -variables. If at least one environment variable in `skip_on_env` is present, all -matrix entries containing this value are skipped. +Additionally, the `skip_on_env` key can be used to specify a list of +environment variables. If at least one environment variable in +`skip_on_env` is present, all matrix entries containing this value are +skipped. -Similarly, the `compilers` key can be used to define a mapping of compilers to languages that are required for this value. +Similarly, the `compilers` key can be used to define a mapping of +compilers to languages that are required for this value. ```json { @@ -314,10 +330,11 @@ Similarly, the `compilers` key can be used to define a mapping of compilers to l } ``` -Specific option combinations can be excluded with the `exclude` section. It should -be noted that `exclude` does not require exact matches. Instead, any matrix entry -containing all option value combinations in `exclude` will be excluded. Thus -an empty dict (`{}`) to will match **all** elements in the test matrix. +Specific option combinations can be excluded with the `exclude` +section. It should be noted that `exclude` does not require exact +matches. Instead, any matrix entry containing all option value +combinations in `exclude` will be excluded. Thus an empty dict (`{}`) +to will match **all** elements in the test matrix. The above example will produce the following matrix entries: - `opt1=abc` @@ -334,26 +351,29 @@ Currently supported values are: #### tools -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). +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). #### stdout -The `stdout` key contains a list of dicts, describing the expected stdout. +The `stdout` key contains a list of dicts, describing the expected +stdout. Each dict contains the following keys: - `line` - `match` (optional) -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. +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. -The `match` element of the dict determines how the `line` element is matched: +The `match` element of the dict determines how the `line` element is +matched: | Type | Description | | -------- | ----------------------- | @@ -362,8 +382,9 @@ The `match` element of the dict determines how the `line` element is matched: ### Skipping integration tests -Meson uses several continuous integration testing systems that have slightly -different interfaces for indicating a commit should be skipped. +Meson uses several continuous integration testing systems that have +slightly different interfaces for indicating a commit should be +skipped. Continuous integration systems currently used: - [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) @@ -373,7 +394,8 @@ Continuous integration systems currently used: To promote consistent naming policy, use: -- `[skip ci]` in the commit title if you want to disable all integration tests +- `[skip ci]` in the commit title if you want to disable all + integration tests ## Documentation @@ -480,7 +502,8 @@ 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. -Meson does not permit this by forbidding these sorts of covert channels. +Meson does not permit this by forbidding these sorts of covert +channels. There is one exception to this rule. Users can call into external commands with `run_command`. If the output of that command does not |