How pulp-platform/bender works
Project Type and Purpose
• This is a Rust-based command-line application (no GUI or web frontend) called bender that manages hardware-design dependencies and generates build/simulation scripts.
• Its core responsibilities are: parsing manifests (Bender.yml), resolving versions (semantic or git), checking out dependencies, collecting source files, generating tool-specific scripts via Tera templates, and managing vendored code.
File Structure
• Top-level Rust project files: Cargo.toml, src/, tests/, .github/, various licenses.
• src/main.rs and src/cli.rs: entry point and argument parsing.
• src/cmd/…: subcommands (checkout, update, sources, script, vendor, etc.).
• Core modules: config.rs (configuration loading/merging), resolver.rs (dependency resolution), git.rs (git wrapper), lockfile.rs (lock-file read/write), src.rs (source collection), sess.rs (interactive session), target.rs (target expression logic), util.rs, error.rs.
• Template files under src/script_fmt/*.tera power the script generation commands.
• Tests in tests/ invoke the CLI in shell scripts to validate behavior.
a. CLI Frontend
• Parses command and flags (Clap or StructOpt in cli.rs).
• Dispatches to a Command Handler (one per subcommand in src/cmd/).
b. Configuration Service
• Reads/merges Bender.yml, Bender.local, user config files.
• Exposes a unified config object.
c. Resolver Service
• Reads manifest dependencies.
• Computes version constraints and resolves to exact git revisions or paths.
d. Git Service
• Invokes git (or wrapper) to clone, checkout, update repositories.
e. Lockfile Manager
• Reads existing Bender.lock, writes updated lock entries.
f. Source Collector
• Processes sources tree: groups, includes, defines, glob patterns.
• Applies target filters (all(...), any(...), etc.).
g. Template Renderer
• Loads *.tera templates.
• Renders tool-specific scripts or file lists.
h. Vendor Manager
• Handles vendor_package entries: clones upstream, applies patches, diff/patch commands.
i. Session / Interactive Layer
• Manages prompts (e.g. plugin prompts, patch messages) in sess.rs.
j. Tests Harness
• Shell scripts that call the binary and verify exit codes or outputs.
Relationships and Data Flow
• User invokes bender <command> → CLI Frontend → appropriate Command Handler.
• Command Handler requests configuration from Configuration Service.
• For dependency-related commands (update, checkout, clone, packages, parents):
• Resolver Service uses Config + existing Lockfile → computes desired state.
• Lockfile Manager updates Bender.lock.
• Git Service synchronizes working copies.
• For source commands (sources, script, fusesoc):
• After checkout, Source Collector assembles file graph.
• Template Renderer emits scripts or JSON to stdout.
• Vendor Manager is invoked for vendor subcommands, coordinated by its Command Handler.
• Errors propagate via error.rs; session prompts via sess.rs; utilities in util.rs.
Architectural Patterns / Design Principles
• Separation of Concerns: each service/module focuses on one responsibility (config, resolve, git, source, rendering).
• Modular CLI Commands: each subcommand implemented in its own file under src/cmd/.
• Plugin-style Templates: Tera templates decoupled from core logic.
• Immutable Lockfile: ensures reproducible builds.
• Expression Tree for target filtering.
Technologies and Frameworks
• Programming language: Rust (Cargo build, crates like tera, possibly clap).
• Templating: Tera (src/script_fmt/*.tera).
• Git integration: shelling out to git via git.rs.
• Shell scripting for tests (tests/*.sh).
• Continuous integration: GitHub Actions (.github/workflows/ci.yml).