--- name: ebuild description: Writing, bumping or fixing an ebuild - a .ebuild file, metadata.xml, Manifest, a live 9999 ebuild, or packaging something for Gentoo that is not in the tree. --- # Ebuild Normative source is devmanual.gentoo.org, `ebuild(5)` and the eclass file itself. Training material is full of EAPI 5 and 6 idioms that the tree has since banned; check before reproducing one. `pkgcheck scan` runs as a hook on every write, so variable order, whitespace, unknown USE flags, deprecated dependencies and missing or unused inherits are reported automatically and are not repeated here. ## Before writing one An ebuild that already exists is not worth rewriting: `ls -d /var/db/repos/*/*/` covers every synced overlay, and GURU carries much of what the tree does not. Not there: copy the closest ebuild of the same build system out of `/var/db/repos/gentoo` and edit it. It already carries the right `inherit`, a current EAPI and the house formatting. Do not write one from memory. Own ebuilds go in the local overlay, `portageq get_repo_path / local`. Creating that overlay, its `repos.conf` entry, and the `package.accept_keywords` line that makes it installable: gentoo skill. ## Layout of a package `///-.ebuild`, beside it `metadata.xml`, `Manifest`, and `files/` for patches and small installed files (`${FILESDIR}`). The category must already exist. With `masters = gentoo` the list comes from `gentoo/profiles/categories`; a genuinely new one needs a `profiles/categories` in your own repo, or every command rejects the package. `metadata.xml` is not optional, and every `IUSE` flag that is not a global USE flag needs a `` entry in it. `pkgdev manifest` after any change to `SRC_URI` or `files/`. Never hand-edit `Manifest`. Version unchanged but the ebuild changed: bump the revision, `-r1`. New upstream version: new file, and the revision starts over. `${S}` defaults to `${WORKDIR}/${P}` and must point at the unpacked directory. A GitHub archive usually unpacks somewhere else, so set it explicitly and check against the tarball rather than guessing. `metadata/layout.conf` is per repo and inherits nothing from its master, so an overlay that does not repeat `eapis-banned` and `eapis-deprecated` gets no EAPI warning from `pkgcheck` at all. Do not read a silent scan as approval of the EAPI. ## EAPI `EAPI=8`, before any other statement. `gentoo/metadata/layout.conf` bans EAPI 0 to 6 and deprecates 7; EAPI 9 exists but is new, so use it only when asked. `eutils.eclass` was removed from the tree and `epatch` with it. `eapply` and the `PATCHES` array replace them. `RDEPEND` has not defaulted to `DEPEND` since EAPI 4. Write both out. `D`, `ED`, `ROOT`, `EROOT` and `SYSROOT` lost their trailing slash in EAPI 7: `"${ED}"/usr/bin`, never `"${ED}usr/bin"`. Helpers die on failure by themselves since EAPI 4. A plain command or a pipeline does not, so `|| die` those. ## Dependency classes `BDEPEND`: executed on the build host during the build. Compilers, `virtual/pkgconfig`, code generators, anything called from `src_*`. `DEPEND`: present in `${SYSROOT}` at build time. Headers and libraries that get linked against. `RDEPEND`: present at run time. Shared libraries, interpreters, data files, binaries the package calls. `IDEPEND`: executed on the build host during `pkg_preinst` and `pkg_postinst`. Icon and mime cache updaters. `PDEPEND` only to break a circular dependency, never for convenience. `BDEPEND` against `DEPEND` only matters when cross-compiling, so a host tool put in `DEPEND` builds fine here and breaks for someone else. Nothing but `pkgcheck` will say so. ## Eclasses The build system chooses the eclass, and the ebuild you copied already names it. `ls /var/db/repos/gentoo/eclass/` for what exists. Read the header of an eclass before inheriting it: `@SUPPORTED_EAPIS` says whether it works with yours, and `@DEPRECATED` names its replacement (`llvm.eclass` and `llvm-r1.eclass` both point at `llvm-r2.eclass`). Its `@ECLASS_VARIABLE` entries say what must be set *before* the `inherit` line. `PYTHON_COMPAT`, `LUA_COMPAT`, `CRATES` and their kind are read at inherit time and do nothing when set after it. Overriding a phase an eclass exports means calling the eclass version inside yours, `cmake_src_configure` and so on, or its work is silently dropped. When two eclasses export the same phase, the last `inherit` wins. Easy to miss because nothing prompts for them: `acct-user` and `acct-group` for a daemon's own user, `optfeature` for suggestions, `verify-sig` for upstream signatures, `readme.gentoo-r1`, `tmpfiles`, `fcaps`. ## Phases The default `src_prepare` applies `PATCHES` and then calls `eapply_user`. Overriding it without calling `default` silently drops the user's `/etc/portage/patches`. `PATCHES=( "${FILESDIR}"/${P}-fix.patch )` is how a package gets patched; the build-system eclasses route through the same default. Install through the helpers: `dobin`, `dolib.so`, `insinto` with `doins`, `newbin`. Never `cp` into `"${D}"`, because the helpers set the permissions and handle prefix. Do not strip, compress or install documentation by hand. `DOCS=( ... )` plus `einstalldocs`, which the eclasses already call. `test` in `IUSE` needs `RESTRICT="!test? ( test )"`, or the tests run even with the flag off. A live ebuild is version `9999`, inherits `git-r3`, sets `EGIT_REPO_URI`, and has `KEYWORDS=""` present and empty. A keyworded live ebuild is a bug. `network-sandbox` is on by default, so nothing may fetch during `src_*`. A build system that downloads its own dependencies needs them in `SRC_URI` through the mechanism its eclass provides, not a `RESTRICT` that switches the sandbox off. ## Verify `ebuild clean install` runs every phase up to install, into `/var/tmp/portage///`, without merging anything. That is the loop to iterate in. Any earlier phase name stops there and runs the ones before it, unless a previous invocation already did; `clean` is what resets that. Then the real thing, `emerge -av /::`, and read what it proposes to pull in.