Nix Package Creator

Real Examples in This Repo

Before writing a derivation, read existing packages for battle-tested patterns:

AppImage Packages

Pre-Packaging Inspection (CRITICAL)

ALWAYS inspect AppImage contents before finalizing the derivation:

1. Write initial derivation with lib.fakeHash → build → get correct hash → update
2. Build again — if file path errors, inspect the extracted store path:

ls /nix/store/*-<pname>-<version>-extracted/
find /nix/store/*-<pname>-<version>-extracted/ -name "*.desktop"
find /nix/store/*-<pname>-<version>-extracted/ -name "*.png" -o -name "*.svg"
cat /nix/store/*-<pname>-<version>-extracted/*.desktop

Gotchas:

• Desktop files are often Capitalized (Quounter.desktop not quounter.desktop)
• Tauri apps use Exec=appname (lowercase) — skip substituteInPlace for AppRun replacement
• Icons may exist at root AND in usr/share/icons/ — prefer the usr/share/icons/ tree

Template

For multi-arch releases, use an srcs attrset keyed by pkgs.system. For single-arch, simplify to a direct fetchurl:

{
  pkgs,
  lib,
}:
let
  pname = "app-name";
  version = "1.0.0";

  # Multi-arch: use srcs attrset (see packages/helium.nix)
  # srcs = {
  #   x86_64-linux = { url = "..."; sha256 = lib.fakeHash; };
  #   aarch64-linux = { url = "..."; sha256 = lib.fakeHash; };
  # };
  # srcInfo = srcs.${pkgs.system} or (throw "Unsupported system: ${pkgs.system}");
  # src = pkgs.fetchurl { inherit (srcInfo) url sha256; };

  # Single-arch: direct fetchurl (see packages/quounter.nix)
  src = pkgs.fetchurl {
    url = "https://example.com/App_${version}_amd64.AppImage";
    sha256 = lib.fakeHash;
    name = "${pname}-${version}.AppImage";
  };

  appimageContents = pkgs.appimageTools.extract { inherit pname version src; };
in
pkgs.appimageTools.wrapType2 {
  inherit pname version src;

  extraPkgs = pkgs: [ ];

  extraInstallCommands = ''
    # Desktop file name is often Capitalized — inspect extracted contents first!
    install -Dm644 ${appimageContents}/AppName.desktop \
      $out/share/applications/${pname}.desktop

    # Only if desktop file has Exec=AppRun (NOT needed for Tauri apps):
    # substituteInPlace $out/share/applications/${pname}.desktop \
    #   --replace-fail "Exec=AppRun" "Exec=${pname}"

    cp -r ${appimageContents}/usr/share/icons $out/share/icons
  '';

  meta = {
    description = "Short description";
    homepage = "https://example.com";
    license = lib.licenses.mit;
    platforms = [ "x86_64-linux" ];
    mainProgram = pname;
    sourceProvenance = [ lib.sourceTypes.binaryNativeCode ];
  };
}

Tauri Applications

• Desktop file: AppName.desktop (capitalized, matches Tauri app name)
• Exec= is already set to lowercase binary name — no AppRun fix needed
• Icons in usr/share/icons/hicolor/ with all standard sizes
• Use AppImage path — do NOT try to build from source (Tauri toolchain is complex in Nix sandbox)
• .deb also available but AppImage is simpler to package

Registering Packages

Add to flake-parts/packages.nix:

packages = {
  # Cross-platform
  my-package = import ../packages/my-package.nix { inherit pkgs; lib = pkgs.lib; };
}
// lib.optionalAttrs pkgs.stdenv.hostPlatform.isLinux {
  linux-pkg = import ../packages/linux-pkg.nix { inherit pkgs; lib = pkgs.lib; };
}
// lib.optionalAttrs pkgs.stdenv.hostPlatform.isDarwin {
  darwin-pkg = import ../packages/darwin-pkg.nix { inherit pkgs; lib = pkgs.lib; };
};

Getting Hashes

1. Use lib.fakeHash initially in all hash fields
2. Run nix build .#package-name — Nix fails with the correct hash
3. Replace lib.fakeHash with the provided hash, rebuild
4. For fetchFromGitHub: nix-prefetch-github owner repo --rev v1.0.0
5. For npm deps: build will fail and provide correct npmDepsHash

Repo requirement: Track new files before building:

jj file track packages/new-package.nix

Common Patterns

makeWrapper

nativeBuildInputs = [ pkgs.makeWrapper ];
postInstall = ''
  wrapProgram $out/bin/app \
    --prefix PATH : ${lib.makeBinPath [ pkgs.git pkgs.curl ]} \
    --set ENV_VAR "value"
'';

autoPatchelfHook (binary dependencies)

nativeBuildInputs = [ pkgs.autoPatchelfHook ];
buildInputs = [ pkgs.stdenv.cc.cc.lib ];

substituteInPlace (file patching)

postPatch = ''
  substituteInPlace src/config.py \
    --replace-fail "/usr/bin/git" "${pkgs.git}/bin/git"
'';

Troubleshooting

Additional Templates

• Deb packages: See references/deb.md
• Node.js (npm, yarn, pnpm, Electron, native deps): See references/nodejs.md
• Source builds (stdenv, Python, Go, Rust): See references/source-builds.md