Skip to main content

Module build

Module build 

Source
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§

BuildReport
What a build did.
ChangingInput
An input that changed and made a step run in the last pass a build allows.
FailedTask
A task that failed in the pass that ended the build.
NoEvents
Follows nothing.
Pass
One pass of a build.
ProgramWrite
A file that a task program changed in the last pass a build allows.
TaskResult
How one run of a task in a pass ended.
UncheckedStep
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§

BuildOutcome
How a build ended.

Constants§

INTERRUPTED
The message of a step that the build did not start because it was interrupted.

Traits§

BuildEvents
Follows a build as it runs, for output.

Functions§

build
Build tasks, the selected tasks in the default order, with engine, in passes until a pass does no work; caller is the caller environment, the lines task programs print go to print, and events follows the build.
learned_order
The order of tasks whose producers, by index, are producers: producers[i] lists the tasks that must run before task i, 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 task as explanations name it.