---
sessionId: session-260819-004513-s2vk
---

# Requirements

### Overview & Goals
Tailor `flake.nix`, development environments, and packaging configurations specifically to the `coldIron` project (a Rust + `iced` desktop GUI application). Prune obsolete template boilerplate and microcontroller/embedded targets, structure the package derivation to conform to standard `nixpkgs` packaging practices (with runtime library wrapping for `winit`/`wayland`/`x11`/`wgpu`), and retain Flatpak build capabilities with a project-tailored manifest.

### Scope
- **In Scope**:
  - Pruning generic template outputs (`templates.default`, `devHelper` binary, embedded `rustup target add` hooks) from `flake.nix`.
  - Creating a clean, idiomatic `nixpkgs`-compatible package derivation (`buildRustPackage` with `makeBinaryWrapper` and `LD_LIBRARY_PATH` wrapping) so `coldIron` can be built with `nix build` and easily contributed/published to `nixpkgs`.
  - Retaining Flatpak build capabilities by maintaining `flatpak` and `flatpak-builder` in the development environment and updating `flatpak/app.flatpak.json` to target `coldIron`.
  - Aligning `project.toml`, `shell.nix`, `default.nix`, and `README.md` with the `coldIron` project metadata.
- **Out of Scope**:
  - Modifying the application's UI logic or Rust code in `src/main.rs`.

# Technical Design

### Current Implementation
- `flake.nix` contains leftover template outputs (`templates.default`), a helper script (`devHelper` / `dev-helper`), and shell hooks attempting to install embedded targets (ARM Cortex-M, RISC-V, ESP32).
- `packages.default` builds a dummy `sample-rust-app` without wrapping required Linux GUI runtime libraries (`wayland`, `libxkbcommon`, `libGL`, `vulkan-loader`, `xorg` libraries).
- `flatpak/app.flatpak.json` references placeholder IDs (`org.example.rustdevshell`) and binary name `rustdevshell-app` instead of `ColdIron`.
- `project.toml` and `README.md` describe a generic reusable template rather than the `coldIron` application.

### Key Decisions
- **Nixpkgs Standard Package (`package.nix` / `packages.default`)**:
  - Define the package derivation using `pkgs.rustPlatform.buildRustPackage` with `nativeBuildInputs = [ pkgs.pkg-config pkgs.makeBinaryWrapper ]` and `buildInputs = runtimeLibs`.
  - Wrap the installed binary (`$out/bin/ColdIron`) with `LD_LIBRARY_PATH` prefixing `runtimeLibs` so that `nix run` or `nix build` produces a standalone binary that starts up without Wayland/X11 dynamic library errors.
  - Structure `package.nix` (or `default.nix`) as a standard `callPackage` function suitable for inclusion in `nixpkgs` (e.g. `pkgs/by-name/co/coldiron/package.nix`).
- **Streamlined devShell**:
  - Retain essential tools for Rust desktop GUI development: `rustToolchain` (fenix), `rust-analyzer`, `pkg-config`, `cargo-watch`, `cargo-edit`, `flatpak`, `flatpak-builder`, `alejandra`, and `runtimeLibs`.
  - Remove embedded microcontroller hooks (`rustup target add ...`) and embedded tools from the shell hook and tool summary.
- **Flatpak Retention & Modernization**:
  - Retain `Makefile` target `flatpak-build` and `flatpak-builder` in the devShell.
  - Update `flatpak/app.flatpak.json` to specify `app-id: "io.github.gooba42.coldiron"`, command `ColdIron`, and clean module definitions.

### File Structure Changes
- `flake.nix`: Prune template/embedded artifacts; configure `packages.default`, `apps.default`, and tailored `devShells.default`.
- `package.nix` (or `default.nix`): Standard `nixpkgs` packaging expression using `callPackage` conventions.
- `flatpak/app.flatpak.json`: Tailor manifest metadata and build command for `coldIron`.
- `project.toml` & `README.md`: Update metadata and documentation to reflect the `coldIron` project.

# Delivery Steps

### ✓ Step 1: Create standard nixpkgs-compatible package derivation in package.nix and default.nix
- Create `package.nix` as a `callPackage`-compatible function using `rustPlatform.buildRustPackage`.
- Add `pkg-config` and `makeBinaryWrapper` to `nativeBuildInputs`, and include `runtimeLibs` in `buildInputs`.
- Add `postInstall` hook using `wrapProgram` to prefix `LD_LIBRARY_PATH` with `runtimeLibs` so the GUI application can dynamically load Wayland/X11 libraries.
- Update `default.nix` to call `package.nix`.

### ✓ Step 2: Update flake.nix packaging, applications, devShell, and prune template/embedded artifacts
- Remove `templates` output and `devHelper` / `dev-helper`.
- Configure `packages.default` (and `packages.coldiron`) to use `package.nix`.
- Configure `apps.default` to run `$out/bin/ColdIron`.
- Streamline `devShells.default` by removing embedded microcontroller targets (`rustup target add`) and updating the shell banner for `coldIron`.
- Ensure Flatpak tools (`flatpak`, `flatpak-builder`) and formatting tools are present.

### ✓ Step 3: Update Flatpak manifest, project metadata, and documentation
- Update `flatpak/app.flatpak.json` with app-id `io.github.gooba42.coldiron`, command `ColdIron`, graphics/wayland/x11 permissions, and build commands.
- Update `project.toml` with `coldiron` project name and description.
- Update `README.md` to describe the `coldIron` Iced application, dev workflow, Nix build/run, and Flatpak build.

### ✓ Step 4: Verify package build, dev shell, tests, and formatting
- Verify `nix build` builds the wrapped `ColdIron` package.
- Run `cargo check` and `cargo test` to verify codebase health.
- Run `alejandra .` to ensure Nix files are formatted cleanly.