Layman

Layman is Article description::Gentoo's primary [[ebuild repository management tool.]] It offers a single command-line interface to repository management for end users.

Features
With users can manage their ebuild repositories (overlays) in a simple, centralized manner. The Layman application provides an overview of available remote repositories and allows the user to select one or more for the system. Once selected, the user can update (similar to ), add, remove, display and information about the overlays. Versions greater than 2.1.0 are improved with a plug-in sync system.

USE flags
The  and   USE flags are especially important in newer versions of.

Please refer to portage projects page.

Emerge
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:

If >=layman-2.3.0 then emerge as normal:

Otherwise, emerge the latest version found at :

Configuration
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 uses the new portage plugins system. Layman will create its configuration file in.

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

Create the directory if it does not exist yet:

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

make.conf method (force old method)
This is the older method, but newer versions of layman still support this.

Configure layman to use the method in :

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

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 repository management activities.

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

To add a repository in the list generated by the local list:

To add an unofficial repository:

To remove a repository from the local list:

To update a specific repository:

To update all repositories:

Mountable repositories with layman-mounter
Since the release of layman-2.2.0, support for squashfs repository types has been included. will interact with squashfs repository by mounting them as read-only on the filesystem. On the initial install of the squashfs repository, it will be mounted as read-only. However, after a reboot the repository will no longer be mounted and the ebuilds in that repository will not be accessible by the system.

In order to assist users in handling these mountable repositories, a utility was added that goes by the name of.

To find all repositories that are currently mounted, type:

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

To mount the mountable repositories, type:

To unmount the repositories, type:

Setting repository priorities with Layman
As each ebuild repository is assigned a unique priority, layman provides a simple way of defining priorities for repositories it manages. For more information about repository priorities see the ebuild repository priorities.

The file contains some information about the repositories, among which is the priority attribute in the repo tag. The number there determines only the priority relative to the other repository entries, 50 is the default value. Larger numbers take priority over smaller numbers. layman then analyses this file and sets the order of the repository 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 repository, and to ensure that the repository has a higher priority, add the repository 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 repositories
To add repositories 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 repository does not provide a repository XML file, create it manually in the folder.

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

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 repository that was created.

External resources

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