Debian Codegraph @

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

raw
1 name: run_target
2 returns: run_tgt
3 description: |
4 This function creates a new top-level target that runs a specified
5 command with the specified arguments. Like all top-level targets, this
6 integrates with the selected backend. For instance, you can run it as
7 `meson compile target_name`. Note that a run target produces no output
8 as far as Meson is concerned. It is only meant for tasks such as
9 running a code formatter or flashing an external device's firmware
10 with a built file.
11
12 The command is run from an *unspecified* directory, and Meson will set
13 three environment variables `MESON_SOURCE_ROOT`, `MESON_BUILD_ROOT`
14 and `MESON_SUBDIR` that specify the source directory, build directory
15 and subdirectory the target was defined in, respectively.
16
17 *Since 0.57.0* The template strings passed to `command` keyword arguments accept
18 the following special substitutions:
19 - `@SOURCE_ROOT@`: the path to the root of the source tree. Depending on the backend,
20 this may be an absolute or a relative to current workdir path.
21 - `@BUILD_ROOT@`: the path to the root of the build tree. Depending on the backend,
22 this may be an absolute or a relative to current workdir path.
23 - `@CURRENT_SOURCE_DIR@` *Since 0.57.1*: this is the directory where the currently
24 processed meson.build is located in. Depending on the backend,
25 this may be an absolute or a relative to current workdir path.
26
27 posargs:
28 target_name:
29 type: str
30 description: The name of the run target
31
32 kwargs:
33 command:
34 type: list[exe| external_program | custom_tgt | file | str]
35 description: |
36 A list containing the command to run and the arguments
37 to pass to it. Each list item may be a string or a target. For
38 instance, passing the return value of [[executable]]
39 as the first item will run that executable, or passing a string as
40 the first item will find that command in `PATH` and run it.
41
42 depends:
43 type: list[build_tgt | custom_tgt | custom_idx]
44 description: |
45 A list of targets that this target depends on but which
46 are not listed in the command array (because, for example, the
47 script does file globbing internally, custom_idx was not possible
48 as a type between 0.60 and 1.4.0).
49
50 env:
51 since: 0.57.0
52 type: env | list[str] | dict[str]
53 description: |
54 environment variables to set, such as
55 `{'NAME1': 'value1', 'NAME2': 'value2'}` or `['NAME1=value1', 'NAME2=value2']`,
56 or an [[@env]] object which allows more sophisticated environment juggling.