Skip to content

ekala-project/corepkgs / .agents/skills/mk-many-variants

mk-many-variants

Verified

Work with multi-version packages under pkgs-many (guile, go, erlang, perl, openssl, ...). Use when adding or changing a package that ships several versions side by side — covers the default.nix/variants.nix/generic.nix three-file pattern, the packageOlder/packageAtLeast version helpers, and mkVariantPassthru.

FileKindSize
SKILL.mdskill md11.0 KB
---
name: mk-many-variants
description: Work with multi-version packages under pkgs-many (guile, go, erlang, perl, openssl, ...). Use when adding or changing a package that ships several versions side by side — covers the default.nix/variants.nix/generic.nix three-file pattern, the packageOlder/packageAtLeast version helpers, and mkVariantPassthru.
---

# mkManyVariants - Multi-Version Package Management

This skill helps you work with the `mkManyVariants` pattern used in this codebase for managing packages that need to support multiple versions (e.g., guile, go, erlang, perl, openssl).

## Key Differences from Normal Nix Packages

Unlike a standard Nix package (like `pkgs/xxHash/default.nix`) which is a single `default.nix` file, mkManyVariants packages are split into **three separate files**:

### Normal Package Structure (e.g., `pkgs/xxHash/`)
```
pkgs/xxHash/
└── default.nix          # Single file with version, src, buildInputs, etc.
```

### mkManyVariants Package Structure (e.g., `pkgs-many/isl/`)
```
pkgs-many/isl/
├── default.nix          # Calls mkManyVariants with configuration
├── generic.nix          # Generic builder that works for all versions
├── variants.nix         # Defines each version's specific data
└── patches/             # Optional: version-specific patches
    ├── 0.20/
    └── 0.23/
```

## The Three-File Pattern

### 1. `default.nix` - Configuration Entry Point

This file calls `mkManyVariants` with configuration:

```nix
{ mkManyVariants, callPackage }:

mkManyVariants {
  variants = ./variants.nix;           # Where version data lives
  aliases = { };                       # Deprecated/aliased versions
  name = "isl";                        # Package name for eol/removed messages
  eol = { };                           # EOL variants (warn + still build)
  removed = { };                       # Removed variants (throw on access)
  defaultSelector = (p: p.v0_20);     # Which version is the default
  genericBuilder = ./generic.nix;      # Builder that handles all versions
  inherit callPackage;
}
```

**Differences from normal package:**
- No `stdenv.mkDerivation` call
- No version/src/buildInputs specified here
- Instead, configures mkManyVariants framework

### 2. `variants.nix` - Version Definitions

This file contains an attribute set where each attribute represents a version:

```nix
{
  v0_20 = rec {
    version = "0.20";
    src-url = [
      "https://libisl.sourceforge.io/isl-${version}.tar.xz"
    ];
    src-hash = "sha256-pVlqn7ils2XLYS5LlihzXW5n6RePrhNKgWrhlQF+d6o=";
    configureFlags = [
      "--with-gcc-arch=generic"
    ];
  };

  v0_23 = rec {
    version = "0.23";
    src-url = [
      "https://libisl.sourceforge.io/isl-${version}.tar.xz"
    ];
    src-hash = "sha256-XvxT767xUTAfTn3eOFa2aBLYFT3t4k+rF2c/gByGmPI=";
    configureFlags = [
      "--with-gcc-arch=generic"
    ];
  };
}
```

**Key points:**
- Each version is a separate attribute (typically named `v<major>_<minor>`)
- Use `rec` to allow self-referencing (e.g., `version` in `src-url`)
- Common fields: `version`, `src-url`, `src-hash`
- Version-specific fields: `configureFlags`, `patches`, `cmakeFlags`, etc.
- **Variant inheritance:** Non-default variants inherit all attributes from the `default` variant (selected by `defaultSelector`). Variants only need to specify attributes that differ — there is no need to repeat `version`, `src-url`, `src-hash`, etc. when only changing build flags or feature toggles.

**Feature-toggle variants** (same version, different build options):
```nix
{
  default = {
    version = "3.27.1";
    src-hash = "sha256-XViRUuuAccAv6rjOarcZ5DGh+8PisXAPVDJjKouSZNw=";
    withGdb = true;
  };

  # Inherits version and src-hash from default, only overrides withGdb.
  light = {
    withGdb = false;
  };
}
```

