Skip to content

pkgforge

pkgforge stages files into a build root and records their intended install metadata — mode, owner, group, type, and free-form key/value meta — in a file DB (JSON Lines by default; YAML or SQLite backends). That DB can then be dumped into packaging manifests such as an RPM %files list or Debian install + dirs + fixperms files, or, from a pkgforge.cfg, a whole RPM spec and debian/ directory for one or several packages. pkgforge verify checks the build root against the DB before you build, and pkgforge package writes the .deb, Arch, Alpine and tar packages itself (the .rpm through rpmbuild).

It is a small, dependency-light helper for unattended build pipelines on Linux: install a source into place, remember how it should be owned and permissioned, and emit that record for the packager.

Why pkgforge

  • One record, many packagers. Stage once, record once, dump to RPM or Debian from the same file DB.
  • Unattended-friendly. Environment-driven configuration (PKGFORGE_ROOT / PKGFORGE_DB), no interactive prompts, resilient defaults.
  • Pythonic and portable. Tar-family archives extract via stdlib tarfile (no external binary); bsdtar is only a fallback for formats it can't handle.
  • Built on duho. A declarative CLI with --version, shell completion, and PKGFORGE_* environment-variable defaults for free.

Install

pip install pkgforge
pip install 'pkgforge[yaml]'   # also the YAML DB backend (PyYAML)
pip install 'pkgforge[zstd]'   # also zstd packages below Python 3.14 (zstandard)

Requires Python 3.9+. Runtime targets Linux (it uses POSIX chmod/chown and symlinks); the CLI and --help import cleanly on any platform.

At a glance

work="$(mktemp -d)"
export PKGFORGE_ROOT="$work/stage" PKGFORGE_DB="$work/files.jsonl"
mkdir -p "$PKGFORGE_ROOT"
printf '[package]\nname = "tool"\n' > "$work/pkgforge.cfg"
export PKGFORGE_CONFIG="$work/pkgforge.cfg"

pkgforge initdb
pkgforge install -p -m 755 -o root -g root ./build/tool /usr/bin
pkgforge install -p -m 640 -o root -g adm -k config-noreplace ./tool.conf /etc
pkgforge install -D -d -m 755 -o root -g root --record-tree ./share /usr/share/tool
pkgforge dbdump -f rpmspecfiles rpm-files.txt
pkgforge dbdump -f debian debian/

See the Guide for the full command and format reference, and From pkgforge.cfg to packages to build packages.