Debian Codegraph @

subprojects/meson-docs/docs/yaml/functions/benchmark.yaml

raw
1 name: benchmark
2 returns: void
3 description: |
4 Creates a benchmark item that will be run when the benchmark target is
5 run. The behavior of this function is identical to [[test]]
6 except for:
7
8 * benchmark() has no `is_parallel` keyword because benchmarks are not run in parallel
9 * benchmark() does not automatically add the `MALLOC_PERTURB_` environment variable
10
11 Defined benchmarks can be run in a backend-agnostic way by calling
12 `meson test --benchmark` inside the build dir, or by using backend-specific
13 commands, such as `ninja benchmark` or `msbuild RUN_TESTS.vcxproj`.
14
15 notes:
16 - Prior to 0.52.0 benchmark would warn that `depends` and
17 `priority` were unsupported, this is incorrect.
18
19 posargs:
20 name:
21 type: str
22 description: The *unique* test id
23
24 executable:
25 type: exe | jar | external_program | file | custom_tgt | custom_idx
26 description: |
27 The program to execute. *(Since 1.4.0)* A CustomTarget is also accepted.
28
29 kwargs:
30 args:
31 type: list[str | file | build_tgt | custom_tgt | custom_idx | external_program]
32 description: Arguments to pass to the executable
33
34 env:
35 type: env | list[str] | dict[str]
36 description: |
37 environment variables to set, such as `['NAME1=value1',
38 'NAME2=value2']`, or an [[@env]] object which allows more sophisticated
39 environment juggling. *(Since 0.52.0)* A dictionary is also accepted.
40
41 should_fail:
42 type: bool
43 default: false
44 description: |
45 when true the test is considered passed if the
46 executable returns a non-zero return value (i.e. reports an error)
47
48 suite:
49 type: str | list[str]
50 description: |
51 `'label'` (or list of labels `['label1', 'label2']`)
52 attached to this test. The suite name is qualified by a (sub)project
53 name resulting in `(sub)project_name:label`. In the case of a list
54 of strings, the suite names will be `(sub)project_name:label1`,
55 `(sub)project_name:label2`, etc.
56
57 timeout:
58 type: int
59 default: 30
60 description: |
61 the amount of seconds the test is allowed to run, a test
62 that exceeds its time limit is always considered failed, defaults to
63 30 seconds. *Since 0.57* if timeout is `<= 0` the test has infinite duration,
64 in previous versions of Meson the test would fail with a timeout immediately.
65
66 workdir:
67 type: str
68 description: |
69 absolute path that will be used as the working directory
70 for the test
71
72 depends:
73 type: list[build_tgt | custom_tgt]
74 since: 0.46.0
75 description: |
76 specifies that this test depends on the specified
77 target(s), even though it does not take any of them as a command
78 line argument. This is meant for cases where test finds those
79 targets internally, e.g. plugins or globbing. Those targets are built
80 before test is executed even if they have `build_by_default : false`.
81
82 protocol:
83 type: str
84 since: 0.50.0
85 default: "'exitcode'"
86 description: |
87 specifies how the test results are parsed and can
88 be one of `exitcode`, `tap`, or `gtest`. For more information about test
89 harness protocol read [Unit Tests](Unit-tests.md). The following values are
90 accepted:
91
92 - `exitcode`: the executable's exit code is used by the test harness
93 to record the outcome of the test).
94 - `tap`: [Test Anything Protocol](https://www.testanything.org/).
95 - `gtest` *(since 0.55.0)*: for Google Tests.
96 - `rust` *(since 0.56.0)*: for native rust tests
97
98 priority:
99 type: int
100 since: 0.52.0
101 default: 0
102 description: |
103 specifies the priority of a test. Tests with a
104 higher priority are *started* before tests with a lower priority.
105 The starting order of tests with identical priorities is
106 implementation-defined. The default priority is 0, negative numbers are
107 permitted.
108
109 verbose:
110 type: bool
111 since: 0.62.0
112 default: false
113 description: |
114 if true, forces the test results to be logged as if `--verbose` was passed
115 to `meson test`.