Previous Page
45 local overlays in portage
  • 02 Oct 2010 23:09:14

Gentoo's portage system is great for installing programs. But what about when you don't want to follow the official portage tree exactly? Of course there are lots of unofficial overlays working via layman. But if you just want a few programs, or some slightly older versions of programs already hosted in portage, or to make your own patches, then you want to run a local overlay.

Creating a local overlay

Making a local overlay is extremely simple. Once you create the directory where it will be located, you should tell portage about it in make.conf:

PORTDIR_OVERLAY=/usr/local/portage


You also likely want to make a directory like /usr/local/portage/profiles and create a file named repo_name to tell portage the repository name:

daid@flux /usr/local/portage/profiles % more repo_name
daid's local overlay


Putting some ebuilds in it

In general for local overlays, I am either using older ebuilds from the official portage tree, or modifying existing ebuilds from the official portage tree.

Sometimes I have local programs that are only compatible with specific versions of other programs, and those versions become dated and removed from the portage tree. In the best case, you know this ahead of time, and before you run emerge --sync you should copy the ebuilds locally.

In cases where you didn't know ahead of time and portage deletes the ebuild you wanted, you'll need to search online for copies of the ebuild and any patches that go with them. Make sure to use the same category structure as found in /usr/portage

If you are getting old code which is not already installed (or you clean out your distfiles heedlessly), you may need to manually locate the source code online and place it in /usr/portage/distfiles if the official mirrors are no longer active. Obviously, you'll know you need to do this when portage complains that the downloads are failing. Usually there are some outdated mirrors floating around you can grab stuff from, sometimes as old as two or three years.

Example with alsamixer

I wanted to add transparency to alsamixer, which required me make a new overlay and edit the ebuild. First I needed to know what package in portage is associate with alsamixer:

daid@flux ~ % equery belongs `which alsamixer`
* Searching for /usr/bin/alsamixer ...
media-sound/alsa-utils-1.0.23-r1 (/usr/bin/alsamixer)

(equery is part of the gentoolkit.)

Now knowing it is associated with alsa-utils, then I can prepare my local overlay. Under your local overlay, you need to make a directory for the category, if it does not already exist:

daid@flux /usr/local/portage % mkdir media-sound && cd media-sound

Since in this case, we are just modifying the code already in the official portage tree, just copy everything from the official portage tree:

daid@flux /usr/local/portage/media-sound % cp -rp /usr/portage/media-sound/alsa-utils ./

Since this page focuses on local overlays, here I don't detail how to create the patch or modify the ebuild. If you actually wanted to follow along with this example, you can use the files I modified; if you already mirrored the official tree, just get the ebuild for one version and a transparency patch (under files/). Otherwise, I just assume the ebuild has now been modified and the patches are in the files/ directory. Now we need to generate a new Manifest:

daid@flux /usr/local/portage/media-sound/alsa-utils % sudo ebuild alsa-utils-1.0.23-r1.ebuild digest
>>> Creating Manifest for /usr/local/portage/media-sound/alsa-utils

Then you could check that portage sees the overlay by running pretend on emerge. It should look something like the following:

daid@flux /usr/local/portage/media-sound/alsa-utils % emerge -pv alsa-utils

These are the packages that would be merged, in order:

Calculating dependencies... done!
[ebuild R ] media-sound/alsa-utils-1.0.23-r1 USE="nls -doc -minimal" 0 kB [1]

Total: 1 package (1 reinstall), Size of downloads: 0 kB
Portage tree and overlays:
[0] /usr/portage
[1] /usr/local/portage

Clearly you can see that it's going to use the overlay here. If you were to actually begin the emerge, you would expect to see something like the following:

daid@flux /usr/local/portage/media-sound/alsa-utils % emerge --oneshot alsa-utils

These are the packages that would be merged, in order:

Calculating dependencies... done!
[ebuild R ] media-sound/alsa-utils-1.0.23-r1 USE="nls -doc -minimal" 0 kB [1]

Total: 1 package (1 reinstall), Size of downloads: 0 kB
Portage tree and overlays:
[0] /usr/portage
[1] /usr/local/portage


>>> Verifying ebuild manifests

>>> Emerging (1 of 1) media-sound/alsa-utils-1.0.23-r1 from daid's local overlay

Of course, the name of the overlay was set earlier by adding information to /usr/local/portage/profiles/repo_name which is reflected here.

Using programs not in portage

In the case a program is not already in portage, you just need to invent a category and add it to /usr/local/portage/profiles/categories

        (__)               __(^^)              /   /    (__)      / PhD  \  (oO)     /|  /---^^---/     / | /| daid  ||    *  || ||------||
Next pageNext page