Skip to main content

mk_rs_core/
lib.rs

1#![forbid(unsafe_code)]
2
3//! plan9 mk build-tool core library.
4//!
5//! mk-core is a faithful Rust port of Andrew Hume's Plan 9 `mk`. It reads mkfiles,
6//! builds a dependency graph, resolves pattern-based metarules, and dispatches
7//! parallel recipe execution through a shell abstraction.
8//!
9//! # Pipeline
10//!
11//! Each `build()` call runs these stages in sequence, each producing an owned
12//! output consumed by the next:
13//!
14//! ```text
15//! ┌─────────────────────────────┐
16//! │   mkfile(s)                  │  user-authored text
17//! └──────────────┬──────────────┘
18//!                │
19//! ┌──────────────▼──────────────┐
20//! │  lex::Lexer                 │  char-by-char → token stream
21//! └──────────────┬──────────────┘
22//!                │  TokenStream
23//! ┌──────────────▼───────────────────────────┐
24//! │ parse::parse_with_scope(tokens, &mut    │  recursive descent → AST with
25//! │   Scope)                                 │  rule-header vars + assignment
26//! │                                          │  RHS expanded at read-time (F-045)
27//! └──────────────┬───────────────────────────┘
28//!                │  Vec<Stmt> (headers/RHS already expanded;
29//!                │     recipe bodies still literal, expanded at exec time)
30//! ┌──────────────▼───────────────────────────┐
31//! │ graph::build_graph(stmts, targets)       │  AST → DAG (metarules, transitive
32//! │                                          │  closure, pruning, cycle detection)
33//! └──────────────┬───────────────────────────┘
34//!                │  Graph
35//! ┌──────────────▼───────────────────────────┐
36//! │ graph::stale_nodes(&graph)              │  mtime staleness; virtual targets
37//! │                                          │  unconditionally stale (no file)
38//! └──────────────┬───────────────────────────┘
39//!                │  stale NodeIndex set
40//! ┌──────────────▼───────────────────────────┐
41//! │ sched::Engine                            │  parallel DAG walk, NPROC pool,
42//! │                                          │  keep-going (-k), exclusive (E)
43//! └──────────────┬───────────────────────────┘
44//!                │  Job queue
45//! ┌──────────────▼───────────────────────────┐
46//! │ recipe::run()                            │  feed recipe to shell; inject
47//! │                                          │  $target/$prereq/$stem env vars
48//! └──────────────┬───────────────────────────┘
49//!                │  exit code
50//! ┌──────────────▼───────────────────────────┐
51//! │ BuildOutcome                             │  success, partial (-k), or failure
52//! └──────────────────────────────────────────┘
53//! ```
54//!
55//! Variable expansion is split across two stages: rule headers and assignment
56//! RHS are expanded at parse-time via the threaded `Scope` (F-045); recipe
57//! bodies are kept literal and `$target`/`$prereq`/`$stem` are injected as
58//! environment variables just before shell dispatch.
59//!
60//! # Module roster
61//!
62//! | Module | Purpose |
63//! |--------|---------|
64//! | [`lex`] | Tokenizer — comment stripping, line continuation, backtick regions, quoting |
65//! | [`parse`] | Recursive-descent parser — rules, assignments, includes, attributes |
66//! | [`graph`] | DAG builder — metarule application, transitive closure, cycle/staleness checks |
67//! | [`var`] | Variable system — symbol table, `$VAR`/`${VAR}` expansion, namelists |
68//! | [`shell`] | `Shell` trait — abstraction for recipe execution (implementations in mk-shell) |
69//! | [`recipe`] | Recipe glue — env injection, attribute handling, CLI flag dispatch |
70//! | [`sched`] | Scheduler — parallel DAG traversal, NPROC worker pool, keep-going support |
71//! | [`attr`] | Attribute bitflags — `V`/`Q`/`N`/`U`/`D`/`E`/`P`/`R`/`n` |
72//! | [`mod@include`] | Recursive `< file` includes — child scopes, circular detection |
73//! | [`archive`] | `lib(member)` syntax — archive member auto-rule generation |
74//! | [`error`] | Centralized error types — `MkError`, `LexError`, `ParseError`, … |
75
76pub mod archive;
77pub mod attr;
78pub mod error;
79pub mod graph;
80pub mod include;
81pub mod lex;
82pub mod parse;
83pub mod recipe;
84pub mod sched;
85pub mod shell;
86pub mod var;