/[gentoo]/xml/htdocs/proj/en/overlays/userguide.xml
Gentoo

Contents of /xml/htdocs/proj/en/overlays/userguide.xml

Parent Directory Parent Directory | Revision Log Revision Log


Revision 1.6 - (hide annotations) (download) (as text)
Sun Feb 1 00:02:22 2009 UTC (5 years, 7 months ago) by jokey
Branch: MAIN
Changes since 1.5: +8 -3 lines
File MIME type: application/xml
Respect older layman versions when referencing paths

1 stuart 1.1 <?xml version="1.0" encoding="UTF-8"?>
2     <!DOCTYPE guide SYSTEM "/dtd/guide.dtd">
3    
4     <guide link="/proj/en/overlays/userguide.xml">
5     <title>Gentoo Overlays: Users' Guide</title>
6    
7     <author title="Author">
8 jokey 1.5 <mail link="stuart">Stuart Herbert</mail>
9     </author>
10    
11     <author title="Author">
12     <mail link="jokey">Markus Ullmann</mail>
13 stuart 1.1 </author>
14    
15     <abstract>This guide helps users understand how to use the Gentoo Overlays service</abstract>
16    
17     <license/>
18    
19 jokey 1.5 <version>1.1</version>
20     <date>2008-10-30</date>
21 stuart 1.1
22     <chapter>
23     <title>Introduction</title>
24     <section>
25     <title>Audience</title>
26     <body>
27     <p>This document has been written for all users of Gentoo. If you are a Gentoo
28     developer or Gentoo staff member, and you want to be able to manage your own
29     overlay, please see the <uri link="/proj/en/overlays/devguide.xml">Developers' Guide</uri>.</p>
30     </body>
31     </section>
32    
33     <section>
34     <title>What Are Overlays?</title>
35     <body>
36 jokey 1.5 <p>"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.</p>
37 stuart 1.1 </body>
38     </section>
39    
40     <section>
41     <title>Why Use Overlays?</title>
42     <body>
43     <p>People create overlays for all sorts of reasons. Here are a few of the main
44     ones:</p>
45     <ul>
46     <li>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.</li>
47     <li>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.</li>
48     <li>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.</li>
49     </ul>
50     </body>
51     </section>
52    
53     <section>
54 jokey 1.5 <title>What is the Gentoo Overlays Project?</title>
55 stuart 1.1 <body>
56 jokey 1.5 <p>Gentoo Overlays provide social workspaces to allow Gentoo projects,
57 stuart 1.1 developers and users to collaborate together on tomorrow's Gentoo packages.
58 jokey 1.5 We do this by hosting overlays for Gentoo projects and developers.</p>
59 stuart 1.1 </body>
60     </section>
61    
62     <section>
63     <title>Are All Official Overlays Hosted On overlays.gentoo.org?</title>
64     <body>
65     <p>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.</p>
66     </body>
67     </section>
68     </chapter>
69    
70     <chapter>
71     <title>Getting Started With Overlays</title>
72     <section>
73     <body>
74 jokey 1.6 <p>Use Gunnar Wrobel's layman to easily install and update overlays over time.</p>
75 stuart 1.1 </body>
76     </section>
77    
78     <section>
79     <title>Installing Layman</title>
80     <body>
81     <p>To install layman, follow these steps:</p>
82     <pre caption="Installing layman">
83     <i>emerge layman</i>
84 jokey 1.6 </pre>
85     <pre caption="Telling Portage about layman-fetched repositories">
86     <comment>(for layman 1.1)</comment>
87     <i># echo "source /usr/portage/local/layman/make.conf" >> /etc/make.conf</i>
88    
89     <comment>(for layman 1.2 and up)</comment>
90     <i># echo "source /usr/local/portage/layman/make.conf" >> /etc/make.conf</i>
91 stuart 1.1 </pre>
92 wrobel 1.2 <note>
93 jokey 1.5 Layman will create "/usr/local/portage/layman/make.conf" once you add
94 wrobel 1.4 your first overlay. But if you do not plan to install an overlay
95     immediately you should ensure that this file actually exists and
96     contains the empty variable "PORTDIR_OVERLAY". Otherwise portage will
97     complain. You can run "echo PORTDIR_OVERLAY=\"\" >
98     /usr/portage/local/layman/make.conf" in order to have the file created
99     correctly.
100 wrobel 1.2 </note>
101 stuart 1.1 </body>
102     </section>
103    
104     <section>
105 jokey 1.5 <title>Listing The Available Overlays</title>
106 stuart 1.1 <body>
107     <p>To see the list of overlays available, run:</p>
108     <pre caption="Listing the available overlays">layman -L</pre>
109     </body>
110     </section>
111    
112     <section>
113     <title>Installing An Overlay</title>
114     <body>
115     <p>To install an overlay on your computer, run:</p>
116     <pre caption="Adding an overlay">
117     layman -a &lt;overlay-name&gt;
118     </pre>
119     <p>For example, to install <uri link="http://overlays.gentoo.org/proj/php">the PHP overlay</uri>, run:</p>
120     <pre caption="Adding the PHP overlay">
121     layman -a php
122     </pre>
123     </body>
124     </section>
125    
126     <section>
127     <title>Installing Packages From An Overlay</title>
128     <body>
129     <p>After installing an overlay, you can install packages from it by running:</p>
130     <pre caption="Installing A Package From An Overlay">
131     emerge -av &lt;category&gt;/&lt;package&gt;
132     </pre>
133     <p>Portage automatically searches your main Portage tree (in /usr/portage), and
134     all of the overlays that you've installed, and picks the latest version of the
135     package that it can find.</p>
136    
137     <p>If Portage isn't picking up the package from the overlay, that's normally
138     because the package is marked ~arch, where "arch" is the architecture of your
139     computer (normally x86).</p>
140     </body>
141     </section>
142    
143     <section>
144     <title>Updating An Overlay</title>
145     <body>
146     <p>To keep your installed overlays up to date, run:</p>
147     <pre caption="Updating All Installed Overlays">
148 jokey 1.5 layman -S
149 stuart 1.1 </pre>
150     <p>Please don't run this more than once a day, or you'll put too much strain on
151     Gentoo's infrastructure.</p>
152     </body>
153     </section>
154     </chapter>
155    
156     <chapter>
157     <title>How To Get More Involved</title>
158    
159     <section>
160     <title>Introduction</title>
161     <body>
162 jokey 1.5 <p>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.</p>
163 stuart 1.1
164     <p>If you start contributing to a project, we'll give you write access to the
165     project's overlay, and we'll provide mentors to help you contribute.
166     Eventually, if we like what you do and the way you do it, we'll invite you to
167 jokey 1.5 go the whole hog and become a full Gentoo developer.</p>
168 stuart 1.1 </body>
169     </section>
170    
171     <section>
172     <title>How To Get Started</title>
173     <body>
174     <p>If you want to contribute to an overlay, the best approach is to build a good
175     working relationship with the Gentoo developers who are responsible for the
176     overlay. You can find out who is responsible for each overlay by going to
177     <uri link="http://overlays.gentoo.org">overlays.gentoo.org's homepage</uri>, and clicking on the link for the overlay in question.</p>
178    
179     <p>Different developers preferred to be contacted in different ways. Some hang
180     out on IRC, and may have their own channels for their projects. Examples of
181     these include the PHP project (#gentoo-php), and the Webapps project
182     (#gentoo-web). Others prefer to be contacted by email only. The only way
183 jokey 1.5 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.</p>
184 stuart 1.1 </body>
185     </section>
186    
187     <section>
188     <title>Working With Subversion</title>
189     <body>
190 jokey 1.5 <p>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.
191     </p>
192     </body>
193     </section>
194    
195     <section>
196     <title>Working With Git</title>
197     <body>
198     <p>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.</p>
199 stuart 1.1 </body>
200     </section>
201    
202     <section>
203     <title>Further Information</title>
204     <body>
205     <p>The Gentoo project (or developer) you're working with should be able to
206     provide you with any further help and assistance that you need.</p>
207     </body>
208     </section>
209     </chapter>
210    
211     <chapter>
212     <title>Frequently Asked Questions</title>
213     <section>
214     <body>
215     <p>Q: Do you host overlays for users?</p>
216     <ul>
217 jokey 1.5 <li>A: No, we do not. If you want an overlay of your own on (git.)overlays.gentoo.org, you must first become a Gentoo developer.</li>
218 stuart 1.1 </ul>
219     </body>
220     </section>
221     </chapter>
222     </guide>

  ViewVC Help
Powered by ViewVC 1.1.20