Skip to main content

Module runtime

Module runtime 

Source
Expand description

The Starlark runtime of task programs.

A task program is a task block plus every module it loads, directly or indirectly. TaskProgram::load reads and evaluates the modules, records each module read as an access of the task, and computes the ProgramHash that covers the block and every module. TaskProgram::run then evaluates the block, handing each run() call to a StepExecutor.

Programs use the extended Starlark dialect, so top-level if and for work. The globals are the standard ones with json.encode and json.decode, plus run, env, fs, print, and fail; load is a statement, and task describes the running task. Functions from modules act on the task that calls them, and calling run() while a module is being loaded, outside any task, is an error.

Each positional argument of run() is a string, or a list or tuple of strings, lists or tuples, which expands in place, in order and at any depth, into the step’s command. The expansion walks the values with its own stack, fails on a list or tuple that contains itself, and stops past a million values, so it never recurses without bound and always ends.

The task environment starts empty, and only the env functions change it; env.caller and env.inherit read the caller environment that TaskProgram::run is given, never the process environment. The task environment and the caller environment exist only while the task runs, so while a module is being loaded, the env functions other than env.read are errors, like run(). The fs functions and env.read work there too, and every file access they make, like each module read, is recorded against the task, as is every file that fs.write or fs.write_json changes.

run() returns a value of the runtime’s own Starlark type, run_result, with the attributes rc, signal, stdout and stderr or output, and cached. The value notes when the program reads rc or signal, or encodes the value with json.encode or fs.write_json, which encode it as an object of its attributes, as they encoded the struct that run() returned before. So when the program ends, TaskRun::unchecked lists every step that exited with a non-zero code or was killed by a signal, whose run() had no expect, and whose result the program never checked (“Exit codes and failure”).

The runtime never panics (“Kizz never panics”): the state of the running task and of a module being loaded lives in Cells, which the private cells module takes out, changes and puts back, where RefCell borrows would panic while the cell is borrowed; and the blank lines that put the block at its line of the kizz.md are pushed into space reserved with String::try_reserve_exact, where str::repeat would panic on a length that overflows.

Structs§

ProgramHash
The BLAKE3 hash of a task program: the block and every module the task loads.
ProgramLoad
The result of TaskProgram::load and TaskProgram::load_noting.
ProgramName
A name that task programs use beyond Starlark’s standard globals.
ProgramNames
Everything that task programs use beyond Starlark’s standard globals, read from the runtime itself, so that the documentation can be checked against it.
ProgramParts
The parts of a task program and the hash of each, so explanations can say whether the block or a named loaded module changed.
TaskInfo
The running task, as task programs see it through task and as messages name it.
TaskProgram
A task program whose modules are loaded, ready to run.
TaskRun
The result of TaskProgram::run.
UncheckedExit
A step whose command exited with a non-zero code or was killed by a signal, whose run() had no expect, and whose result the task program never checked: it never read the result’s rc or signal and never encoded the result (“Exit codes and failure”). A result from the cache counts like any other.
UnexpectedExit
A step whose exit status was not one its expect list accepts.

Enums§

NameKind
What a name that task programs use is, which decides how documentation writes it: a function with (), such as run(), and a module or a value without, such as env or task.args.
TaskFailure
Why a task failed.

Constants§

MERGED_RESULT_ATTRIBUTES
The attributes of a run() result with capture = "merged", in the order the struct that run() returned before had them.
SPLIT_RESULT_ATTRIBUTES
The attributes of a run() result with capture = "split", in the order the struct that run() returned before had them.
TASK_MEMBERS
The members of TASK_VALUE, in the order the value holds them, under which the runtime sets the values that describe the running task.
TASK_VALUE
The name of the value that describes the running task, which every task program’s module holds besides the globals.

Traits§

PrintSink
Where the lines that task programs print go.

Functions§

program_names
Everything that task programs use beyond Starlark’s standard globals: the globals of task programs that the standard ones lack, with the members of each module, run()’s parameters from its signature, task with TASK_MEMBERS, and the result’s attributes from SPLIT_RESULT_ATTRIBUTES and MERGED_RESULT_ATTRIBUTES.