Overlay

Portage can look in multiple places for packages by using an overlay. The locations of overlays are controlled by the location variable in one or more repos.conf files.

The overlay should contain the same directory structure as PORTDIR (although only the necessary directories need be included). For example, a simple overlay might have a directory structure like:

overlay
|-- dev-util
    `-- gengetopt
        |-- Manifest
        |-- files
        |   `-- gengetopt-2.13-foobar.patch
        `-- gengetopt-2.13.ebuild

An overlay can be used to 'add' items to the tree (although you must ensure that /etc/portage/categories is used if any new categories are added) or to override existing entries.

Overlay and Eclasses

Be very careful when using eclasses in an overlay. Portage will not do cache updates when an overlay eclass is changed, nor will it do cache updates when a main Gentoo repository eclass which is used by an overlay ebuild changes. You may also encounter bogus 'illegal inherit' notices when working with eclasses in an overlay (see QA Notice: ECLASS foo inherited illegally). To be safe, manually touch all relevant overlay files after updating overlay eclasses.