gentoo-portage-config/README.md

Gentoo Portage: amd64, musl, LLVM

This repository is a versioned snapshot of the local /etc/portage policy on my Gentoo machine. It targets the default/linux/amd64/23.0/musl/llvm profile and x86_64-pc-linux-musl; it is not a generic Gentoo configuration. The profile selection itself remains a system symlink and is recorded here rather than copied into the repository.

The screenshot below shows the host and active Gentoo profile from the terminal. The captured kernel and package counts describe the system at screenshot time, not necessarily its current state.

Explicit world set

This is the host's /var/lib/portage/world snapshot, captured on 2026-10-15. It records packages selected explicitly with Portage; dependencies installed to satisfy them aren't necessarily listed here. The plain source list is also tracked as world.

app-admin/doas
app-editors/nano
app-editors/neovim
app-eselect/eselect-repository
app-misc/brightnessctl
app-misc/fastfetch
app-portage/gentoolkit
app-shells/fish
dev-cpp/cairomm
dev-lang/execline
dev-util/codex
dev-util/flatpak-builder
gui-apps/foot
gui-apps/grim
gui-apps/hyprpaper
gui-apps/hyprsunset
gui-apps/quickshell
gui-apps/slurp
gui-apps/tuigreet
gui-apps/wl-clip-persist
gui-apps/wl-clipboard
gui-libs/display-manager-init
gui-libs/greetd
gui-libs/hyprcursor
gui-libs/hyprland-guiutils
gui-wm/cage
gui-wm/hyprland
media-fonts/fontawesome
media-fonts/maple-mono
media-fonts/nerdfonts
media-gfx/imv
media-libs/gst-plugins-good
media-libs/libpulse
media-sound/pavucontrol
media-sound/playerctl
media-video/pipewire
net-misc/chrony
net-vpn/wireguard-tools
net-wireless/iwd
sys-apps/flatpak
sys-apps/pciutils
sys-apps/s6
sys-apps/s6-linux-init
sys-apps/s6-rc
sys-auth/seatd
sys-boot/efibootmgr
sys-boot/limine
sys-cluster/kubectl
sys-devel/mold
sys-firmware/intel-microcode
sys-fs/btrfs-progs
sys-fs/fuse:0
sys-kernel/cachyos-kernel
sys-kernel/dracut
sys-kernel/gentoo-kernel-bin
sys-kernel/gentoo-sources
sys-kernel/installkernel
sys-kernel/linux-firmware
sys-libs/gcompat
sys-process/htop
x11-themes/bibata-xcursors

Build contract

Setting	Current value	Effect
Profile	default/linux/amd64/23.0/musl/llvm	amd64, musl, LLVM profile defaults
CHOST	x86_64-pc-linux-musl	Build target tuple for the musl userspace
C/C++ flags	-march=native -O3 -pipe	Tune builds for the local CPU; resulting binaries are not portable to older or different CPUs
Rust	-C target-cpu=native	Apply the same local-CPU assumption to Rust builds
Linker	-fuse-ld=mold globally	Use mold for builds that honor LDFLAGS
Build parallelism	MAKEOPTS="-j4 -l5", emerge --jobs=4	Limit make jobs and concurrent emerge work
Global USE	wayland -X hyprland dbus wifi bluetooth system-pipewire pulseaudio	Set the desktop and service feature baseline
Licenses	ACCEPT_LICENSE="*"	Accept every license identifier; review this policy before reusing the config

The selected profile owns the system toolchain defaults; make.conf does not globally force CC or CXX. Compiler and resource changes are attached to package atoms through package.env. Some of those snippets select Clang/LLVM tools and LLD with ThinLTO, while the global linker is mold, so check the resolved environment for the package you are building instead of assuming one linker applies everywhere.

Repository map

The files at the repository root mirror /etc/portage:

Path	Role
make.conf	Global flags, USE policy, license policy, jobs, binary-package features, and mirrors
repos.conf/	Gentoo rsync configuration and Git overlays, including CachyOS kernels, GURU, Hyprland, LibreWolf, the local repository, and wfalkowski-overlay
binrepos.conf/	Signed Gentoo binary-package repository
package.use/	Directory-form per-package USE overrides, split into desktop, kernel, audio, and other groups
package.accept_keywords/	Narrow keyword exceptions for selected packages and overlays
package.unmask/	Local version policy exceptions; no local package masks are configured
package.env/, env/	Package-scoped environment files for compiler, linker, and resource settings
savedconfig/	Saved CachyOS kernel and linux-firmware package configuration
world	Captured explicit Portage world atoms from /var/lib/portage/world
bashrc	Portage package hooks, including Btrfs snapshots and a Firefox-specific Rust flag
usr/local/libexec/	Executable helpers called by the Portage hooks: Btrfs snapshot lifecycle and Limine menu maintenance

Btrfs and Limine hooks

bashrc calls portage-btrfs-snapshot after each package install and removal. The helper limits itself to operations against the live root, checks that / and /.snapshots are on the same Btrfs filesystem, requires at least 2 GiB free, creates read-only snapshots under /.snapshots/portage, and retains up to 32 of its own snapshots. When pruning, it removes the corresponding Limine recovery entry and writable clone before deleting the old read-only snapshot.

portage-limine-menu maintains /boot/limine.conf. After a sys-kernel install, the snapshot helper asks it to reconcile kernel entries and attach compatible snapshots. Other package installs create recovery entries when a compatible kernel/initramfs group exists; removals clean up the matching Limine entries and writable recovery clones. The manager validates the menu before writing it and keeps a one-time pre-change copy alongside the Limine config. Both scripts assume the host layout and Btrfs/Limine setup above; they are not portable drop-in hooks for another machine.

The scripts are stored at their corresponding paths under usr/local/libexec/ in this repository. To install or update them on this host, from the repository root:

doas install -D -m 0755 usr/local/libexec/portage-btrfs-snapshot /usr/local/libexec/portage-btrfs-snapshot
doas install -D -m 0755 usr/local/libexec/portage-limine-menu /usr/local/libexec/portage-limine-menu

Snapshot boundaries

The non-backup CachyOS kernel configs and the linux-firmware saved config are included. Portage’s generated ._cfg* merge candidates and timestamped backups are omitted; those are pending-update artifacts or historical copies, not active policy. /etc/portage/gnupg is also excluded because it can contain private signing keys and local trust state. The signed-binhost configuration is tracked, but its key material is not.

Applying the snapshot

First compare the target host’s state and profile; don’t copy this over a different ABI or profile. The diff excludes repository metadata and files deliberately omitted from the snapshot:

eselect profile show
emerge --info
diff -ru --exclude=.git --exclude=gnupg --exclude=make.profile --exclude=README.md --exclude=LICENSE --exclude=.gitignore --exclude=usr --exclude='._cfg*' --exclude='*~' --exclude='*.backup*' --exclude='*.bak*' /etc/portage .

After reviewing the diff, merge only the intended files into /etc/portage. This checkout also contains Git metadata, documentation, and ignore rules, so copying the repository root wholesale is not appropriate. Before any package operation, preview the resolver plan with emerge -pv and inspect USE, slots, keywords, masks, and removals.