Updated project details
This commit is contained in:
@@ -1,163 +1,95 @@
|
||||
# Rust Nix Flake Template
|
||||
# ColdIron
|
||||
|
||||
This template provides a reproducible Rust development environment using Nix flakes and the fenix toolchain.
|
||||
ColdIron is a desktop GUI application built with [Rust](https://www.rust-lang.org/) and the [Iced](https://iced.rs/) GUI framework.
|
||||
|
||||
## Quick Start
|
||||
|
||||
### Nix Flakes (Recommended)
|
||||
|
||||
Enter the reproducible development shell with all Rust tools and Linux GUI runtime dependencies (`wayland`, `libxkbcommon`, `libGL`, `vulkan-loader`, `xorg` libraries):
|
||||
|
||||
```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
|
||||
Then run the application:
|
||||
|
||||
```sh
|
||||
nix flake init -t path:../flakes#rust
|
||||
nix develop
|
||||
cargo build
|
||||
cargo run
|
||||
```
|
||||
|
||||
## Embedded Rust Support
|
||||
### Running Tests & Quality Checks
|
||||
|
||||
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
|
||||
```sh
|
||||
# Run unit and integration tests
|
||||
cargo test
|
||||
|
||||
# Check code with clippy
|
||||
# Run linter
|
||||
cargo clippy
|
||||
|
||||
# Format code
|
||||
cargo fmt
|
||||
|
||||
# Build for embedded target
|
||||
cargo build --target thumbv7em-none-eabihf --release
|
||||
```
|
||||
|
||||
## Project Layout
|
||||
## Nix Packaging & nixpkgs Compatibility
|
||||
|
||||
```
|
||||
Cargo.toml
|
||||
Cargo.lock
|
||||
src/
|
||||
└── main.rs (or lib.rs)
|
||||
Makefile
|
||||
.envrc
|
||||
flake.nix
|
||||
`coldIron` provides an idiomatic, `nixpkgs`-compatible package expression in `package.nix` and `flake.nix`.
|
||||
|
||||
### Build with Nix
|
||||
|
||||
```sh
|
||||
nix build
|
||||
./result/bin/ColdIron
|
||||
```
|
||||
|
||||
## Legacy Usage
|
||||
Or run directly via flake:
|
||||
|
||||
If you do not use flakes, run:
|
||||
```sh
|
||||
nix run
|
||||
```
|
||||
|
||||
### Contributing to nixpkgs
|
||||
|
||||
The `package.nix` derivation is designed for direct integration into `nixpkgs` (e.g. under `pkgs/by-name/co/coldiron/package.nix`). It uses `rustPlatform.buildRustPackage`, `makeBinaryWrapper`, and wraps the executable with runtime graphics and windowing libraries (`LD_LIBRARY_PATH`).
|
||||
|
||||
## Flatpak Packaging
|
||||
|
||||
ColdIron includes Flatpak packaging configuration for containerized desktop distribution.
|
||||
|
||||
### Build Flatpak Package
|
||||
|
||||
1. Enter the dev shell (`nix develop`) which includes `flatpak` and `flatpak-builder`.
|
||||
2. Run:
|
||||
|
||||
```bash
|
||||
make flatpak-build
|
||||
```
|
||||
|
||||
This uses the manifest in `flatpak/app.flatpak.json` (Application ID: `io.github.gooba42.coldiron`) to build the application into `build-flatpak/`.
|
||||
|
||||
## Legacy Nix Shell
|
||||
|
||||
If you are not using Nix flakes, you can enter the development environment using:
|
||||
|
||||
```sh
|
||||
nix-shell
|
||||
```
|
||||
|
||||
## Project Metadata
|
||||
## Project Structure
|
||||
|
||||
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)
|
||||
```
|
||||
ColdIron/
|
||||
├── Cargo.toml # Rust package manifest
|
||||
├── Cargo.lock # Exact dependency lockfile
|
||||
├── flake.nix # Nix flake for devShell, packages, and apps
|
||||
├── package.nix # Nixpkgs-compatible buildRustPackage derivation
|
||||
├── default.nix # nix-build entrypoint calling package.nix
|
||||
├── shell.nix # Legacy nix-shell configuration
|
||||
├── flatpak/
|
||||
│ └── app.flatpak.json # Flatpak application manifest
|
||||
├── src/
|
||||
│ └── main.rs # Iced application entrypoint and UI
|
||||
└── tests/ # Integration tests
|
||||
```
|
||||
|
||||
Reference in New Issue
Block a user