Cutting Gentoo Build Times with Binary Package Caching

The Problem: Rebuilding the Same Packages Everywhere

If you manage more than one Gentoo system — say a laptop, a server, and a CI runner — you've felt the pain of compiling identical packages three times over. Each emerge invocation burns CPU cycles and wall-clock time producing the same binaries for the same architecture. Gentoo's buildpkg FEATURE solves this by generating installable .tbz2 binary packages during every build, creating a local cache you can reuse across machines.

How buildpkg Works

When FEATURES="buildpkg" is set in /etc/portage/make.conf, Portage creates a binary package artifact after successfully compiling each ebuild. These .tbz2 files land in ${PKGDIR} (default /var/cache/binpkgs) organized by category. The binary captures the exact USE flag state, compiler flags, and dependency versions active at build time.

On a target machine, emerge --getbinpkg (or --usepkg / --usepkgonly) pulls the prebuilt artifact instead of invoking the compiler. This is not a new concept — it's the same mechanism Gentoo's official binary packages use — but buildpkg lets you produce them locally with your exact configuration.

Worked Example: Building and Reusing a Package

Assume two x86_64 systems with identical make.conf USE flags and ACCEPT_KEYWORDS="~amd64". On the builder machine:

# /etc/portage/make.conf
FEATURES="buildpkg"
PKGDIR="/var/cache/binpkgs"

Run the build (requires root or portage group membership):

emerge --buildpkg app-editors/vim

Verify the artifact exists:

ls -lh /var/cache/binpkgs/app-editors/vim-*.tbz2

Copy the .tbz2 to the target machine (via rsync, NFS, or a local HTTP server). On the target, install without recompilation:

emerge --getbinpkg app-editors/vim

Portage will fetch the binary from PKGDIR (or a configured PORTAGE_BINHOST) and install it. Check the emerge output for >> Installing binary package to confirm no compilation occurred.

Trade-offs and Limitations

• USE flag lock-in: A binary built with USE="-X -gtk" will not satisfy a dependency expecting USE="gtk". Keep make.conf synchronized across machines, or maintain separate binary repositories per flag profile.
• Disk growth: Each .tbz2 adds 10–200 MB. A full @world rebuild can consume 5–15 GB. Set up a cron job to prune old versions: eclean-pkg -t 30d (requires app-portage/gentoolkit).
• Architecture and ABI boundaries: Binaries are tied to CHOST, CFLAGS, and kernel headers. Do not copy x86_64 binaries to arm64, or -march=native builds across different CPU generations.
• distcc/ccache interaction: buildpkg works alongside distributed compilation, but the resulting binary reflects the compiler environment of the node that linked it. Ensure all distcc volunteers share the same toolchain version.

Verifying It Works

After enabling buildpkg, run a test build and confirm:

1. A .tbz2 appears in ${PKGDIR}/category/.
2. emerge --getbinpkg category/package on a second machine installs without invoking gcc or ld.
3. emerge --version shows Portage 3.x (behavior stable since 3.0; 2.x may differ).

If the binary install pulls source anyway, check emerge --pretend --getbinpkg output for use flag mismatches or missing PORTAGE_BINHOST configuration.

Next Steps

Enable FEATURES="buildpkg" on your fastest machine, point PKGDIR to a shared filesystem or sync target, and build your common package set once. Monitor /var/cache/binpkgs size weekly. For larger fleets, consider exposing PKGDIR via a simple HTTP server and setting PORTAGE_BINHOST on clients — turning your workstation into a private binary host without the overhead of a full binhost setup.