# AGENTS.md — kzd-ebuilds

Personal Gentoo overlay (repo_name `kzd`, see `profiles/repo_name`) maintained
by Kyle Dixon <kzd@56709.net>. Contains ~59 live ebuilds plus disabled ones; no
source code, no CI, no test suite. "Building" means an ebuild merges cleanly on
the maintainer's machine (Ryzen 9 7950X3D, `~amd64`, OpenRC desktop).

## Commands

There is no build/lint/test script, and **this git checkout is not what
Portage reads**. Two separate locations:

- `~/dev/kzd-ebuilds` — the working git checkout (user-owned). All edits and
  commits happen here. Portage ignores it.
- `/var/db/repos/kzd` — the root-owned clone Portage actually syncs from
  (`/etc/portage/repos.conf/eselect-repo.conf`, installed via eselect-repo).

`emerge` therefore cannot see anything until it is pushed to GitLab and the
serving clone is updated `sudo git -C /var/db/repos/kzd pull` — a root
operation the maintainer performs by hand. Agent workflow: commit locally, ask
the user to push (or push only when explicitly told), then ask the user to
root-pull the serving clone before any emerge test. Do not try to
copy/link ebuilds into `/var/db/repos` or override `location` in repos.conf to
short-circuit this.

Commands once working against the serving copy (all need root there):

```sh
# regenerate per-package Manifest (DIST lines) after adding/changing an ebuild
repoman manifest          # NOT installed on the maintainer box as of 2026-09; install with emerge app-portage/repoman if needed

# regenerate the committed metadata cache
emaint regenerate --to kzd    # use the repo_name ("kzd"), NOT the directory name ("kzd-ebuilds")

# validate a change
emerge -avv =<category>/<pkg>-<version>
```

`e` (eix) is the usual frontend on this machine; check availability before
assuming `emerge`/`equery` invocation style.

## Commit conventions

- Messages are terse and package-oriented: `zen 7.2.3`, `proton ge 11-6`,
  `cudnn 9.25 test`. Suffix `test` marks a not-yet-verified ebuild (common for
  CUDA/NVIDIA bumps).
- A "version bump" commit normally contains exactly: new `.ebuild` file, an
  added `DIST` line in that package's `Manifest`, and a new
  `metadata/md5-cache/<category>/<pkg>-<pv>` file.
- Cleanup commits delete old ebuild versions (sometimes via `git mv` to the new
  version with no content change) and trim Manifest DIST lines.
- Do not push; the maintainer pushes manually (remote is
  `git@gitlab.com:kzdixon/kzd-ebuilds.git`, private).

## Metadata & Manifest gotchas

- `metadata/layout.conf`: `masters = gentoo steam-overlay`,
  `thin-manifests = true`, `sign-manifests = false`. Thin manifests mean
  `Manifest` files contain **only `DIST` lines** — ebuilds and patches under
  `files/` are not checksummed there. Don't expect `AUX` entries.
- `metadata/md5-cache/` entries are committed to the repo. They are
  machine-generated; never hand-edit the `_md5_=` line or the full dependency
  expansion — regenerate with `emaint regenerate --to kzd`.
- Both Manifests and md5-cache drift: they contain stale entries for removed
  ebuilds (e.g. `metadata/md5-cache/app-misc`, `dev-games` categories no longer
  exist; `app-emulation/proton-ge-custom-bin/Manifest` keeps old DIST lines).
  This is tolerated; don't "fix" it unless asked.
- Obsolete ebuilds are usually **renamed to `*.ebuild.disabled`** rather than
  deleted (ROCm set, gamescope, mesa, bottles, etc.). Portage ignores them.
  Several package dirs (gamescope, mesa) contain only disabled ebuilds.
- Some packages lack `metadata.xml` entirely (e.g. `dev-libs/cudnn`); not every
  package has one.

## Ebuild conventions

- `EAPI=8` everywhere. Standard Gentoo header
  (`# Copyright ... Gentoo Authors` / `# Distributed under the terms of the GNU
  General Public License v2`).
- Never place `#` comments inside a quoted `RDEPEND=`/`SRC_URI=` string:
  portage then reports "masked by: invalid ... Invalid atom (#)" for the whole
  package. Comments go above the assignment. `pkgcheck scan` catches it.
