Skip to main content

Crate kizz_core

Crate kizz_core 

Source
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: every kizz.md under the current directory, in the default order.
  • tasks: the task blocks of a kizz.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 the env and fs functions.
  • dotenv: the dotenv files that env.load_file and env.read read.
  • files: the file operations behind the fs functions, which record every access and every file a write changed.
  • step: the step specification that run() 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 the PATH of a task environment or of the caller of kizz execute.
  • patterns: the path patterns of ignore and track.
  • 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 of kizz 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 for kizz 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 for kizz run, once, with its arguments, the nearest task of the name winning, and the observation report of kizz run --output.
  • cleanup: the entries kizz cache clean removes because their files are gone, and the entries kizz cache reset wipes for the tasks under a path.
  • pool: the worker pool that runs a command’s parallel work, whose threads start through kizz_threads, so rayon’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::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 clean removes because the files they are about are gone, and the entries kizz cache reset wipes for the tasks under a path.
discovery
Discovery of kizz.md files.
dotenv
The dotenv files that env.load_file and env.read read.
engine
The engine side of the step executor.
execute
Running one command for kizz execute (“Observing any command with kizz 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 fs functions and the dotenv reads of env.load_file and env.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 ignore and track.
pool
The worker pool of a command (“Kizz never panics”).
project
Loading a project: discovering its kizz.md files and parsing their tasks.
render
How explanations read: the one-line reason that kizz build prints for each command it runs, the full reasons of --explain and kizz 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 execute or kizz run touched, organized by process, for people and for programs.
run
Running one task by its name, for kizz run (“Running one task with kizz 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.md files.
warning
Warnings found while discovering kizz.md files 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 /proc and /sys accesses, 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.