Layman

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.

Using layman

Installing layman

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

root # emerge --ask app-portage/layman

Next, edit /etc/portage/make.conf to include the following line:

Note

Please add the 'source' statement to make.conf only AFTER you added your first overlay. Otherwise portage will fail.

File/etc/portage/make.confLayman-specific entry in make.conf

source /var/lib/layman/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.

File/etc/portage/make.confEnsuring that layman's PORTDIR_OVERLAY is not overwritten

PORTDIR_OVERLAY="${PORTDIR_OVERLAY} ..."

Using layman

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 have a list of all the overlays, type:

root # layman -L

To add an overlay in the list, type:

root # layman -a <name>

To remove an overlay from the local list, type:

root # layman -d <name>

To update all overlays, type:

root # layman -S

Setting overlay priorities with layman

As each overlay is assigned a unique priority, layman provides a simple way of defining priorities for overlays it manages. For more information about overlay priorities see the overlay article.

The file /var/lib/layman/overlays.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 /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/overlays.xml, it is strongly recommended that only /var/lib/layman/overlays.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 /etc/portage/make.conf before /var/lib/layman/make.conf is sourced.

File/var/lib/layman/make.confExample layman overlays setting

PORTDIR_OVERLAY="
/var/lib/layman/gamerlay
/var/lib/layman/lisp
/var/lib/layman/Spring
$PORTDIR_OVERLAY" #the variable defined in /etc/portage/make.conf is now expanded
                  #when /var/lib/layman/make.conf is sourced in /etc/portage/make.conf

However, this can be also "fooled" by defining the PORTDIR_OVERLAY in /etc/portage/make.conf after you source /var/lib/layman/make.conf

File/etc/portage/make.confCustom overlay setting

source /var/lib/layman/make.conf #this sources the PORTDIR_OVERLAY variable defined by layman.
                                 #however, the variable expanded by layman was empty
PORTDIR_OVERLAY="/home/user/overlay ${PORTDIR} ${PORTDIR_OVERLAY}" #now the layman defined overlays take precedence,
                                                                   #but the user defined overlay still has the lowest priority 

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:

File/etc/layman/layman.cfgOverlay list setting

overlays  : http://www.gentoo.org/proj/en/overlays/repositories.xml

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:

File/etc/layman/layman.cfgOverlay list setting

overlays  : http://www.gentoo.org/proj/en/overlays/repositories.xml
            file:///var/lib/layman/my-list.xml

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:

File/var/lib/layman/my-list.xmlCustom overlays list

<?xml version="1.0" ?>                                                                                                     
<repositories version="1.0">
	<repo priority="50" quality="experimental" status="unofficial">
		<name>sarnold</name>
		<description>Custom stuff for PPC from sarnold.</description>
		<homepage>http://github.com/sarnold/</homepage>
		<owner>
			<email>sarnold@gentoo.org</email>
		</owner>
		<source type="git">git://github.com/sarnold/portage-overlay.git</source>
	</repo>
</repositories>

When finished just run layman -f -a sarnold (change sarnold with the name of the repository you want to add).

See also

• Gentoo Overlay's: Users Guide on Gentoo.org

External resources

• Layman Homepage on Sourceforge.net