X Package Manager

Modern, high-performance package manager written in pure Rust for X

Menu

• Overview
• Key Features
• Installation
• Quick Install (Published Package)
• Build From Source
• Usage
• Progress Bars
• Pacman-Style Aliases
• Global Flags
• Configuration
• Signed Repository Bootstrap
• Key Bootstrap Checklist (xpm Native Repository)
• Signature Troubleshooting
• Repository Management
• Project Structure
• Technical Architecture
• Dependency Resolution
• Package Format
• Security
• Repository Hosting
• Relationship with xpkg
• Roadmap
• License
• Command Cheatsheet
• X

Overview

xpm is a native Rust replacement for pacman and libalpm, designed for the X distribution. It uses the .xp package format (X Package) natively and maintains compatibility with Arch Linux .pkg.tar.zst packages. Packages are built with xpkg, the companion builder tool.

Key Features

• Pure Rust - zero C dependencies at any stage
• Native .xp format - X Package format (tar.zst) with .PKGINFO / .BUILDINFO / .MTREE metadata
• SAT-based dependency resolver - powered by resolvo with CDCL and watched-literal propagation
• Arch compatible - reads .pkg.tar.zst packages and alpm-repo-db databases
• Flexible repository management - predefined and temporary repos with xpm repo add/remove/list
• OpenPGP verification - detached signatures with Web of Trust model
• TOML configuration - clean, human-readable config at /etc/xpm.conf

Installation

Quick Install (Published Package)

Install the latest published xpm build directly from the official repository:

curl -fsSL https://raw.githubusercontent.com/equislinux/xpm/main/install.sh | bash

If curl is not available:

wget -qO- https://raw.githubusercontent.com/equislinux/xpm/main/install.sh | bash

Optional environment variables for the installer:

• XPM_PKG_URL: override the package URL (for testing another build)
• INSTALL_PREFIX: change install prefix (default: /usr/local)

Example:

INSTALL_PREFIX=/usr XPM_PKG_URL="https://equislinux.github.io/x-repo/x/x86_64/xpm-0.1.0-4-x86_64.xp" \
curl -fsSL https://raw.githubusercontent.com/equislinux/xpm/main/install.sh | bash

Build From Source

git clone https://github.com/equislinux/xpm.git
cd xpm
cargo build --release
sudo cp target/release/xpm /usr/local/bin/

Usage

# Sync package databases
xpm sync

# Install packages
xpm install <package> [<package>...]

# Remove packages
xpm remove <package>

# System upgrade
xpm upgrade

# Search packages
xpm search <query>

# Query installed packages
xpm query

# Package info
xpm info <package>

# List files owned by a package
xpm files <package>

# Manage repositories
xpm repo list
xpm repo add <name> <url>
xpm repo remove <name>

Progress Bars

Progress is split into independent phases; there is no combined download | verify | extract line.

