diff --git a/.editorconfig b/.editorconfig new file mode 100644 index 0000000..f02fd20 --- /dev/null +++ b/.editorconfig @@ -0,0 +1,9 @@ +# EditorConfig for Rust template +root = false +[*] +charset = utf-8 +end_of_line = lf +insert_final_newline = true +indent_style = space +indent_size = 2 +trim_trailing_whitespace = true diff --git a/.idea/inspectionProfiles/Project_Default.xml b/.idea/inspectionProfiles/Project_Default.xml new file mode 100644 index 0000000..9213c29 --- /dev/null +++ b/.idea/inspectionProfiles/Project_Default.xml @@ -0,0 +1,13 @@ + + + + \ No newline at end of file diff --git a/.idea/modules.xml b/.idea/modules.xml new file mode 100644 index 0000000..ebddd55 --- /dev/null +++ b/.idea/modules.xml @@ -0,0 +1,8 @@ + + + + + + + + \ No newline at end of file diff --git a/.idea/rusty_dog.iml b/.idea/rusty_dog.iml new file mode 100644 index 0000000..bbe0a70 --- /dev/null +++ b/.idea/rusty_dog.iml @@ -0,0 +1,12 @@ + + + + + + + + + + + + \ No newline at end of file diff --git a/.idea/vcs.xml b/.idea/vcs.xml new file mode 100644 index 0000000..94a25f7 --- /dev/null +++ b/.idea/vcs.xml @@ -0,0 +1,6 @@ + + + + + + \ No newline at end of file diff --git a/.pre-commit-config.yaml b/.pre-commit-config.yaml new file mode 100644 index 0000000..93d696f --- /dev/null +++ b/.pre-commit-config.yaml @@ -0,0 +1,8 @@ +repos: + - repo: https://github.com/pre-commit/pre-commit-hooks + rev: v4.4.0 + hooks: + - id: trailing-whitespace + - id: end-of-file-fixer + - id: check-yaml + - id: check-added-large-files diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md new file mode 100644 index 0000000..a94fcb9 --- /dev/null +++ b/CONTRIBUTING.md @@ -0,0 +1,9 @@ +# Contributing + +Thank you for considering contributing! + +- Please follow the project coding style and directory structure. +- Submit issues or pull requests for bugs, features, or improvements. +- Add tests for new features where possible. +- Ensure your code builds and passes tests before submitting. +- Contributions are licensed under CC BY-SA 4.0. diff --git a/Cargo.toml b/Cargo.toml new file mode 100644 index 0000000..c98b383 --- /dev/null +++ b/Cargo.toml @@ -0,0 +1,22 @@ +[package] +name = "rusty-dog" +version = "0.1.0" +edition = "2021" + +[dependencies] +embassy-executor = { version = "0.7.0", features = ["task-arena-size-32768", "arch-cortex-m", "executor-thread", "executor-interrupt"] } +embassy-time = { version = "0.4.0", features = ["generic-queue-8"] } +embassy-rp = { version = "0.3.0", features = ["defmt", "unstable-pac", "time-driver", "critical-section-impl"] } +embassy-net = { version = "0.6.0", features = ["defmt", "tcp", "udp", "dhcpv4", "medium-ethernet"] } +embassy-sync = { version = "0.6.1" } +embassy-usb = { version = "0.4.0" } +cyw43 = { version = "0.3.0", features = ["defmt", "firmware-logs"] } +cyw43-pio = { version = "0.3.0", features = ["defmt"] } + +cortex-m = "0.7.7" +cortex-m-rt = "0.7.5" +panic-probe = { version = "0.3.2", features = ["print-defmt"] } +defmt = "0.3.10" +defmt-rtt = "0.4.1" +static_cell = "2.1.0" +portable-atomic = { version = "1.11.0", features = ["critical-section"] } diff --git a/LICENSE b/LICENSE new file mode 100644 index 0000000..eae17d3 --- /dev/null +++ b/LICENSE @@ -0,0 +1,17 @@ +Creative Commons Attribution-ShareAlike 4.0 International + + + +You are free to: + +- Share — copy and redistribute the material in any medium or format +- Adapt — remix, transform, and build upon the material for any purpose, even commercially. + +Under the following terms: + +- Attribution — You must give appropriate credit, provide a link to the license, and indicate if changes were made. +- ShareAlike — If you remix, transform, or build upon the material, you must distribute your contributions under the same license as the original. + +No additional restrictions — You may not apply legal terms or technological measures that legally restrict others from doing anything the license permits. + +See the full license at the link above. diff --git a/Makefile b/Makefile new file mode 100644 index 0000000..efd5f56 --- /dev/null +++ b/Makefile @@ -0,0 +1,19 @@ +build: + cargo build + +run: + cargo run + +test: + cargo test + +clean: + cargo clean + +.PHONY: build run test clean + + +# Flatpak build target +.PHONY: flatpak-build +flatpak-build: + flatpak-builder --force-clean build-flatpak flatpak/app.flatpak.json diff --git a/README.md b/README.md new file mode 100644 index 0000000..02e68ed --- /dev/null +++ b/README.md @@ -0,0 +1,167 @@ +# Rusty Dog - Pico W Embedded Rust + +This project is an embedded Rust application for the Raspberry Pi Pico W, utilizing the Embassy async framework. + +## 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 common embedded Rust targets (ARM Cortex-M, RISC-V) +✓ **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 common embedded Rust targets via `rustup`: + +| Target | Platform | Use Case | +|--------|----------|----------| +| `thumbv6m-none-eabi` | ARM Cortex-M0/M0+ | RP2040 (Pico) | +| `thumbv7em-none-eabihf` | ARM Cortex-M4F/M7F | STM32, nRF52840 | +| `riscv32imc-unknown-none-elf` | RISC-V 32-bit | ESP32-C3 (basic) | +| `riscv32imac-unknown-none-elf` | RISC-V 32-bit (atomic) | ESP32-C3 (advanced) | + +**Note:** ESP32 Xtensa targets require espup or custom toolchains (see [esp-rs](https://github.com/esp-rs)). + +## 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 for ARM targets | +| **espflash** | Flashing tool for ESP32 boards | +| **openocd** | JTAG/SWD debugger for ARM and other targets | +| **minicom** | Serial terminal for device output | +| **elf2uf2-rs** | Convert ELF to UF2 format (RP2040) | +| **picotool** | Pico-specific firmware operations | +| **avrdude** | AVR microcontroller programmer | +| **ravedude** | Rapid AVR development utility | + +## 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 thumbv7em-none-eabihf --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) diff --git a/agents.md b/agents.md new file mode 100644 index 0000000..395f12a --- /dev/null +++ b/agents.md @@ -0,0 +1,11 @@ +# LLM Agent Guidelines + +LLM agents and autonomous programmers are subject to the following rules: + +- **Executable Code**: Do NOT modify or write executable code (e.g., `.rs` files). +- **Configuration & Housekeeping**: You ARE allowed to manage and modify: + - Nix configuration files (`flake.nix`, `default.nix`, `shell.nix`, etc.). + - Cargo configuration (`Cargo.toml`). + - Project housekeeping files (`.gitignore`, `.run/*.xml`, etc.). + - Project layout and file organization. +- **Code Assistance**: If asked for code help, do NOT provide example code. Provide explanations of how to approach the task and link to primary sources (e.g., [The Rust Programming Language](https://doc.rust-lang.org/book/)). diff --git a/default.nix b/default.nix new file mode 100644 index 0000000..9bfc4d3 --- /dev/null +++ b/default.nix @@ -0,0 +1,29 @@ +{ pkgs }: +let + lib = pkgs.lib; + templateName = builtins.baseNameOf (toString ./.); +in +{ + ${templateName} = pkgs.stdenvNoCC.mkDerivation { + pname = templateName; + version = "0.1.0"; + src = ./.; + dontBuild = true; + installPhase = '' + mkdir -p $out/share/${templateName} + if [ -d src ]; then + cp -r src $out/share/${templateName}/ + fi + for f in README.md project.toml flake.nix default.nix shell.nix Makefile .editorconfig .gitignore; do + if [ -f "$f" ]; then + cp "$f" $out/share/${templateName}/ + fi + done + ''; + meta = with lib; { + description = "Template project: ${templateName}"; + license = licenses.unfreeRedistributable; + platforms = platforms.all; + }; + }; +} diff --git a/flake.nix b/flake.nix new file mode 100644 index 0000000..583ccfd --- /dev/null +++ b/flake.nix @@ -0,0 +1,155 @@ +{ + description = "A Nix-flake-based Rust development environment"; + + inputs = { + nixpkgs.url = "github:NixOS/nixpkgs/nixos-unstable"; + fenix = { + url = "github:nix-community/fenix"; + inputs.nixpkgs.follows = "nixpkgs"; + }; + }; + + outputs = + inputs@{ self, ... }: + let + supportedSystems = [ + "x86_64-linux" + "aarch64-linux" + "x86_64-darwin" + "aarch64-darwin" + ]; + forEachSupportedSystem = + f: + inputs.nixpkgs.lib.genAttrs supportedSystems ( + system: + f { + pkgs = import inputs.nixpkgs { + inherit system; + overlays = [ + inputs.self.overlays.default + ]; + }; + } + ); + in + { + templates = { + default = { + path = ./.; + description = "Rust dev environment using fenix; includes a skeletal Cargo project and packaged helper app"; + }; + }; + + overlays.default = _final: prev: { + rustToolchain = + with inputs.fenix.packages.${prev.stdenv.hostPlatform.system}; + combine ( + with stable; + [ + clippy + rustc + cargo + rustfmt + rust-src + ] + ); + }; + + devShells = forEachSupportedSystem ( + { pkgs }: + { + default = pkgs.mkShell { + packages = with pkgs; [ + rustToolchain + git + gnumake + openssl + pkg-config + cargo-deny + cargo-edit + cargo-watch + cargo-generate + rust-analyzer + rustup + # Embedded Rust tooling + probe-rs-tools + espflash + openocd + minicom + # RP2040 UF2 workflows + elf2uf2-rs + picotool + avrdude + pkgsCross.avr.buildPackages.libc + pkgsCross.avr.buildPackages.gcc + ravedude + pre-commit + ]; + + env = { + # Required by rust-analyzer + RUST_SRC_PATH = "${pkgs.rustToolchain}/lib/rustlib/src/rust/library"; + }; + + shellHook = '' + # Initialize git repository if not already present + if [ ! -d .git ]; then + git init + echo "✓ Initialized git repository" + fi + + # Ensure user's Cargo-installed binaries are available + export PATH="$HOME/.cargo/bin:$PATH" + + if command -v rustup >/dev/null 2>&1; then + echo "Ensuring common embedded Rust targets are available (idempotent)..." + rustup target add thumbv6m-none-eabi >/dev/null 2>&1 || true # Cortex-M0/M0+ (RP2040) + rustup target add thumbv7em-none-eabihf >/dev/null 2>&1 || true # Cortex-M4F/M7F (many STM32/nRF52) + rustup target add riscv32imc-unknown-none-elf >/dev/null 2>&1 || true + rustup target add riscv32imac-unknown-none-elf >/dev/null 2>&1 || true # ESP32-C3 class + echo "Note: ESP32 Xtensa targets require espup/custom toolchains (see esp-rs)." + fi + echo "[rust-template] Welcome to the Rust dev shell!" + echo "Tools: cargo, rustc, clippy, rustfmt, rust-analyzer, probe-rs, espflash, openocd, minicom, elf2uf2-rs, picotool, avrdude, ravedude" + echo "Run 'cargo build' to build, or 'nix run .#dev-helper' for a tool summary." + echo "See README.md for usage." + ''; + }; + } + ); + + packages = forEachSupportedSystem ( + { pkgs }: + { + # Build the skeletal Cargo project + default = pkgs.rustPlatform.buildRustPackage { + pname = "rusty-dog"; + version = "0.1.0"; + src = ./.; + cargoLock.lockFile = ./Cargo.lock; + }; + + devHelper = pkgs.writeShellScriptBin "dev-helper" '' + echo "Rust toolchain available:" + command -v cargo >/dev/null 2>&1 && cargo --version || true + command -v rustc >/dev/null 2>&1 && rustc --version || true + echo "This binary is built by Nix (packages.default)." + ''; + } + ); + + apps = forEachSupportedSystem ( + { pkgs }: + { + default = { + type = "app"; + program = pkgs.lib.getExe self.packages.${pkgs.stdenv.hostPlatform.system}.default; + }; + dev-helper = { + type = "app"; + program = pkgs.lib.getExe self.packages.${pkgs.stdenv.hostPlatform.system}.devHelper; + }; + } + ); + }; +} diff --git a/flatpak/app.flatpak.json b/flatpak/app.flatpak.json new file mode 100644 index 0000000..d096fc6 --- /dev/null +++ b/flatpak/app.flatpak.json @@ -0,0 +1,22 @@ +{ + "app-id": "org.example.rustdevshell", + "runtime": "org.freedesktop.Platform", + "runtime-version": "23.08", + "sdk": "org.freedesktop.Sdk", + "command": "rustdevshell-app", + "modules": [ + { + "name": "rustdevshell-app", + "buildsystem": "simple", + "build-commands": [ + "cargo build --release" + ], + "sources": [ + { + "type": "dir", + "path": "../src" + } + ] + } + ] +} \ No newline at end of file diff --git a/project.toml b/project.toml new file mode 100644 index 0000000..47f6547 --- /dev/null +++ b/project.toml @@ -0,0 +1,6 @@ +[project] +name = "rust-template" +description = "A reusable Nix flake template for Rust development." +version = "0.1.0" +authors = ["gooba42 "] +license = "MIT" diff --git a/shell.nix b/shell.nix new file mode 100644 index 0000000..c0c1627 --- /dev/null +++ b/shell.nix @@ -0,0 +1,15 @@ +{ + pkgs ? import { }, +}: +pkgs.mkShell { + buildInputs = [ + pkgs.rustc + pkgs.cargo + pkgs.rustfmt + pkgs.clippy + pkgs.rust-analyzer + ]; + shellHook = '' + echo "[shell.nix] Legacy shell for Rust dev. Use 'nix develop' for full flake support." + ''; +} diff --git a/src/main.rs b/src/main.rs new file mode 100644 index 0000000..c1b53ae --- /dev/null +++ b/src/main.rs @@ -0,0 +1,3 @@ +fn main() { + println!("Hello from Rust skeletal app. Edit src/main.rs to get started!"); +} diff --git a/tests/sample_test.rs b/tests/sample_test.rs new file mode 100644 index 0000000..7c050df --- /dev/null +++ b/tests/sample_test.rs @@ -0,0 +1,4 @@ +#[test] +fn test_sample() { + assert_eq!(1, 1); +}