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.

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.

# 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

meta = {
  # maintainers = ...;  DELETE — not a recognised meta key here, fails check-meta
  # teams = ...;        DELETE — likewise
};

passthru = {
  # updateScript = gnome.updateScript { ... };  DELETE
  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:

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:

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

configureFlags = [
  "--without-selinux"
  "--without-cap"
];

5. Validate

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

{
  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

{
  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
• 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