The kizz.md format

This page describes the format of a kizz.md file: its task blocks, their targets, and their task options. The kizz.md guide explains how to write one, and the Starlark API describes what a task program can call.

Overview

A kizz.md is an ordinary Markdown file, and kizz reads only its task blocks. A task block is a fenced code block whose info string starts with the word starlark. The rest of the info string tags the block with targets and task options, and the block's content is the task's program:

# Server

## Lint the sources

```starlark ci check name=lint
env.inherit("PATH", "HOME")
run("cargo", "clippy", "--", "-D", "warnings", expect = [0])
```

Here ci and check are targets, name=lint is a task option, and "Lint the sources" is the task's heading. kizz build ci, kizz build check and kizz run lint all run this task.

Everything else in the file is documentation, so a kizz.md can explain its tasks in prose, lists and other code blocks.

File name and discovery

Kizz reads only files named exactly kizz.md; every other Markdown file is documentation, which kizz does not read.

The default order of tasks is the order of discovery: a directory's kizz.md before those of its subdirectories, sibling directories in the byte order of their names, and the blocks of one file in file order. A build changes it only where it has learned that a task consumes what another task writes, as the kizz.md guide explains.

Fences

Kizz reads Markdown as CommonMark does, so a task block is a fenced code block by CommonMark's rules:

The block's content, the lines between its fences, is the task's Starlark source. Its line numbers are kept: a Starlark error in the block names the line of the kizz.md.

The info string

The info string is the text after the opening fence. Kizz splits it into words at whitespace:

Targets

A target is the name of a group of tasks that people build together, such as ci, check or test. A task can have any number of targets, and many tasks in many kizz.md files can share one.

The command line selects tasks by a target expression: one target, or several joined with +, such as ci+check.

error: no target given; give one target, or several joined with `+`; the available targets are: check, ci
error: invalid target expression `ci+`: a target is missing; join targets with `+`, such as `ci+check`

Task options

A task option is a key=value word of the info string, after starlark. There are two, name= and cache=never.

kizz.md:5 (Lint the sources) [ci, check] name=lint
kizz.md:12 (Deploy) [] name=deploy cache=never

These are the problems of a task option, each a configuration error with its own message:

name=

name=<name> names the task, so that kizz run <name> can run it.

cache=never

cache=never makes every command of the task run in every build that reaches it, as if each of its run() calls had always = True.

run `echo deploying production` (step 1): its task is marked `cache=never`

The heading

The task's heading is the nearest Markdown heading above its block.

A short heading that says what the task does makes kizz's output easy to read.

Task identity

A task is identified by the absolute path of its kizz.md, the path through which discovery reached it, and its position among the task blocks of that file, counting from zero.

Untagged blocks

A starlark block with neither targets nor a name is not a task, because nothing could select it. Kizz warns about it, because it is probably a mistake, and repeats the warning in the summary:

warning: kizz.md:3 (Notes): this starlark block has neither targets nor a name, so it is not a task

Configuration errors

A configuration error anywhere under the current directory stops kizz build, kizz run and kizz list before any task runs, with exit status 2. Kizz prints every configuration error of every file, each with the file, the line of the block's opening fence and its heading. For a file whose blocks have several mistakes, the output starts:

error: kizz.md:5 (One): invalid value in task option `cache=sometimes`: `cache` accepts only `never`
error: kizz.md:10 (Two): invalid target name `ci!`: target names use only letters, digits, `_`, `.` and `-`
error: kizz.md:10 (Two): task option `=x` has no key: a task option is a `key=value` word
error: kizz.md:10 (Two): unknown task option `color=red`: the task options are `name=<name>` and `cache=never`
error: kizz.md:10 (Two): task option `name=b` gives the key `name` again, which a block gives once

The configuration errors are:

A block with a configuration error is not a task. A Starlark error in a block is not a configuration error: it fails only that task, when it runs.

Caching controls

This list gathers everything that decides whether a command runs or comes from the cache. By default, kizz records what each command touched, and replays the command's recorded result while none of it has changed.

In a run() call:

In the info string:

On the command line:

No option forces caching: a command marked always, or of a task marked cache=never, runs whatever else is given. Some results are never a cache hit in a later build, such as that of a command killed by a signal. While no path that such a command touched has changed, a later pass of the same build does not run it again: it returns the same result, with cached set, and a command that could not start, which has no result, fails its task again with the same error. The caching guide lists them.

Recommended usage gives the advice in full; in short: