Skip to content

ekala-project/corepkgs / .agents/skills/packaging

packaging

Verified

corepkgs packaging conventions. Use when writing or reviewing any pkgs/<name>/default.nix — covers package organization (auto-registration, top-level.nix, alternative implementations), the finalAttrs pattern, meta attributes, where each kind of dependency belongs, fetchers, patching, install phases, multiple outputs, and passthru.

Packaging Conventions

Package Organization

Packages in pkgs/ and pkgs-many/ are automatically added to the pkgs.* scope based on their directory name. No explicit entry in top-level.nix is needed.

When to add an explicit top-level.nix entry:

  • Only when inputs deviate from those declared in the nix expression
  • Or when overriding default arguments / providing additional configuration
# top-level.nix — only if inputs deviate
libxslt = callPackage ./pkgs/libxslt {
  pythonSupport = false;
  cryptoSupport = true;
};

Alternative Implementations

Keep alternative implementations in the same package directory using multiple files: default.nix (short selector), generic.nix (usual implementation), darwin.nix (Apple's implementation).

Keep selection logic inside the package folder using ordinary if expressions and callPackage, forwarding explicit overrides. Avoid separate apple-<package> entries.

Expose libpcap.apple when callers need to choose an implementation. Preserve .override and .overrideAttrs on each implementation. For pkgs-many/ families, dispatch to separate implementation files from generic.nix. Use short variant names (real, darwin, v3_3); don't repeat the package name in package-local aliases.

Rules

  • Never set meta.maintainers or meta.teams — neither is a recognised meta key; setting one fails check-meta. Simply omit them.
  • __structuredAttrs = true is the default — never set it explicitly. If phases break, fix them instead of disabling. See structured-attrs.
  • doCheck = false and doInstallCheck = false are defaults — don't set them explicitly. Use passthru.tests for test coverage.

Package Structure

Use finalAttrs pattern for self-referencing:

stdenv.mkDerivation (finalAttrs: {
  pname = "example";
  version = "1.0.0";

  src = fetchFromGitHub {
    owner = "example";
    repo = "example";
    tag = "v${finalAttrs.version}";
    hash = "sha256-...";
  };

  passthru.tests = {
    unittests = runUnitTests finalAttrs.finalPackage;
  };
})

Meta Attributes

Required fields:

meta = {
  description = "Brief description";
  license = lib.licenses.mit;
  platforms = lib.platforms.linux;
};

Common licenses:

license = lib.licenses.mit;
license = lib.licenses.gpl3Plus;
license = with lib.licenses; [ gpl2Plus lgpl21Plus ];

Platform options:

platforms = lib.platforms.linux;    # Linux only
platforms = lib.platforms.unix;     # Unix-like
platforms = lib.platforms.darwin;   # macOS only
platforms = lib.platforms.all;      # All platforms

Testing

Goal: Keep builds as fast as possible by disabling in-build tests. Use passthru.tests to preserve test coverage without slowing every build.

Defaults

doCheck = false; and doInstallCheck = false; are the defaults across all build systems (stdenv.mkDerivation, buildPythonPackage, buildRustPackage, buildGoModule, buildPerlPackage). Don't set them explicitly.

Auto-Generated passthru.tests.build

buildRustPackage and buildGoModule automatically provide passthru.tests.build — a variant that re-runs the build with doCheck = true. User-supplied passthru.tests entries are merged alongside, not replaced.

For stdenv.mkDerivation packages, add passthru.tests manually:

passthru.tests = {
  withChecks = finalAttrs.finalPackage.overrideAttrs { doCheck = true; };
};

Python: testPaths (Preferred)

Set testPaths to auto-generate passthru.tests.python and a test_src output:

nativeCheckInputs = [ pytestCheckHook ];
testPaths = [ "tests" ];

The test_src output bundles the listed paths plus config files (conftest.py, pyproject.toml, etc.). A standalone test derivation runs the suite against the installed package.

For suites that need extra files (helper modules, fixture data):

testPaths = [ "tests" "src/helpers" "README.rst" ];

Test configuration attributes are forwarded automatically:

  • disabledTests, disabledTestPaths, enabledTestPaths
  • pytestFlags, pytestFlagsArray, unittestFlagsArray
  • preCheck, postCheck, preInstallCheck, postInstallCheck

Python: Manual tests.nix (Fallback)

When testPaths is not suitable (e.g., circular dependencies with pytest), create a separate tests.nix:

# default.nix
passthru.tests = {
  pytest = callPackage ./tests.nix { };
};

Acceptable In-Build Checks

doInstallCheck = true; is acceptable for:

  • versionCheckHook — verifies the built binary runs and prints expected version
  • pythonImportsCheck — runs automatically in buildPythonPackage, no need to enable explicitly

Dependencies

nativeBuildInputs = [    # Build tools (build platform)
  pkg-config
  cmake
];

buildInputs = [          # Libraries (host platform)
  zlib
  openssl
];

checkInputs = [          # Test dependencies
  pytest
];

propagatedBuildInputs = [ # Runtime deps for dependents
  python3
];

Cross-compilation:

strictDeps = true;

depsBuildBuild = [ pkg-config ];    # Build -> build tools
nativeBuildInputs = [ cmake ];      # Build -> host tools
buildInputs = [ zlib ];             # Host libraries

Fetching Sources

GitHub:

src = fetchFromGitHub {
  owner = "example";
  repo = "example";
  tag = "v${finalAttrs.version}";
  hash = "sha256-...";
};

GitLab:

src = fetchFromGitLab {
  domain = "gitlab.com";
  owner = "example";
  repo = "example";
  tag = finalAttrs.version;
  hash = "sha256-...";
};

Tarball:

src = fetchurl {
  url = "https://example.com/releases/example-${finalAttrs.version}.tar.gz";
  hash = "sha256-...";
};

Patching

Substitutions:

postPatch = ''
  substituteInPlace Makefile \
    --replace '/usr/local' "$out" \
    --replace 'python' '${python3}/bin/python3'
'';

Patch files:

patches = [
  ./fix-build.patch
  (fetchpatch {
    url = "https://github.com/example/example/commit/abc123.patch";
    hash = "sha256-...";
  })
];

Install Phase

installPhase = ''
  runHook preInstall

  mkdir -p $out/bin
  cp example $out/bin/

  runHook postInstall
'';

Post-install fixups:

postInstall = ''
  wrapProgram $out/bin/example \
    --prefix PATH : ${lib.makeBinPath [ coreutils ]}
'';

Multiple Outputs

outputs = [ "out" "dev" "doc" ];

postInstall = ''
  moveToOutput include $dev
  moveToOutput share/doc $doc
'';

Passthru

passthru = {
  tests = {
    unittests = runUnitTests finalAttrs.finalPackage;
  };

  plugins = {
    foo = callPackage ./plugins/foo.nix { };
  };
};

Automated Updates (ekapkgs-update)

The ekapkgs-update tool discovers new upstream versions and updates package files automatically. It reads passthru.ekapkgs-update attributes to control its behavior.

When no configuration is needed: packages using fetchFromGitHub, fetchFromGitLab, fetchFromSourcehut, or fetchurl from PyPI/GNU mirrors/SourceForge are auto-detected. No passthru is required.

When to add ekapkgs-update passthru:

SituationWhat to set
Non-standard tag format (e.g., go1.25.1)version-regex = "^go(.+)$";
Source URL not auto-detected (e.g., fetchurl from custom host)github-repo = "owner/repo";
Custom release listing (no GitHub/GitLab/PyPI)update-script = writeScript "list-versions" ''...'';
Component that inherits version from parentskip = true;
pkgs-many variant — pin to patch releasessemver-strategy = "patch";

Basic configuration

passthru.ekapkgs-update = {
  semver-strategy = "patch";  # "latest", "major", "minor", or "patch"
};

Explicit upstream repo

For packages where src.url can't be auto-detected (e.g., fetchurl from a custom host):

passthru.ekapkgs-update = {
  github-repo = "golang/go";
  version-regex = "^go(.+)$";
};

Custom version-listing script

For packages hosted outside GitHub/GitLab/PyPI where no auto-detection works, provide a script that prints available versions to stdout (one per line). ekapkgs-update handles the rest — semver filtering, hash updates, patch recovery, commits:

passthru.ekapkgs-update = {
  update-script = writeScript "list-cmake-releases" ''
    ${curl}/bin/curl -s https://cmake.org/files/ \
      | ${pcregrep}/bin/pcregrep -o1 'v([0-9]+\.[0-9]+\.[0-9]+)/' \
      | sort -u
  '';
  semver-strategy = "patch";
};

The script only lists versions — it must not modify any files.

Porting from nixpkgs

Remove:

  • updateScript from passthru (ekapkgs-update discovers versions natively via src.url parsing; add passthru.ekapkgs-update hints only when auto-detection fails — see above)
  • Maintainers list (set to [ ])
  • nixpkgs-specific test infrastructure

Add TODO for missing deps:

buildInputs = [
  zlib
  # TODO(corepkgs): Port openssl for TLS support
];

Complete Example

{
  lib,
  stdenv,
  fetchFromGitHub,
  cmake,
  pkg-config,
  zlib,
}:

stdenv.mkDerivation (finalAttrs: {
  pname = "example";
  version = "2.1.0";

  src = fetchFromGitHub {
    owner = "example-org";
    repo = "example";
    tag = "v${finalAttrs.version}";
    hash = "sha256-...";
  };

  nativeBuildInputs = [
    cmake
    cmake.configurePhaseHook
    pkg-config
  ];

  buildInputs = [ zlib ];

  strictDeps = true;
  cmakeBuildType = "Release";

  passthru.tests = {
    unittests = runUnitTests finalAttrs.finalPackage;
  };

  meta = {
    description = "Example library";
    homepage = "https://github.com/example-org/example";
    license = lib.licenses.mit;
    platforms = lib.platforms.unix;
  };
})
receiving-code-reviewobra/superpowersUse when receiving code review feedback, before implementing suggestions, especially if feedback seems unclear or technically questionable - requires technical rigor and verification, not performative agreement or blind implementationStars: 319kUpdated Claude CodeCodexVerifiedInstall
requesting-code-reviewobra/superpowersUse when completing tasks, implementing major features, or before merging to verify work meets requirementsStars: 319kUpdated Claude CodeCodexVerifiedInstall
using-git-worktreesobra/superpowersUse when starting feature work that needs isolation from current workspace or before executing implementation plans - ensures an isolated workspace exists via native tools or git worktree fallbackStars: 319kUpdated Claude CodeCodexVerifiedInstall
verification-before-completionobra/superpowersUse when about to claim work is complete, fixed, or passing, before committing or creating PRs - requires running verification commands and confirming output before making any success claims; evidence before assertions alwaysStars: 319kUpdated Claude CodeCodexVerifiedInstall