Gentoo Overlays: Users' Guide
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'
What Are Overlays?
"Overlays" are package trees for Portage. They contain additional ebuilds for
Gentoo. They are maintained by Gentoo developers and projects but 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
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 the Gentoo Overlays Project?
Gentoo Overlays provide social workspaces to allow Gentoo projects, developers
and users to collaborate together on tomorrow's Gentoo packages. We do this by
hosting overlays for Gentoo projects, developers, and users.
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.
Getting Started With Overlays
Use layman to easily install and update overlays over time.
Before you install layman it is worth mentioning that you probably want USE="git subversion" for it.
After adjusting use flags, to install layman you run:
Code Listing 2.1: Installing layman
# emerge layman
Code Listing 2.2: Telling Portage about layman-fetched repositories
# echo "source /usr/portage/local/layman/make.conf" >> /etc/portage/make.conf
# echo "source /usr/local/portage/layman/make.conf" >> /etc/portage/make.conf
# echo "source /var/lib/layman/make.conf" >> /etc/portage/make.conf
Layman will create /var/lib/layman/make.conf once you add
your first overlay. But if you do not plan to install an overlay immediately you
should ensure that this file actually exists and contains the empty variable
PORTDIR_OVERLAY. Otherwise Portage will complain. You can run echo
PORTDIR_OVERLAY=\"\" > /var/lib/layman/make.conf in order to have
the file created correctly.
Listing The Available Overlays
To see the list of overlays available, run:
Code Listing 2.3: Listing the available overlays
# layman -L
Installing An Overlay
To install an overlay on your computer, run:
Code Listing 2.4: Adding an overlay
# layman -a <overlay-name>
For example, to install the PHP
Code Listing 2.5: Adding the PHP overlay
# layman -a php
Installing Packages From An Overlay
After installing an overlay, you can install packages from it by running:
Code Listing 2.6: Installing a package from an overlay
# emerge -av <category>/<package>
Portage automatically searches your Gentoo main 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. You'll need to keyword the package as explained in the Gentoo Handbook.
Updating An Overlay
To keep your installed overlays up to date, run:
Code Listing 2.7: Updating all installed overlays
# layman -S
Please don't run this more than once a day, or you'll put too much strain on
How To Get More Involved
All Gentoo developers were users of Gentoo before they became developers and
still are users. 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.
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 prefer 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. Commonly people in #gentoo-bugs on
freenode IRC know where to find the people in question.
Working With Subversion
Subversion is one version control
software we use to manage the contents of our overlays. If you have never used
Subversion before, the Subversion book is an excellent way to learn Subversion.
You can buy it in dead-tree format if you prefer or read it online for free.
Working With Git
Git is another version control software we use to manage the contents of our
overlays. To get in touch with it, see the tutorial provided on the homepage.
The Gentoo project (or developer) you're working with should be able to provide
you with any further help and assistance that you need.
Frequently Asked Questions
Q: Do you host overlays for users?
A: Yes, we do. Please see this post for instructions on how
to host your overlay on Gentoo infrastructure.
The contents of this document, unless otherwise expressly stated, are licensed under the CC-BY-SA-2.5 license. The Gentoo Name and Logo Usage Guidelines apply.