tpkg — POSIX package builder and manager

tpkg is a minimalist, POSIX-compliant packaging tool written in Go. It builds software from source, packs it into compressed tar archives with PAX extended headers, installs packages to the system, and resolves dependencies — all without dpkg, RPM, or any external package format.

Features

• Build — execute build steps in an isolated temp directory, capture stdout/stderr, abort on failure.
• Pack — create .tpkg.gz or .tpkg.bz2 archives with PAX extended headers and a replicated PKG-INFO file for integrity validation.
• Install — install from a local .tpkg.gz file or resolve by name from a repository index. Detects file conflicts and prevents overwrites.
• Remove — uninstall by package name, remove files in reverse order, clean up empty directories, update the database.
• Dependency resolution — semver constraint parsing (>=, <=, =, ~>), transitive dependency resolution, cycle detection, topological install order.
• Repository support — JSON-based repo index, tpkg update to refresh metadata, name-based install with full dep graph resolution.
• Staging — --root flag for container-safe installs to alternate roots; DESTDIR support in build steps.
• POSIX sh test harness — shell-based integration tests covering pack roundtrip, conflict detection, root isolation, and dependency resolution.
• No runtime dependencies — single static binary, pure Go, no external package manager required.

Installation

From source

go install git.lan.thwap.org/thwap/tpkg/cmd/tpkg@latest

Bootstrap script

sh -c "$(curl -fsSL https://git.lan.thwap.org/thwap/tpkg/raw/branch/main/contrib/bootstrap.sh)"

Or clone and run manually:

git clone https://git.lan.thwap.org/thwap/tpkg.git
cd tpkg
go build -o tpkg ./cmd/tpkg
install tpkg /usr/local/bin/

Usage

Creating a package

Create a package.yaml in your source tree:

name: hello
version: 1.0.0
build_steps:
  - ./configure --prefix=/usr
  - make
install_steps:
  - make install DESTDIR="$DESTDIR"
artifacts:
  - usr/bin/hello

Build and pack:

tpkg build --source=.
tpkg pack --source=./pkg --output=hello-1.0.0.tpkg.gz

Installing a package

# From a file
tpkg install hello-1.0.0.tpkg.gz

# With staging (no writes outside root)
tpkg install --root=/tmp/staging hello-1.0.0.tpkg.gz

# From a repository by name
tpkg install --repo=/var/lib/tpkg/repo.json hello

Removing a package

tpkg remove hello

Repository management

# Refresh the local repo index
tpkg update --url=https://repo.example.com/tpkg/repo.json

package.yaml reference

Field	Type	Description
name	string	Package name (required)
version	string	Semver major.minor.patch (required)
dependencies	map	name: constraint pairs (>=, <=, =, ~>)
build_steps	list	Shell commands run via sh -c during tpkg build
install_steps	list	Commands run with DESTDIR set to the staging root
artifacts	list	Files/dirs to include in the package archive

Archive format

tpkg archives are standard tar streams (optionally gzip or bzip2 compressed) with the following structure:

1. PAX global extended header (TypeXGlobalHeader) — metadata (name, version, dependencies) as PAX key-value records.
2. PKG-INFO — plain-text file replicating the PAX records for validation.
3. File entries — each artifact as a regular tar entry.

On extraction, the PAX records and PKG-INFO are compared; any mismatch causes the operation to abort.

Database

Installed packages are tracked in /var/lib/tpkg/db.json (or under the --root prefix). Each entry records the package name, version, and a file manifest with SHA-256 checksums.

Commands

Command	Description
tpkg build	Run build steps in an isolated temp directory
tpkg pack	Create a .tpkg.gz/.tpkg.bz2 archive from a staged root
tpkg install	Install a package (from .tpkg.gz file or repo name)
tpkg remove	Uninstall a package by name
tpkg update	Refresh the local repository index

Development

Prerequisites

• Go 1.25+

Building

git clone https://git.lan.thwap.org/thwap/tpkg.git
cd tpkg
go build -o tpkg ./cmd/tpkg

Running tests

# Go unit tests
go test ./...

# Shell integration test harness
go build -o tpkg ./cmd/tpkg
PATH="$PWD:$PATH" sh tests/run_tests.sh

Linting

golangci-lint run --config=.golangci.yml ./...

Project structure

├── cmd/tpkg/           # CLI entry point
│   ├── main.go        # Command dispatch
│   ├── pack.go        # tpkg pack
│   ├── build.go       # tpkg build
│   ├── install.go     # tpkg install
│   ├── remove.go      # tpkg remove
│   └── update.go      # tpkg update
├── internal/
│   ├── archive/       # PAX tar archive creation/extraction
│   ├── builder/       # Isolated build step execution
│   ├── compress/      # gzip/bzip2 compression wrappers
│   ├── db/            # Installed package database (JSON)
│   ├── pax/           # PAX extended header read/write
│   ├── resolver/      # Dependency graph resolver
│   └── version/       # Semver parsing and constraint matching
├── pkg/models/         # Core data structures
├── tests/              # POSIX shell test harness
├── man/                # Man page sources (mdoc)
└── contrib/            # Bootstrap script and example files

License

MIT