bottle

README

bottle

The pure-Go pkgx bottle client — the shared backend of the pure-Go pkgx family. It resolves a package's dependency closure from the pkgx pantry, downloads the bottles from dist.pkgx.dev, completes the implicit libc/gcc closure a FROM scratch image needs, and execs through the pkgx glibc loader. CGO_ENABLED=0, no runtime dependencies of its own.

Consumed by:

• go-pkgx/pkgm — the installer
• go-pkgx/pkgx — the runtime

so both tools share one source of truth for the bottle protocol.

Highlights

• Reads package.yml + versions.txt from the pantry, BFS the runtime dependency closure, streams gzip/xz + tar into PKGX_DIR.
• Soname-exact FROM-scratch completion: walks each bottle's ELF DT_NEEDED and pulls the provider version that ships the exact soname an ABI needs (not merely the latest), so drifted sonames resolve.
• Embedded Mozilla CA bundle (net/http with no system trust store), pure-Go DNS. Cross-compiles to six 64-bit targets.

BSD-3-Clause.

Documentation

Overview

Package bottle is the reusable pkgx "bottle backend": it resolves a package's runtime dependency closure from the pkgx pantry, downloads the bottles from dist.pkgx.dev, and installs them — with no runtime dependencies of its own (pure Go, CGO_ENABLED=0, runnable on a `FROM scratch` image). It is imported by the pkgm CLI and by sibling tools so there is one source of truth.

Index

• Variables
• func BinNames(project string, provides []string) []string
• func CanonicalLoaderExists() bool
• func Dir() string
• func FetchMeta(project string) (deps map[string]string, provides []string, err error)
• func FindClosureBin(closure []Resolved, dir, project, name string) string
• func FindLoader(dir string) string
• func GOARCH() string
• func GOOS() string
• func HostSlug() (string, string)
• func Install(r Resolved, pkgxDir string) (bool, error)
• func IsELF(p string) bool
• func LibPath(closure []Resolved, dir string) string
• func LoaderName() string
• func NewHTTPClient() *http.Client
• func PrefixOf(project string, closure []Resolved, dir string) string
• func PrimaryBin(project string, provides []string) string
• func SetupScratchRootfs(loader, shellPath string)
• func StubBins(closure []Resolved, dir, prefix string) (int, error)
• type Resolved
  • func CompleteClosure(roots map[string]string, dir string) ([]Resolved, error)
  • func MergeClosures(a, b []Resolved) []Resolved
  • func ResolveClosure(roots map[string]string) ([]Resolved, error)
• type Ver
  • func FetchVersions(project string) ([]Ver, error)
  • func ParseVer(s string) Ver
  • func PickVersion(project, constraint string) (Ver, error)

Variables

var (
	DistBase   = "https://dist.pkgx.dev"
	PantryBase = "https://raw.githubusercontent.com/pkgxdev/pantry/main/projects"
)

Base URLs for the pkgx distribution + pantry; overridable in tests.

var Exec = syscall.Exec

Exec replaces the current process image; overridable in tests.

var HTTPClient = NewHTTPClient()

HTTPClient is an HTTP client that trusts the embedded CA bundle (falling back to the system pool if, somehow, the embed is empty). It is overridable.

Functions

func BinNames

func BinNames(project string, provides []string) []string

BinNames returns the base names of the binaries a package provides, falling back to the project's leaf name when it declares no `provides:`.

func CanonicalLoaderExists

func CanonicalLoaderExists() bool

CanonicalLoaderExists reports whether /lib{,64}/ld-linux-* is present.

func Dir

func Dir() string

Dir resolves the bottle store (PKGX_DIR, default ~/.pkgx).

func FetchMeta

func FetchMeta(project string) (deps map[string]string, provides []string, err error)

FetchMeta returns the host-relevant runtime dependencies (project -> constraint) and the list of provided paths for a project's package.yml.

func FindClosureBin

func FindClosureBin(closure []Resolved, dir, project, name string) string

FindClosureBin returns the path to <project>/…/bin/<name> if that project is in the installed closure, else "".

func FindLoader

func FindLoader(dir string) string

FindLoader locates the pkgx glibc dynamic loader in an installed closure.

