The portage holds all ebuilds maintained and tested by the Gentoo developers but there is also a need to develop and test ebuilds outside of the regular tree. If ebuild modifications would be done inside the /usr/portage directory, the changes would be wiped out after emerge --sync. Therefore such ebuilds have to be put in Overlays (as found at https://overlays.gentoo.org/) to be untouched from emerge --sync.

There is an old and simple way via PORT_OVERLAY variable in /etc/portage/make.conf and there is a new way via the /etc/portage/repos.conf directory.


Overlay means two times the same ebuilds could be found. If this is the case then emerge and its friends complain. However this applies just for the ebuild files not for the directories or the Manifest files.

The overlay directories

Local overlays are mainly used to develop ebuilds.

Create a local overlay directory where the collection of ebuilds go:

mkdir<path to overlay directory>>

Tell /etc/portage/make.conf where it is by adding the following line

PORTDIR_OVERLAY="<path to directory>"

Or add a new overlay to the line above:

PORTDIR_OVERLAY="<path to first overlay directory> <path to second overlay directory>"

Now additional sub-directories serving as categories (as app-editors) can be created there where the ebuilds to be developed can be put. Note that a profiles and metadata subdirectory should exist. Check existing overlays as found in /var/lib/layman, /usr/portage or read the gentoo manual. It appears that the following files are necessary profiles/file repo_name and metadata/layout.conf .

Now let your console know what you did:

source /etc/portage/make.conf

And verify the result:


Now you can work in this console with your local overlay. Since every process has it own environmental variables, just this console and its children will have the PORTDIR_OVERLAY variable updated.


Since there are many other people around that want to do exactly the same, share the ebuilds is the next step. Gentoo manages https://overlays.gentoo.org/ for that.

The tool layman (emerge layman) expands with the overlays selected by layman. Additionally layman copies the ebuilds from the Internet and puts them into the overlay directories created.

After that, those ebuilds are available to emerge (or ebuild).

Now its time to use layman. To see what overlays you can get

layman -L

You see layman is a tool that deals with lists of overlays (and not directly with a single overlay). See http://layman.sourceforge.net/

To add a single overlay out of the list of available overlays:

layman -a<overlay-name>

As example layman -a sunrise

To see what overlays you have installed

layman -l

To de-install

layman -d <overlay-name>

To install a package from the overlay (= ebuild)

emerge -av<category>/<package>

To update the overlays

layman -s <overlay name>


layman -s ALL


layman -S


Overlays can also mask packages. Therefore look to directories as:


To unmask the files edit /etc/portage/package.unmask and if they are unstable unmask them in /etc/potrage/package.keywords

layman caches under /var/lib/layman and remembers things that are no more there.

Using layman on self made overlays

Once you are happy with your ebuilds, you might want to put them on a server and have them available to other PC's and users.

The layman configuration file /etc/layman/layman.cfg holds the description where the overlays are. Per default the list of overlays found are in the xml file:

https://api.gentoo.org/overlays/repositories.xml (or https://api.gentoo.org/overlays/repositories.xml that points to the first uri).

This file can be opened and contains a list of overlays described using XML. It can be observed in a web browser. man 8 layman shows an example of the current used XML overlay list format.

Example 14.1. overlay list file

          <?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE repositories SYSTEM "/dtd/repositories.dtd">
<repositories xmlns="" version="1.0">
<repo quality="experimental" status="official">
    <description>experimental linurs ebuilds</description>
    <owner type="project">
    <source type="tar">http://<...>/overlay.tar.gz</source> 

The format is mostly self-explanatory except the elements <feed> and <source> rise some questions.

  • The element <feed> is optional so don't use if you have no need for it. It is a http url that contains a regular web page where information can be get. Some of those web pages contain rss feeds.

  • The element <source> is mandatory since it points to the overlay.

Overlays can be off different types. Keeping track of versions is a key issue during development and therefore most overlays make used of version control systems.

  • Many use git.

  • Other types using version control systems are: mercurial, svn, bzr

  • Types not using version control systems are: rsync and tar.

Working on the local file-system

When experimenting with the layman and not having a local web server, it is a hassle to copy always to the Internet and maybe run in server permission and setup problems. Therefore everything can be in the local file-system.

In the layman config file /etc/layman/layman.cfg a overlay list file can be added

file:///home/<path>/<myoverlay list>.xml

The same applies inside the overlay list file.

        <source type="tar">file:///home/<path>/olay.tar.gz</source> 

Then try to add it layman -a <myoverlay>. When it runs remove it layman -d <myoverlay> and copy it to the Internet.

Tar overlays

Tar is the most basic overlay that has the advantage to have an easy setup on a server since just a file has to be put there. The disadvantages are that with every modification the complete tar.gz need to be done and also the whole file need to be fetched from the Internet. For just a couple stable ebuilds this is acceptable.

        <source type="tar"><...>/overlay.tar.gz</source> 

Go to the directory that contains the ebuilds and type (If you use a GUI window-manager for that, make sure you do not produce a subdirectory called overlay):

tar -czf overlay.tar.gz *


Make sure you pack it in a way all individual subdirectories as app-portage, app-misc can directly be seen and no directory as overlay is between

What remains is the installation on the client.

Having the file overlay.tar.gz that contains all ebuilds and the overlay list file is everything that needs to be on the server.

Git overlays

Git overlays work easily when having them on the local file-system or on a web server where you are the administrator. Two things are required:

  • A git bare repository (this is a git repository where nothing is checked out, basically what is in the .git directory)

  • An overlay list file xml (this can be in the git directory or better somewhere else)

There are different ways how to setup git on a web server.

Git overlays using http

When git is not installed on the server the overlay can be downloaded using http and the line in the overlay list file could look as follows:

          <source type="git">http://<path></source>

Using git a bare repository needs to be created on the server. See the git section in this book for the details of the setup. To test this go in a temporary directory and git clone http://<server name>/<name of remote repository>.git

Once this works, the overlay list file must be created and the layman configuration file /etc/layman/layman.cfg must be edited to point to it. layman -L | gerp <myoverlay list> should then show it.

Maintain the git http overlay

Test the ebuild and make sure the manifest file gets updated. Tools as http://www.linurs.org/ebuildtool.html are helpful for that.

Commit the changes to git until git status is happy

Go inside the working tree (the directory where you have the ebuilds) and do git push --all <file system path on the server where the bare repository is>/<name>.git/

or if the access rights permit it

git push --all http://<server name>/<name>.git

To verify that it happen cd <path on the server where the bare repository is>/<name>.git/ and git log. Q brings you back.


In case of using something as firefox fireFTP delete the directory on the Internet first and then copy over the local directory, sync might create a mess.

Once done update it (and all others) with layman -S

And what to do when it does not run?

Within /var/lib/layman/ an update should be found.

If not create mkdir ~/temp and go into cd ~/temp

Do git clone <file system path on the server where the bare repository is>/<name>.git/

or for the Internet server

git clone http://www.linurs.org/overlay.git/

Check if git did not get the update.

Git overlays using git

When git is installed on the server then the overlay can be downloaded using git protocol and the line in the overlay list file could look as follows:

          <source type="git">git://<path></source>

Linurs Overlay

Personal overlay lists can be added after emerging and configuring layman. Those overlay lists can be added to /etc/layman/layman.cfg next to the default overlay. The following shows how the linurs overlay is added to /etc/layman/layman.cfg:

      overlays  :  https://api.gentoo.org/overlays/repositories.xml

If layman is configured correctly than layman -L | grep linurs should now show the overlay. The -f option forces the download and overwrites an eventually existing layman cache that might have an old copy:

layman -f -a linurs

Once done you can update it (and all others)later by:

layman -S

And in case you want to delete it:

layman -d linurs

As an alternative layman can be called with the -o or --overlays option to pass a link to self made overlays list. To install:

layman -o http://www.linurs.org/overlay.git/linurs.xml -f -a linurs

Or when the overlay list file is on the local computer (note just one / behind file:)

layman -o file:/home/lindegur/Urs/Homepage/overlay.git/linurs.xml -f -a linurs

Eix search in not installed overlays

Commands as emerge --search, esearch or gui programs as porthole will find the ebuilds in the installed overlays. However there are many overlays not installed and it makes no sense to install all available overlays just to look for an ebuild that might or not might be there. To get a tool that can search in not installed overlays emerge eix

eix is much more than just an overlay search tool, it is an alternative to various gentoo tools. Therefore it has a

Kuban huge list of options as man eix shows. eix-update will update is cache containing portage and the installed overlays. The command eix-remote update will download the /var/cache/eix/remote.tar.bz2 file and than unpack it, it is quite common that this file has a newer version than eix being used and then fails. In this case simply update eix to the newest version..

Per default eix-update will rewrite the cache and therefore delete what eix-remote update added. To avoid that a variable needs to be set check if eix --dump | grep KEEP_VIRTUALS. As default it reports false, so the following needs to be added to /etc/eixrc then it has to be added


Finally to look for a ebuild type eix<ebuildname>.

Publish self-made programs

  1. Use a version management system, create an version. Also update man pages and change logs.

  2. Pack everything necessary into a tar.gz file. It is best to have all the source files in a single directory and try to have it clean from automatically created files. The tar.gz file should have a file name as <name of the program>-<version number>.tar.gz. Go inside the directory containing the source code and do tar -czf<file name>-<version number>.tar.gz * Hidden stuff as .git will no go into the tar.gz.

  3. Move the file to a directory containing all your files being published. Then mark the file as read only. Then upload it to your web server.

  4. Create an ebuild either from scratch or in case of an update from the previous one. If the ebuild was written nicely, it will be just a copy and a rename to have the ebuild with the new version inside the filename. Now the digest manifest file will not match anymore and need to be recreated. This is best done by ebuildtool http://www.linurs.org/ebuildtool.html. Using ebuildtool press O edit the config file to have the correct name of the ebuild. Then press D to get the digest manifest.

  5. All ebuilds of your overlay need to be packed into a tar.gz. Again this is best done using ebuildtool. If it is the first time you use it, press O to edit the config file and verify that it point to the top directory of your ebuilds. To create overly.tar.gz and have it in the directory to be published to the web server press V. Then publish it to the web server.

  6. Everything is done so far, and will be emerged on the next updated. However you probably like to do it now, so type layman -S to have the portage updated. Then type emerge -s<myebuild> to see what you have and what you can update. If it looks ok type emerge -u<myebuild>

Linurs Servernest startpage