Files

T

kosmos a9f1d0c689 Add spec, schema and README for pkgatlas

Specification for a cross-distro file -> package resolver, grounded in
verified upstream formats for deb (Contents), rpm (filelists.xml) and
pacman (*.files.tar.gz).

No implementation: spec only.

2026-09-22 22:47:05 +00:00

2.8 KiB

Raw Permalink Blame History

pkgatlas

Cross-distro file → package resolver. Answers one question well:

Given a build-time dependency signal — a linker flag (-lcurses), a missing header (ncurses.h), a pkg-config name, or a bare file path — which package do I install on (distro, release, arch)?

Built for build automation. Primary consumer: saggar (auto-magic dependency detection), where a -lcurses not found error currently has no reliable answer.

Why

That mapping does exist upstream, but only as large per-distro indexes that are slow to query, differently shaped per package manager, and unavailable mid-build:

Manager	Source	Size
deb	`Contents-<arch>.gz`	12.7 – 47.6 MB
rpm	`filelists.xml.zst`	39.7 – 48.9 MB (→ 875 MB uncompressed)
pacman	`<repo>.files.tar.gz`	1.5 – 51 MB

pkgatlas precomputes them into one small, uniform, queryable artifact.

The same mapping is also distro-dependent: -lcurses is libncurses-dev on Debian but termcap-devel on openSUSE. So answers cannot be inferred across distros — they must be built per distro.

Shape

pkgatlas-build  ──> snapshot .sqlite  ──┬──> pkgatlas-serve (HTTP API)
   (ETL)              (the artifact)    └──> published file (offline query)

The artifact is the product. Consumers can pin a snapshot for reproducible builds, or query locally with no network dependency mid-build.

Status

Pre-implementation. Spec and schema are written and grounded in verified upstream formats; the Go implementation is in progress.

docs/SPEC.md — full specification
schema.sql — database schema

API (planned)

GET /v1/resolve?lib=curses&distro=ubuntu&release=24.04&arch=riscv64
GET /v1/resolve?header=ncurses.h
GET /v1/resolve?pc=ncurses
GET /v1/resolve?file=libcurses.so

{
  "query": { "kind": "lib", "value": "curses" },
  "resolved": [{
    "manager": "deb", "distro": "ubuntu", "release": "24.04", "arch": "riscv64",
    "path": "usr/lib/riscv64-linux-gnu/libcurses.so",
    "package": "libncurses-dev",
    "install": "apt-get install -y libncurses-dev"
  }],
  "ambiguous": false,
  "truncated": false
}

resolved is always an array — an empty one means "genuinely unavailable on this distro", which is a real answer. When a flag maps to several packages (-lcurl → libcurl4-openssl-dev and libcurl4-gnutls-dev), ambiguous is true and the consumer chooses; pkgatlas never picks silently.

Scope

v1 covers deb, rpm and pacman. apk and nix are deferred. Language-registry metadata (npm/cargo/pypi) is explicitly out of scope — that is deps.dev's job.

Build

CGO_ENABLED=0 go build ./...
go test ./...

Requires Go 1.25+. No CGO: SQLite is modernc.org/sqlite, zstd is klauspost/compress.

License

TBD.

2.8 KiB Raw Permalink Blame History Unescape Escape