coldIron/.junie/plans/fix-iced-linux-runtime-dependencies.md

sessionId

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.