rippkgs

The rippkgs-index CLI is used to create a SQLite database of nixpkgs expressions. You can index the default nixpkgs channel, a specific directory, or a registry generated via a flake.

Indexing the default nixpkgs channel

rippkgs-index nixpkgs -o $XDG_DATA_HOME/rippkgs-index.sqlite

Indexing a specific nixpkgs directory

If you have a custom channel, pass the path explicitly:

rippkgs-index nixpkgs -o $XDG_DATA_HOME/rippkgs-index.sqlite ~/.nix-defexpr/channels/my-very-special-nixpkgs-channel

Indexing via a registry (to avoid recursive-nix problems)

First, generate a registry JSON using nix eval, then pass it to rippkgs-index:

nix eval -L .#lib.genRegistry --apply 'f: f (import <nixpkgs> { })' --impure --json > registry.json
rippkgs-index registry -o rippkgs-index.sqlite registry.json

You can install the rippkgs CLI and the rippkgs-index utility using nix profile install or by adding them to your NixOS configuration.

Using nix profile

nix profile install nixpkgs#rippkgs nixpkgs#rippkgs-index
# Or via flake directly
nix profile install github:replit/rippkgs/v1.1.0

Using NixOS configuration

If you are using a flake to configure your system, add the packages to your environment.systemPackages list:

environment.systemPackages = [
  pkgs.rippkgs
  pkgs.rippkgs-index
  # If using as a flake input:
  inputs.rippkgs.packages.${system}.rippkgs
  inputs.rippkgs.packages.${system}.rippkgs-index
];

Once an index has been generated, use the rippkgs CLI to search for package expressions.

Note: You must specify the index file created by rippkgs-index using the -i flag.

# Basic search
rippkgs -i path/to/index.sqlite rustc

rippkgs -i nixpkgs.sqlite rustc

The search function allows for an exact match lookup of a package in the database using a specific attribute string.

If a package is found, the function returns an Option<Package>. Note that the following cases will return None even if a row is found:

• The package is stdenv (not installable).
• The package is part of bootstrapping.
• The package does not have an out path in its store_paths (meaning it is not installable).

If the package is found and installable, the present field in the returned Package struct is automatically updated to reflect whether the package's out path currently exists in /nix/store/.

// Signature of the search function
pub fn search(query_str: &str, db: &Connection) -> eyre::Result<Option<Package>> {
    // ...
}

The PackageInfo struct defines the schema for indexed package information. When consuming data generated or used by rippkgs, the following fields are available (note that fields are serialized using camelCase in JSON):

• pname: The package name.
• version: The package version.
• meta: A PackageMeta object containing metadata.
• store_paths: A mapping of store path identifiers to their actual paths.
• propagated_build_inputs: A list of propagated build inputs.
• propagated_native_build_inputs: A list of propagated native build inputs.

{
  "pname": "example-pkg",
  "version": "1.0.0",
  "meta": {
    "description": "A description",
    "available": true
  },
  "storePaths": {
    "out": "/nix/store/...-example-pkg"
  },
  "propagatedBuildInputs": ["dep1"],
  "propagatedNativeBuildInputs": ["dep2"]
}

Use the registry subcommand to import a registry that was previously generated (e.g., via genRegistry from the flake library) and convert it into a SQLite index.

Arguments:

• registry: The path to the registry JSON file to import.

Options:

• -o, --output <PATH>: The location to write the saved index to. Defaults to rippkgs-index.sqlite.

rippkgs-index registry <PATH_TO_REGISTRY> --output <OUTPUT_PATH>

Use the nixpkgs subcommand to evaluate a Nixpkgs expression directly and build a SQLite index. This command uses nix eval under the hood.

Arguments:

• nixpkgs: (Optional) The location of Nixpkgs on-disk to index. If provided, it passes the -I nixpkgs=<PATH> flag to the nix command.

Options:

• -r, --save-registry <PATH>: (Optional) Save the evaluated registry as a JSON file before indexing.
• -a, --nixpkgs-arg <STRING>: (Optional) A JSON string to pass as the config argument to the Nixpkgs import. Defaults to {}.
• -o, --output <PATH>: The location to write the saved index to. Defaults to rippkgs-index.sqlite.

rippkgs-index nixpkgs [-I <PATH>] [-r <SAVE_PATH>] [-a <ARG_JSON>] [-o <OUTPUT_PATH>]

The rippkgs-index command is used to create a SQLite database index of packages. This index can then be used by the rippkgs CLI for searching and comparison. You can generate an index from two different sources: an existing registry JSON file or directly from a Nixpkgs expression.

By default, the index is saved to rippkgs-index.sqlite in the current directory.

# Example: Generate index from a Nixpkgs expression
rippkgs-index nixpkgs --output my-index.sqlite

# Example: Generate index from a pre-generated registry JSON
rippkgs-index registry my-registry.json --output my-index.sqlite