Skip to main content

Crate mk_rs_core

Crate mk_rs_core 

Source
Expand description

plan9 mk build-tool core library.

mk-core is a faithful Rust port of Andrew Hume’s Plan 9 mk. It reads mkfiles, builds a dependency graph, resolves pattern-based metarules, and dispatches parallel recipe execution through a shell abstraction.

§Pipeline

Each build() call runs these stages in sequence, each producing an owned output consumed by the next:

┌─────────────────────────────┐
│   mkfile(s)                  │  user-authored text
└──────────────┬──────────────┘
               │
┌──────────────▼──────────────┐
│  lex::Lexer                 │  char-by-char → token stream
└──────────────┬──────────────┘
               │  TokenStream
┌──────────────▼───────────────────────────┐
│ parse::parse_with_scope(tokens, &mut    │  recursive descent → AST with
│   Scope)                                 │  rule-header vars + assignment
│                                          │  RHS expanded at read-time (F-045)
└──────────────┬───────────────────────────┘
               │  Vec<Stmt> (headers/RHS already expanded;
               │     recipe bodies still literal, expanded at exec time)
┌──────────────▼───────────────────────────┐
│ graph::build_graph(stmts, targets)       │  AST → DAG (metarules, transitive
│                                          │  closure, pruning, cycle detection)
└──────────────┬───────────────────────────┘
               │  Graph
┌──────────────▼───────────────────────────┐
│ graph::stale_nodes(&graph)              │  mtime staleness; virtual targets
│                                          │  unconditionally stale (no file)
└──────────────┬───────────────────────────┘
               │  stale NodeIndex set
┌──────────────▼───────────────────────────┐
│ sched::Engine                            │  parallel DAG walk, NPROC pool,
│                                          │  keep-going (-k), exclusive (E)
└──────────────┬───────────────────────────┘
               │  Job queue
┌──────────────▼───────────────────────────┐
│ recipe::run()                            │  feed recipe to shell; inject
│                                          │  $target/$prereq/$stem env vars
└──────────────┬───────────────────────────┘
               │  exit code
┌──────────────▼───────────────────────────┐
│ BuildOutcome                             │  success, partial (-k), or failure
└──────────────────────────────────────────┘

Variable expansion is split across two stages: rule headers and assignment RHS are expanded at parse-time via the threaded Scope (F-045); recipe bodies are kept literal and $target/$prereq/$stem are injected as environment variables just before shell dispatch.

§Module roster

ModulePurpose
lexTokenizer — comment stripping, line continuation, backtick regions, quoting
parseRecursive-descent parser — rules, assignments, includes, attributes
graphDAG builder — metarule application, transitive closure, cycle/staleness checks
varVariable system — symbol table, $VAR/${VAR} expansion, namelists
shellShell trait — abstraction for recipe execution (implementations in mk-shell)
recipeRecipe glue — env injection, attribute handling, CLI flag dispatch
schedScheduler — parallel DAG traversal, NPROC worker pool, keep-going support
attrAttribute bitflags — V/Q/N/U/D/E/P/R/n
includeRecursive < file includes — child scopes, circular detection
archivelib(member) syntax — archive member auto-rule generation
errorCentralized error types — MkError, LexError, ParseError, …

Modules§

archive
Archive member syntax: lib.a(member.o).
attr
Rule attribute system.
error
Centralized error types for mk-core.
graph
DAG builder, cycle detector, and staleness checker.
include
Recursive mkfile include system.
lex
Tokenizer for Plan 9 mk mkfile syntax.
parse
Parser for mkfile syntax.
recipe
Recipe execution glue: elision, printing, shell dispatch.
sched
Build scheduler — orchestrates DAG traversal and recipe execution.
shell
Shell abstraction for recipe execution.
var
Variable system for mk-core: symbol table with precedence, parent-chain lookup for nested includes, and $VAR / ${VAR} / $$ expansion.