func GOARCH

func GOARCH() string

GOARCH returns the pkgx architecture slug (e.g. "x86-64", "aarch64") for the running machine.

func GOOS

func GOOS() string

GOOS returns the pkgx OS slug ("linux" or "darwin") for the running machine.

func HostSlug

func HostSlug() (string, string)

HostSlug returns the pkgx (os, arch) slug for the running machine.

func Install

func Install(r Resolved, pkgxDir string) (bool, error)

Install downloads and extracts one bottle into pkgxDir (skips if the versioned prefix already exists), then writes major/minor convenience links. Extraction is atomic — the bottle is unpacked into a temp dir and the versioned prefix is renamed into place — so concurrent installs sharing one PKGX_DIR never observe a half-extracted prefix.

func IsELF

func IsELF(p string) bool

IsELF reports whether the file at p starts with the ELF magic.

func LibPath

func LibPath(closure []Resolved, dir string) string

LibPath returns a ":"-joined library path covering every lib dir in an installed closure (including glibc's versioned sub-libdir).

func LoaderName

func LoaderName() string

LoaderName is the dynamic-loader soname for the current architecture.

func NewHTTPClient

func NewHTTPClient() *http.Client

NewHTTPClient builds an *http.Client that trusts the embedded CA bundle in addition to the host's system trust store.

func PrefixOf

func PrefixOf(project string, closure []Resolved, dir string) string

PrefixOf returns the installed prefix directory <dir>/<project>/v<version> for the Resolved whose Project equals project in the closure, or "" if the project is not part of the closure.

func PrimaryBin

func PrimaryBin(project string, provides []string) string

PrimaryBin picks the binary to run for a project: the one whose name matches the project's path leaf (gnu.org/wget -> wget) or its domain's second-level label (perl.org -> perl, not the first-listed corelist), else the first provided binary.

func SetupScratchRootfs

func SetupScratchRootfs(loader, shellPath string)

SetupScratchRootfs makes the pkgx loader and a shell available at their canonical absolute paths (best-effort). On a FROM-scratch image this lets every bottle ELF — the one we exec AND any child processes it spawns — resolve its PT_INTERP=/lib/ld-linux natively, and (when shellPath is set) lets "#!/bin/sh" wrapper scripts resolve to the pkgx bash we installed. On a normal system these paths already exist, so os.Symlink fails and is ignored (no clobbering).

func StubBins

func StubBins(closure []Resolved, dir, prefix string) (int, error)

StubBins writes a small env-setting shell stub into <prefix>/bin for every binary in the closure, mirroring the reference pkgm: the stub exports the closure's LD_LIBRARY_PATH and exec's the real bottle binary.

Types

type Resolved

type Resolved struct {
	Project string
	Version Ver
}

Resolved is a project pinned to a concrete version.

func CompleteClosure

func CompleteClosure(roots map[string]string, dir string) ([]Resolved, error)

CompleteClosure resolves a package's declared closure, installs it, then iteratively reads the bottles' ELF DT_NEEDED and pulls whatever bottle provides each unsatisfied soname — the implicit glibc/gcc system libraries and the common undeclared libraries (libz, libbz2, ncurses…) that package.yml graphs omit — until every NEEDED soname is satisfied. This makes the closure complete enough to run on a `FROM scratch` image.

func MergeClosures

func MergeClosures(a, b []Resolved) []Resolved

MergeClosures appends the packages of b not already in a (dedup by project).

func ResolveClosure

func ResolveClosure(roots map[string]string) ([]Resolved, error)

ResolveClosure walks the runtime dependency graph breadth-first.

type Ver

type Ver struct {
	Raw  string
	Nums []int
}

Ver is a parsed pkgx version: its numeric components plus the raw string.

func FetchVersions

func FetchVersions(project string) ([]Ver, error)

FetchVersions returns the available versions of a project, ascending.

func ParseVer

func ParseVer(s string) Ver

ParseVer parses a pkgx version string into a Ver, stopping each component at the first non-numeric character (e.g. "1w" in openssl 1.1.1w).

func PickVersion

func PickVersion(project, constraint string) (Ver, error)

PickVersion returns the highest available version satisfying constraint.