diff options
Diffstat (limited to 'docs')
| -rw-r--r-- | docs/markdown/Contributing.md | 132 | ||||
| -rw-r--r-- | docs/markdown/External-commands.md | 2 | ||||
| -rw-r--r-- | docs/markdown/Release-notes-for-0.50.0.md | 4 | ||||
| -rw-r--r-- | docs/markdown/Unit-tests.md | 2 | ||||
| -rw-r--r-- | docs/markdown/snippets/consistent_file_locations.md | 9 |
5 files changed, 133 insertions, 16 deletions
diff --git a/docs/markdown/Contributing.md b/docs/markdown/Contributing.md index c5b8608..26f3512 100644 --- a/docs/markdown/Contributing.md +++ b/docs/markdown/Contributing.md @@ -163,28 +163,136 @@ 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. -The following files in the test's source root are consulted, if they exist: - -* `installed_files.txt` lists the files which are expected to be installed. -Various constructs containing `?` are used to indicate platform specific -filename variations (e.g. `?so` represents the platform appropriate suffix for a -shared library) - -* `setup_env.json` contains a dictionary which specifies additional -environment variables to be set during the configure step of the test. `@ROOT@` -is replaced with the absolute path of the source directory. +Additionally: * `crossfile.ini` and `nativefile.ini` are passed to the configure step with `--cross-file` and `--native-file` options, respectively. -Additionally: - * `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`. +#### Configuring project tests + +The (optional) `test.json` file, in the root of a test case, is used +for configuring the test. All of the following root entries in the `test.json` +are independent of each other and can be combined as needed. + +Exanple `test.json`: + +```json +{ + "env": { + "VAR": "VAL" + }, + "installed": [ + { "type": "exe", "file": "usr/bin/testexe" }, + { "type": "pdb", "file": "usr/bin/testexe" }, + ], + "matrix": { + "options": { + "opt1": [ + { "val": "abc" }, + { "val": "qwert" }, + { "val": "bad" } + ], + "opt2": [ + { "val": null }, + { "val": "true" }, + { "val": "false" }, + ] + }, + "exclude": [ + { "opt1": "qwert", "opt2": "false" }, + { "opt1": "bad" } + ] + } +} +``` + +##### env + +The `env` key contains a dictionary which specifies additional +environment variables to be set during the configure step of the test. `@ROOT@` +is replaced with the absolute path of the source directory. + +##### installed + +The `installed` dict contains a list of dicts, describing which files are expected +to be installed. Each dict contains the following keys: + +- `file` +- `type` +- `platform` (optional) + +The `file` entry contains the relative path (from the install root) to the +actually installed file. + +The `type` entry specifies how the `file` path should be interpreted based on the +current platform. The following values are currently supported: + +| `type` | Description | +| :-----------: | -------------------------------------------------------------------------------- | +| `file` | No postprocessing, just use the provided path | +| `exe` | For executables. On Windows the `.exe` suffix is added to the path in `file` | +| `pdb` | For Windows PDB files. PDB entries are ignored on non Windows platforms | +| `implib` | For Windows import libraries. These entries are ignored on non Windows platforms | +| `implibempty` | Like `implib`, but no symbols are exported in the library | +| `expr` | `file` is an expression. This type should be avoided and removed if possible | + +Except for the `file` and `expr` types, all paths should be provided *without* a suffix. + +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 | +| :--------: | -------------------------------------------------------------------- | +| `msvc` | Matches when a msvc like compiler is used (`msvc`, `clang-cl`, etc.) | +| `gcc` | Not `msvc` | +| `cygwin` | Matches when the platform is cygwin | +| `!cygwin` | Not `cygwin` | + +##### matrix + +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. + +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. + +Similarly, the `compilers` key can be used to define a set of compilers required +for this value. + + +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` +- `opt1=abc opt2=true` +- `opt1=abc opt2=false` +- `opt1=qwert` +- `opt1=qwert opt2=true` + +##### do_not_set_opts + +Currently supported values are: +- `prefix` +- `libdir` + ### Skipping integration tests Meson uses several continuous integration testing systems that have slightly diff --git a/docs/markdown/External-commands.md b/docs/markdown/External-commands.md index e8f335f..272182c 100644 --- a/docs/markdown/External-commands.md +++ b/docs/markdown/External-commands.md @@ -23,7 +23,7 @@ run_command('command', 'arg1', 'arg2', env: {'FOO': 'bar'}) ``` Since 0.50.0, you can also pass the command -[`environment`](Reference-manual.html#environment-object) object: +[`environment`](Reference-manual.md#environment-object) object: ```meson env = environment() diff --git a/docs/markdown/Release-notes-for-0.50.0.md b/docs/markdown/Release-notes-for-0.50.0.md index 62a4b80..a9363d8 100644 --- a/docs/markdown/Release-notes-for-0.50.0.md +++ b/docs/markdown/Release-notes-for-0.50.0.md @@ -197,8 +197,8 @@ dependency tracking does not work. ## `run_command()` accepts `env` kwarg -You can pass [`environment`](Reference-manual.html#environment-object) -object to [`run_command`](Reference-manual.html#run-command), just +You can pass [`environment`](Reference-manual.md#environment-object) +object to [`run_command`](Reference-manual.md#run-command), just like to `test`: ```meson diff --git a/docs/markdown/Unit-tests.md b/docs/markdown/Unit-tests.md index 066b57e..97ee867 100644 --- a/docs/markdown/Unit-tests.md +++ b/docs/markdown/Unit-tests.md @@ -32,7 +32,7 @@ By default, environment variable [`MALLOC_PERTURB_`](http://man7.org/linux/man-pages/man3/mallopt.3.html) is set to a random value between 1..255. This can help find memory leaks on configurations using glibc, including with non-GCC compilers. -This feature can be disabled as discussed in [test()](./Reference-manual#test). +This feature can be disabled as discussed in [test()](Reference-manual.md#test). ## Coverage diff --git a/docs/markdown/snippets/consistent_file_locations.md b/docs/markdown/snippets/consistent_file_locations.md new file mode 100644 index 0000000..5f384fe --- /dev/null +++ b/docs/markdown/snippets/consistent_file_locations.md @@ -0,0 +1,9 @@ +## Consistently report file locations relative to cwd + +The paths for filenames in error and warning locations are now consistently +reported relative to the current working directory (when possible), or as +absolute paths (when a relative path does not exist, e.g. a Windows path +starting with a different drive letter to the current working directory). + +(The previous behaviour was to report a path relative to the source root for all +warnings and most errors, and relative to cwd for certain parser errors) |