Layman

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

Features
With 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 ), add local overlays, and more. Versions greater than 2.0.0 are improved with the new plug-in sync system. Although this is a cool feature all this versions of layman are masked at the moment for all targets.

USE flags
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, etc.).

Emerge
Next install the Layman package:

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

make.conf method (older method)
This is an older method, still widely used. Very old portage versions support only this method.

Configure layman to use method in. Older layman installations will have this already set:

Insert a reference to Layman in

Adding the  command to the  (performed in the command above) will ensure that Portage, when asked, will check the content of the various overlays managed by Layman in the  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, make sure its value is not overwritten with the value Layman provides.

repos.conf method (default method for or later )
This method uses a new portage plugins system. Layman will create its configuration file in directory. There is no need for PORTDIR_OVERLAY changes in.

Configure layman to use method in. New installations of layman will probably have this already set correctly:

Create directory, if it does not exist yet:

If you have or later installed, you can force a rebuild of layman's  files:

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:

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

To add an unofficial overlay:

To remove an overlay from the local list:

To update a specific overlay:

To update all overlays:

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

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
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 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.

As the file is automatically generated by layman based on the settings in, it is strongly recommended that only  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 is sourced.

However, this can be also "fooled" by defining the PORTDIR_OVERLAY in after  has been sourced.

This "trick" is merely an opportunity offered by shell variable expansion.

Adding custom overlays
To add overlays which are not listed when is ran, find their repository XML files and add them using the   option.

Example: in brother-overlay

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

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

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. As long as the overlay information has been properly added via the prompts, will create a XML defined overlay and save into  or the specified in the layman configuration file for overlay_defs.

can become a useful tool in assisting users who would like to submit a patch to have their overlays added to the official file.

To use the utility simply invoke it by name:

and go through its prompts until completion.

When finished run:

Followed by

where is the name of the overlay you just created.

External resources

 * The Layman man page locally or online at Sourceforge.net