projects

APKG Package System

Custom Gentoo package management tool built to learn Portage from the inside out

February 23, 2026

APKG Package System

apkg is a custom package management tool for Gentoo Linux. It wraps Portage’s emerge with a streamlined interface for common operations — searching, installing, updating, querying — while preserving full access to emerge’s capabilities underneath.

The important context: apkg was built intentionally to learn how Portage and emerge work at a deep level. Not by accident. Not because emerge is bad. It was a deliberate learning project: “I want to understand how Gentoo’s package manager actually works, and the best way to learn is to build something on top of it.” It turned into something genuinely useful along the way.

Why Build a Wrapper?

Portage is powerful but verbose. A typical Gentoo workflow involves remembering specific flag combinations, understanding the difference between --ask, --pretend, --verbose, and their shorthand equivalents, and knowing when to use --depclean vs --unmerge vs --prune. Experienced Gentoo users have this muscle memory. Newcomers (and tired engineers at midnight) don’t.

apkg doesn’t hide Portage’s complexity — it provides shortcuts to the common paths while keeping the full power available. Think of it as a convenience layer, not a replacement.

What apkg Is

  • A CLI tool that simplifies frequent Portage operations
  • A learning tool that helped the author understand emerge internals
  • A wrapper that calls emerge, equery, eix, and related tools under the hood
  • Part of the Argo OS ecosystem, designed for the driver workstation workflow

What apkg Is Not

  • A replacement for emerge (emerge is always available and sometimes necessary)
  • A package manager (Portage is the package manager; apkg is a frontend)
  • An abstraction that hides what’s happening (apkg shows you the emerge commands it runs)

Usage

Core Commands

# Search for packages
apkg search firefox
# Equivalent: eix firefox (or emerge --search firefox)

# Install a package (binary-only on driver systems)
apkg install www-client/firefox
# Equivalent: emerge --usepkg --usepkgonly www-client/firefox

# Remove a package
apkg remove www-client/firefox
# Equivalent: emerge --depclean www-client/firefox

# Check for available updates
apkg update
# Equivalent: emerge -puDN @world

# Full world update (binary-only)
apkg world
# Equivalent: emerge --usepkg --usepkgonly -uDN @world

# Show package info
apkg info www-client/firefox
# Equivalent: equery meta www-client/firefox + equery uses www-client/firefox

# List installed packages
apkg list
# Equivalent: qlist -I

# Show what depends on a package
apkg depends dev-libs/openssl
# Equivalent: equery depends dev-libs/openssl

# Check for broken packages
apkg check
# Equivalent: revdep-rebuild -p

Advanced Operations

# Sync the Portage tree
apkg sync
# Equivalent: emerge --sync

# Update the Portage tree and show available updates
apkg sync-and-check
# Equivalent: emerge --sync && emerge -puDN @world

# Clean old binary packages
apkg clean-binpkgs
# Removes old versions from the binhost directory

# Show USE flags for a package
apkg uses www-client/firefox
# Equivalent: equery uses www-client/firefox

# Show files installed by a package
apkg files www-client/firefox
# Equivalent: equery files www-client/firefox

# Pretend mode (show what would happen)
apkg install --pretend www-client/firefox
# Equivalent: emerge --pretend www-client/firefox

Integration with Build Swarm

When running on the driver system (Capella-Outpost), apkg is aware of the build swarm and integrates with it:

# Check for updates and submit to build swarm
apkg swarm-update
# 1. Runs emerge -puDN @world
# 2. Parses the package list
# 3. Submits to build swarm via build-swarm submit
# 4. Monitors build progress

# Check swarm status
apkg swarm-status
# Equivalent: build-swarm status

# Install after swarm build completes
apkg swarm-install
# Runs emerge --usepkg --usepkgonly -uDN @world

This is the full workflow in three commands: apkg swarm-update to submit, wait for the swarm to build, then apkg swarm-install to pull the binaries.

Architecture

Under the Hood

