Expand description
Building the selected tasks in passes (“Order of execution”, “Failure and interruption”).
build runs the selected tasks one at a time, in passes. The tasks start in
the default order, which load already gives them: a
directory’s kizz.md before those of its subdirectories, sibling directories in
byte order of their names, and task blocks in file order. The learned order
overrides it: a task whose stored LearnedOrder names producers among the
selected tasks runs after them, and every other task keeps its default place
(learned_order).
Every pass tries every selected task, and a failed task does not stop the pass.
Each task program runs again in every pass, and every run() goes through the
engine’s cache check, so a task whose recorded inputs changed runs those commands
again, including a failed task whose looked-for paths have appeared, while a task
whose inputs did not change is a cache hit, and a failed one fails again from the
cache without running anything. A missing file is a dependency like any other,
never a scheduling signal: nothing waits for a path to appear.
A pass does work when a command runs in it or a task program changes a file in
it through fs.write or fs.write_json; a write that leaves the file as it was
is no change. After a pass that did work, another pass checks every selected
task. The build ends when a pass does no work: it succeeds if no task failed in
that pass, and otherwise it fails, listing each failed task with the paths it
looked for and did not find. The pass limit is one more than the number of tasks
(pass_limit); when the last pass it allows still does work, the build stops,
naming the paths that keep changing and who writes them, and the files that task
programs changed in it. A command marked
always runs at most once per build, when a pass first reaches it, normally the
first one, because the engine runs each always step key once per build; later
passes reuse its result, and one first reached in a later pass, or with a new step
key, runs once in that pass. Every command of a task marked cache=never runs
the same way, because the engine runs it as if it were marked always; a task
with a name and no targets is never selected, because selection goes by targets.
When a task program ends, whether it succeeded or failed, each step it left
unchecked, which exited with a non-zero code or was killed by a signal, had no
expect, and whose result the program never checked, by reading its rc or
signal or by encoding it, is in TaskResult::unchecked, with its step key
and whether the build ran a command under that key; a result from the cache
counts like any other (“Exit codes and failure”). Only the unchecked steps that
stand when the build settles warn, the final-state rule
(BuildReport::unchecked): those of each task’s latest run in the build,
which in a settled build is its run in the final pass, because every pass tries
every selected task. A task that runs again in a later pass replaces its
earlier results, so a superseded unchecked step never warns, and a build that
does not settle or is interrupted warns about none. With
Engine::with_fail_unchecked (kizz build --fail-unchecked), a run whose
program succeeded but left a step unchecked fails with
TaskFailure::Unchecked, which names every unchecked step; as for every
failure, the final pass decides whether the build fails, and a program that
failed keeps its own failure. Without the option, an unchecked step fails
nothing.
Once cancellation is requested, the build starts nothing new: no further task or
command starts, the outcome is BuildOutcome::Interrupted, and no learned
order is stored.
After every build that is not interrupted, kizz records, for each task that ran,
the tasks whose outputs it consumed: the last writers of the paths its steps and
its program read, checked, listed, or ran, including the paths written into a
directory it listed, and the paths other task programs wrote in this build. A
task program that changes a file is stored as the file’s last writer when its run
ends (Engine::program_wrote), so the order learned from it holds in a later
build in which the program does not write the file.
Each run of a task ends with TaskSteps::finish, which stores the task record:
the program hash and a summary of the run.
The builder keeps the step keys under which the build ran a command in a field
that only its own &mut self methods change, so no RefCell borrow, which
would panic while the cell is borrowed, is needed (“Kizz never panics”).
Structs§
- Build
Report - What a build did.
- Changing
Input - An input that changed and made a step run in the last pass a build allows.
- Failed
Task - A task that failed in the pass that ended the build.
- NoEvents
- Follows nothing.
- Pass
- One pass of a build.
- Program
Write - A file that a task program changed in the last pass a build allows.
- Task
Result - How one run of a task in a pass ended.
- Unchecked
Step - A step that a task run left unchecked (“Exit codes and failure”): its task, its step key, the step itself, and whether the build ran a command under the key.
Enums§
- Build
Outcome - How a build ended.
Constants§
- INTERRUPTED
- The message of a step that the build did not start because it was interrupted.
Traits§
- Build
Events - Follows a build as it runs, for output.
Functions§
- build
- Build
tasks, the selected tasks in the default order, withengine, in passes until a pass does no work;calleris the caller environment, the lines task programs print go toprint, andeventsfollows the build. - learned_
order - The order of tasks whose producers, by index, are
producers:producers[i]lists the tasks that must run before taski, and the indices are the default order. Each task, in the default order, runs once its producers have run, which are placed first, each in the same way and in their default order; every task without such an edge keeps its default place. A cycle of producers is broken where it closes: a producer already being placed is not waited for. Unknown indices and a task naming itself are ignored. - pass_
limit - The number of passes a build may take: one more than the number of tasks.
- task_id
- The identity of the task
task. - task_
label - The task
taskas explanations name it.