The layman application is Gentoo's primary overlay management tool, offering centralized repository management for the end user.
With app-portage/layman users can manage their overlays in a simple, centralized manner. The layman application provides an overview of available remote overlay repositories and allows the user to select one or more for his system. Once selected, the user can update the repositories (similar to emerge --sync), add his local overlays, and more.
Installing layman is a breeze. First check the USE flags that the layman package supports; most of the USE flags trigger which kinds of remote repository types layman supports (such as git repositories, cvs repositories ...). Then install the layman package
Insert layman reference to /etc/portage/make.conf.
This will ensure that Portage, when asked, will also check the content of the various overlays managed by layman. In effect, it will set the PORTDIR_OVERLAY variable, so if you already define that one in /etc/portage/make.conf, make sure that you do not overwrite the value that layman already provides.
The layman man page (see External resources) provides a full overview of the available functions within layman. However, for most people, the following commands suffice for their overlay management activities.
To fetch & display a list of all the overlays, type:
To add an overlay in the list, type:
To remove an overlay from the local list, type:
To update all overlays, type:
Setting overlay priorities with layman
/var/lib/layman/installed.xml contains some information about the overlays, among which is the priority attribute in the repo tag. The number there determines only the priority relative to the other overlay entries, 50 is the default value. layman then analyses this file and sets the order of the overlay entries in the
PORTDIR_OVELRAY variable defined in
As the file
/var/lib/layman/make.conf is automatically generated by layman based on the settings in
/var/lib/layman/installed.xml, it is strongly recommended that only
/var/lib/layman/installed.xml is used to set the priorities.
Because layman generates the
PORTDIR_OVERLAY variable in
/var/lib/layman/make.conf which in such a way that the
PORTDIR_OVERLAY variable from
/etc/portage/make.conf is put at the end, all overlays defined in
/etc/portage/make.conf take precedence over those defined by layman, provided the
PORTDIR_OVERLAY variable is defined in
/var/lib/layman/make.conf is sourced.
However, this can be also "fooled" by defining the
/etc/portage/make.conf after you source
This "trick" is merely an opportunity offered by shell variable expansion.
Adding custom overlays
If you want to add overlays which are not listed when you run
layman -L you can do it by editing the file
/etc/layman/layman.cfg. If you haven't made any change to that file before, you should have a line like this one:
You have to add a new line after that line pointing to an xml file which contains the list of your custom overlays. Don't forget the
file:// at the beginning of the line. An example could be this one:
Now you have to edit the file
/var/lib/layman/my-list.xml (in case you have followed the example) and add your custom overlays there. Here is an example:
When finished just run
layman -f -a sarnold (change sarnold with the name of the repository you want to add).
- Gentoo Overlay's: Users Guide on Gentoo.org
- Layman Homepage on Sourceforge.net