ekala-project/corepkgs / .agents/skills/packaging
packaging
Verifiedcorepkgs 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.
| File | Kind | Size |
|---|---|---|
| SKILL.md | skill md | 10.0 KB |
SKILL.md
View on GitHub---
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;
};
})
```
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| 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 implementation | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| requesting-code-reviewobra/superpowersUse when completing tasks, implementing major features, or before merging to verify work meets requirements | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| 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 fallback | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| 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 always | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |