Gentoo Overlays: Users' Guide

1.  Introduction

Audience

This document has been written for all users of Gentoo. If you are a Gentoo developer or Gentoo staff member, and you want to be able to manage your own overlay, please see the Developers' Guide.

What Are Overlays?

"Overlays" are package trees for Portage. They contain additional ebuilds for Gentoo. They are maintained by Gentoo developers, but are distributed separately from the main Portage tree.

Why Use Overlays?

People create overlays for all sorts of reasons. Here are a few of the main ones:

• If you modify an ebuild in /usr/portage, your change will be lost the next time you emerge --sync. But, if you put your modified ebuild into an overlay, your change is safe from emerge --sync.
• Because overlays are not the main Gentoo Portage package tree, they're a great place to develop and test an ebuild without fear of breaking the main Gentoo Portage package tree.
• Not every ebuild belongs in the Gentoo Portage package tree. An overlay is a great place to store an ebuild until it is ready to go into the Gentoo Portage package tree.

What Is overlays.gentoo.org?

overlays.gentoo.org provides social workspaces to allow Gentoo projects, developers and users to collaborate together on tomorrow's Gentoo packages. We do this by host overlays for Gentoo projects, and overlays for Gentoo developers.

Are All Official Overlays Hosted On overlays.gentoo.org?

No. Gentoo developers are free to put their overlay wherever suits them best; they don't have to use overlays.gentoo.org if they don't want to.

2.  Getting Started With Overlays

Use Gunnar Wrobel's layman to easily install and update overlays over time.

Installing Layman

To install layman, follow these steps:

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

Listing The Overlays Available

To see the list of overlays available, run:

layman -L

Installing An Overlay

To install an overlay on your computer, run:

layman -a <overlay-name>

For example, to install the PHP overlay, run:

layman -a php

Installing Packages From An Overlay

After installing an overlay, you can install packages from it by running:

emerge -av <category>/<package>

Portage automatically searches your main Portage tree (in /usr/portage), and all of the overlays that you've installed, and picks the latest version of the package that it can find.

If Portage isn't picking up the package from the overlay, that's normally because the package is marked ~arch, where "arch" is the architecture of your computer (normally x86).

Updating An Overlay

To keep your installed overlays up to date, run:

layman --sync ALL

Please don't run this more than once a day, or you'll put too much strain on Gentoo's infrastructure.

3.  How To Get More Involved

Introduction

All Gentoo developers were users of Gentoo before they became developers. Our users aren't just the reason Gentoo exists today; they're our future volunteers too.

If you start contributing to a project, we'll give you write access to the project's overlay, and we'll provide mentors to help you contribute. Eventually, if we like what you do and the way you do it, we'll invite you to go the whole hog and become a full Gentoo developer, with a nice shiny @gentoo.org email address.

How To Get Started

If you want to contribute to an overlay, the best approach is to build a good working relationship with the Gentoo developers who are responsible for the overlay. You can find out who is responsible for each overlay by going to overlays.gentoo.org's homepage, and clicking on the link for the overlay in question.

Different developers preferred to be contacted in different ways. Some hang out on IRC, and may have their own channels for their projects. Examples of these include the PHP project (#gentoo-php), and the Webapps project (#gentoo-web). Others prefer to be contacted by email only. The only way you'll find out is to try and make contact, and take it from there.

Working With Subversion

You'll need to get comfortable working with Subversion. Subversion is the version control software we use to manage the contents of our overlays. If you have never used Subversion before, the online book is an excellent way to learn Subversion. You can buy it in dead-tree format too if you prefer.

Further Information

The Gentoo project (or developer) you're working with should be able to provide you with any further help and assistance that you need.

4.  Frequently Asked Questions

Q: Do you host overlays for users?

• A: No, we do not. If you want an overlay of your own on o.g.o, you must first become a Gentoo developer.

The contents of this document are licensed under the Creative Commons - Attribution / Share Alike license.