ekala-project/corepkgs / .agents/skills/porting
porting
VerifiedPort a package from nixpkgs into corepkgs. Use when adding a package that already exists upstream — covers copying it across, checking dependencies first, stripping nixpkgs-only attributes, recording TODOs for missing features, and wiring it into top-level.nix.
| File | Kind | Size |
|---|---|---|
| SKILL.md | skill md | 6.7 KB |
SKILL.md
View on GitHub---
name: porting
description: Port a package from nixpkgs into corepkgs. Use when adding a package that already exists upstream — covers copying it across, checking dependencies first, stripping nixpkgs-only attributes, recording TODOs for missing features, and wiring it into top-level.nix.
---
# Porting from nixpkgs
## Workflow
### 1. Check dependencies exist
Do this **before** importing anything: a package whose dependencies are missing
cannot be evaluated, and it is cheaper to find out now than after editing.
```bash
for dep in acl lzo cmocka libuuid util-linux zlib zstd; do
printf '%s: ' "$dep"
nix-instantiate -A "$dep" >/dev/null 2>&1 && echo "✓" || echo "✗"
done
```
Do **not** grep `top-level.nix` to check for a dependency. Packages in `pkgs/`
and `pkgs-many/` are registered automatically and often have no entry there. For
attributes that are not derivations, use `nix-instantiate --eval -A <attr>`.
If a dependency is missing, either port it first or add a TODO and disable the
feature that needs it (step 4).
### 2. Copy the package across
Copy the whole directory so patch files and other assets come along, then rename
the entry point to the corepkgs convention.
```bash
# pkgs/by-name/cu/curl -> pkgs/curl
cp -r ../nixpkgs/pkgs/by-name/cu/curl pkgs/curl
mv pkgs/curl/package.nix pkgs/curl/default.nix
# pkgs/development/python-modules/httpx -> python/pkgs/httpx
cp -r ../nixpkgs/pkgs/development/python-modules/httpx python/pkgs/httpx
```
| Source in nixpkgs | Destination |
| --- | --- |
| `pkgs/by-name/<xx>/<name>` | `pkgs/<name>` |
| `pkgs/development/python-modules/<name>` | `python/pkgs/<name>` |
| `pkgs/development/...` (older layout) | `pkgs/<name>` |
`<xx>` is the lowercase two-letter prefix of the attribute name, so `SDL2_gfx`
is found under `sd/` and `R` under `r/`. Only `by-name` packages have a
`package.nix` to rename; the older trees already use `default.nix`.
Copying makes **no edits to the expression itself** — every cleanup in step 3 is
manual.
**Packages with multiple versions** belong in `pkgs-many/` and need to be
restructured into the `default.nix` / `variants.nix` / `generic.nix` layout
rather than copied — see the `mk-many-variants` skill.
### 3. Strip nixpkgs-only attributes
```nix
meta = {
# maintainers = ...; DELETE — not a recognised meta key here, fails check-meta
# teams = ...; DELETE — likewise
};
passthru = {
# updateScript = gnome.updateScript { ... }; DELETE — ekapkgs-update
# handles version discovery natively via src.url parsing.
# Add passthru.ekapkgs-update hints only when auto-detection fails
# (see packaging skill, "Automated Updates" section).
tests = { ... }; # KEEP
};
```
Also drop `doCheck = false;` if the expression sets it — that is already the
default across the package set. To keep a test suite, move it to
`passthru.tests` instead:
```nix
passthru.tests = {
unittests = runUnitTests finalAttrs.finalPackage;
};
```
Build-system hooks are explicit here, so an imported expression usually needs
one added: `cmake.configurePhaseHook`, or `meson.configurePhaseHook` plus
`ninja`. See the `cmake` and `meson` skills.
### 4. Record what you disabled
Every feature turned off for a missing dependency gets a TODO naming the
dependency, so the package can be completed later without re-deriving why:
```nix
buildInputs = [
zlib
# TODO(corepkgs): Port openssl for TLS support
# TODO(corepkgs): Port libxml2 for XML processing
];
configureFlags = [
"--without-selinux"
"--without-cap"
];
```
### 5. Validate
```bash
nix-instantiate -A example
nix-build -A example
./result/bin/example --version
```
Run `./ci/eval.sh` before committing to confirm nothing else in the set broke.
See the `validation` skill for the full procedure and error triage.
### 6. Add to top-level.nix only if needed
Packages in `pkgs/` and `pkgs-many/` are auto-registered by directory name. Add
an explicit entry **only** when the inputs deviate from what the expression
declares, or you need to override arguments or pass extra configuration.
## Example: straightforward package
```nix
{
lib,
stdenv,
fetchFromGitHub,
meson,
ninja,
pkg-config,
libcap,
libseccomp,
}:
stdenv.mkDerivation (finalAttrs: {
pname = "bubblewrap";
version = "0.8.0";
src = fetchFromGitHub {
owner = "containers";
repo = "bubblewrap";
tag = "v${finalAttrs.version}";
hash = "sha256-...";
};
nativeBuildInputs = [
meson
meson.configurePhaseHook
ninja
pkg-config
];
buildInputs = [
libcap
libseccomp
];
meta = {
description = "Unprivileged sandboxing tool";
homepage = "https://github.com/containers/bubblewrap";
license = lib.licenses.lgpl2Plus;
platforms = lib.platforms.linux;
};
})
```
## Example: features disabled for missing dependencies
```nix
{
lib,
stdenv,
fetchurl,
pkg-config,
zlib,
bzip2,
file,
lua,
}:
stdenv.mkDerivation (finalAttrs: {
pname = "rpm";
version = "4.18.0";
src = fetchurl {
url = "https://ftp.rpm.org/releases/rpm-4.18.x/rpm-${finalAttrs.version}.tar.bz2";
hash = "sha256-...";
};
nativeBuildInputs = [ pkg-config ];
buildInputs = [
zlib
bzip2
file
lua
# TODO(corepkgs): Port popt for enhanced CLI parsing
# TODO(corepkgs): Port beecrypt for signature verification
];
configureFlags = [
"--without-selinux"
"--without-cap"
];
meta = {
description = "RPM Package Manager";
license = lib.licenses.gpl2Plus;
};
})
```
## Common issues
**`Source path does not exist`** — the package is not in `by-name` (copy it by
hand), the name is not the attribute name, or `--nixpkgs-root` points at the
wrong checkout.
**`error: attribute 'somelib' missing`** — a dependency was never ported. Port
it, or drop the argument and disable the feature with a TODO.
**`configure: error: libfoo is required`** — the build system wants a dependency
you removed. Disable it explicitly, e.g. `configureFlags = [ "--without-foo" ];`.
**Nothing configures / no `Makefile` found** — the build-system hook was not
carried over. Add `cmake.configurePhaseHook` or `meson.configurePhaseHook`.
**`check-meta` rejects the package** — `meta.maintainers` or `meta.teams`
survived the cleanup.
## Checklist
- [ ] Dependencies checked with `nix-instantiate -A <dep>`
- [ ] Copied across and `package.nix` renamed to `default.nix`
- [ ] `meta.maintainers`, `meta.teams`, and `updateScript` removed (add `passthru.ekapkgs-update` if auto-detection won't work)
- [ ] Build-system configure hook added
- [ ] Missing dependencies recorded as `TODO(corepkgs)` comments
- [ ] License and any security patches preserved
- [ ] Validated per the `validation` skill, and `./ci/eval.sh` passes
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| slack-gif-creatoranthropics/skillsKnowledge and utilities for creating animated GIFs optimized for Slack. Provides constraints, validation tools, and animation concepts. Use when users request animated GIFs for Slack like "make me a GIF of X doing Y for Slack." | Stars: 198k | Updated | Claude CodeCodex | Verified | Install |
| ponytailDietrichGebert/ponytailLazy senior dev mode for any coding task: the smallest change that fully solves it, and a reply a busy human understands in one read. | Stars: 194k | Updated | Claude CodeCodex | Verified | Install |
| ponytail-debtDietrichGebert/ponytailHarvest every shortcut: comment into one debt ledger, so deferrals get tracked instead of forgotten. One-shot report. | Stars: 194k | Updated | Claude CodeCodex | Verified | Install |
| ponytail-debtDietrichGebert/ponytailList every `shortcut:` comment (and older `ponytail:` ones) as a debt ledger. One-shot report, changes nothing. Use for "ponytail debt", "what did ponytail defer", "list the shortcuts", /ponytail-debt. | Stars: 194k | Updated | Claude CodeCodex | Verified | Install |