### 3. `generic.nix` - Generic Builder with Conditional Logic

This file is a **two-stage function** that receives variant args first, then package args:

```nix
{
  version,
  src-url,
  src-hash,
  configureFlags ? [ ],
  patches ? [ ],
  packageAtLeast,     # Helper: version >= X
  packageOlder,       # Helper: version < X
  ...
}@variantArgs:

{
  lib,
  stdenv,
  fetchurl,
  gmp,
  buildPackages,
  ...
}@args:

stdenv.mkDerivation {
  pname = "isl";
  inherit version;

  src = fetchurl {
    url = src-url;
    hash = src-hash;
  };

  inherit patches;

  # Version-conditional logic using helper functions
  strictDeps = true;
  depsBuildBuild = lib.optionals (packageAtLeast "0.23") [
    buildPackages.stdenv.cc
  ];

  nativeBuildInputs =
    lib.optionals (stdenv.hostPlatform.isRiscV && packageOlder "0.23") [
      autoreconfHook
    ] ++ [
      updateAutotoolsGnuConfigScriptsHook
    ];

  inherit configureFlags;

  meta = { ... };
}
```

**Key differences from normal package:**
- **Two parameter sets**: First `variantArgs`, then package dependencies
- **Helper functions available**: `packageAtLeast`, `packageOlder`, `packageBetween`
- **Conditional logic**: Use helpers to vary dependencies/patches by version
- **Generic src handling**: Takes `src-url` and `src-hash` from variants

## Version Helper Functions

These functions are automatically injected into `variantArgs`:

### `packageOlder`
```nix
packageOlder "2.0"  # Returns true if version < 2.0
```

### `packageAtLeast`
```nix
packageAtLeast "2.0"  # Returns true if version >= 2.0
```

### `packageBetween`
```nix
packageBetween "2.0" "3.0"  # Returns true if 2.0 <= version < 3.0
```

### Real-world examples from guile:

```nix
# Different source extensions by version
srcExtension = if packageOlder "2.0" then "tar.gz" else "tar.xz";

# Version ranges
patches =
  lib.optionals (packageOlder "2.0") [
    ./patches/1.8/...
  ]
  ++ lib.optionals (packageAtLeast "2.0" && packageOlder "2.2") [
    ./patches/2.0/...
  ]
  ++ lib.optionals (packageAtLeast "2.2") [
    ./patches/2.2/...
  ];

# Platform-specific conditionals with version
configureFlags = lib.optional (packageAtLeast "3.0" && stdenv.hostPlatform.isDarwin)
  "--disable-lto";
```

## Common Patterns

### Pattern 1: Version-Specific Patches
```nix
patches = [ ]
  ++ lib.optionals (packageOlder "2.0") [
    ./patches/1.x/fix-something.patch
  ]
  ++ lib.optionals (packageAtLeast "2.0") [
    ./patches/2.x/new-fix.patch
  ];
```

### Pattern 2: Conditional Dependencies
```nix
buildInputs = [
  alwaysNeeded
] ++ lib.optionals (packageAtLeast "3.0") [
  onlyNeededInV3
];
```

### Pattern 3: Setup Hooks by Version
```nix
setupHook =
  if packageOlder "2.0" then
    ./setup-hooks/v1-hook.sh
  else if packageOlder "3.0" then
    ./setup-hooks/v2-hook.sh
  else
    ./setup-hooks/v3-hook.sh;
```

### Pattern 4: Using mkVariantPassthru (Advanced)
```nix
# In generic.nix, add to passthru to enable variant composition
passthru = mkVariantPassthru variantArgs // {
  # other passthru attrs
};
```

This allows accessing other variants from a built package: `isl.variants.v0_27`

## EOL and Removed Variants

When a version reaches end-of-life or is dropped from `variants.nix`, use the `eol` and `removed` parameters to provide clear messages instead of silent breakage.

Both require `name` to be set.

### `eol` — Warn but still build

For variants that are still in `variants.nix` but have reached end-of-life upstream. Accessing them emits a `lib.warn` and still returns the built package.