apkg is a command-line tool that maps user-friendly commands to Portage operations. When you run apkg install firefox:

  1. apkg resolves the package name — if you say firefox, it figures out you mean www-client/firefox
  2. apkg checks if this is a driver system — if yes, it adds --usepkg --usepkgonly flags automatically
  3. apkg constructs the emerge command with appropriate flags
  4. apkg shows you the command it’s about to run (transparency — you always know what’s happening)
  5. apkg executes the command and captures the output
  6. apkg formats the output for readability

The transparency part is intentional. apkg always shows you the actual emerge command before running it. This means every apkg invocation is also a learning moment — you see exactly what Portage flags map to what behavior.

Driver System Detection

apkg knows whether it’s running on a driver system (Capella-Outpost) or a build drone. On the driver, every install command enforces binary-only mode (--usepkg --usepkgonly). On a drone, installs use source compilation (--buildpkg to produce binaries).

The detection is based on hostname and the presence of a /etc/apkg/driver flag file. If both match, binary-only mode is enforced.

Package Name Resolution

Portage packages have a category/name format (www-client/firefox), but humans usually just say the name (firefox). apkg handles resolution:

  1. If the input contains a /, treat it as a full category/name
  2. If not, search for matching packages and:
    • If exactly one match, use it
    • If multiple matches, show the list and ask which one
    • If no matches, suggest alternatives

This prevents the annoying Portage error where you type emerge firefox and get scolded for not specifying the category.

Configuration

apkg’s configuration lives in /etc/apkg/:

/etc/apkg/
├── apkg.conf          # Main configuration
├── driver             # Flag file: this is a driver system (binary-only)
└── swarm.conf         # Build swarm integration settings

apkg.conf

[general]
# Show emerge command before execution
show_commands = true

# Ask for confirmation before destructive operations
confirm_remove = true

# Color output
color = true

[binhost]
# Binhost URL for binary package fetching
url = http://10.42.0.194/packages

[swarm]
# Enable build swarm integration
enabled = true
gateway_url = http://10.42.0.199:8090
orchestrator_url = http://10.42.0.201:8080

The Learning Journey

apkg exists because of a specific question: “How does emerge actually work?” Reading the Portage documentation answers part of it. Reading the Portage source code answers more. But building a tool that interacts with Portage’s infrastructure — querying the package database, resolving dependencies, managing USE flags, handling binary packages — forces you to understand all of it.

The journey produced several insights that are hard to get from documentation alone:

Dependency resolution is graph theory. Portage’s dependency resolver builds a directed acyclic graph of package dependencies, then performs a topological sort to determine build order. When you have circular dependencies (they exist, especially in the toolchain), Portage has to break the cycle by building with reduced features and rebuilding later. Understanding this made the build swarm’s dependency-aware queue make a lot more sense.

USE flags are not just compile-time options. They affect dependency resolution, binary compatibility, and package selection. A USE flag change can cascade through the entire dependency tree, pulling in new packages or removing old ones. apkg has to understand this to give accurate “what will change” previews.

The binary package format is simpler than expected. Gentoo binary packages (.tbz2, now .gpkg) are just tarballs with metadata. The binhost is just an HTTP server serving files. The matching logic between a binary package and a local system’s configuration is the complex part — USE flags, CFLAGS, and dependencies all have to match.

Slot conflicts are the worst. When two packages need different versions of the same library, Portage’s slot system usually handles it. When it doesn’t, you get slot conflicts that require manual resolution. apkg’s check command specifically looks for potential slot conflicts before they become a problem.

Interactive Playground

An interactive apkg tutorial is available on the Arcturus-Prime website at:

https://Arcturus-Prime.com/playground/apkg-tutorial

The playground provides a simulated terminal where you can run apkg commands against a mock package database without needing a Gentoo system. It’s designed for people who want to see what Gentoo package management looks like without spinning up a VM.

The tutorial walks through:

  1. Searching for packages
  2. Understanding USE flags
  3. Installing from binary packages
  4. Running world updates
  5. Integrating with the build swarm

apkg is part of the broader Argo OS ecosystem. For more context:

The blog series on Arcturus-Prime.com (homelab-series/) includes posts about apkg’s development, covering the design decisions, implementation challenges, and how building a Portage wrapper teaches you things that reading documentation can’t.

apkggentooportagepackage-managementargo-os