os_run
os_run executes a command from a directory in the project during xx run. Pass the returned dependency to another task's deps to make that task wait for the command and receive environment changes from its dependencies.
Each task gets an independent, clean operating-system environment rather than the invoking shell's full environment. PATH starts empty, HOME points to xx-managed storage, XDG_* variables are excluded, and temporary variables point to storage removed after the run. Dependencies change the task environment from left to right without affecting other tasks. Use os_system_tools when a command intentionally needs standard host utilities.
The working directory must exist inside the project when os_run is called and must remain there after deps finish.
Arguments
| Argument | Required | Description |
|---|---|---|
command | Yes | Non-empty tuple of strings. First item is the executable; remaining items are arguments. |
deps | No | Dependencies activated before the command, in list order. Defaults to []. |
dir | No | Project-relative working directory. Defaults to ".". |
A bare executable name uses the task's resulting PATH. Relative executable paths and relative PATH entries start from dir. Absolute executable paths are also accepted. Output is forwarded to xx.
Examples
Run a command
load("@[email protected]", "go")
load("@os@1", "os_run")
os_run(("go", "version"), deps=[go])
A one-item tuple needs a trailing comma:
os_run(("tools/check",))
Configure its environment
load("@[email protected]", "go")
load("@os@1", "env_set", "os_run")
os_run(
("go", "test", "./..."),
deps=[go, env_set("CGO_ENABLED", "0")],
)
Change the working directory
load("@[email protected]", "go")
load("@os@1", "os_run")
os_run(("go", "test", "./..."), deps=[go], dir="backend")
Order commands
load("@os@1", "os_run")
generate = os_run(("tools/generate",))
os_run(("tools/check",), deps=[generate])