Ebuild repository

An overlay is an additional repository that Portage takes into account when dealing with software.

Within Gentoo Linux, users already have one "main" package repository, called the Portage tree. This main repository contains all the software packages (called ebuilds) maintained by Gentoo developers. But users can add additional repositories to the tree that are "layed over" the main tree - hence the name, overlays.

Since package repositories are nothing more (or less) than a set of files (ebuilds, metadata files, ChangeLog entries ...) these repositories can be pulled in from public repositories (git, cvs, svn ...) or downloaded as tarballs and extracted manually onto the system. It is advised to use managed repositories by trusted third parties; any installed overlay will cause Portage to look through the overlayed files when deciding which software to install. If compromised code is in the overlay, then compromised packages could be installed on the system.

Treatment of overlays
Portage can use the method (see /etc/portage/repos.conf) and also supports older layman versions (< 2.3.0) with the  method.

Manually setting overlay locations
There are two supported ways to manually set overlay locations. The first one uses a configuration directory called which, alternatively could also be a file in which Gentoo portage trees (repositories) can be configured, ordered and tuned. The second method is the (old) declaration of local overlays.

For more information, please refer to /etc/portage/repos.conf and.

Add user to Portage group
To add a user to the portage group, use the gpasswd command like so:

See also adding a user to a group.

Using crossdev
crossdev will automatically place the ebuilds/categories it generates into the first overlay found in. Most users will want to prevent crossdev from disturbing layman's overlays or the user's personal per-machine overlay (normally created at ). Create an overlay specifically for crossdev's use:

Then instruct Portage and crossdev to use this overlay:

Using layman
The layman application makes it easier to manage and update multiple additional overlays. It is a command-line application through which publicly available overlays can be listed, subscribed to and unsubscribed from, as well as update those repositories.

For more information, see Layman.

Local overlay
Systems can be configured to add additional local overlays. These are directory structures on the system which are made part of the set of repositories accessible by the system.

For more information, see.

Syncing
When the added repositories are configured with automatic synchronization, then running emerge --sync will update those repositories as well. If that is not the case, then the repository synchronization will need to happen manually.

For more information, see Operation in the Sync article.

Overlay priorities
Each overlay has its unique priority. This makes sure that in the case of a specific version being found in several overlays, the resolution is unambiguous. Ebuilds from overlays with higher priorities take precedence over ebuilds from overlays with lower priorities.

The list of overlays with their priorities can be obtained through the output of the following command

Unless the  variable has been modified as described below, the default Gentoo Portage tree will have a priority of -1000. That means that all other overlays take precedence. That is the default behavior, because overlays are designed to "lay over/on top" of the portage tree.

Setting overlay priorities
It is possible to prioritize one repository over another. When a package is available in multiple repositories, then Portage will use the one declared in the highest-ranking repository.

For more information, see Attributes supported in sections of repositories in the repos.conf article.

Repository Constraints
For overlay specific masking, unmasking, keywording, USE-flagging in the files see the section   in man 5 portage and Version_specifier.

Using unsafe overlays
When using huge overlays or those with unknown/low quality it is best practice to hardmask the whole overlay.

After that unmask the packages that will be installed.

This way nothing weird will happen on updates and it is safer than using priorities.

Cache generation
When large overlays are installed, portage may take a long time to perform operations like dependency resolution. This is because overlays do not usually contain a metadata cache.

Generate a local metadata cache by running emerge --regen after syncing the overlays:

Be careful, because emerge --regen takes a lot of time and it's not recommended for rsync users as rsync updates the cache using server-side caches (most of users of portage are rsync users). Rsync users should simply run emerge --sync (or eix-sync) to regenerate the cache. It's probably only users of very large overlays should try emerge --regen</tt>.

eix-sync
eix-sync</tt> can run emerge --regen</tt> after syncing the overlays and portage tree.

eix-update
eix-update</tt> can utilize the metadata cache generated by emerge --regen</tt> for a speedup and better accuracy. To enable this, set the  to   in.