gentoo fundamentals intermediate 15 min

Binary Package Distribution

Understanding binary package distribution in Gentoo Linux - compile once, deploy everywhere

Binary Package Distribution

What It Is

A package distribution model where one system (binhost) compiles all packages from source, creating binary packages that other systems (drivers) install directly without compilation.

Why It Matters

Gentoo’s power comes from source compilation with custom flags—but this takes 20+ hours for a full system. Binary distribution provides 90% time savings while maintaining optimization benefits.

The tradeoff is simple: you sacrifice some per-system customization for dramatic speed improvements. For most use cases, especially workstations with identical hardware profiles, this is an excellent deal.

Architecture Overview

Binhost (Compile Server)        Driver (Client System)
├── Compiles all packages       ├── Pulls binaries via SSH/HTTP
├── Creates .gpkg.tar files     ├── Never compiles
├── Serves via SSH/HTTP         ├── 90% faster installs
└── Daily automated updates     └── Matches binhost config

Key Concepts

The Binhost

The binhost is a dedicated system that:

  • Has FEATURES="buildpkg" enabled
  • Compiles every package from source
  • Stores binary packages in /var/cache/binpkgs/
  • Serves packages via HTTP or SSH

The Driver

Driver systems:

  • Use FEATURES="getbinpkg" to prefer binaries
  • Match the binhost’s USE flags and configuration
  • Fall back to source compilation when binaries aren’t available
  • Install packages in minutes instead of hours

The GPKG Format

Modern Portage uses the GPKG format for binary packages:

  • Path: /var/cache/binpkgs/{category}/{name}-{version}.gpkg.tar
  • Example: /var/cache/binpkgs/kde-frameworks/kconfig-6.22.0.gpkg.tar
  • Self-contained archives with metadata

Configuration

Binhost Configuration

# /etc/portage/make.conf on binhost
FEATURES="buildpkg"
PORTAGE_BINHOST=""  # Not needed on the binhost itself

Driver Configuration

# /etc/portage/make.conf on driver
FEATURES="getbinpkg binpkg-ignore-signature"
PORTAGE_BINHOST="ssh://[email protected]/var/cache/binpkgs"
EMERGE_DEFAULT_OPTS="--usepkg --usepkgonly"

Critical Requirements

Configuration Matching

The driver must match the binhost’s:

  • USE flags - Mismatches cause missing features or compilation
  • PYTHON_TARGETS - Python version bindings must align
  • Gentoo Profile - Must use the same profile
  • CFLAGS - Architecture must be compatible (binhost’s -march must work on drivers)

Network Accessibility

The driver needs to reach the binhost:

  • SSH-based transport (most secure)
  • HTTP/HTTPS transport (simpler setup)
  • Local network or VPN connection

Practical Example

Installing KDE Plasma with binary packages:

# Without binhost: 8-12 hours
emerge kde-plasma/plasma-meta

# With binhost: 30-45 minutes
PORTAGE_BINHOST="ssh://[email protected]/var/cache/binpkgs" \
emerge --usepkg --usepkgonly kde-plasma/plasma-meta

That’s the same result in a fraction of the time.

Scaling Up: The Build Swarm

When one binhost isn’t enough, the Build Swarm architecture distributes compilation across multiple nodes:

  • 5 drones with 66 total cores
  • 140GB combined RAM
  • Cross-network deployment via Tailscale
  • Atomic releases with staging/production split

See the Build Swarm Architecture for details.

  • Portage - Gentoo’s package manager that handles binary packages
  • Build Swarm - Distributed compilation system
  • Btrfs Snapshots - Safety net when updates go wrong
gentoobinary-packagesportageinfrastructure