From b5977d64ed915648958db295dbb7ed51f4e09ef5 Mon Sep 17 00:00:00 2001 From: Kyle J Turpin Date: Thu, 4 Jun 2026 13:42:31 -0500 Subject: [PATCH] Add .gitignore entries for IDE and project-specific files --- .editorconfig | 9 + .idea/inspectionProfiles/Project_Default.xml | 13 ++ .idea/modules.xml | 8 + .idea/rusty_dog.iml | 12 ++ .idea/vcs.xml | 6 + .pre-commit-config.yaml | 8 + CONTRIBUTING.md | 9 + Cargo.toml | 22 +++ LICENSE | 17 ++ Makefile | 19 +++ README.md | 167 +++++++++++++++++++ agents.md | 11 ++ default.nix | 29 ++++ flake.nix | 155 +++++++++++++++++ flatpak/app.flatpak.json | 22 +++ project.toml | 6 + shell.nix | 15 ++ src/main.rs | 3 + tests/sample_test.rs | 4 + 19 files changed, 535 insertions(+) create mode 100644 .editorconfig create mode 100644 .idea/inspectionProfiles/Project_Default.xml create mode 100644 .idea/modules.xml create mode 100644 .idea/rusty_dog.iml create mode 100644 .idea/vcs.xml create mode 100644 .pre-commit-config.yaml create mode 100644 CONTRIBUTING.md create mode 100644 Cargo.toml create mode 100644 LICENSE create mode 100644 Makefile create mode 100644 README.md create mode 100644 agents.md create mode 100644 default.nix create mode 100644 flake.nix create mode 100644 flatpak/app.flatpak.json create mode 100644 project.toml create mode 100644 shell.nix create mode 100644 src/main.rs create mode 100644 tests/sample_test.rs 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); +}