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.

FileKindSize
SKILL.mdskill md10.0 KB
---
name: packaging
description: 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

```nix
# 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](../structured-attrs/SKILL.md).
- **`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:

```nix
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:**
```nix
meta = {
  description = "Brief description";
  license = lib.licenses.mit;
  platforms = lib.platforms.linux;
};
```

**Common licenses:**
```nix
license = lib.licenses.mit;
license = lib.licenses.gpl3Plus;
license = with lib.licenses; [ gpl2Plus lgpl21Plus ];
```

**Platform options:**
```nix
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:

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

### Python: `testPaths` (Preferred)

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

```nix
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):
```nix
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`:

```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

```nix
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:**
```nix
strictDeps = true;

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

## Fetching Sources

**GitHub:**
```nix
src = fetchFromGitHub {
  owner = "example";
  repo = "example";
  tag = "v${finalAttrs.version}";
  hash = "sha256-...";
};
```

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

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

## Patching

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

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

## Install Phase

```nix
installPhase = ''
  runHook preInstall

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

  runHook postInstall
'';
```

**Post-install fixups:**
```nix
postInstall = ''
  wrapProgram $out/bin/example \
    --prefix PATH : ${lib.makeBinPath [ coreutils ]}
'';
```

## Multiple Outputs

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

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

## Passthru

```nix
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:**

| Situation | What 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 parent | `skip = true;` |
| pkgs-many variant — pin to patch releases | `semver-strategy = "patch";` |

### Basic configuration

```nix
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):

```nix
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:

```nix
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:**
```nix
buildInputs = [
  zlib
  # TODO(corepkgs): Port openssl for TLS support
];
```

## Complete Example

```nix
{
  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: 322kUpdated Claude CodeCodexVerifiedInstall
requesting-code-reviewobra/superpowersUse when completing tasks, implementing major features, or before merging to verify work meets requirementsStars: 322kUpdated 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: 322kUpdated 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: 322kUpdated Claude CodeCodexVerifiedInstall