From d45322b6d1e330fe51f45d1427d131faddf69d6f Mon Sep 17 00:00:00 2001 From: Kyle J Turpin Date: Fri, 10 Jul 2026 07:22:34 -0500 Subject: [PATCH] Initial Checkin for Housekeeping --- .editorconfig | 9 +++ .envrc | 2 + .pre-commit-config.yaml | 8 ++ CONTRIBUTING.md | 9 +++ LICENSE | 17 ++++ Makefile | 19 +++++ README.md | 163 +++++++++++++++++++++++++++++++++++++++ agents.md | 16 ++++ default.nix | 29 +++++++ flake.lock | 66 ++++++++++++++++ flatpak/app.flatpak.json | 22 ++++++ project.toml | 6 ++ shell.nix | 15 ++++ src/main.rs | 3 + tests/sample_test.rs | 4 + 15 files changed, 388 insertions(+) create mode 100644 .editorconfig create mode 100644 .envrc create mode 100644 .pre-commit-config.yaml create mode 100644 CONTRIBUTING.md 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.lock 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/.envrc b/.envrc new file mode 100644 index 0000000..ea35353 --- /dev/null +++ b/.envrc @@ -0,0 +1,2 @@ +# Direnv configuration for Nix flakes +use flake \ 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/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..19a5f90 --- /dev/null +++ b/README.md @@ -0,0 +1,163 @@ +# Rust Nix Flake Template + +This template provides a reproducible Rust development environment using Nix flakes and the fenix toolchain. + +## 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..1bb9395 --- /dev/null +++ b/agents.md @@ -0,0 +1,16 @@ +# Coding Agent Instructions + +This project is intended for educational purposes. To support this, please adhere to the following guidelines: + +## Allowed Actions +- **Environment Maintenance:** Feel free to update Nix flakes, shell configurations, or other environment-related setup. +- **Project Housekeeping:** Maintain a standard project layout, keep `README.md` up-to-date, and clean up temporary or build-related files. +- **Documentation:** Add comments, manage project documentation, and add links to relevant external resources. + +## Restricted Actions +- **Source Code Editing:** You are NOT allowed to edit the executable source code (`src/` directory) except to improve documentation.. +- **Code Generation:** Do not provide example code unless explicitly asked by the user. + +## Communication Guidelines +- **Educational Focus:** When asked about code, prioritize explaining the concepts and providing advice over writing code. +- **Documentation Links:** Always include links to official language or library documentation for references. 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.lock b/flake.lock new file mode 100644 index 0000000..6361417 --- /dev/null +++ b/flake.lock @@ -0,0 +1,66 @@ +{ + "nodes": { + "fenix": { + "inputs": { + "nixpkgs": [ + "nixpkgs" + ], + "rust-analyzer-src": "rust-analyzer-src" + }, + "locked": { + "lastModified": 1783676673, + "narHash": "sha256-A4Sy9xQrO5wTaPue9JISqSuJbFU/NECHLFQm70C1ehM=", + "owner": "nix-community", + "repo": "fenix", + "rev": "9239e256596333bf1eb49068e8544786c3a853c8", + "type": "github" + }, + "original": { + "owner": "nix-community", + "repo": "fenix", + "type": "github" + } + }, + "nixpkgs": { + "locked": { + "lastModified": 1783522502, + "narHash": "sha256-iffAls3iaNTyJC2faYcUXSI+Gp02cDjYl+MygxKl2GI=", + "owner": "NixOS", + "repo": "nixpkgs", + "rev": "0bb7ec54c8483066ec9d7720e780a5caa71f8612", + "type": "github" + }, + "original": { + "owner": "NixOS", + "ref": "nixos-unstable", + "repo": "nixpkgs", + "type": "github" + } + }, + "root": { + "inputs": { + "fenix": "fenix", + "nixpkgs": "nixpkgs" + } + }, + "rust-analyzer-src": { + "flake": false, + "locked": { + "lastModified": 1783531694, + "narHash": "sha256-qnAn5Z/BhCj71mU/yWhRhapukrPYmIqu+kAsARdAHmg=", + "owner": "rust-lang", + "repo": "rust-analyzer", + "rev": "e7e17b692a073ca9820d1822626646b9cc045153", + "type": "github" + }, + "original": { + "owner": "rust-lang", + "ref": "nightly", + "repo": "rust-analyzer", + "type": "github" + } + } + }, + "root": "root", + "version": 7 +} diff --git a/flatpak/app.flatpak.json b/flatpak/app.flatpak.json new file mode 100644 index 0000000..c4e609c --- /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": ".." + } + ] + } + ] +} \ 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..e7a11a9 --- /dev/null +++ b/src/main.rs @@ -0,0 +1,3 @@ +fn main() { + println!("Hello, world!"); +} 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); +}