# Anvil

**Arduino project generator and build tool -- forges clean embedded projects.**

A single binary that scaffolds self-contained Arduino projects with hardware
abstraction, Google Mock infrastructure, and a streamlined build/upload/monitor
workflow. Works on Linux and Windows.

Generated projects are fully standalone -- they only need `arduino-cli` in
PATH. The Anvil binary is a scaffolding and diagnostic tool, not a runtime
dependency.

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

# Enter the project
cd blink

# Compile (verify only)
./build.sh

# Compile and upload to board
./upload.sh

# Compile, upload, and open serial monitor
./upload.sh --monitor

# Run host-side tests (no board needed)
./test/run_tests.sh
```

On Windows, use `build.bat`, `upload.bat`, `monitor.bat`, and
`test\run_tests.bat`.

## What Anvil Does vs. What the Project Does

| Need Anvil for                | Don't need Anvil for          |
|-------------------------------|-------------------------------|
| `anvil new` (create project)  | `./build.sh` (compile)        |
| `anvil doctor` (diagnose)     | `./upload.sh` (flash)         |
| `anvil setup` (install core)  | `./monitor.sh` (serial)       |
| `anvil devices` (port scan)   | `./test/run_tests.sh` (test)  |

Once a project is created, Anvil is optional. Students clone the repo,
plug in a board, and run `./upload.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 (convenience)       |
| `anvil upload DIR`| Upload cached build (convenience)               |
| `anvil monitor`   | Open serial monitor (convenience)               |

The `build`, `upload`, and `monitor` commands are convenience wrappers.
They do the same thing as the generated scripts.

## 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
    build.sh / build.bat            -- compile
    upload.sh / upload.bat          -- compile + flash
    monitor.sh / monitor.bat        -- serial monitor
    .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).