Command Examples

The os_run symbol from @os@1 can express project tasks even when no language package is involved.

Run a Project Script

Paths containing a slash are resolved from project root:

load("@os@1", "os_run")

os_run(("tools/check", "--all"))

On Windows, use forward slashes in build definitions when practical:

os_run(("tools/check.exe", "--all"))

Add a Project Tool Directory

Prepend a relative directory to a task's PATH, then use a bare command name:

load("@os@1", "env_prepend", "os_run")

os_run(
    ("project-linter", "check"),
    deps=[env_prepend("PATH", "tools/bin", unique=True)],
)

xx resolves relative PATH entries from project root.

Reuse an Environment

Combine dependencies into a named value:

load("@os@1", "env_set", "env_unset", "os_run")

ci_env = (
    env_set("CI", "true") +
    env_set("MODE", "check") +
    env_unset("LOCAL_CONFIG")
)

os_run(("tools/lint",), deps=[ci_env])
os_run(("tools/verify",), deps=[ci_env])

Each command has an independent environment. Applying ci_env to one task does not change another task or xx itself.

Share Rules Between Entrypoints

Move repeated Starlark definitions into another file:

.xx/rules.star:

load("@os@1", "env_set")

ci_env = env_set("CI", "true") + env_set("MODE", "check")

.xx/check.star:

load("@os@1", "os_run")
load("rules.star", "ci_env")

os_run(("tools/check",), deps=[ci_env])

Loaded files must import their own built-in symbols. See Loading files for relative imports, project-root imports, aliases, repeated loads, and path rules.