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 a specific overlay, type:
To update all overlays, type:
With the addition of layman-2.2.0 comes the support for squashfs overlay types. layman will interact with squashfs overlays by mounting them as read-only on the filesystem. On the initial install of the squashfs overlay, it will be mounted as read-only. However, after a reboot the overlay will no longer be mounted and the ebuilds in that overlay will not be accessible by the system.
In order to assist users in handling these mountable overlays, a utility was added that goes by the name of layman-mounter.
To find all overlays that are currently mounted, type:
To find all overlays that are installed by layman that can be mounted, type:
To mount the mountable overlays, type:
To unmount the overlays, type:
Setting overlay priorities with layman
The file /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_OVERLAY variable defined in /var/lib/layman/make.conf.
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.
To add your personal overlay, and to ensure that your overlay has a higher priority, add your overlay before /var/lib/layman/make.conf is sourced.
However, this can be also "fooled" by defining the
PORTDIR_OVERLAY in /etc/portage/make.conf after you source /var/lib/layman/make.conf.
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 adding XML files into /etc/layman/overlays. For example:
NEW: With the addition of layman-2.2.0 a new utility was added to assist users in this process that goes by the name of layman-overlay-maker. As long as you know the information of the overlay that you're trying to add this utility will create the overlay XML for you and save into /etc/layman/overlays or whatever path value you have specified in the layman configuration file for overlay_defs.
layman-overlay-maker can become a useful tool in assisting users who would like to submit a patch to have their overlays added to the official repositories.xml file.
To use the utility simply invoke it by name, as so:
and go through its prompts until completetion.
When finished just run:
- Gentoo Overlay's: Users Guide on Gentoo.org
- Layman Homepage on Sourceforge.net