Gentoo Overlays: Users' Guide

=20 -1.1 -2008-10-30 +1.2 +2010-07-13 =20 Introduction

Audience -

This document has been written for all users of Gentoo. If you are a= Gentoo + +

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

+overlay, please see the Dev= elopers' +Guide. +

=20

What Are Overlays? -

"Overlays" are package trees for Portage. They contain additional eb= uilds for Gentoo. They are maintained by Gentoo developers and projects = but distributed separately from the main Portage tree.

+ +

+"Overlays" are package trees for Portage. They contain additional ebuild= s for +Gentoo. They are maintained by Gentoo developers and projects but distri= buted +separately from the main Portage tree. +

=20

Why Use Overlays? -

People create overlays for all sorts of reasons. Here are a few of t= he main -ones:

+ +

+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 th= e 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 t= he main Gentoo Portage package tree.
Not every ebuild belongs in the Gentoo Portage package tree. An ove= rlay is a great place to store an ebuild until it is ready to go into the= Gentoo Portage package tree.
+ If you modify an ebuild in /usr/portage, your change wi= ll be + lost the next time you emerge --sync. But, if you put your mo= dified + 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 t= he main + Gentoo Portage package tree. +
+ Not every ebuild belongs in the Gentoo Portage package tree. An over= lay is + a great place to store an ebuild until it is ready to go into the Ge= ntoo + 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 packag= es. -We do this by hosting overlays for Gentoo projects and developers.

+ +

+Gentoo Overlays provide social workspaces to allow Gentoo projects, deve= lopers +and users to collaborate together on tomorrow's Gentoo packages. We do t= his 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 t= hem best; they don't have to use overlays.gentoo.org if they don't want t= o.

+ +

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

@@ -71,142 +113,210 @@ Getting Started With Overlays

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

+ +

+Use layman to easily install and update overlays over time. +

Installing Layman -

To install layman, follow these steps:

+ +

+To install layman, follow these steps: +

-emerge layman
+# emerge layman

 (for layman 1.1)
-# echo "source /usr/portage/local/layman/make.conf" >> /etc/make.conf=

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

=20
 (for layman 1.2)
-# echo "source /usr/local/portage/layman/make.conf" >> /etc/make.conf=

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

=20
 (for layman 1.3)
-# echo "source /var/lib/layman/make.conf" >> /etc/make.conf
+# echo "source /var/lib/layman/make.conf" >> /etc/make.conf

+ -Layman will create "/usr/local/portage/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=3D\"\" > -/usr/portage/local/layman/make.conf" in order to have the file created -correctly. +Layman will create /usr/local/portage/layman/make.conf once= you add +your first overlay. But if you do not plan to install an overlay immedia= tely you +should ensure that this file actually exists and contains the empty vari= able +PORTDIR_OVERLAY. Otherwise Portage will complain. You can run = echo +PORTDIR_OVERLAY=3D\"\" > /usr/portage/local/layman/make.conf in orde= r to have +the file created correctly. +

Listing The Available Overlays -

To see the list of overlays available, run:

layman -L

+ +

+To see the list of overlays available, run: +

+ +

+# layman -L
+

Installing An Overlay -

To install an overlay on your computer, run:

+ +

+To install an overlay on your computer, run: +

-layman -a <overlay-name>
+# layman -a <overlay-name>

For example, to install the PHP overlay, run:

+ +

+For example, to install the PHP +overlay, run: +

-layman -a php
+# layman -a php

Installing Packages From An Overlay -

After installing an overlay, you can install packages from it by runn= ing:

-emerge -av <category>/<package>
-

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

=20 -

If Portage isn't picking up the package from the overlay, that's norm= ally +

+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 normall= y because the package is marked ~arch, where "arch" is the architecture of= your -computer (normally x86).

+computer. You'll need to keyword the package as explained in the Portage Handbook. +

Updating An Overlay -

To keep your installed overlays up to date, run:

-layman -S + +

+To keep your installed overlays up to date, run: +

+ +

+# layman -S

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

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

=20 How To Get More Involved -

Introduction -

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

=20 -

If you start contributing to a project, we'll give you write access t= o the +

+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; t= hey're +our future volunteers too. +

+ +

+If you start contributing to a project, we'll give you write access to t= he 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 y= ou to -go the whole hog and become a full Gentoo developer.

+Eventually, if we like what you do and the way you do it, we'll invite y= ou 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 buil= d a good + +

+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<= /uri>, and clicking on the link for the overlay in question.

+overlay. You can find out who is responsible for each overlay by going t= o 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 the= se +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 ou= t 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. +

=20 -

Different developers preferred to be contacted in different ways. So= me hang -out on IRC, and may have their own channels for their projects. Example= s of -these include the PHP project (#gentoo-php), and the Webapps project -(#gentoo-web). Others prefer to be contacted by email only. The only w= ay -you'll find out is to try and make contact, and take it from there. Comm= only 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 conte= nts of our overlays. If you have never used Subversion before, the Subve= rsion book is an excellent way to learn Subversion. You can buy it in de= ad-tree format if you prefer or read it online for free. + +

+Subversion is one versi= on control +software we use to manage the contents of our overlays. If you have neve= r used +Subversion before, the Subversion book is an excellent way to learn Subv= ersion. +You can buy it in dead-tree format if you prefer or read it online for f= ree.

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.

+ +

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

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.

+ +

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

@@ -215,11 +325,17 @@ Frequently Asked Questions

Q: Do you host overlays for users?

A: Yes, we do. Please see this post for instructions to get hosted.

+ +

+Q: Do you host overlays for users? +

+ +

+A: Yes, we do. Please see this post for instructi= ons on how +to host your overlay on Gentoo infrastructure. +