Overlay FAQ
This document covers common issues or questions about ChromiumOS's use of Portage overlays. See also the Ebuild FAQ for information about ebuilds.
Gentoo has its own documentation on ebuild repositories (a.k.a., "overlays") and their repository format.
How do I write a metadata/layout.conf file?
The metadata/layout.conf file describes some properties of an overlay repository. While Gentoo provides documentation for metadata/layout.conf, it's important to note that ChromeOS extends the usage of the masters field with some unique behavior.
Particularly, ChromeOS uses the masters field to construct a sysroot's
PORTDIR_OVERLAY variable, which determines the set of visible overlays. This
ChromeOS-specific logic transitively (unlike Gentoo's use, which does not
inherit from parents) walks the masters from each entry, starting with any
existing overlay-${BOARD}-private and overlay-${BOARD}. Some useful tips:
- Include private repositories after public ones. The masters list is in reverse priority order: later entries take precedence.
- Always include your parent repositories; even if things work for you today,
you might be leaving a confusing problem for future developers who might
inherit from your overlays, if the transitive inclusion or implied
${BOARD}/${BOARD}-privatehandling lines up differently.
Note that this walk is recursive, which means we will walk every item's private and regular overlay, until we have walked the whole tree.
Profiles
Whereas the metadata/layout.conf has the masters list where the list of
overlays populated, the profiles/{profile}/parent file contains profiles from
which configs are pulled.
Overlays
portage-stable
The src/third_party/portage-stable/ tree is an overlay containing the majority
of the unmodified packages from upstream Gentoo. Developers can utilize the
cros_portage_upgrade tool to automatically
import packages.
"Unmodified" isn't exactly true. A number of modifications are made to ebuilds when importing from upstream. The spirit of this overlay is to simplify the upgrade process: updates can be made without having to review any changes to previous versions. So along those lines, changes that are made, or allowed:
- Change
KEYWORDS="*". - Downgrade
EAPIversions in case Gentoo uses a newer version our current portage version does not yet support. - Fixes that have been sent upstream Gentoo (via PR's to Gentoo's GH).
- In limited situations, cherry-picks from newer versions. We have a much stronger preference to upgrade to newer versions, so this situation has to be justified (e.g. an important security fix).
chromiumos-overlay
The src/third_party/chromiumos-overlay/ tree contains public first-party
packages, as well as forked upstream packages.
For example, if we need to apply custom patches to Gentoo ebuilds, they should be moved to this overlay. That way when the package gets upgraded, developers closely review the existing ebuild & patches to forward port those changes.
Try to include a README.md in the package directory providing some details as
to what/why the package has been forked.
eclass-overlay
The src/third_party/eclass-overlay/ tree contains custom & forked eclasses.
It is generally not expected for modifications to be done to this tree.
Board overlays
The src/overlays/ tree contains all the boards & projects. This is where
the software meets the hardware.