Skip to main content

Module explain

Module explain 

Source
Expand description

Explaining decisions: why a step ran (“Explaining decisions”).

The engine turns the cache check’s RunReason into an Explanation before a step runs:

  • A step key with no record is explained through the step-position records: when the task used another key at the same position last time, the reasons compare that key’s specification with this one. The task program, the arguments, the environment, the working directory, stdin, the capture mode, the ignore patterns, the track patterns, the timestamps option, and the machine names each give their own reason; a changed program names its block or each loaded module that changed, from the part hashes of the task record. Without an earlier specification, or when only the occurrence number differs, the step never ran.
  • A step whose record names parts of the machine state, and whose cache check found values of them changed, gives a reason of its own that names each changed value, old and new, after the changed inputs.
  • Each changed input names who last wrote it, from the last-writer records: this command on its previous run, another step in this build, a step of an earlier build, the program of a task, through fs.write or fs.write_json, in this build or an earlier one, or something outside kizz. A write that kizz recorded before the step’s recorded state was taken cannot have changed the path since, so then the writer is something outside kizz. A task program is named as the writer even when it is the program of the step’s own task.
  • A changed input is self-inflicted when this command last wrote it on its previous run and also reads it, or when the step that wrote it in this build runs on every build, because it is marked always, its task is marked cache=never, or it re-runs for a self-inflicted reason itself. A path the command read and wrote before is not self-inflicted when something outside kizz, another task, or a task program changed it since; a change that a task program made is never self-inflicted.
  • A step that re-runs for a self-inflicted input that also made it run in its task’s previous build gets the loud warning for consecutive builds: the step-position record carries the self-inflicted inputs of the previous build’s run.

Structs§

Baseline
The recorded state a cache check compared the file system with: the paths the step wrote and also read, and when the state was taken.
InputContext
What attributing the changed inputs of one step needs.
RepeatedWarning
The loud warning for a step that re-ran in consecutive builds for the same self-inflicted reason.
StepDecision
What a build decided about one step of a task run, for the line kizz build prints for each command it runs and for --explain.
TaskIdentity
The identity of a task whose steps the engine runs: what its step positions, last writers, and task record are stored under, and how output names it.

Functions§

carried_from
The self-inflicted inputs that made the step at a position run in its task’s previous build, sorted, given previous, the step-position record before this build’s decision.
changed_inputs
Every changed input of differences, with who last wrote it and whether the change is self-inflicted.
spec_reasons
The reasons that compare old, the specification the task used last time at the same position, with new, in the order of the spec’s list.