Ebuild repository

An ebuild repository is Article description::a file-structure that provides packages for a Gentoo system. Ebuild repositories contain ebuilds, eclasses, and other types of descriptive metadata files that inform Portage of software available for installation, news items, profile targets, etc.

The Gentoo ebuild repository, Gentoo project's primary and official ebuild repository, is the source for all the information needed to build and install Gentoo packages.

As well as providing new packages, an active ebuild repository can replace packages from the Gentoo ebuild repository - with newer or alternative versions for example - if they provide packages that already exist in the Gentoo repository. According to a set order of priority, active ebuild repositories can also replace packages from other ebuild repositories - hence the colloquial name overlay.

Administrators of Gentoo systems can add additional ebuild repositories by using the utilities and methods described below.

The Gentoo ebuild repository
The Gentoo ebuild repository is the primary ebuild repository of a Gentoo system, usually where all the packages come from. It is hosted and maintained on a Gentoo server, and gets synchronized to local machines, to be available to Portage.

The Gentoo ebuild repository contains ebuild files that tell Portage how to build each package that makes up an "official" Gentoo installation. These ebuilds describe all the software available for installation, with metadata, dependency info and everything else needed for installation. The metadata provides the package's name, version, available USE flags, license, website etc.

Dependency information in ebuilds allows Portage to pull in any other packages required to build and run whatever is to be installed - no more, no less. Dependencies are very granular in Gentoo. Where many other distributions would have one large dependency, Gentoo will cut them up into elemental units, so as to pull in only the parts that are really required. On the surface this may make dependencies seem more numerous, but the packages on the disk will take up no more space for this, and it allows to install even less code - only what is absolutely needed. Dependencies will even vary depending on what use flags are selected, for ultimate selectivity.

Perhaps most importantly, the ebuilds contain the information required to configure, build (compile), install, and test each package, usually from a project's own source code.

In addition to the ebuilds, the Gentoo ebuild repository contains the official profiles, which define the default state of USE flags, default values for most variables found in, the set of system packages, and select available package versions that define what packages are available for a given architecture.

The Gentoo ebuild repository is also the place where the news items are provided, which is why any new news items will be highlighted after a Gentoo ebuild repository synchronization.

The Gentoo ebuild repository, and it's ebuilds, are maintained by the Gentoo developers and other members of the community.

Repositories in general
Ebuild repositories consist of a set of files (ebuilds, metadata files, ...) that can be pulled in from public repositories (through git, CVS, SVN, etc.) or downloaded as tarballs and extracted manually onto the system.

Ebuild Repositories are handled through (which, like many other Portage configuration locations, can be a file or a directory), and the Eselect/Repository is is a tool to manage this configuration.

Repository definitions inside also inform Portage if and how the repository can be updated. With it, calling will automatically update the enabled repositories as well.

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

For more information, see /etc/portage/repos.conf and the Portage/Sync article.

An ebuild repository should conform to one or more Ebuild APIs as detailed in Gentoo's Package Manager Specification.

Priorities
Each ebuild repository has a unique priority to the package manager. This ensures that in the case of a specific version being found in several ebuild repositories, the resolution is unambiguous. Ebuilds from repositories with higher priority numbers (for example ) will take precedence over ebuilds from repositories with lower priorities (such as  ).

The list of ebuild repositories with their priorities can be obtained through the output of the following commands (look for the "Repositories" string):

The Gentoo ebuild repository will have a priority of  which means that all other repositories generally take precedence if they are assigned a higher priority. This is the default behaviour, because ebuild repositories are designed to "lay over" or "on top" of the Gentoo repository. To set the priority of other repositories, manually edit the relevant repos.conf section and set priority = to the desired value. For example:

Repositories that do not have a priority set default to 0.

Repository synchronization
Ebuild repositories should be updated, aka synchronized, so that local copies will reflect a recent state of the parent repositories, to be able to keep the system up to date, and install current software. Regularly synchronizing with the Gentoo repository and updating the system in this way is important, to ensure that all the latest security updates are installed, and that the local system does not get too out of sync with the Gentoo repository, as this can make upgrades complicated.

Repository synchronization is managed with the command:

Synchronization for each repository is configured through the files in.

To sync all repositories for which  is set, run  with the   switch (  for short). This is usually the command that should be run regularly, before system updates and package installation (and is equivalent to using the old command):

To sync the foo repository (irrespective of the foo auto-sync setting):

To sync all repositories with a valid sync-type and sync-url defined. (ignoring auto-sync settings):

See for information on how to use the portage synchronization commands. See the Portage project sync article about migrating to the new modular sync system from Portage version 2.2.16, it contains important information, notably for users of, , and.

Repository management
Use the Eselect/Repository tool to manage ebuild repositories registered on repos.gentoo.org, or custom ebuild repositories, automatically through.

Local repositories can alternatively be defined by hand.

Layman can still be used to manage repositories, but it is superseded by for most uses. does support some version control systems which the Portage does not natively sync (e.g. darcs and g-sorcery).

Emerging a duplicate package
When working with ebuild repositories it is possible to encounter a situation where multiple versions of the same package are available from different ebuild repositories. Instruct Portage to install a specific package from a specific ebuild repository with the  version specifier:

The same notation can be used for different emerge instructions, including uninstalling a package through.

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

Generate a local metadata cache by running after syncing the ebuild repositories:

Be careful, because 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 (or ) to regenerate the cache. It's probably only users of very large ebuild repositories should try.

Masking enabled ebuild repositories
When using large ebuild repositories or those with unknown/low quality code, it is best practice to hard mask the whole ebuild repository and only accept specific ebuilds on a case-by-case basis. For example, for an overlay named "repository-foobar":

Then add the specific package(s) from the repository-foobar overlay so that they will be available visible to Portage for installation:

After the above unmask the package named "foo-category/bar" should be available and none of the other packages from the repository-foobar overlay will be available, which is by design.

External resources

 * https://repos.gentoo.org - Gentoo's official ebuild repository hosting location.
 * https://github.com/gentoo/ - GitHub mirror of the Gentoo's ebuild repository.
 * https://gpo.zugaina.org/Overlays - A non-official very useful site for searching overlays.