run_target()

This function creates a new top-level target that runs a specified command with the specified arguments. Like all top-level targets, this integrates with the selected backend. For instance, you can run it as meson compile target_name. Note that a run target produces no output as far as Meson is concerned. It is only meant for tasks such as running a code formatter or flashing an external device's firmware with a built file.

The command is run from an unspecified directory, and Meson will set three environment variables MESON_SOURCE_ROOT, MESON_BUILD_ROOT and MESON_SUBDIR that specify the source directory, build directory and subdirectory the target was defined in, respectively.

Since 0.57.0 The template strings passed to command keyword arguments accept the following special substitutions:

  • @SOURCE_ROOT@: the path to the root of the source tree. Depending on the backend, this may be an absolute or a relative to current workdir path.
  • @BUILD_ROOT@: the path to the root of the build tree. Depending on the backend, this may be an absolute or a relative to current workdir path.
  • @CURRENT_SOURCE_DIR@ Since 0.57.1: this is the directory where the currently processed meson.build is located in. Depending on the backend, this may be an absolute or a relative to current workdir path.

Signature

# This function creates a new top-level target that runs a specified
run_tgt run_target(
  str target_name,     # The name of the run target

  # Keyword arguments:
  command : array[exe | external_program | custom_tgt | file | str]  # An array containing the command to run and the arguments
  depends : array[build_tgt | custom_tgt | custom_idx]               # An array of targets that this target depends on but which
  env     : env | array[str] | dict[str]                             # environment variables to set, such as
)

Arguments

The function run_target() accepts the following positional arguments:

Name Type Description Tags
target_name str

The name of the run target

Finally, run_target() accepts the following keyword arguments:

Name Type Description Tags
command array[exe | external_program | custom_tgt | file | str]

An array containing the command to run and the arguments to pass to it. Each array element may be a string or a target. For instance, passing the return value of executable() as the first item will run that executable, or passing a string as the first item will find that command in PATH and run it.
depends array[build_tgt | custom_tgt | custom_idx]

An array of targets that this target depends on but which are not listed in the command array (because, for example, the script does file globbing internally, custom_idx was not possible as a type between 0.60 and 1.4.0).
env env | array[str] | dict[str]

environment variables to set, such as {'NAME1': 'value1', 'NAME2': 'value2'} or ['NAME1=value1', 'NAME2=value2'], or an env object which allows more sophisticated environment juggling.

(since 0.57.0)

The results of the search are