Creating an ebuild repository

From Gentoo Wiki
Jump to:navigation Jump to:search

Create an ebuild repository to house ebuilds to be made available to Portage for installation. Once an ebuild repository is created, and ebuilds are added to it, it may be shared with others (via a publicly available git repository, for example). This article will cover all the basics of creating an ebuild repository and maintaining ebuilds in it.

Creating ebuild repositories and ebuilds can can be a good way to learn more about the how Gentoo works, fundamentally. Publishing an ebuild repository can also be a good way to contribute to the community (though helping out with GURU, or becoming a proxy maintainer can be even more helpful).

See the ebuild repository article about what an ebuild repository is, the Ebuild article for explanations about ebuilds themselves, and the basic guide to write Gentoo Ebuilds for creating ebuilds to house in a repository.

Creating an empty ebuild repository

Using the eselect repository module, it is possible to make an ebuild repository skeleton with just one command:

root #eselect repository create <repository_name>

A new ebuild repository can also be created "by hand", as explained in the Handbook section defining a custom ebuild repository.

Some users will maintain an ebuild repository named "local" for personal things or packages only needed on one machine: eselect repository create local.

If creating a repository for publication that is mainly destined to contain a central package with its dependencies, it may be helpful to give it a name en rapport with its contents (ebuild repositories often get named for the person maintaining them, which isn't always the most descriptive name). The same applies for a repository that will contain packages with usage centered around a particular theme.

Track changes (optional)

Using a Version Control System (VCS) is good practice when creating or maintaining any ebuild repository. A VCS will track changes to ebuild files and allow "undoing" mistakes, among other useful features. A VCS can also make it easier to share an ebuild repository, if or when desired.

Portage has support for several VCSs to automatically provide ebuild repository synchronization, easily retrieving updates from the ebuild repositories available to Portage. CVS, git, Mercurial, and Subversion are supported in this fashion. Other VCSs may be used, if an ebuild repository is to provide synchronization by other means, or not at all.


git allows different version branches, which are useful for testing things out. It provides easy diff facilities, and many other features that can help to create and maintain an ebuild repository.

To start using git to develop an ebuild repository, first initialize the git repository:

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

Adding an ebuild to an ebuild repository

With the basic layout in order thanks to eselect repository, and a VCS such as git set up, adding ebuilds to a newly created repository is simple.

For this example, app-dicts/artha-1.0.2[1] will be used; of course, a new ebuild repository will usually be destined to contain newly written ebuilds. To follow on with this guide, consider that the artha ebuild is in the homedir of the user larry, in a file named artha-1.0.2.ebuild.

Directories to house the ebuild must first be created. Inside the repository directory, create an appropriate category directory. Inside that, create a directory with the package name, to house the ebuild:

root #mkdir -p /var/db/repos/local/app-dicts/artha

Create the ebuild file. Note the ebuild corresponds to a specific version, which is reflected in the file name. Several different versions of a package may be present via several different ebuilds in this package directory. This example uses a preexisting file, so simply copy it:

root #cp /home/larry/artha-1.0.2.ebuild /var/db/repos/local/app-dicts/artha/artha-1.0.2.ebuild

Give the file the appropriate permissions:

root #chown -R portage:portage /var/db/repos/local

Run pkgdev manifest to create the package's Manifest file:

root #cd /var/db/repos/local/app-dicts/artha
root #pkgdev manifest

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

Sometimes, when a new version comes out upstream, it can be possible to update an ebuild to the new version by doing a "simple version bump". If the following are true, an update may be a good candidate to perform a "bump" on:

  • 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

In the best possible case, it may be feasible to bump a package to the new version just by duplicating the ebuild and updating the version number in the filename.

Do not to try to modify ebuilds in a local mirror synced from a remotely hosted repository, such as the Gentoo ebuild repository - all changes would be overwritten on syncing (though if sync-type git is in use, a topic branch could be used to avoid this). Do not do this:
root #cd /var/db/repos/gentoo/app-containers/docker
root #cp docker-1.11.0 docker-1.12.6
root #pkgdev manifest
root #pkgcheck scan
Beware particularly of this false shortcut, as this method is sometimes suggested in conversations.

If a newer version of the package from the previous example were available upstream, and it were possible to bump it by simply updating the version in the filename, just copy the previous ebuild, update the version number, and run pkgdev and pkgcheck:

user $cd /var/db/repos/local/app-dicts/artha/
user $cp artha-1.0.2.ebuild artha-<newversion>.ebuild
user $pkgdev manifest
user $pkgcheck scan

Bump of an ebuild from the Gentoo ebuild repository

If a newer version of a package from the Gentoo ebuild repository is available upstream, and the update is "bumpable", do not try to bump it directly in the Gentoo ebuild repository directory. To bump an ebuild from a synced repository, copy the ebuild to an appropriate ebuild repository that will not sync over the new ebuild.

For example, to perform an elementary "bump" to a newer version of app-containers/docker from the Gentoo ebuild repository, create the appropriate directories in a repository that will not sync over, make a copy of the ebuild, giving it the correct name, and run pkgcheck scan:

user $mkdir -v /var/db/repos/local/app-containers
user $cd /var/db/repos/local/app-containers
user $cp -r /var/db/repos/gentoo/app-containers/docker .
user $cd docker/
user $cp docker-1.11.0.ebuild docker-1.12.6.ebuild
user $pkgdev manifest
user $pkgcheck scan

Now test the installation:

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

Finished ebuilds should be added to the version control system, to make the updated ebuild available to others. If using an ebuild repository from GitHub, consider adding a pull request.

See also


  • Section on methods to share an ebuild repository (github, rsync...) / how to provide synchronization for an ebuild repository that has been shared.
  • Section on how to register an ebuild repository on r.g.o.


  1. one example of semantic version number is described on