Running one task

This page explains kizz run, which runs one named task, with arguments, as a command runner.

Overview

kizz run <name> finds the task named <name> and runs its program once, showing each command and its output as it runs. It uses and updates the same cache as kizz build, so a command whose recorded inputs have not changed is normally replayed from the cache instead of running; --no-cache, cache=never and always make commands run anyway.

kizz run [--no-cache] [--explain] [--fail-unchecked] [--cache-unknown-syscalls]
         [--output=<file>] [--compact] [--json] <name> [-- <arguments>...]

Naming tasks

A task gets its name from the name= option in its info string:

## Greet

```starlark name=greet
env.inherit("PATH")
who = task.args[0] if task.args else "world"
run("echo", "hello,", who, expect = [0])
```

A name uses only letters, digits, _, . and -, and is unique within its kizz.md. A task can have targets as well as a name, and then kizz build runs it too. A task with a name and no targets runs only under kizz run. The kizz.md page explains task options.

How the name is found

kizz run discovers tasks as kizz build does: in the current directory and every directory below it.

error: 2 tasks named `hello` are 1 directory level below `.`, so kizz cannot choose one: a/kizz.md:3 (A), b/kizz.md:3 (B)
error: no task named `nope` under `.`; the task names under `.` are: greet

So the same name can mean a different task in each part of a project, and you pick one by where you run it.

Arguments and task.args

The words after -- are the task's arguments, and its program reads them as task.args, a list of strings:

kizz run greet -- kizz

To pass every argument through to a command, give task.args to run() as one positional argument:

run("cargo", "test", task.args)

run() expands the list in place, so for a task named test with this call, kizz run test -- --release foo runs cargo test --release foo, each argument as one word, and kizz run test runs cargo test, because an empty task.args adds nothing. A variable that holds [] or a list of words works the same way for an argument that only some runs need; the argv entry of the reference gives every rule.

Live output and cached replay

kizz run shows each command as it starts, then its output as it comes, as if every run() had stream = True. A cache hit shows its command marked as cached, then replays its stored output. With split capture, the default, a command's standard output goes to standard output and its standard error to standard error. With merged capture, both of its output streams are one stream, which goes to standard output. Both hold live and when a cache hit replays the stored output.

run `echo hello, world` (step 1): never run: there is no record for this step
hello, world
run succeeded: kizz.md:13 (Greet); 1 command ran, 0 cached

Run it again, and the command comes from the cache:

cached `echo hello, world` (step 1)
hello, world
run succeeded: kizz.md:13 (Greet); 0 commands ran, 1 cached

Scope of a run

No cache and cache=never

--no-cache runs every command of the task, as if each had always = True, and still records each result:

run `echo hello, world` (step 1): `kizz run --no-cache` was given

A task marked cache=never runs every command in every run and in every build that reaches it, and so does a command marked always. No option forces caching: kizz run can make a cached command run, but never make such a command cached.

Reports

--output=<file> writes an observation report of the run once it ends, in the format of kizz execute:

kizz run greet --output=run-report.txt
kizz observation report, version 1, hierarchical
trace: complete
totals: commands 1, cached 1, processes 0, programs 0, paths 0, connections 0
paths by access: read 0, probe 0, list 0, write 0, exec 0, xattr 0

command 1: echo hello, world
  program: /usr/bin/echo
  directory: /tmp/demo/hello
  outcome: exited with 0
  trace: cached, not traced

task program: kizz.md:13 (Greet)
error: --compact and --json shape the report that --output writes, so they need --output

Without --output, kizz run writes no report, and shows only each command and its output.

Standard input

A command's standard input is what its run() gives with stdin, or /dev/null, as in a build. So a command that reads the terminal interactively does not work under kizz run. Planned: interactive commands in kizz run, which planned features describes.

Exit statuses