From Gentoo Wiki
Jump to: navigation, search

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

Insert layman reference to /etc/portage/make.conf.

root # echo "source /var/lib/layman/make.conf" >> /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.

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


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 fetch & display 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 a specific overlay, type:

root # layman -s <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/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.

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

${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 adding XML files into /etc/layman/overlays. For example:

File/etc/layman/overlays/sarnold.xmlCustom overlay

<?xml version="1.0" ?>

<repositories version="1.0">
	<repo priority="50" quality="experimental" status="unofficial">
		<description>Custom stuff for PPC from sarnold.</description>
		<source type="git">git://</source>

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

See also

External resources