```nix
mkManyVariants {
  variants = ./variants.nix;
  name = "nodejs";
  eol = {
    v18 = "2025-04-30";    # Node.js 18 EOL date
    v20 = "2026-04-30";
  };
  # ...
}
```

Evaluating `nodejs.v18` prints:
```
evaluation warning: nodejs.v18 is EOL as of 2025-04-30. It is recommended to use a newer version.
```

### `removed` — Throw on access

For variants that have been deleted from `variants.nix`. Accessing them throws an error. Only honoured when `config.aliases.nixpkgs` is `true` (the default), so CI evaluation with `aliases.nixpkgs = false` is unaffected.

```nix
mkManyVariants {
  variants = ./variants.nix;
  name = "linux";
  removed = {
    v6_17 = "2026-08-30";
  };
  # ...
}
```

Evaluating `linux.v6_17` throws:
```
error: linux.v6_17 is no longer available and was removed on 2026-08-30.
```

Aliases in `aliases/nixpkgs.nix` should continue pointing to the variant (e.g. `linuxPackages_6_17 = linux.v6_17.pkgs;`) so the specific error is emitted instead of a generic "attribute missing".

## When to Use mkManyVariants

Use mkManyVariants when:
- Package needs **multiple versions** available simultaneously
- Different versions have **conditional dependencies** or build logic
- Versions share **most of the build logic** but differ in specifics
- Package needs **feature-toggle variants** of the same version (e.g., `valgrind` vs `valgrind.light`, `graphviz.withXorg` vs `graphviz.withoutXorg`)
- Want to provide **variant composition** (access to other versions)

Don't use for:
- Single-version packages with no feature variants (use normal `pkgs/` structure)
- Completely different build processes per version (use separate packages)

## Creating a New mkManyVariants Package

1. Create directory in `pkgs-many/<package>/`
2. Create `variants.nix` with your versions
3. Create `generic.nix` with shared build logic and conditionals
4. Create `default.nix` calling mkManyVariants
5. Choose default version with `defaultSelector`
6. Test building: `nix-build -A <package>` (default) and `nix-build -A <package>.variants.v<version>`

## Automated Updates (ekapkgs-update)

The `ekapkgs-update` tool manages version updates for mkManyVariants packages. Set `passthru.ekapkgs-update` in `generic.nix` to control update behavior.

**Typical configuration** — update each variant to its latest patch release:

```nix
passthru.ekapkgs-update = {
  semver-strategy = "patch";
};
```

**Retaining every version** — use `keep` to automatically create a new variant entry for each upstream patch/minor release:

```nix
passthru.ekapkgs-update = {
  semver-strategy = "patch";
  keep = "patch";    # one variant per patch release (v1_26_8, v1_26_9, ...)
};
```

**Non-standard tags** — when upstream tags don't follow the `v1.2.3` convention:

```nix
passthru.ekapkgs-update = {
  semver-strategy = "patch";
  github-repo = "golang/go";
  version-regex = "^go(.+)$";
  keep = "patch";
};
```

**Custom version source** — for packages not hosted on GitHub/GitLab/PyPI, provide an `update-script` that prints available versions (one per line):

```nix
passthru.ekapkgs-update = {
  update-script = writeScript "list-openssl-releases" ''
    ${curl}/bin/curl -s https://www.openssl.org/source/ \
      | ${pcregrep}/bin/pcregrep -o1 'openssl-([0-9]+\.[0-9]+\.[0-9]+)\.tar' \
      | sort -uV
  '';
  semver-strategy = "patch";
};
```

**Sub-packages that inherit version** — skip them so the parent variant drives the update:

```nix
passthru.ekapkgs-update.skip = true;
```

## Common Gotchas

- **Don't forget `rec`** in variants.nix if using `${version}` in fields
- **Two-stage function** in generic.nix: variantArgs first, then package args
- **Helper functions** only available in first parameter set (variantArgs)
- **Default selector** must be a function taking the variants attrset
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: 198kUpdated Claude CodeCodexVerifiedInstall
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: 194kUpdated Claude CodeCodexVerifiedInstall
ponytail-debtDietrichGebert/ponytailHarvest every shortcut: comment into one debt ledger, so deferrals get tracked instead of forgotten. One-shot report.Stars: 194kUpdated Claude CodeCodexVerifiedInstall
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: 194kUpdated Claude CodeCodexVerifiedInstall