• Downloads (per package and the aggregate Downloading packages line) use x fill: [xxxxxxxxxx----------].
• Verification uses / fill: Verifying signatures [//////////----------].
• Install/upgrade uses a separate Installing packages bar with / fill.
• Removal uses a separate Removing packages bar with / fill.

--noprogressbar or XPM_NO_PROGRESS=1 disables rendering. xpm-aur uses x for sync/ resolve and / for build/install phases.

Pacman-Style Aliases

Alias	Command
xpm Sy	xpm sync
xpm S <pkg>	xpm install <pkg>
xpm R <pkg>	xpm remove <pkg>
xpm Su	xpm upgrade
xpm Q	xpm query
xpm Ss <query>	xpm search <query>
xpm Si <pkg>	xpm info <pkg>
xpm Ql <pkg>	xpm files <pkg>

Global Flags

Flag	Description
-c, --config <PATH>	Custom configuration file
-v, --verbose	Increase verbosity (-v, -vv, -vvv)
--no-confirm	Skip confirmation prompts
--root <PATH>	Alternative installation root
--dbpath <PATH>	Alternative database directory
--cachedir <PATH>	Alternative cache directory
--no-color	Disable colored output

Performance

xpm install parses each package archive once for metadata, then extracts pure installs (no .INSTALL scriptlets) in parallel across available cores. Downloads and signature checks use up to parallel_downloads workers (default 10). Progress is rendered per phase (download, verify, install/remove) so parallel workers do not interleave output and each phase has a distinct bar.

# Compare an installed xpm with a local build (network-free):
cargo build --release -p xpm
scripts/bench-install-local.sh --old /usr/bin/xpm --new target/release/xpm

# Override the extraction worker cap (default: min(available CPUs, 8)):
XPM_EXTRACT_WORKERS=4 xpm install --needed ...

Set XPM_NO_PROGRESS=1 or pass --noprogressbar to disable phase progress in scripts.

Configuration

Configuration file: /etc/xpm.conf (TOML format).

See etc/xpm.conf.example for all available options.

[options]
root_dir = "/"
db_path = "/var/lib/xpm/"
cache_dir = "/var/cache/xpm/pkg/"
gpg_dir = "/etc/xpm/gnupg/"
sig_level = "optional"
parallel_downloads = 10

[[repo]]
name = "x"
server = [
        "https://equislinux.github.io/x-repo/x/$arch",
]

Optional additional repositories can be appended as extra [[repo]] blocks.

The keyring directory resolves at runtime through effective_gpg_dir(): the configured gpg_dir wins when it exists, then the native xpm keyring (/etc/xpm/gnupg). Pacman's keyring is used only when it is configured explicitly, for compatibility.

Signed Repository Bootstrap

To enforce signature verification from the official repository, install the published trusted keyring and switch the repository to required mode:

# System-wide keyring directory used by xpm (must match gpg_dir in config)
sudo install -d -m 755 /etc/xpm/gnupg

# Download repository public keyring
sudo curl -fsSL \
        https://equislinux.github.io/x-repo/x/x86_64/trustedkeys.gpg \
        -o /etc/xpm/gnupg/trustedkeys.gpg

# Optional: keep the ASCII-armored public key for auditing
sudo curl -fsSL \
        https://equislinux.github.io/x-repo/x/x86_64/signing.pub \
        -o /etc/xpm/gnupg/signing.pub

Then set:

[options]
gpg_dir = "/etc/xpm/gnupg/"
sig_level = "required"

You can also override per repository:

[[repo]]
name = "x"
server = ["https://equislinux.github.io/x-repo/x/$arch"]
sig_level = "required"

Key Bootstrap Checklist (xpm Native Repository)

Use this checklist to avoid signature-related install failures when consuming the X native .xp repository:

# 1) Ensure keyring directory exists
sudo install -d -m 755 /etc/xpm/gnupg

# 2) Import published keyring + public key
sudo curl -fsSL https://equislinux.github.io/x-repo/x/x86_64/trustedkeys.gpg \
        -o /etc/xpm/gnupg/trustedkeys.gpg
sudo curl -fsSL https://equislinux.github.io/x-repo/x/x86_64/signing.pub \
        -o /etc/xpm/gnupg/signing.pub

# 3) Confirm /etc/xpm.conf points to x endpoint and required signatures
sudo tee /etc/xpm.conf >/dev/null <<'EOF'
[options]
root_dir = "/"
db_path = "/var/lib/xpm/"
cache_dir = "/var/cache/xpm/pkg/"
gpg_dir = "/etc/xpm/gnupg/"
sig_level = "required"
parallel_downloads = 10

[[repo]]
name = "x"
server = ["https://equislinux.github.io/x-repo/x/$arch"]
sig_level = "required"
EOF

# 4) Sync and install from signed .xp repository
sudo xpm sync
sudo xpm install xpkg

Signature Troubleshooting

• signature required but could not be downloaded:
  • Check that .sig exists for package/database in x/x86_64 endpoint.
• failed to load keyring or no certificates found in keyring:
  • Confirm gpg_dir and trustedkeys.gpg path in /etc/xpm.conf.
• signature is valid but key is unknown:
  • Refresh /etc/xpm/gnupg/trustedkeys.gpg from published endpoint and re-sync.
• Package not found:
  • Confirm xpm repository URL is https://equislinux.github.io/x-repo/x/$arch and not the pacman endpoint under /repo/x86_64.

Repository Management

Predefined repositories are configured in /etc/xpm.conf. Temporary repositories can be added at runtime with xpm repo add and are stored in /etc/xpm.d/.

Project Structure

xpm/
├── Cargo.toml                  # Workspace root
├── crates/
│   ├── xpm/                    # Binary crate (CLI frontend)
│   │   └── src/
│   │       ├── main.rs         # Entry point, logging, config, dispatch
│   │       └── cli.rs          # clap CLI definition
│   └── xpm-core/               # Library crate (core logic)
│       └── src/
│           ├── lib.rs           # Module root
│           ├── config.rs        # TOML configuration parser
│           ├── error.rs         # Error types
│           └── repo.rs          # Repository manager
├── etc/
│   └── xpm.conf.example        # Example configuration
└── ROADMAP.md                   # Development roadmap

Technical Architecture

Dependency Resolution

xpm uses a logic-based SAT solver (resolvo) that transforms package relationships into CNF boolean clauses:

Requirement	CNF Clause	Meaning
Dependency	!foo OR bar	If foo is installed, bar must be too
Root requirement	foo	Target package is mandatory
Conflict	!bar_v1 OR !bar_v2	Mutually exclusive versions

The solver implements Unit Propagation with watched literals and Conflict-Driven Clause Learning (CDCL) for efficient backtracking.

Package Format

Packages use the ALPM .pkg.tar.zst format with Zstandard compression:

• .PKGINFO - package name, version, dependencies
• .BUILDINFO - reproducible build environment
• .MTREE - file integrity hashes
• .INSTALL - optional pre/post install, upgrade, and remove scripts (executed by xpm during transactions)

Security

• OpenPGP detached signatures (.sig) for packages and databases
• Web of Trust model for key validation
• Fakeroot build environment for safe package creation
• Package linting framework for quality assurance

Repository Hosting

The default package repository is hosted on GitHub Pages at equislinux.github.io/x-repo (organization equislinux). xpm supports any HTTP-based static file server, making future migrations transparent.

Relationship with xpkg

xpm and xpkg are complementary tools in the X ecosystem. They share the same package format and metadata structures but are independent binaries.

Tool	Role	Analogy
xpm	Package manager — install, remove, upgrade, resolve deps	pacman
xpkg	Package builder — compile, package, lint, manage repos	makepkg + repo-add + namcap

xpkg produces .xp packages that xpm installs. During installation, xpm executes any .INSTALL scriptlets generated by xpkg (post_install, pre_upgrade, etc.) and verifies signatures created during the build process.

See the Integration Guide for detailed information about how the tools work together.

Roadmap

See ROADMAP.md for the full development roadmap.

Version	Milestone
v0.1.0	Functional CLI with configuration
v0.5.0	Native engine (resolver + packages + repo db)
v0.8.0	Security and transaction management
v1.0.0	Benchmarked, tested, production-ready

License

GPL-3.0-or-later. See LICENSE.

Command Cheatsheet

# Sync repositories
xpm sync

# Install package(s)
xpm install <pkg>
xpm install <pkg1> <pkg2>

# Install without prompt
xpm install --no-confirm <pkg>

# Remove package(s)
xpm remove <pkg>

# Upgrade all installed packages
xpm upgrade

# Search package
xpm search <query>

# Package info
xpm info <pkg>

# List files owned by a package
xpm files <pkg>

# Query local packages
xpm query

# Show configured repos
xpm repo list

X

X Web & X Profile

- Documentation: https://github.com/equislinux/wiki