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.
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.maintainersormeta.teams— neither is a recognisedmetakey; setting one failscheck-meta. Simply omit them. __structuredAttrs = trueis the default — never set it explicitly. If phases break, fix them instead of disabling. See structured-attrs.doCheck = falseanddoInstallCheck = falseare defaults — don't set them explicitly. Usepassthru.testsfor 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,enabledTestPathspytestFlags,pytestFlagsArray,unittestFlagsArraypreCheck,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 versionpythonImportsCheck— runs automatically inbuildPythonPackage, 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:
| 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
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:
updateScriptfrom passthru (ekapkgs-update discovers versions natively viasrc.urlparsing; addpassthru.ekapkgs-updatehints 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;
};
})
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: 319k | Updated | Claude CodeCodex | Verified | Install |
| requesting-code-reviewobra/superpowersUse when completing tasks, implementing major features, or before merging to verify work meets requirements | Stars: 319k | 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: 319k | 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: 319k | Updated | Claude CodeCodex | Verified | Install |