Skip to content

Packaging builders

Dense map: ecosystem → Nixpkgs builder → FOD / hash knobs → wiki leaf. Prefer language builders over bare stdenv.mkDerivation. Canonical API: Languages and frameworks. Stay inside one package set scope. Cross: keep tools in nativeBuildInputs and libraries in buildInputs — Cross compilation.

Builders and FOD knobs

Ecosystem Builder / entry Hash / FOD knobs Deep leaf
Generic / Autotools stdenv.mkDerivation src via fetchurl / fetchFromGitHub / … (hash) Simple package · Fetchers
Python buildPythonPackage, buildPythonApplication; env: python.withPackages src hash; deps from same python3Packages Python / Node / Rust / Go
Go buildGoModule (versioned buildGo*Module when needed) vendorHash (null if committed vendor/); src hash Python / Node / Rust / Go
Rust rustPlatform.buildRustPackage cargoHash or cargoLock (lockFile / …); src hash Python / Node / Rust / Go
Node / npm buildNpmPackage; or npmHooks + stdenv npmDepsHash; src hash Python / Node / Rust / Go
Haskell haskellPackages.mkDerivation / callPackage Set pins one version per name (no Cabal solver); jailbreak / doJailbreak for bounds Haskell packaging
Gradle / Java Gradle setup hook + mitmCache; Ant + jdk / javaPackages mitmCache = gradle.fetchDeps { data = ./deps.json; … }; refresh via updateScript JVM / PHP and others
PHP / Composer php.buildComposerProject2 vendorHash; optional composerLock if lock missing from src JVM / PHP and others
Perl buildPerlPackage in perlPackages src hash (often mirror://cpan/); siblings from same set JVM / PHP and others

FOD loop: placeholder / fake hash → build → copy reported SRI hash. Changing URL/rev without resetting the hash can serve stale store content — Fetchers and pinning.

Shell vs package

Goal Reach for Not a substitute for
Reproducible package / CI Language builder above Host pip / cargo / npm / go alone
Day-to-day edit mkShell + compilers from nixpkgs Packaging FODs and install layout

Map of shell tools vs builders: Language toolchains. Nested sets (python3Packages, haskellPackages, …): Package sets.

Failure callouts

Symptom / mistake Fix
hash mismatch in fixed-output derivation (src / vendor / npm / cargo) Reset the FOD hash after URL/rev/lock changes; copy the reported SRI — Fetchers and pinning
Haskell Cabal version-bound / dependency check fails Set pins one version; jailbreak / doJailbreak lifts bounds only (still no solver) — Haskell packaging
Gradle deps / mitmCache fail; PHP vendorHash mismatch Refresh deps.json via mitmCache.updateScript, or re-pin Composer vendorHash / lock — JVM / PHP and others
Works native, breaks under cross Tools in nativeBuildInputs, libraries in buildInputs; try strictDeps — Cross compilation
Mixing package-set scopes (wrong Python/GHC/…) Depend on siblings from the same set — Package sets

See also

References