- Single-impl packages (`DISTUTILS_SINGLE_IMPL=1`, e.g. `sci-ml/transformers`)
  have no `python_targets_*` USE flags — never decorate an atom for them with
  `[${PYTHON_USEDEP}]`; use a bare atom. The HF stack lives in `sci-ml/*`
  (huggingface_hub, tokenizers, safetensors, hf_xet, transformers), and Python
  ONNX Runtime is `sci-libs/onnxruntime[python]` in guru — not under
  `dev-python/`.
- Many ebuilds are copies of upstream overlay ebuilds with an attribution
  comment under the license header, e.g. `# modified from ebuild available in
  the touchfish-os overlay` or `# converted and modified from AUR ...`. Keep
  these comments when bumping.
- Provenance sources to consider when bumping: touchfish-os overlay (proton-ge,
  wine-mono, ultraleap meta), steam-overlay (listed in masters), AUR
  conversions, and the Gentoo tree.
- SLOT strategies vary per package; check before assuming:
  - `SLOT="${PV}"` — proton-ge-custom-bin, wine-mono (install-many-versions)
  - `SLOT="${PV%.*_*}"` — zen-sources (kernel series)
  - `SLOT="0/$(ver_cut 1-3)"` — cudnn
  - nvidia-cuda-toolkit keeps a commented-out toggle between slotted and
    unslootted (`SLOT="0/${PV}"` vs `SLOT="${PV}"`); flip only deliberately.
- Binpkg-style packages set `RESTRICT="mirror strip"` (plus `bindist`/`test`
  for NVIDIA) and silence prebuilt QA with `QA_PREBUILT` (proton-ge uses the
  `{*}` glob syntax).
- Multilib ebuilds (proton-ge) use
  `MULTILIB_COMPAT=(abi_x86_{32,64})` + `inherit multilib-minimal` and tag
  deps with `${MULTILIB_USEDEP}`.
- Live ebuilds use the `if [[ ${PV} == 9999 ]]` pattern with conditional
  `inherit git-r3` (`${GIT_ECLASS}` idiom in cmake-based ones). wivrn-9999 pins
  a fork branch via `EDIT_OVERRIDE_BRANCH_WIVRN_WIVRN="test/fence2"` — a
  nonstandard override; preserve unless the task says otherwise.
- Why some packages exist here at all: the tree lags on NVIDIA/CUDA
  (`dev-libs/cudnn` here is the `_cuda13` redist variant pinned to
  `=dev-util/nvidia-cuda-toolkit-13*`; the tree only ships `_cuda12`). cudnn
  honors a `CUDNN_PATH` env var override for side-by-side installs.
- zen-sources ebuilds derive the zen patch URI from `PV` with parameter
  expansion (`${PV%_*}-zen${PV#*p}`); a version bump only needs the new ebuild
  plus matching `K_GENPATCHES_VER`, and the SRC_URI/UNIPATCH names follow
  automatically. The zen patch is zstd-compressed, hence `inherit unpacker` +
  explicit `unpacker` call in `src_unpack`.
- proton-ge ebuilds carry huge explicit `keepdir` lists for the bundled Wine
  prefix; empty dirs must be preserved or base-prefix copying fails. Version
  naming maps `PV` like `11.6` → `GE-Proton11-6` (`${PV/./-}`); `_pNN` PVs map
  to `-rtspNN`-style release tags — verify against the actual GitHub release
  asset name when bumping.
- Patches live in per-package `files/` dirs, named
  `<pkg-or-version>-<description>.patch`; version-specific patches are common
  for NVIDIA/ROCm backports (e.g.
  `13.1.1-glibc-2.43-backport-from-13.2.1.patch`).

## profile / masking

- `profiles/package.mask` documents why each mask exists (hotfixed proton-ge
  releases, the PolyMC zip-import CVE, etc.). When masking, add a comment; when
  unmasking, confirm the reason no longer applies.
- There is no `profiles/eapi`, `arch.list`, or use.mask — do not add them
  without need. There is no `eclass` directory; all eclasses come from masters.

## Scope notes

- Everything is `~amd64`-centric; only a few packages keyword `~arm64`
  (zen-sources, cudnn, nvidia-cuda-toolkit) or `~x86` (zen-sources).
- VR/XR stack (WiVRn, Monado, OpenXR, Ultraleap) and gaming/Wine stack
  (proton-ge, gamemode, gamescope) are the two main clusters; ROCm cluster is
  fully disabled.
- `sys-kernel/zen-sources/log` is a merge-time benchmark log from the
  maintainer's box — informational only, appended by tooling, leave alone.