registry.md

PkgDb Registry

A registry in pkgdb is a structure used to organize a set of nix flakes, called inputs throughout this document, which have been assigned short-names and additional metadata.

While the registry structure in pkgdb is similar to that used by nix, it has been extended to record additional information for each input related to package resolution/search.

Additionally the registry carries a small number of global settings such as priority ( resolution/search ranking for each input ), and default/fallback settings to be used if/when inputs do not explicitly declare some settings.

Schemas

Before diving into the details of individual parts of the schema, lets start with an example of a registry with three inputs. Here we use JSON, but any trivial format could be used.

{
  "inputs": {
    "nixpkgs": {
      "from": {
        "type": "github"
      , "owner": "NixOS"
      , "repo": "nixpkgs"
      , "rev":  "e8039594435c68eb4f780f3e9bf3972a7399c4b1"
      }
    , "subtrees": ["legacyPackages"]
    }
  , "floco": {
      "from": {
        "type": "github"
      , "owner": "aakropotkin"
      , "repo": "floco"
      }
    , "subtrees": ["packages"]
    }
, "defaults": {
    "subtrees": null
  }
, "priority": ["nixpkgs"]
}

At the top level the abstract schema for the whole registry is:

Subtree :: "packages" | "legacyPackages"

FlakeRef :: ? URL string or Attr Set ?

InputPreferences :: {
  subtrees    = null | [Subtree...]
}

Input :: {
  from = FlakeRef
  subtrees    = null | [Subtree...]
}

Registry :: {
  inputs   = { <INPUT-NAME> = Input, ... }
, defaults = InputPreferences
, priority = null | [<INPUT-NAME>...]
}

Fields

You must provide at least one input. The keys in this attribute set correspond to keys in the priority list, and are often used in the output of search and resolve invocations.

The from fields in each input are flake references like those seen in flake.nix files, being either a URL string or an attribute set representation. These flake references may be locked or unlocked but locking is strongly recommended for most use cases.

The priority list should contain ONLY keys from inputs, and is used to indicate a "high" to "low" priority order for performing resolution and search. Any inputs which are missing from priority will be ranked lexicographically after all explicitly prioritized inputs.

The defaults field may be used to set fallback settings for inputs members. Explicit definitions in inputs override defaults settings. This is discussed further in the section below.

Fallbacks

The fields defaults and priority are optional.

The fields subtrees are optional ( everywhere ).

An explicit null is treated the same as omitting a field.

If no default or explicit settings are given for subtrees there is fallback behavior which attempts to do the right thing without being overly eager about scraping everything for each input. Omitting subtrees will cause flakes to use packages, and finally legacyPackages - only one output will be searched with this behavior.