bottlepkg

Documentation

Overview

Package bottlepkg packages a finished install tree into a pkgx bottle.

A pkgx bottle is a compressed tar whose entries are all prefixed "<project>/v<version>/" (e.g. "openssl.org/v1.1.1w/bin/openssl"). The dist layout places each bottle at "<project>/<os>/<arch>/v<version><ext>" next to a "versions.txt" listing the published versions, one per line.

Codec chooses the compression. It stays gzip until the readers are deployed: publishing a codec the installed base cannot read would brick every install, and a bottle already published is never rewritten. See Codec.

Index

• Variables
• func Bottle(installDir, project, version string, w io.Writer) error
• func WriteBottle(installDir, project, version, os, arch, outDir string) (string, error)

Variables

var Codec = bottle.ExtTarZst

Codec is the extension — and therefore the compression — new bottles are written with. One of bottle.ExtTarGz or bottle.ExtTarZst.

It defaults to zstd. The readers shipped first (bottle v0.8.0, in pkgx, pkgm and bk), which is the order that mattered: a consumer meeting a codec it cannot decode fails with "invalid header", which reads like a corrupt download rather than a format it was never taught.

The blast radius of this default is bounded by construction. Bottles already published are never rewritten — they stay gzip and stay readable by anything, old binaries included. Only NEW publishes change, and an operator who needs the old format says --compress gzip.

Measured on the same package, version and platform (lz4.org 1.10.0, linux/aarch64): the published gzip layer is 311 344 bytes, the zstd bottle 169 518 — 1.83x smaller, and faster to decompress.

Measured on real bottle payloads, zstd -19 beats xz on ratio, compression time AND decompression time, and gzip has the poorest ratio of the three while decompressing slower than zstd. Every install pays the decompression; the factory pays the compression once.

Functions

func Bottle

func Bottle(installDir, project, version string, w io.Writer) error

Bottle walks installDir and writes a gzip'd tar to w in which every entry path is "<project>/v<version>/<relpath>". Regular files (with their mode bits), directories, and symlinks (tar TypeSymlink plus link target) are preserved. Hidden files are included; only the walk root itself is skipped. Paths are sorted for deterministic output.

func WriteBottle

func WriteBottle(installDir, project, version, os, arch, outDir string) (string, error)

WriteBottle creates "outDir/<project>/<os>/<arch>/v<version>.tar.gz", bottles installDir into it, and appends version to the sibling "versions.txt". It returns the tarball path.