Creating an ebuild repository
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
eselect repository create <repository_name>
--2022-11-21 15:42:35-- https://qa-reports.gentoo.org/output/repos/repositories.xml Resolving qa-reports.gentoo.org... 18.104.22.168, 22.214.171.124, 126.96.36.199, ... Connecting to qa-reports.gentoo.org|188.8.131.52|:443... connected. HTTP request sent, awaiting response... 304 Not Modified File '/root/.cache/eselect-repo/repositories.xml' not modified on server. Omitting download. Adding <repository_name> to /etc/portage/repos.conf ... Repository <repository_name> created and added
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:
Initialized empty Git repository in /var/db/repos/local/.git/
git add .
Adding an ebuild to an ebuild repository
For this example,
app-dicts/artha-1.0.2 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:
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:
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:
chown -R portage:portage /var/db/repos/local
Run pkgdev manifest to create the package's Manifest file:
It should now be possible to install the package from the ebuild repository with the emerge command:
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 
- 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:
cp docker-1.11.0 docker-1.12.6
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:
cp artha-1.0.2.ebuild artha-<newversion>.ebuild
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:
mkdir -v /var/db/repos/local/app-containers
cp -r /var/db/repos/gentoo/app-containers/docker .
cp docker-1.11.0.ebuild docker-1.12.6.ebuild
Now test the installation:
emerge --ask =app-containers/docker-1.12.6
- Basic guide to write Gentoo Ebuilds — getting started writing ebuilds, to harness the power of Portage, to install and manage even more software.
- Defining a custom repository (amd64 handbook)
- Ebuild — a text file, usually stored in a repository, which identifies a specific software package and tells the Gentoo package manager how to handle it.
- Ebuild repository — a file-structure that can provide packages for installation on a Gentoo system.
- GitHub Pull Requests — how to contribute to Gentoo by creating pull requests on GitHub.
- Repository format — A quick reference to Gentoo ebuild repository (overlay) format.
- Project:Overlays/Overlays_guide - Request adding an ebuild repository to repos.gentoo.org
- 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.
- one example of semantic version number is described on https://semver.org/