Custom ebuild repository

From Gentoo Wiki
Jump to:navigation Jump to:search

Creating custom ebuilds repositories is helpful for community members who want to get their hands dirty with Gentoo ebuild maintenance. This article defines the basics of ebuild maintenance by way of a custom ebuild repository (overlay).

Creating a local repository

Original method (Handbook)

See Defining a custom ebuild repository in the Handbook for Handbook instructions for creating a custom ebuild repository.

eselect repository method

Alternatively, beginning with version 10 of the eselect repository module, the create subcommand will make an ebuild repository skeleton (requires app-eselect/eselect-repository):

create <name> [<path>]    Create a local repository
   <name>                    Name of the new repository
   <path>                    Path to use (default: ${REPOS_BASE}/<name>)
root #eselect repository create localrepo

Optional: Use version history

In order to keep track of all changes done in the custom repository, and to make it easier to contribute code upstream or to other users, revision control software is almost a necessity. While it is possible to maintain local repositories manually, it is much more effort for repository maintenance when attempting to track down changes.


Using git provides the possibility for testing with different version branches, easy diffs, and a number of other features.

Initialize the git repository:

user $cd /var/db/repos/localrepo/
root #git init
Initialized empty Git repository in /var/db/repos/localrepo/.git/
root #git add .
root #git commit

Adding an ebuild to the repository

Now that the basic layout is in order, an ebuild could be added to the repository. In this example, app-dicts/artha-1.0.2 (available at [1]). Assumed the ebuild is in the homedir of the user larry, and named artha-1.0.2.ebuild.

root #mkdir -p /var/db/repos/localrepo/app-dicts/artha
root #cp ~larry/artha-1.0.2.ebuild /var/db/repos/localrepo/app-dicts/artha/artha-1.0.2.ebuild
root #chown -R portage:portage /var/db/repos/localrepo
root #pushd /var/db/repos/localrepo/app-dicts/artha
root #repoman manifest
root #popd

It should now be possible to install the package from the ebuild repository with the emerge command:

root #emerge --ask --verbose app-dicts/artha

Simple version bump of an ebuild in the local repository

In theory one can update an ebuild to the next version number with a "simple version bump". Indicators that this is promising are:

  • Upstream fixed only minor bugs.
  • Dependencies did not change.
  • Upstream uses semantic version numbers and changed only the minor number [1]
  • The ebuild file is small and does not use many patches.

For the simplest bump place a copy of the ebuild in the local repository and update the version number in the filename.

Presuming the local repository was created in localrepo already and want to bump to a newer version of app-emulation/docker.

user $mkdir -v /var/db/repos/localrepo/app-emulation
user $cd /var/db/repos/localrepo/app-emulation
user $cp -r /var/db/repos/gentoo/app-emulation/docker .
user $cd docker/
user $cp docker-1.11.0.ebuild docker-1.12.6.ebuild
user $repoman --digest=y -d full

Now test the installation:

root #emerge --ask =app-emulation/docker-1.12.6

Finished ebuilds should be added to the version control system. If using git, consider adding a pull request to GitHub.

Avoid a direct version bump

The direct version bump in the official ebuild repository is often suggested, but should be avoided, because:

  • All changes get lost on the next sync of the repository (unless sync-type git is in use, in that case a topic branch could be used)
  • User contributions should be separated from the official ebuild repository

Do not do this:

root # # cd /usr/portage/app-emulation/docker
root # # cp docker-1.11.0 docker-1.12.6
root # # repoman --digest=y -d full


sys-devel/crossdev will place the ebuilds/categories it generates into one of four places in this order:

  1. An overlay specified on the command-line with the --ov-output (-oO) option
  2. An overlay named 'cross-${CTARGET}'
  3. An overlay named 'crossdev'
  4. Finally, it falls back on the overlay having the lowest priority value in /etc/portage/repos.conf/.

If the overlays have the same priority, it will use the overlay determined to be the first, alphabetically.

Most users will want to prevent crossdev from disturbing layman's overlays or the user's personal per-machine overlay (commonly created at /var/db/repos/localrepo/). The best solution is to create an overlay specifically for crossdev's use:

root #mkdir -p /var/db/repos/crossdev/{profiles,metadata}
root #echo 'crossdev' > /var/db/repos/crossdev/profiles/repo_name
root #echo 'masters = gentoo' > /var/db/repos/crossdev/metadata/layout.conf
root #chown -R portage:portage /var/db/repos/crossdev

If the main Portage tree is synchronized by using Git, or any other method with Manifest files that do not include checksums for ebuilds, prevent "masked by: corruption" errors with:

FILE /var/db/repos/crossdev/metadata/layout.conf
masters = gentoo
thin-manifests = true

Then instruct Portage and crossdev to use this overlay:

FILE /etc/portage/repos.conf/crossdev.conf
location = /var/db/repos/crossdev
priority = 10
masters = gentoo
auto-sync = no


Older versions of sys-apps/portage included repoman. Starting from portage-2.3.0, repoman has been 'unbundled' into separate package. Be sure it is installed before following this guide:

root #emerge --ask app-portage/repoman

Alternatively, the ebuild command can still be used to generate manifest/digest files, however it does not include any of the other quality check benefits (such as debug output) included with repoman:

root #ebuild foo.ebuild digest
>>> Creating Manifest for /usr/local/portage/bar/foo

See also


  1. one example of semantic version number is described on