WARNING

layman makes it easy to retrieve and update overlays for Gentoo. In addition it makes it TRIVIAL to break your system.

The main portage tree provides you with high quality ebuilds that are all maintained by Gentoo developers. This will not be the case for most of the overlays you can get by using layman. Thus you are removing the security shield that the standard tree provides for you. You should keep that in mind when installing ebuilds from an overlay.

To ensure the security of your system you MUST read the source of the ebuild you are about to install.

Actions

List of possible layman actions.

Other options

List of other available layman options.

Overlay lists

layman allows you to fetch an overlay without the need to modify any configuration files. In order for this to be possible the script needs an external list of possible overlay sources. There is a centralized list available at http://www.gentoo.org/proj/en/overlays/repositories.xml but nothing will prevent you from using or publishing your own list of overlays. The location of the remote lists can also be modified using the --overlays option when running layman.

To get a new overlay added to the central list provided for layman, send a mail to <overlays@gentoo.org>. Gentoo developers may add their overlay entries directly into the list which can be accessed over the CVS repository for the Gentoo website.

You can also use several lists at the same time. Just add one URL per line to the overlays variable in your configuration file. layman will merge the contents of all lists.

layman also allows you to define local files in this list. Just make sure you prepend these path names in standard URL notation with file://.

If you need to use a proxy for access to the Internet, you can use the corresponding variable in the layman configuration file. Layman will also respect the http_proxy environment variable in case you set it.

Local cache

layman stores a local copy of the fetched remote list. It will be stored in /var/lib/layman/cache.xml by default. There exists only one such cache file and it will be overwritten every time you run layman.

Handling /etc/make.conf

Since layman is designed to automatically handle the inclusion of overlays into your system it needs to be able to modify the PORTDIR_OVERLAY variable in your /etc/make.conf file. But /etc/make.conf is a very central and essential configuration file for a Gentoo system. Automatically modifying this file would be somewhat dangerous. You can allow layman to do this by setting the make_conf variable in the configuration file to /etc/make.conf.

A much safer and in fact recommended solution to the problem is to let layman handle an external file that only contains the PORTDIR_OVERLAY variable and is sourced within the standard /etc/make.conf file. Just add the following line to the end of your /etc/make.conf file:

source /var/lib/layman/make.conf

/var/lib/layman/make.conf is the default provided in the layman configuration. Change this file name in case you decide to store it somewhere else.

The file does not necessarily need to exist at the beginning. If it is missing, layman will create it for you.

There is also no need to remove the original PORTDIR_OVERLAY variable from the make.conf file. Layman will simply add new overlays to this variable and all your old entries will remain in there.

Adding, removing and updating overlays

Once a remote list of overlays has been fetched, layman allows to add overlays from the remote list to your system. The script will try to fetch the overlay. If this is successful the overlay information will be copied from the cache to the list of locally installed overlays. In addition layman will modify the PORTDIR_OVERLAY variable to include the new overlay path.

Removing the overlay with layman will delete the overlay without leaving any traces behind.

In order to update all overlays managed by layman you can run the script with the --sync ALL option or the --sync-all flag.

List overlays

layman provides the --list and --list-local options to print a list of available respectively installed overlays.

Listing will prepend all fully supported overlays with a green asterisk, all non-official overlays with a yellow asterisk and all overlays that you will not be able to use since you do not have the necessary tools installed with a red asterisk.

In the default mode layman will be strict about listing overlays and only present you with overlays that are fully supported. In addition it will complain about overlays that are missing a description field or a contact attribute. This type of behavior has been added with layman-1.0.7 and if you'd like to return to the old behavior you may use the k option flag or set the nocheck option in the configuration file.

Searching ebuilds in overlays

You can search through the ebuilds available in the overlays on http://overlays.gentoo.org by using "eix". Emerge the package and run update-eix-remote update.

Overlay types

Currently layman supports overlays that are exported via rsync, subversion, bzr, darcs, git, mercurial or provided as tar packages.

Overlay list format

Layman uses a central list of overlays in XML format. The file looks like this:

	      <?xml version="1.0" encoding="UTF-8"?>
	      <!DOCTYPE repositories SYSTEM "/dtd/repositories.dtd">
	      <repositories xmlns="" version="1.0">
	        <repo quality="experimental" status="official">
	          <name>gnome</name>
	          <description>experimental gnome ebuilds</description>
	          <homepage>http://git.overlays.gentoo.org/gitweb/?p=proj/gnome.git;a=summary</homepage>
	          <owner type="project">
	            <email>gnome@gentoo.org</email>
	            <name>GNOME herd</name>
	          </owner>
	          <source type="git">git://git.overlays.gentoo.org/proj/gnome.git</source>
	          <source type="git">http://git.overlays.gentoo.org/gitroot/proj/gnome.git</source>
	          <source type="git">git+ssh://git@git.overlays.gentoo.org/proj/gnome.git</source>
	          <feed>http://git.overlays.gentoo.org/gitweb/?p=proj/gnome.git;a=atom</feed>
	          <feed>http://git.overlays.gentoo.org/gitweb/?p=proj/gnome.git;a=rss</feed>
	        </repo>
	      </repositories>
	      

Adding an overlay locally

Simply create an overlay list in the format described above and run layman with the -o switch. You need to prepend local file URLs with file://.

Adding an overlay globally

The global list of overlays used by layman lies at http://www.gentoo.org/proj/en/overlays/repositories.xml.

All Gentoo developers have access to this location via CVS and can modify the list of overlays.

If you are not a Gentoo developer but wish to get your overlay listed you should contact the Gentoo Overlays team at <overlays@gentoo.org>. You can also join #gentoo-overlays on irc.freenode.net.

Installing an overlay

layman -f -a wrobel

This would add the overlay with the id wrobel to your list of installed overlays.

Syncing your overlays

layman -s ALL

This updates all overlays

Performing several actions at the same time

layman -f -a wrobel -a webapps-experimental

This fetches the remote list and immediately adds two overlays