/[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.11 - (hide annotations) (download) (as text)
Mon Jul 25 01:17:54 2011 UTC (3 years, 2 months ago) by sping
Branch: MAIN
Changes since 1.10: +7 -6 lines
File MIME type: application/xml
Mention USE="git subversion" for layman (bug #228427), fix mis-use of term "portage", move version to integer

1 stuart 1.1 <?xml version="1.0" encoding="UTF-8"?>
2     <!DOCTYPE guide SYSTEM "/dtd/guide.dtd">
3 sping 1.11 <!-- $Header: /var/cvsroot/gentoo/xml/htdocs/proj/en/overlays/userguide.xml,v 1.10 2010/11/10 00:36:44 sping Exp $ -->
4 stuart 1.1
5 nightmorph 1.9 <guide>
6 stuart 1.1 <title>Gentoo Overlays: Users' Guide</title>
7    
8     <author title="Author">
9 nightmorph 1.9 <mail link="stuart"/>
10 jokey 1.5 </author>
11     <author title="Author">
12 nightmorph 1.9 <mail link="jokey"/>
13     </author>
14     <author title="Editor">
15     <mail link="nightmorph"/>
16 stuart 1.1 </author>
17    
18 nightmorph 1.9 <abstract>
19     This guide helps users understand how to use the Gentoo Overlays service.
20     </abstract>
21 stuart 1.1
22 nightmorph 1.9 <!-- The content of this document is licensed under the CC-BY-SA license -->
23     <!-- See http://creativecommons.org/licenses/by-sa/2.5 -->
24 stuart 1.1 <license/>
25    
26 sping 1.11 <version>2</version>
27     <date>2011-07-25</date>
28 stuart 1.1
29     <chapter>
30     <title>Introduction</title>
31     <section>
32     <title>Audience</title>
33     <body>
34 nightmorph 1.9
35     <p>
36     This document has been written for all users of Gentoo. If you are a Gentoo
37 stuart 1.1 developer or Gentoo staff member, and you want to be able to manage your own
38 nightmorph 1.9 overlay, please see the <uri link="/proj/en/overlays/devguide.xml">Developers'
39     Guide</uri>.
40     </p>
41    
42 stuart 1.1 </body>
43     </section>
44    
45     <section>
46     <title>What Are Overlays?</title>
47     <body>
48 nightmorph 1.9
49     <p>
50     "Overlays" are package trees for Portage. They contain additional ebuilds for
51     Gentoo. They are maintained by Gentoo developers and projects but distributed
52     separately from the main Portage tree.
53     </p>
54    
55 stuart 1.1 </body>
56     </section>
57    
58     <section>
59     <title>Why Use Overlays?</title>
60     <body>
61 nightmorph 1.9
62     <p>
63     People create overlays for all sorts of reasons. Here are a few of the main
64     ones:
65     </p>
66    
67 stuart 1.1 <ul>
68 nightmorph 1.9 <li>
69     If you modify an ebuild in <path>/usr/portage</path>, your change will be
70     lost the next time you <c>emerge --sync</c>. But, if you put your modified
71     ebuild into an overlay, your change is safe from <c>emerge --sync</c>.
72     </li>
73     <li>
74     Because overlays are not the main Gentoo Portage package tree, they're a
75     great place to develop and test an ebuild without fear of breaking the main
76     Gentoo Portage package tree.
77     </li>
78     <li>
79     Not every ebuild belongs in the Gentoo Portage package tree. An overlay is
80     a great place to store an ebuild until it is ready to go into the Gentoo
81     Portage package tree.
82     </li>
83 stuart 1.1 </ul>
84 nightmorph 1.9
85 stuart 1.1 </body>
86     </section>
87     <section>
88 jokey 1.5 <title>What is the Gentoo Overlays Project?</title>
89 stuart 1.1 <body>
90 nightmorph 1.9
91     <p>
92     Gentoo Overlays provide social workspaces to allow Gentoo projects, developers
93     and users to collaborate together on tomorrow's Gentoo packages. We do this by
94     hosting overlays for Gentoo projects, developers, and users.
95     </p>
96    
97 stuart 1.1 </body>
98     </section>
99     <section>
100     <title>Are All Official Overlays Hosted On overlays.gentoo.org?</title>
101     <body>
102 nightmorph 1.9
103     <p>
104     No. Gentoo developers are free to put their overlay wherever suits them best;
105     they don't have to use overlays.gentoo.org if they don't want to.
106     </p>
107    
108 stuart 1.1 </body>
109     </section>
110     </chapter>
111    
112     <chapter>
113     <title>Getting Started With Overlays</title>
114     <section>
115     <body>
116 nightmorph 1.9
117     <p>
118     Use <c>layman</c> to easily install and update overlays over time.
119     </p>
120    
121 stuart 1.1 </body>
122     </section>
123     <section>
124     <title>Installing Layman</title>
125     <body>
126 nightmorph 1.9
127     <p>
128 sping 1.11 Before you install layman it is worth mentioning that you probably want <c>USE=&quot;git subversion&quot;</c> for it.
129     After adjusting use flags, to install <c>layman</c> you run:
130 nightmorph 1.9 </p>
131    
132 stuart 1.1 <pre caption="Installing layman">
133 nightmorph 1.9 # <i>emerge layman</i>
134 jokey 1.6 </pre>
135 nightmorph 1.9
136 jokey 1.6 <pre caption="Telling Portage about layman-fetched repositories">
137     <comment>(for layman 1.1)</comment>
138 nightmorph 1.9 # <i>echo "source /usr/portage/local/layman/make.conf" >> /etc/make.conf</i>
139 jokey 1.6
140 sping 1.8 <comment>(for layman 1.2)</comment>
141 nightmorph 1.9 # <i>echo "source /usr/local/portage/layman/make.conf" >> /etc/make.conf</i>
142 sping 1.8
143 sping 1.10 <comment>(for layman 1.3 and later)</comment>
144 nightmorph 1.9 # <i>echo "source /var/lib/layman/make.conf" >> /etc/make.conf</i>
145 stuart 1.1 </pre>
146 nightmorph 1.9
147 wrobel 1.2 <note>
148 sping 1.10 Layman will create <path>/var/lib/layman/make.conf</path> once you add
149 nightmorph 1.9 your first overlay. But if you do not plan to install an overlay immediately you
150     should ensure that this file actually exists and contains the empty variable
151     <c>PORTDIR_OVERLAY</c>. Otherwise Portage will complain. You can run <c>echo
152 sping 1.10 PORTDIR_OVERLAY=\"\" > /var/lib/layman/make.conf</c> in order to have
153 nightmorph 1.9 the file created correctly.
154 wrobel 1.2 </note>
155 nightmorph 1.9
156 stuart 1.1 </body>
157     </section>
158     <section>
159 jokey 1.5 <title>Listing The Available Overlays</title>
160 stuart 1.1 <body>
161 nightmorph 1.9
162     <p>
163     To see the list of overlays available, run:
164     </p>
165    
166     <pre caption="Listing the available overlays">
167     # <i>layman -L</i>
168     </pre>
169    
170 stuart 1.1 </body>
171     </section>
172     <section>
173     <title>Installing An Overlay</title>
174     <body>
175 nightmorph 1.9
176     <p>
177     To install an overlay on your computer, run:
178     </p>
179    
180 stuart 1.1 <pre caption="Adding an overlay">
181 nightmorph 1.9 # <i>layman -a &lt;overlay-name&gt;</i>
182 stuart 1.1 </pre>
183 nightmorph 1.9
184     <p>
185     For example, to install <uri link="http://overlays.gentoo.org/proj/php">the PHP
186     overlay</uri>, run:
187     </p>
188    
189 stuart 1.1 <pre caption="Adding the PHP overlay">
190 nightmorph 1.9 # <i>layman -a php</i>
191 stuart 1.1 </pre>
192 nightmorph 1.9
193 stuart 1.1 </body>
194     </section>
195     <section>
196     <title>Installing Packages From An Overlay</title>
197     <body>
198    
199 nightmorph 1.9 <p>
200     After installing an overlay, you can install packages from it by running:
201     </p>
202    
203     <pre caption="Installing a package from an overlay">
204     # <i>emerge -av &lt;category&gt;/&lt;package&gt;</i>
205     </pre>
206    
207     <p>
208 sping 1.11 Portage automatically searches your Gentoo main tree (in
209 nightmorph 1.9 <path>/usr/portage</path>) and all of the overlays that you've installed, and
210     picks the latest version of the package that it can find.
211     </p>
212    
213     <p>
214     If Portage isn't picking up the package from the overlay, that's normally
215 stuart 1.1 because the package is marked ~arch, where "arch" is the architecture of your
216 nightmorph 1.9 computer. You'll need to keyword the package as explained in the <uri
217 sping 1.11 link="/doc/en/handbook/">Gentoo Handbook</uri>.
218 nightmorph 1.9 </p>
219    
220 stuart 1.1 </body>
221     </section>
222     <section>
223     <title>Updating An Overlay</title>
224     <body>
225 nightmorph 1.9
226     <p>
227     To keep your installed overlays up to date, run:
228     </p>
229    
230     <pre caption="Updating all installed overlays">
231     # <i>layman -S</i>
232 stuart 1.1 </pre>
233 nightmorph 1.9
234     <impo>
235     Please don't run this more than once a day, or you'll put too much strain on
236     Gentoo's infrastructure.
237     </impo>
238    
239 stuart 1.1 </body>
240     </section>
241     </chapter>
242    
243     <chapter>
244     <title>How To Get More Involved</title>
245     <section>
246     <title>Introduction</title>
247     <body>
248    
249 nightmorph 1.9 <p>
250     All Gentoo developers were users of Gentoo before they became developers and
251     still are users. Our users aren't just the reason Gentoo exists today; they're
252     our future volunteers too.
253     </p>
254    
255     <p>
256     If you start contributing to a project, we'll give you write access to the
257 stuart 1.1 project's overlay, and we'll provide mentors to help you contribute.
258 nightmorph 1.9 Eventually, if we like what you do and the way you do it, we'll invite you to go
259     the whole hog and become a full Gentoo developer.
260     </p>
261    
262 stuart 1.1 </body>
263     </section>
264     <section>
265     <title>How To Get Started</title>
266     <body>
267 nightmorph 1.9
268     <p>
269     If you want to contribute to an overlay, the best approach is to build a good
270 stuart 1.1 working relationship with the Gentoo developers who are responsible for the
271 nightmorph 1.9 overlay. You can find out who is responsible for each overlay by going to <uri
272     link="http://overlays.gentoo.org">overlays.gentoo.org's homepage</uri>, and
273     clicking on the link for the overlay in question.
274     </p>
275    
276     <p>
277     Different developers prefer to be contacted in different ways. Some hang out on
278     IRC, and may have their own channels for their projects. Examples of these
279     include the PHP project (#gentoo-php), and the Webapps project (#gentoo-web).
280     Others prefer to be contacted by email only. The only way you'll find out is to
281     try and make contact, and take it from there. Commonly people in #gentoo-bugs on
282     freenode IRC know where to find the people in question.
283     </p>
284 stuart 1.1
285     </body>
286     </section>
287     <section>
288     <title>Working With Subversion</title>
289     <body>
290 nightmorph 1.9
291     <p>
292     <uri link="http://subversion.apache.org">Subversion</uri> is one version control
293     software we use to manage the contents of our overlays. If you have never used
294     Subversion before, the Subversion book is an excellent way to learn Subversion.
295     You can buy it in dead-tree format if you prefer or read it online for free.
296 jokey 1.5 </p>
297 nightmorph 1.9
298 jokey 1.5 </body>
299     </section>
300     <section>
301     <title>Working With Git</title>
302     <body>
303 nightmorph 1.9
304     <p>
305     Git is another version control software we use to manage the contents of our
306     overlays. To get in touch with it, see the tutorial provided on the <uri
307     link="http://www.git-scm.com">homepage</uri>.
308     </p>
309    
310 stuart 1.1 </body>
311     </section>
312     <section>
313     <title>Further Information</title>
314     <body>
315 nightmorph 1.9
316     <p>
317     The Gentoo project (or developer) you're working with should be able to provide
318     you with any further help and assistance that you need.
319     </p>
320    
321 stuart 1.1 </body>
322     </section>
323     </chapter>
324    
325     <chapter>
326     <title>Frequently Asked Questions</title>
327     <section>
328     <body>
329 nightmorph 1.9
330     <p>
331     <b>Q:</b> Do you host overlays for users?
332     </p>
333    
334     <p>
335     <b>A:</b> Yes, we do. Please see <uri
336     link="http://blog.hartwork.org/?p=843">this post</uri> for instructions on how
337     to host your overlay on Gentoo infrastructure.
338     </p>
339    
340 stuart 1.1 </body>
341     </section>
342     </chapter>
343     </guide>

  ViewVC Help
Powered by ViewVC 1.1.20