Within Gentoo Linux, users already have one "main" package repository. The main repository contains all the software packages (called ebuilds) maintained by Gentoo developers. Additional package trees are usually hosted by repositories. Users can add such additional repositories to the tree that are "laid over" the main tree - hence the name, overlays.
Package repositories are nothing more (or less) than a set of files (ebuilds, metadata files, ChangeLog entries ...). These 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 overlaid files when deciding which software to install. If compromised code is in the overlay, then compromised packages could be installed on the system.
The now default approach for handling repositories is through /etc/portage/repos.conf which, like many other Portage related locations, can be a directory as well.
Repository definitions inside /etc/portage/repos.conf/ also inform Portage if and how the repository can be updated. With it, calling emerge --sync will automatically update the repositories as well.
A deprecated, yet still supported method is to use the PORTDIR_OVERLAY variable inside /etc/portage/make.conf. This variable can point to one or more additional locations on the file system where repositories are available. The use of the /etc/portage/repos.conf/ directory is highly preferred.
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 priority numbers (for example 60) take precedence over ebuilds from overlays with lower priorities (such as 50).
The list of overlays with their priorities can be obtained through the output of the following commands (look for the "Repositories" string):
emerge --info --verbose
portageq repos_config /
The Gentoo repository will have a priority of -1000. That means that all other overlays generally take precedence as they are assigned a higher priority. That is the default behavior, because overlays are designed to "lay over/on top" of the Gentoo repository.
A number of tools support or integrate with overlays.
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.
- When using the make.conf method, layman manages a dedicated configuration file which should be sourced in by make.conf
- When using repos.conf, layman manages the /etc/portage/repos.conf/layman.conf file directly
See the Sync (Portage project) article and man 1 emaint.
eix-sync is a wrapper starting emerge --sync (which in turn starts emaint sync --auto) followed by eix-update. For further details see the Eix article and man 1 eix.
Emerging a duplicate package
When working with overlays it is possible to encounter a situation where multiple versions of the same package are available from different overlays. Instruct Portage to install a specific package from a specific overlay with the
emerge --ask category/atom::overlay-name
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:
( ulimit -n 4096 && emerge --regen )
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.
Masking when 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.
- Overlays project - The official Gentoo project for overlays support.
- Overlays guide (Overlay project) - A user guide written by the Overlay project.
- Developer's guide to Gentoo overlays - This document is kept only for historical purposes. The current guide is maintained as Project:Overlays/Overlays guide.
- Defining a Portage overlay directory - An outdated description in Gentoo Handbook