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§
- Program
Hash - The BLAKE3 hash of a task program: the block and every module the task loads.
- Program
Load - The result of
TaskProgram::loadandTaskProgram::load_noting. - Program
Name - A name that task programs use beyond Starlark’s standard globals.
- Program
Names - Everything that task programs use beyond Starlark’s standard globals, read from the runtime itself, so that the documentation can be checked against it.
- Program
Parts - The parts of a task program and the hash of each, so explanations can say whether the block or a named loaded module changed.
- Task
Info - The running task, as task programs see it through
taskand as messages name it. - Task
Program - A task program whose modules are loaded, ready to run.
- TaskRun
- The result of
TaskProgram::run. - Unchecked
Exit - A step whose command exited with a non-zero code or was killed by a signal,
whose
run()had noexpect, and whose result the task program never checked: it never read the result’srcorsignaland never encoded the result (“Exit codes and failure”). A result from the cache counts like any other. - Unexpected
Exit - A step whose exit status was not one its
expectlist accepts.
Enums§
- Name
Kind - What a name that task programs use is, which decides how documentation writes
it: a function with
(), such asrun(), and a module or a value without, such asenvortask.args. - Task
Failure - Why a task failed.
Constants§
- MERGED_
RESULT_ ATTRIBUTES - The attributes of a
run()result withcapture = "merged", in the order the struct thatrun()returned before had them. - SPLIT_
RESULT_ ATTRIBUTES - The attributes of a
run()result withcapture = "split", in the order the struct thatrun()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§
- Print
Sink - Where the lines that task programs
printgo.
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,taskwithTASK_MEMBERS, and the result’s attributes fromSPLIT_RESULT_ATTRIBUTESandMERGED_RESULT_ATTRIBUTES.