Anvil v1.0.0 -- Arduino build tool with HAL and test scaffolding

Single-binary CLI that scaffolds testable Arduino projects, compiles, uploads, and monitors serial output. Templates embed a hardware abstraction layer, Google Mock infrastructure, and CMake-based host tests so application logic can be verified without hardware. Commands: new, doctor, setup, devices, build, upload, monitor 39 Rust tests (21 unit, 18 integration) Cross-platform: Linux and Windows
2026-02-15 11:16:17 -06:00
commit 3298844399
41 changed files with 4866 additions and 0 deletions
--- a/README.md
+++ b/README.md
@@ -0,0 +1,112 @@
+# Anvil
+
+**Arduino project generator and build tool -- forges clean embedded projects.**
+
+A single binary that scaffolds testable Arduino projects with hardware abstraction,
+Google Mock infrastructure, and a streamlined build/upload/monitor workflow. Works on
+Linux and Windows.
+
+Anvil is a [Nexus Workshops](https://nxlearn.net) project.
+
+## Install
+
+Download the latest release binary for your platform:
+
+```bash
+# Linux
+chmod +x anvil
+sudo mv anvil /usr/local/bin/
+
+# Windows
+# Add anvil.exe to a directory in your PATH
+```
+
+Then run first-time setup:
+
+```bash
+anvil setup
+```
+
+This checks for `arduino-cli`, installs the `arduino:avr` core, and verifies
+your system is ready.
+
+## Quick Start
+
+```bash
+# Create a new project
+anvil new blink
+
+# Check system health
+anvil doctor
+
+# Find your board
+anvil devices
+
+# Compile, upload, and open serial monitor
+cd blink
+anvil build --monitor blink
+
+# Run host-side tests (no board needed)
+cd test && ./run_tests.sh
+```
+
+## Commands
+
+| Command           | Description                                    |
+|-------------------|------------------------------------------------|
+| `anvil new NAME`  | Create a new project with HAL and test scaffold |
+| `anvil doctor`    | Check system prerequisites                      |
+| `anvil setup`     | Install arduino-cli and AVR core                |
+| `anvil devices`   | List connected boards and serial ports          |
+| `anvil build DIR` | Compile and upload a sketch                     |
+| `anvil upload DIR`| Upload cached build (no recompile)              |
+| `anvil monitor`   | Open serial monitor (`--watch` for persistent)  |
+
+## Project Architecture
+
+Every Anvil project uses a Hardware Abstraction Layer (HAL):
+
+```
+your-project/
+    your-project/your-project.ino   -- entry point
+    lib/hal/hal.h                   -- abstract interface
+    lib/hal/hal_arduino.h           -- real hardware (Arduino.h)
+    lib/app/your-project_app.h      -- app logic (testable)
+    test/mocks/mock_hal.h           -- Google Mock HAL
+    test/test_unit.cpp              -- unit tests
+    .anvil.toml                     -- project config
+```
+
+The app code depends on `Hal`, never on `Arduino.h` directly. This means
+your application logic compiles and runs on the host for testing.
+
+## Configuration
+
+Each project has an `.anvil.toml`:
+
+```toml
+[project]
+name = "blink"
+
+[build]
+fqbn = "arduino:avr:uno"
+warnings = "more"
+include_dirs = ["lib/hal", "lib/app"]
+extra_flags = ["-Werror"]
+
+[monitor]
+baud = 115200
+```
+
+## Building from Source
+
+```bash
+cargo build --release
+```
+
+The release binary is at `target/release/anvil` (Linux) or
+`target\release\anvil.exe` (Windows).
+
+## License
+
+MIT -- see [LICENSE](LICENSE).