not-matthias/nix-package

Nix Package Creation & Debugging

Guide for creating custom Nix packages, debugging build failures, and integrating packages into a NixOS overlay.

When to Use This Skill

• Creating a new package in pkgs/
• Updating a package version (hash mismatch)
• Debugging eval errors or build failures
• Wrapping an AppImage or prebuilt binary
• Adding a package to the overlay

Rapid Prototyping

Before writing a full package, test dependencies or binaries in a shell:

# Enter shell with specific packages
nix-shell -p openssl pkg-config gnumake

# Test a prebuilt binary's dynamic links
nix-shell -p ldd --run "ldd ./my-binary"

Boilerplate Generation

Use nix-init to automatically generate a package from a URL or repo:

nix-shell -p nix-init --run "nix-init https://github.com/user/repo"

It handles hash generation, fetchers, and standard build inputs automatically.

Adding a New Package

Step 1: Create pkgs/<name>/default.nix (or pkgs/<name>.nix)

URL/Tarball (prebuilt binary)

{lib, stdenv, fetchurl, ...}: let
  pname = "my-app";
  version = "1.2.3";
in stdenv.mkDerivation {
  inherit pname version;
  src = fetchurl {
    url = "https://example.com/my-app-${version}.tar.gz";
    hash = "sha256-AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA=";
  };
  installPhase = ''
    mkdir -p $out/bin
    cp my-app $out/bin/
    chmod +x $out/bin/my-app
  '';
  meta = {
    description = "My application";
    homepage = "https://example.com";
    license = lib.licenses.mit;
    platforms = lib.platforms.linux;
    mainProgram = "my-app";
  };
}

AppImage

{lib, appimageTools, fetchurl}: let
  pname = "my-app";
  version = "1.2.3";
  src = fetchurl {
    url = "https://example.com/my-app-${version}.AppImage";
    hash = "sha256-AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA=";
  };
in appimageTools.wrapType2 {
  inherit pname version src;
  meta = {
    description = "My application";
    homepage = "https://example.com";
    license = lib.licenses.unfree;
    platforms = ["x86_64-linux"];
    mainProgram = pname;
  };
}

GitHub Source

{lib, stdenv, fetchFromGitHub, cmake, ...}: stdenv.mkDerivation rec {
  pname = "my-tool";
  version = "1.2.3";
  src = fetchFromGitHub {
    owner = "org";
    repo = "repo";
    rev = "v${version}";
    hash = "sha256-AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA=";
  };
  nativeBuildInputs = [cmake];
  meta = {
    description = "My tool";
    homepage = "https://github.com/org/repo";
    license = lib.licenses.mit;
    platforms = lib.platforms.linux;
  };
}

Step 2: Register in overlay (modules/overlays/pkgs.nix)

(_self: super: {
  my-app = super.callPackage ../../pkgs/my-app.nix {};
  # For subdirectory packages:
  my-app = super.callPackage ../../pkgs/my-app {};
})

Step 3: Add to host config

home.packages = with pkgs; [my-app];
# or system-wide:
environment.systemPackages = with pkgs; [my-app];

Updating Existing Packages

Before editing a package for a new version, check what changed upstream:

# For electron apps — fetch package.json from the new tag to verify:
# - electron version (may need electron_NN bump in nix)
# - dropped dependencies (e.g. sass-embedded removed → delete preBuild hook)
curl -s "https://raw.githubusercontent.com/<owner>/<repo>/refs/tags/v<version>/package.json" | jq '{electron: .devDependencies.electron}'

Changes to watch for:

• Electron version bump → update electron_NN input
• Dropped build-time deps (sass, native addons) → remove corresponding nativeBuildInputs and build hooks
• New postPatch substitutions → check if old substituteInPlace paths still exist in the new source

Getting Hashes

Start with a fake hash — Nix will tell you the real one:

hash = "sha256-AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA=";

Build fails with: hash mismatch ... got: sha256-<actual> — copy that value.

# Prefetch before writing the package
nix-prefetch-url --type sha256 <url>
# Convert hex → SRI: nix hash to-sri --type sha256 <hex>

# For GitHub
nix-prefetch-fetchFromGitHub --owner <org> --repo <repo> --rev <tag>

Debugging Build Failures

Eval errors (before build)

sudo nixos-rebuild build --flake .#framework --show-trace
# Cached failure? Force re-eval:
sudo nixos-rebuild build --flake .#framework --option eval-cache false

Common eval errors:

• attribute 'X' missing → Check overlay registration or callPackage args
• infinite recursion → Use super not self in overlay
• cannot coerce X to string → Wrong type passed to a string context

Build errors (during build)

# Build single package in isolation
# NOTE: nix build -f pkgs/<name>.nix only works for argument-free packages.
# For callPackage-style packages (with lib, stdenv, etc.) use:
nix build --impure --expr 'let pkgs = import <nixpkgs> {}; in pkgs.callPackage ./pkgs/<name>.nix {}'

# Interactive build env
nix develop .#<derivation>

Common build errors:

• Missing library → add to buildInputs
• Missing build tool → add to nativeBuildInputs
• Prebuilt binary RPATH issues:

  nativeBuildInputs = [patchelf autoPatchelfHook];
  buildInputs = [stdenv.cc.cc.lib zlib];
  

Using Unstable Packages

# In a module
{pkgs-unstable, ...}: {
  home.packages = [pkgs-unstable.some-package];
}

Checklist for New Package

• [ ] nix build -f pkgs/<name>.nix succeeds
• [ ] Overlay entry in modules/overlays/pkgs.nix
• [ ] Added to home.packages or environment.systemPackages
• [ ] sudo nixos-rebuild build --flake .#framework succeeds
• [ ] meta.mainProgram set for executables
• [ ] License set (lib.licenses.unfree for proprietary)