# 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.

![Gentoo Portage host information and active profile](screenshots/gentoo-portage-host.png)

## 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`](world).

```text
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, and local repositories |
| `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:

```sh
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:

```sh
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.