Ebuild repository

Resources

Overlays Gentoo Project

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.

Repositories

Additional package trees are usually hosted by repositories. These are overlays that are ready to be incorporated on Gentoo systems. 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.

A deprecated, yet still supported method is to use the PORTDIR_OVERLAY variable inside make.conf. This variable can point to one or more additional locations on the file system where repositories are available. The use of the repos.conf location is preferred though.

Repository definitions inside 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.

For more information, see /etc/portage/repos.conf and Project:Portage/Sync#Operation.

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 (look for the "Repositories" string):

user $emerge --info --verbose

The default Gentoo Portage tree 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 portage tree.

Supporting tools

A number of tools support or integrate with overlays.

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.

It supports both the PORTDIR_OVERLAY as well as repos.conf method.

• When using PORTDIR_OVERLAY, layman manages a dedicated configuration file which should be sourced in by make.conf
• When using repos.conf, layman manages files inside the repos.conf/ directory directly

For more information, see Layman.

emaint

See Project:Portage/Sync#Operation.

eix

Overlay/eix-sync

Crossdev

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

root #mkdir -p /usr/local/portage-crossdev/profiles

root #echo local-crossdev > /usr/local/portage-crossdev/profiles/repo_name

Then instruct Portage and crossdev to use this overlay:

FILE /etc/portage/make.confLet crossdev to store its ebuild in local-crossdev and indicate that the local overlay should override every other overlay

source /var/lib/layman/make.conf
PORTDIR_OVERLAY="/usr/local/portage-crossdev ${PORTDIR_OVERLAY} /usr/local/portage"

FILE /etc/portage/make.confPrevent crossdev from messing with the local overlay when not using layman

PORTDIR_OVERLAY="/usr/local/portage-crossdev /usr/local/portage"

Best practices

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:

root #layman -S

root #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.

FILE /etc/portage/package.maskMask all packages in an overlay

*/*::overlay-name

After that unmask the packages that will be installed.

FILE /etc/portage/package.unmaskUnmask a specific package in an overlay

foo/bar::overlay-name

See also

• Project:Overlays - The official Gentoo project for overlays support.
• Project:Overlays/User_Guide - A user guide written by the Overlay project.