rusty-dog/README.md

# Rusty Dog - Pico W Embedded Rust

This project is an embedded Rust application for the Raspberry Pi Pico W, utilizing the Embassy async framework.

## Build Commands

This project uses a `Makefile` to simplify common tasks. The `Makefile` is configured to automatically use `direnv` to load the Nix environment if `direnv` is installed on your system. This ensures that the correct Rust toolchain and dependencies are available even if you haven't manually run `nix develop` or `direnv allow`.

| Command | Description |
|---------|-------------|
| `make build` | Build the project using `cargo build` |
| `make run` | Run the project using `cargo run` |
| `make test` | Run tests using `cargo test` |
| `make clean` | Clean build artifacts |
| `make flatpak-build` | Build the Flatpak package |

## LLM Agent Guidelines

This project uses LLM agents for configuration and housekeeping. Please refer to [agents.md](agents.md) for the rules and guidelines governing their use.

## Quick Start

```sh
nix develop
# or with direnv:
direnv allow
```

### Automatic Environment Setup

When you enter the devShell (via `direnv allow` or `nix develop`), the following happens automatically:

✓ **Git Repository**: Initializes `.git` if not present
✓ **Rust Targets**: Automatically adds the RP2040 (Pico W) target: `thumbv6m-none-eabi`
✓ **Cargo Paths**: Sets up `$HOME/.cargo/bin` in PATH for cargo-installed binaries
✓ **Welcome Banner**: Displays available tools and quick commands

No manual setup needed! Just start coding.

## Quickstart

```sh
nix flake init -t path:../flakes#rust
nix develop
cargo build
```

## Embedded Rust Support

The devShell automatically installs the Raspberry Pi Pico W target via `rustup`:

| Target | Platform | Use Case |
|--------|----------|----------|
| `thumbv6m-none-eabi` | ARM Cortex-M0/M0+ | RP2040 (Pico W) |

## Flatpak Packaging

This template supports building Flatpak packages for your Rust application.

### Build Flatpak Package

1. Ensure you have `flatpak-builder` installed.
2. Run:

  ```bash
  make flatpak-build
  ```

This will use the manifest at `flatpak/app.flatpak.json` to build a Flatpak bundle in the `build-flatpak/` directory.

### Customize Manifest

Edit `flatpak/app.flatpak.json` to update app ID, runtime, build commands, or sources as needed for your project.

### Install/Run Flatpak Locally

You can install and run the built Flatpak locally:

```bash
flatpak install --user build-flatpak/org.example.rustdevshell.flatpak
flatpak run org.example.rustdevshell
```

## Included Tools

| Tool | Purpose |
|------|---------|
| **cargo** | Rust package manager and build system |
| **rustc** | Rust compiler |
| **clippy** | Rust linter for catching common mistakes |
| **rustfmt** | Rust code formatter |
| **rust-analyzer** | Language server for IDE integration |
| **rust-src** | Rust source code (for tools like rust-analyzer) |
| **probe-rs** | Embedded debugger/flasher |
| **openocd** | JTAG/SWD debugger |
| **minicom** | Serial terminal for device output |
| **elf2uf2-rs** | Convert ELF to UF2 format (RP2040) |
| **picotool** | Pico-specific firmware operations |
| **cargo-binutils** | LLVM tools for size and object analysis |
| **flip-link** | Stack overflow protection for embedded |
| **tea** | Gitea CLI for repository management |

## Flashing & IDE Integration

This project is configured for seamless flashing from the IDE or terminal.

### Flashing from IDE

If you are using **RustRover** or **IntelliJ Rust**, you can use the "Flash Pico W" run configuration provided in the `.run` folder. Just select it from the run menu and click "Run".

### Flashing from Terminal

You can flash the Pico W by running:

```bash
cargo run --release
```

This uses `probe-rs` (configured in `.cargo/config.toml`) to flash and run the binary via a CMSIS-DAP debugger or similar.

If you prefer to use the UF2 bootloader (dragging to the drive or using `elf2uf2-rs`), you can change the runner in `.cargo/config.toml` to:
`runner = "elf2uf2-rs -d"`

## Testing & Development Features

Build and testing tools:

- **cargo test** - Run unit and integration tests
- **cargo clippy** - Lint code for common issues
- **cargo fmt** - Format code consistently with rustfmt

**Example usage:**

```bash
# Run tests
cargo test

# Check code with clippy
cargo clippy

# Format code
cargo fmt

# Build for embedded target
cargo build --target thumbv6m-none-eabi --release

# Analyze binary size
cargo size --target thumbv6m-none-eabi --release
```

## Project Layout

```
Cargo.toml
Cargo.lock
src/
  └── main.rs (or lib.rs)
Makefile
.envrc
flake.nix
```

## Legacy Usage

If you do not use flakes, run:

```sh
nix-shell
```

## Project Metadata

See project.toml for example metadata.

## Helper Tools

- **`nix run .#dev-helper`** - Display tool versions and availability
- **`cargo build`** - Build the project
- **`cargo check`** - Quick syntax check without building
- **`cargo doc --open`** - Generate and view documentation

## Packaging for nixpkgs

This template is structured for easy packaging in nixpkgs:

- All sources in `src/`
- `flake.nix` provides a devShell and template
- Add a `default.nix` or package expression as needed for nixpkgs

See [nixpkgs Rust packaging docs](https://nixos.org/manual/nixpkgs/stable/#rust) for more details.

## Customization

Edit `flake.nix` to:

- Add additional Rust targets via `rustup target add [target]`
- Include additional cargo plugins
- Add board-specific tools (e.g., stm32cube, nrfjprog)