From Gentoo Wiki
Jump to: navigation, search
This page contains changes which are not marked for translation.

The information in this article is probably outdated. You can help the Gentoo Wiki by verifying and updating this article.


Layman is Gentoo's primary overlay management tool, offering centralized repository management for end users.


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 the system. Once selected, the user can update the repositories (similar to emerge --sync), add local overlays, and more. Versions greater than 2.1.0 are improved with a plug-in sync system.

Although not all features of plug-in sync system of portage are supported yet from layman the migration of portage is a good step to be prepared for that.


USE flags

First check the USE flags that the Layman package supports...

root #emerge --ask app-portage/layman

...and add the necessary USE flags.

FILE /etc/portage/package.use/laymanadd the USE flags you need
app-portage/layman git subversion

Following table show all the USE flags of layman (including not supported flags in your special version).

USE flags for app-portage/layman Tool to manage Gentoo overlays

bazaar Support dev-vcs/bzr based overlays local
cvs Support dev-vcs/cvs based overlays local
darcs Support dev-vcs/darcs based overlays local
g-sorcery Support app-portage/g-sorcery based overlays local
git Support dev-vcs/git based overlays local
gpg Support app-crypt/gnupg signed overlays lists and manifests local
mercurial Support dev-vcs/mercurial based overlays local
sqlite Add support for sqlite - embedded sql database global
squashfs Support mounting squashfs image overlays locally read-only local
subversion Support dev-vcs/subversion based overlays local
sync-plugin-portage Install the sys-apps/portage sync module local
test Workaround to pull in packages needed to run with FEATURES=test. Portage-2.1.2 handles this internally, so don't set it in make.conf/package.use anymore global

The USE flag sync-plugin-portage is especially important in newer versions. Please refer to portage projects page.


Next install the Layman package:

To follow this guide, you may need to install a later version than that which is in the portage tree. Check the version available to you in portage:

user $emerge --search layman

If >layman-2.3.0 then emerge as normal:

root #emerge --ask app-portage/layman

Otherwise, emerge the latest version found at app-portage/layman:

root #emerge --ask =app-portage/layman-2.4.2


There are two methods of integrating layman into portage. Newer versions support both methods at the same time, so there is no need to configure portage (except configurations mentioned in this section).

repos.conf method (default)

This method was added in version 2.1.0 of layman.

This method uses the new portage plugins system. Layman will create its configuration file in /etc/portage/repos.conf/.

Configure layman to use the repos.conf method in /etc/layman/layman.cfg. New installations of layman will probably have this already set correctly:

FILE /etc/layman/layman.cfg
# Repository config types used by layman
# (repos.conf, make.conf)
conf_type : repos.conf

Create the /etc/portage/repos.conf/ directory if it does not exist yet:

If you have >=layman-2.3.0 installed, you can force a rebuild of layman's repos.conf files:

root #layman-updater -R

make.conf method (force old method)

This is the older method, but newer versions of layman still support this.

Configure layman to use the make.conf method in /etc/layman/layman.cfg:

FILE /etc/layman/layman.cfg
# Repository config types used by layman
# (repos.conf, make.conf)
conf_type : make.conf

Insert a reference to Layman in /etc/portage/make.conf

root #echo "source /var/lib/layman/make.conf" >> /etc/portage/make.conf

Adding the source command to the /etc/portage/make.conf (performed in the command above) will ensure that Portage, when asked, will check the content of the various overlays managed by Layman in the /var/lib/layman/make.conf file. In effect, it will update the PORTDIR_OVERLAY variable with directories Layman uses. If a special directory has been previously defined for PORTDIR_OVERLAY in /etc/portage/make.conf, make sure its value is not overwritten with the value Layman provides.

FILE /etc/portage/make.confEnsuring that layman's PORTDIR_OVERLAY is not overwritten
source /var/lib/layman/make.conf
#for some local ebuilds to test, have to be after line for layman above!
PORTDIR_OVERLAY="/usr/local/portage/ ${PORTDIR_OVERLAY}"


Basic invocations

The Layman man page (see External resources) provides a full overview of the available functions within Layman. However, for most users, the following commands suffice for overlay management activities.

To fetch and display a list of all the overlays available through official references:

root #layman -L

To add an overlay in the list generated by the local list:

root #layman -a <name>

To add an unofficial overlay:

root #layman -o <url of repository xml file> -f -a <name>

To remove an overlay from the local list:

root #layman -d <name>

To update a specific overlay:

root #layman -s <name>

To update all overlays:

root #layman -S

Mountable overlays with layman-mounter

Since the release of layman-2.2.0, support for squashfs overlay types has been included. 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:

root #layman-mounter -l

To find all overlays that are installed by layman that can be mounted, type:

root #layman-mounter -L

To mount the mountable overlays, type:

root #layman-mounter -m <name>

To unmount the overlays, type:

root #layman-mounter -u <name>

Setting overlay priorities with Layman

The information in this section is deprecated but has been kept for archival purposes. It may or may not be relative for contemporary usage. Handle with care!

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. Larger numbers take priority over smaller numbers. 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 a personal overlay, and to ensure that the overlay has a higher priority, add the 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 /var/lib/layman/make.conf has been sourced.

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

To add overlays which are not listed when layman -L is ran, find their repository XML files and add them using the -o option.

Example: repositories.xml in brother-overlay

In case the overlay does not provide a repository XML file, create it manually in the /etc/layman/overlays folder.

For example, if Larry the cow were to create an overlay:

FILE /etc/layman/overlays/larry.xmlLarry the cow's ngix overlay
<?xml version="1.0" ?>

<repositories version="1.0">
	<repo priority="50" quality="experimental" status="unofficial">
		<description>nginx server for the barn computer from Larry the cow.</description>
		<source type="git"></source>

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 the overlay information has been properly added via the prompts, layman-overlay-maker will create a XML defined overlay and save into /etc/layman/overlays or the 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:

root #layman-overlay-maker

and go through its prompts until completion.

When finished run:

root #layman-updater -R

Followed by:

root #layman -a <name>

where <name> is the name of the overlay you just created.

See also

External resources