nix-packaging-best-practices_skill

Overview

This skill documents practical best practices for packaging pre-compiled binary distributions (.deb, .rpm, .tar.gz, .zip, AppImage) for NixOS. It focuses on reproducible extraction, correct dependency mapping, and fixing "library not found" errors with autoPatchelf and wrappers. The guidance emphasizes sourcing original archives and avoiding fragile local workarounds.

How this skill works

The skill explains a core Nix derivation pattern: point src at the original archive, use nativeBuildInputs to supply extraction and patching tools (dpkg, rpm2cpio, unzip, autoPatchelfHook), and run unpack/install phases to place files into $out. It teaches how to discover missing libraries with ldd, map missing .so files to nixpkgs packages, and add runtime libraries to buildInputs or use makeWrapper for runtime environment fixes.

When to use it

• Converting binary distributions (deb, rpm, tar.gz, zip) to Nix derivations
• Packaging proprietary or closed-source software distributed only as binaries
• Fixing GUI/Electron apps that fail with "library not found" errors
• When a user supplies a binary archive rather than source code
• Needing reproducible extraction and library path fixes during builds

Best practices

• Always source from the original archive (src = ./package-${version}.tar.gz or fetchurl), never use a pre-extracted directory
• Add autoPatchelfHook to nativeBuildInputs to fix RPATH and interpreter issues automatically
• Use dpkg/rpm2cpio/unzip in nativeBuildInputs for correct archive extraction inside the build sandbox
• Find true dependencies with ldd on the built binary; map each missing .so to the correct nix package
• Prefer explicit buildInputs for runtime libs (gtk3, glib, libpulseaudio, mesa) instead of guessing
• Avoid absolute paths and ad-hoc local fixes that break reproducibility

Example use cases

• Packaging a .deb distributed GUI app: use ar/tar extraction, add autoPatchelfHook, copy opt/AppName to $out
• Converting an .rpm: use rpm2cpio | cpio -idmv and add rpm/cpio to nativeBuildInputs
• Troubleshooting an Electron app: add electron-specific dependency mappings and consult ldd output for missing libs
• Testing a patched binary quickly with nix-shell -p steam-run and steam-run ./binary
• Debugging autoPatchelf by inspecting build logs with nix log on the derivation