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 project.

Install

Download the latest release binary for your platform:

# 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:

anvil setup

This checks for arduino-cli, installs the arduino:avr core, and verifies your system is ready.

Quick Start

# 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:

[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

cargo build --release

The release binary is at target/release/anvil (Linux) or target\release\anvil.exe (Windows).

License

MIT -- see LICENSE.

3.7 KiB Raw Blame History