Expand description
The kizz build engine.
This crate holds discovery, Markdown parsing, the Starlark runtime, step keys,
cache checks, explanations, ordering, observation reports, and running
kizz execute. It contains no Linux-specific code: it runs commands only through
the tracer interface of kizz_trace, reads extended attributes only through that
interface’s attribute query, and keeps its records in kizz_store, so its tests
use a fake tracer.
discovery: everykizz.mdunder the current directory, in the default order.tasks: the task blocks of akizz.md.targets: target names, target expressions joined with+, and task selection.project: discovery and parsing together, with their configuration errors.runtime: the Starlark runtime of task programs, with module loading, the program hash, and theenvandfsfunctions.dotenv: the dotenv files thatenv.load_fileandenv.readread.files: the file operations behind thefsfunctions, which record every access and every file a write changed.step: the step specification thatrun()builds, and the step executor the runtime hands it to.warning: the warnings of discovery and parsing.key: step keys, derived with BLAKE3 from a deterministic CBOR encoding.lookup: program lookup through thePATHof a task environment or of the caller ofkizz execute.patterns: the path patterns ofignoreandtrack.observe: the recorded state of every path a step touched.states: the in-memory concurrent cache of file states and hashes of one build, so a file is hashed once per build.check: the cache check, which compares a step’s recorded observations with the file system.engine: the engine side of the step executor, which checks the cache for each step, replays a hit, and otherwise runs the step through the tracer and stores its record, unless the result is not cached.explain: why each step ran, from the cache check, the step-position records, and the last-writer records, with the warning for steps that re-run for a self-inflicted reason.render: the one-line and full reasons as output shows them.why: the report ofkizz why, read from the cache.report: observation reports, built from the tracer’s process trees and the commands’ outcomes, and written as text or JSON, hierarchical or compact.execute: running one command forkizz execute, with the caller’s environment and working directory, the kept terminal and the process tree, and its exit status and observation report, without the cache.build: building the selected tasks in passes, in the default or learned order, until a pass does no work, with failure handling and the pass limit.run: running one task by its name forkizz run, once, with its arguments, the nearest task of the name winning, and the observation report ofkizz run --output.cleanup: the entrieskizz cache cleanremoves because their files are gone, and the entrieskizz cache resetwipes for the tasks under a path.pool: the worker pool that runs a command’s parallel work, whose threads start throughkizz_threads, sorayon’s global pool never starts.
State that one thread changes through shared references lives in a Cell, which
the private cells module takes out, changes and puts back, where a RefCell
borrow would panic while the cell is borrowed; state that threads share is locked
with kizz_threads::lock, where Mutex::lock may panic (“Kizz never panics”).
Re-exports§
pub use build::BuildEvents;pub use build::BuildOutcome;pub use build::BuildReport;pub use build::ChangingInput;pub use build::FailedTask;pub use build::INTERRUPTED;pub use build::NoEvents;pub use build::Pass;pub use build::ProgramWrite;pub use build::TaskResult;pub use build::UncheckedStep;pub use build::build;pub use build::learned_order;pub use build::pass_limit;pub use build::task_id;pub use build::task_label;pub use check::Checked;pub use check::RACY_WINDOW_NANOS;pub use check::check;pub use cleanup::Cleaned;pub use cleanup::ResetPlan;pub use cleanup::clean;pub use cleanup::plan_reset;pub use discovery::Discovery;pub use discovery::KIZZ_FILE_NAME;pub use discovery::KizzFile;pub use discovery::default_order;pub use discovery::discover;pub use dotenv::DotenvError;pub use engine::Engine;pub use engine::NoStepEvents;pub use engine::StepConnections;pub use engine::StepEvents;pub use engine::TaskSteps;pub use engine::UnknownCalls;pub use execute::ExecuteRequest;pub use execute::Executed;pub use execute::STATUS_FAILED;pub use execute::STATUS_NOT_EXECUTABLE;pub use execute::STATUS_NOT_FOUND;pub use execute::execute;pub use execute::exit_status;pub use execute::not_executed;pub use explain::Baseline;pub use explain::InputContext;pub use explain::RepeatedWarning;pub use explain::StepDecision;pub use explain::TaskIdentity;pub use explain::carried_from;pub use explain::changed_inputs;pub use explain::spec_reasons;pub use files::AccessOutcomes;pub use files::ChangedFile;pub use files::FileChanges;pub use files::FileError;pub use files::Files;pub use files::stable_json;pub use key::KeyError;pub use key::Occurrences;pub use key::STEP_KEY_CONTEXT;pub use key::step_key;pub use lookup::NoPathError;pub use lookup::PATH_VARIABLE;pub use lookup::ProgramLookup;pub use lookup::ProgramSearch;pub use lookup::check_path;pub use lookup::find_program;pub use lookup::search_program;pub use lookup::search_step_program;pub use observe::HashCounter;pub use observe::Observed;pub use observe::access_bits;pub use observe::changed_after_read;pub use observe::is_kernel_path;pub use observe::kernel_links;pub use observe::observe;pub use observe::path_state;pub use observe::reaches_kernel;pub use observe::record_attributes;pub use patterns::PathPatterns;pub use patterns::PatternError;pub use patterns::REGEX_PREFIX;pub use pool::MAX_WORKERS;pub use pool::PoolError;pub use pool::WorkerPool;pub use project::ConfigError;pub use project::LoadError;pub use project::Project;pub use project::load;pub use render::CACHED;pub use render::Render;pub use render::access_kinds;pub use report::CommandInput;pub use report::CommandOutcome;pub use report::Execution;pub use report::JSON_FIELDS;pub use report::JsonField;pub use report::Report;pub use report::ReportFormat;pub use report::ReportMode;pub use report::TaskProgramInput;pub use run::NameError;pub use run::RunObservations;pub use run::RunReport;pub use run::run;pub use run::select_by_name;pub use run::task_level;pub use runtime::PrintSink;pub use runtime::ProgramHash;pub use runtime::ProgramLoad;pub use runtime::ProgramParts;pub use runtime::TaskFailure;pub use runtime::TaskInfo;pub use runtime::TaskProgram;pub use runtime::TaskRun;pub use runtime::UncheckedExit;pub use runtime::UnexpectedExit;pub use states::FileStates;pub use step::StepError;pub use step::StepExecutor;pub use step::StepOutcome;pub use step::StepSpec;pub use targets::Selected;pub use targets::TARGET_NAME_RULE;pub use targets::TargetExpr;pub use targets::TargetExprError;pub use targets::is_valid_target;pub use tasks::OptionProblem;pub use tasks::ParsedFile;pub use tasks::TASK_LANGUAGE;pub use tasks::TASK_NAME_RULE;pub use tasks::TASK_OPTION_KEYS;pub use tasks::Task;pub use tasks::TaskOptions;pub use tasks::parse_tasks;pub use warning::Warning;pub use why::WhyReport;pub use why::WhyStep;pub use why::WhyTask;pub use why::why;
Modules§
- build
- Building the selected tasks in passes (“Order of execution”, “Failure and interruption”).
- check
- The cache check: comparing a step’s recorded observations with the file system.
- cleanup
- Cleaning up the cache: the entries
kizz cache cleanremoves because the files they are about are gone, and the entrieskizz cache resetwipes for the tasks under a path. - discovery
- Discovery of
kizz.mdfiles. - dotenv
- The dotenv files that
env.load_fileandenv.readread. - engine
- The engine side of the step executor.
- execute
- Running one command for
kizz execute(“Observing any command withkizz execute”), through the tracer interface and without the cache. - explain
- Explaining decisions: why a step ran (“Explaining decisions”).
- files
- The file operations of task programs, behind the
fsfunctions and the dotenv reads ofenv.load_fileandenv.read. - key
- Step keys.
- lookup
- Program lookup through an environment’s
PATH. - observe
- The state of every path a step touched, recorded when the step finishes.
- patterns
- The path patterns of
ignoreandtrack. - pool
- The worker pool of a command (“Kizz never panics”).
- project
- Loading a project: discovering its
kizz.mdfiles and parsing their tasks. - render
- How explanations read: the one-line reason that
kizz buildprints for each command it runs, the full reasons of--explainandkizz why, and the loud warning for a step that re-runs in consecutive builds for the same self-inflicted reason. - report
- Observation reports (“Observation reports”): what the commands of
kizz executeorkizz runtouched, organized by process, for people and for programs. - run
- Running one task by its name, for
kizz run(“Running one task withkizz run”). - runtime
- The Starlark runtime of task programs.
- states
- The in-memory concurrent cache of file states and hashes of one build.
- step
- The boundary between task programs and the engine.
- targets
- Target names, target expressions, and task selection.
- tasks
- Task blocks in
kizz.mdfiles. - warning
- Warnings found while discovering
kizz.mdfiles and parsing their task blocks. - why
- The report of
kizz why: the reasons stored by the most recent build for the tasks under a path, with each step’s untracked/procand/sysaccesses, its connections to the network and to Unix sockets, the system calls it made that the tracer does not know, the recorded machine state of the parts it names, or of every part with--verbose, and how many accesses it ignored.