Overlay

From Gentoo Linux Wiki

Jump to: navigation, search
Please format this article according to the Style Guidelines and Wikification suggestions, then remove this notice {{Wikify}} from the article.

Reason(s): No reason supplied.

Gentoo.png
Gentoo has an official article on:

Overlays are used in gentoo to manage packages not available in the portage tree. Packages in overlays are exactly like normal packages. There are a lot of overlays already available for you to use, but you can also add a local overlay to install your own ebuilds.

Contents

[edit] Which overlays do I want?

How you decide which overlays to add is of course fully up to you. However, as a general advice, you should not add overlays you don't need, for this clutters up your package trees and might introduce bugs the Gentoo developers cannot fix. The Gentoo Overlays Project is an effort to provide a central repository for overlays. The left column contains all the overlays that are strongly associated with a Gentoo project or a Gentoo developer.

There are lots of these third-party externally produced overlays, some of which are quite specialized. This page lists some of those.

Warning: Overlays may contain low quality ebuilds and may break things, so use at your own risk. If you do have trouble with an ebuild in a Portage overlay please take it up with the provider of that specific ebuild or the provider of the overlay, never the good people at gentoo. Don't report bugs at bugs.gentoo.org for these ebuilds.

Also remember that untrustworthy ebuilds may be deliberately malicious. Ebuilds could contain security problems such as contaminated versions of core applications like GCC or OpenSSH. Be careful.

Finally, you may want a local overlay to add ebuilds which don't exist in any public overlay, for example ebuilds from bugs.gentoo.org.

[edit] Software

How and where you setup overlays depends on which package manager you're using and what kind of overlay you want.

[edit] Paludis

Paludis has full native support for multiple repositories. Overlays are merely a special case where a repository has another 'master' repository.

In its default location, /etc/paludis/repositories contains configuration files for overlays. You can add an overlay by manually writing new files, or by using playman -- a ruby script included with Paludis when built with ruby. playman can only create repository information files, not modify or delete them. You'll have to do this manually.

Please note that if you're using Paludis, you might not need a local overlay, because paludis comes with a neat tool called importare.

[edit] Layman

Layman is a tool designed to help automate management of your local repository of overlays you want included into your Gentoo system. It downloads a list of existing overlays from the Internet, and it can only handle overlays from this list. Most of its documentation can be found on its website or man page. Start with installing Layman.

emerge layman

Additionally you will probably need to emerge "dev-util/subversion" and "dev-util/git", since otherwise layman will by default show only strictly checked rsync-overlays. Which might be just one...

In its default configuration Layman doesn't mangle your configuration files. You should manually edit make.conf to incorporate the layman-managed overlays with the following command.

For layman versions prior to 1.2.0 use:

echo "source /usr/portage/local/layman/make.conf" >> /etc/make.conf

For layman versions 1.2.0 and later use:

echo "source /usr/local/portage/layman/make.conf" >> /etc/make.conf
Note: You should add overlays to layman before adding this line to make.conf, or else Portage will error out.

Ensure that layman has a working PORTDIR_OVERLAY env variable: 

echo 'PORTDIR_OVERLAY="${PORTDIR_OVERLAY}"' >> /usr/local/portage/layman/make.conf

Download (or update) the list of available overlays:

layman --fetch
Note: Note that a fetch is performed automatically on a list, sync or sync-all action. This behavior can be overridden with the nofetch option. It's also deprecated.

You can print a list of overlays to choose from:

layman --list
Note: If you get an empty list or a list with very few entries, you need to emerge rsync and subversion. layman is using these to to sync the overlays, but they are not pulled in automatically, because it's not a hard dependency.

Finally you can select and add an overlay:

layman --add <name>

Most of the overlays listed here are supported by layman. If you feel there should be an entry added, removed or edited from the central list that layman uses, send a mail to overlays-at-gentoo-dot-org.

From time to time you can update the overlay :

layman --sync <name>

You can also chose to update all your selected overlays with:

layman -S

[edit] Creating a local overlay

To create a local overlay, the first step is to choose a directory in which it will live. A common place is /usr/local/portage/. Create that directory now.

# mkdir -p /usr/local/portage/

In accordance with portage overlay specifications, we'll need to add a file specifying the name of the repository. For all conveniences, we'll name the local overlay local_overlay. Create a profiles directory and add a repo_name file:

# mkdir -p /usr/local/portage/profiles/ # echo "local_overlay" > /usr/local/portage/profiles/repo_name

[edit] Local overlays in portage

Now we'll update /etc/make.conf. Open it up. Find this line: 

source /usr/local/portage/layman/make.conf

And add below: 

PORTDIR_OVERLAY="${PORTDIR_OVERLAY} /usr/local/portage/"

[edit] Local overlays in paludis

Paludis users need to create a new file in /etc/paludis/repositories/, for example one called /etc/paludis/repositories/local_overlay.conf. In it, place these contents:

File: /etc/paludis/repositories/
location=${ROOT}/usr/local/portage/
sync = 
master_repository = gentoo
format = ebuild
names_cache = ${location}/.cache/names
write_cache = /var/cache/paludis/metadata

And sync this repository:

# paludis -s x-local_overlay

[edit] Populating your local overlay

Now you can add ebuilds to /usr/local/portage/ in the same way the portage tree, or any ebuild-style overlay is populated. For example, if you want to emerge www-foo/foofox-3.5 which you found in the bugtracker, create a directory /usr/local/portage/www-foo/foofox/ and add the ebuild in there. Then cd to that directory, and make a digest of the ebuild:

# cd /usr/local/portage/www-foo/foofox/ # ebuild foofox-3.5.ebuild digest

Now you can install it like any other package. If you're using paludis, don't forget to sync your local overlay first.

[edit] Deprecated Utility Programs

[edit] Gensync

Warning: Using gensync is deprecated. If you have no special reason for using it, please use layman instead.

Please note that not all the alternate ebuild sites listed here are available via gensync. Gensync is part of gentoolkit-dev. To install gensync:

emerge gentoolkit-dev

After that you can copy and paste some of the following overlay destinations. Remember that the folder which is stated in "overlay" must exist.

To update the overlay you have to use gensync. This is not done by emerge --sync.

gensync <id>

<id> is the same id as in the description files. It is useful to put an alias in ~/.bashrc (or the appropiate file for your shell) to synchronize everything.

alias emerge sync=emerge --sync && gensync bmg-main && gensync gentoo-de

After updating, edit your make.conf so that Portage can see your new overlay. If you use more than one overlay, separate the directories with a space:

File: /etc/make.conf
# For example:
# PORTDIR_OVERLAY="/usr/local/gentoo-de"
PORTDIR_OVERLAY="FULL/PATH/TO/OVERLAY1 FULL/PATH/TO/OVERLAY2"

[edit] See Also

[edit] External Links

Retrieved from "http://en.gentoo-wiki.com/wiki/Overlay"
Personal tools
In other languages