zeta-reconstructor/README.md

zeta-reconstruct

zeta-reconstruct — convert Arch Linux packages (binary .pkg.tar.zst and source PKGBUILD/.SRCINFO) into Zeta package format.

The tool is a translator. It never runs makepkg, never compiles anything, and never publishes packages. It only converts files and writes them to disk, warning on stderr whenever a dependency or edge case cannot be mapped cleanly.

Build

Requires Go 1.26 or newer. The only external dependency is github.com/klauspost/compress (zstd decoding); everything else uses the Go standard library.

go build ./cmd/zeta-reconstruct

This writes the zeta-reconstruct binary into the current directory. To place it next to the sources instead:

go build -o ./cmd/zeta-reconstruct/zeta-reconstruct ./cmd/zeta-reconstruct

Usage

$ zeta-reconstruct --help
usage: zeta-reconstruct <command> [flags] <input>

Commands:
  arch-binary  convert an Arch binary package (.pkg.tar.zst) to Zeta
  arch-src     convert a PKGBUILD/.SRCINFO source recipe to Zeta

Flags:
  --list       list registered frontends
  -h, --help   show this help

arch-binary flags:
  --output <dir>  output directory (default ".")
  --repo <url>    repository base URL (default "https://raw.githubusercontent.com/gretagen/zeta-packages/refs/heads/main")

arch-src flags:
  --output <dir>  output directory (default ".")
  --arch <arch>   target architecture (default "x86_64")

--list prints the registered frontends: arch-binary and arch-src.

zeta-reconstruct --list
zeta-reconstruct arch-binary <input.pkg.tar.zst> --output <dir> [--repo <url>]
zeta-reconstruct arch-src <PKGBUILD|.SRCINFO|dir> --output <dir> [--arch <arch>]

For arch-binary the input must end in .pkg.tar.zst. For arch-src the input may be a PKGBUILD, a .SRCINFO, or a directory containing either; a .SRCINFO is preferred when both are present.

Outputs

• arch-binary writes packages/<name>/<name>-<version>.tar.gz and a package.lua manifest beside it, under the --output directory.
• arch-src writes <name>.recipe and a generated build.sh into the --output directory.

Workflow

• The emitted package.lua is an archive-mode manifest consumed by zeta (the package manager). zeta downloads the tarball at the manifest url, verifies its sha256, and installs it with strip = 1.
• The emitted .recipe plus build.sh are consumed by zeta-makepkg to build the binary package from source. The recipe declares build_system = "custom" and build_script = "build.sh"; zeta-makepkg fetches the source, extracts it, and runs the script under sh with DESTDIR set.

Field mapping: .PKGINFO → package.lua

.PKGINFO field	package.lua field	Notes
pkgname	name
pkgver	version	verbatim, already in epoch+pkgrel form (e.g. 1.0-1)
pkgdesc	summary
url	n/a	not carried over; the manifest url is built from --repo plus packages/<name>/<name>-<version>.tar.gz
depend	deps	each relation mapped through the Arch→Zeta name table; dropped deps are skipped with a warning
n/a	archive	{ strip = 1 }
n/a	sha256	sha256 of the emitted tarball

Arch metadata members that are not payload (.BUILDINFO, .MTREE, .INSTALL, .Changelog) are skipped during extraction.

Field mapping: .SRCINFO/PKGBUILD → .recipe

source field	recipe field	Notes
pkgname	name	v1 covers exactly one package per recipe
pkgver	version	upstream version; pkgrel is dropped
pkgdesc	summary	falls back to the package name when empty
source[0]	url	the text after a name:: prefix if present, else the whole string; the URL scheme is never stripped
sha256sums[0]	sha256	the line is omitted entirely when the value is empty or SKIP; a non-hex64 value is dropped with a warning
depends	deps	each relation mapped through the Arch→Zeta name table
n/a	build_system	"custom"
n/a	build_script	"build.sh"

The generated build.sh reproduces the PKGBUILD's prepare() (if present), build() (if present), and package() functions with $pkgdir pointed at $DESTDIR. Function bodies are embedded from the PKGBUILD file; a .SRCINFO-only input yields stub functions.

Dependency mapping

Each Arch dependency relation is mapped in this order:

1. An optdepend-style description (name: description) is stripped back to the name.
2. If the name matches a Zeta package name verbatim (checked against the Zeta package index), it passes through unchanged. Version constraints are preserved; a bare Arch = is normalized to == (Zeta's canonical form).
3. Otherwise a curated rename table is applied, with a warning.
4. Otherwise, if the name is on the base-system drop list, it is dropped, with a warning.
5. Otherwise it passes through with a warning (nothing is silently lost).

Renames

Arch	Zeta
zlib	libz
xz	xz-utils
freetype2	freetype
libxkbcommon	xkbcommon
libice	libICE
libsm	libSM
libx11 … libxxf86vm	libX11 … libXxf86vm

The X11 family is pure case correction: Arch spells it lowercase (libx11, libxau, libxext, libxrender, libxft, and the rest of the libx* set), while the Zeta index uses libX*. Names like libxcb and libxml2 are already correct and are deliberately absent from the table.

Dropped (base system)

These packages are provided outside the package manager, so Zeta has no package for them:

glibc, gcc-libs, gcc, bash, coreutils, filesystem, linux-api-headers, systemd, util-linux, ncurses, readline, tzdata, ca-certificates.

Version and epoch

• Binary packages keep the .PKGINFO pkgver verbatim, epoch and pkgrel included (1.0-1, or 1:1.0-1 when an epoch exists).
• Source recipes use version = pkgver (the upstream version); pkgrel is dropped, matching how versions appear in the Zeta package index.
• An epoch is never folded into the Zeta version. When a : epoch is present, a warning is emitted and the version string keeps its epoch form.

Not yet supported (v1)

The following shapes are not yet supported in v1. They produce an explicit error, except where noted:

• Split packages (more than one pkgname): error.
• VCS sources: git+, svn+, hg+, bzr+ protocol prefixes, <vcs>::<url> fragments (e.g. git::https://…), and dynamic pkgver() functions: error.
• Multiple sources (more than one source entry): error.
• Zero sources: error (a recipe requires a url).
• makedepends, optdepends, provides, conflicts, replaces: parsed but dropped with a warning; Zeta's formats have no fields for them.
• Bash-only constructs in PKGBUILD function bodies (arrays, [[ ]], local, process substitution): the generated build.sh carries a warning that it may need manual adjustment.
• Gentoo ebuilds and void-src packages: not supported. The frontend registry interface is in place, so future converters can be added as new frontends, but no such converter ships in v1.