Overview/xpkg — package builder

xpkg - Usage

How to install and drive xpkg: installation, the command surface, flags, configuration, and the typical packaging workflows.

Related documents in this folder:

• 01 - Overview and status
• 03 - Architecture
• 04 - Future integration

For full details on every command and flag, see the existing flat docs: CLI Reference, XBUILD Specification, Packaging Guide, Installation Guide, Source Management, Package Signing, Repository Management and Linting Rules.

Installation

Requirements: Rust 1.70+ (2021 edition), Cargo, and git. Optional runtime tools: fakeroot (preferred for rootless packaging, auto-detected) and strip (ELF stripping, from binutils).

git clone https://github.com/equislinux/xpkg.git
cd xpkg
cargo build --release
sudo install -Dm755 target/release/xpkg /usr/local/bin/xpkg

Configuration defaults work out of the box. To customise, copy etc/xpkg.conf.example to ~/.config/xpkg/xpkg.conf and edit it.

Commands

Global flags

build - Build a Package

Runs the full pipeline: parse recipe, fetch sources, prepare, build, check, package, strip, archive, sign.

xpkg build                             # Build from ./XBUILD
xpkg build -f path/to/XBUILD          # Build from a specific file
xpkg build --pkgbuild -f ./PKGBUILD   # Build from a PKGBUILD
xpkg build --no-check -o ./out        # Skip tests, output to ./out
xpkg build --sign                      # Build and sign the package

lint - Lint a Package Archive

Extracts the archive, reads .PKGINFO, and runs all lint rules.

xpkg lint hello-2.12-1-x86_64.xp
xpkg lint hello-2.12-1-x86_64.xp --strict

Lint categories: permissions, paths, metadata, dependencies, and ELF analysis. Recipe-level source-unpinned checks (sources with no usable checksum and no pinned Git commit/tag) run at the start of xpkg build and never stop the build. See Linting Rules for the complete list.

info - Display Package Metadata

Inspect a .xp archive without installing it.

xpkg info hello-2.12-1-x86_64.xp           # Human-readable metadata
xpkg info hello-2.12-1-x86_64.xp --files   # Include file listing
xpkg info hello-2.12-1-x86_64.xp --json    # JSON output for scripting

verify - Verify Package Integrity

Verifies the OpenPGP detached signature of a .xp package. Looks for a .xp.sig file alongside the package.

xpkg verify hello-2.12-1-x86_64.xp --key packager.pub
xpkg verify hello-2.12-1-x86_64.xp -k /etc/xpkg/trusted.gpg

new - Create an XBUILD Template

xpkg new hello                  # Creates hello/XBUILD
xpkg new mylib -o packages/     # Creates packages/XBUILD

srcinfo - Generate Source Info

Produces .SRCINFO-style output from a parsed and validated XBUILD.

xpkg srcinfo                     # Print to stdout
xpkg srcinfo > .SRCINFO          # Write output to .SRCINFO

repo-add / repo-remove / repo-prune - Repository management

Manage an ALPM-compatible database (myrepo.db.tar.zst by default; also .db.tar.gz and .db.tar.xz, auto-detected from the extension). The database is created automatically on first add.

xpkg repo-add myrepo.db.tar.zst hello-2.12-1-x86_64.xp
xpkg repo-add myrepo.db.tar.zst hello-2.12-1-x86_64.xp --sign
xpkg repo-add myrepo.db.tar.zst hello-2.12-2-x86_64.xp --keep 3  # retain 3 versions

xpkg repo-remove myrepo.db.tar.zst hello
xpkg repo-remove myrepo.db.tar.zst hello --sign

Adding an existing package name replaces the entry with the new version. repo-add also maintains history.json (schema 1) next to the database, recording every version still available for each package (version, filename, sha256, builddate, optional .sig and source provenance). The index is signed as history.json.sig when a signing key is configured (or --sign is passed); otherwise a stale signature is removed with a warning. With --keep N, the N newest versions per package (by builddate) plus the version exposed by the database are preserved and older files listed in the index are deleted; --keep 0 (default) disables pruning.

repo-prune applies the same retention policy to an existing repository and rewrites history.json:

xpkg repo-prune myrepo.db.tar.zst --keep 3           # keep the last 3 versions
xpkg repo-prune myrepo.db.tar.zst --keep 3 --dry-run # preview the sweep
xpkg repo-prune myrepo.db.tar.zst                    # keep only the current version

The version exposed by the database is never deleted, and files that are not listed in history.json are never touched. If the index is missing, repo-prune seeds it from the database entries whose files exist in the repository directory. See Repository Management for hosting instructions.

Exit codes

Environment variables

During builds, these variables are set for the build scripts:

Configuration

Configuration file: ~/.config/xpkg/xpkg.conf (TOML), or any path passed via --config. Key sections:

• [options] - builddir, outdir, sign, sign_key, compress method/level, strip_binaries
• [environment] - MAKEFLAGS, CFLAGS, CXXFLAGS, LDFLAGS
• [lint] - enable/disable linting, strict mode

[options]
builddir = "/tmp/xpkg-build"
outdir = "."
strip_binaries = true
compress = "zstd"       # zstd | gzip | xz
compress_level = 19

[environment]
makeflags = "-j$(nproc)"
cflags = "-march=x86-64 -O2 -pipe"
cxxflags = "-march=x86-64 -O2 -pipe"

See etc/xpkg.conf.example for every option.

Typical workflows

1. New package - xpkg new hello, edit hello/XBUILD, xpkg build, inspect with xpkg info, quality-check with xpkg lint, install with sudo xpm install hello-...-x86_64.xp.
2. Arch compatibility - keep an existing PKGBUILD and run xpkg build --pkgbuild -f ./PKGBUILD.
3. Publishing - xpkg repo-add x.db.tar.zst pkg-...-x86_64.xp inside the hosted directory; optionally --sign the database. Add --keep N to retain old versions and keep history.json populated, and use xpkg repo-prune <db> --keep N to sweep the repository later.
4. Reproducible builds - SOURCE_DATE_EPOCH=<epoch> xpkg build pins the metadata builddate and tar entry mtimes.
5. Signing setup - export a secret key to ~/.config/xpkg/signing.key, set sign = true and sign_key in the config, build with --sign.

Edit this page on GitHub