Command Examples

The @os@1 package 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", "run")

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

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

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

Add a Project Tool Directory

Prepend a relative directory to virtual PATH, then use a bare command name:

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

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", "run")

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

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

Each command gets a separate environment clone. Applying ci_env to one task does not mutate 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", "run")
load("rules.star", "ci_env")

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, caching, and safety rules.