the Chromium logo

The Chromium Projects

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:

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.


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.



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:


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 in the package directory providing some details as to what/why the package has been forked.


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.