/[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.9 - (hide annotations) (download) (as text)
Tue Jul 13 21:52:27 2010 UTC (4 years ago) by nightmorph
Branch: MAIN
Changes since 1.8: +201 -85 lines
File MIME type: application/xml
significant guideXML fixes, grammar fixes, rewrites to be more helpful. discovered while updating the documentation in the main tree to recommend layman instead of gensync, primpted by bug 305047.

1 stuart 1.1 <?xml version="1.0" encoding="UTF-8"?>
2     <!DOCTYPE guide SYSTEM "/dtd/guide.dtd">
3 nightmorph 1.9 <!-- $Header: $ -->
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 nightmorph 1.9 <version>1.2</version>
27     <date>2010-07-13</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     To install <c>layman</c>, follow these steps:
129     </p>
130    
131 stuart 1.1 <pre caption="Installing layman">
132 nightmorph 1.9 # <i>emerge layman</i>
133 jokey 1.6 </pre>
134 nightmorph 1.9
135 jokey 1.6 <pre caption="Telling Portage about layman-fetched repositories">
136     <comment>(for layman 1.1)</comment>
137 nightmorph 1.9 # <i>echo "source /usr/portage/local/layman/make.conf" >> /etc/make.conf</i>
138 jokey 1.6
139 sping 1.8 <comment>(for layman 1.2)</comment>
140 nightmorph 1.9 # <i>echo "source /usr/local/portage/layman/make.conf" >> /etc/make.conf</i>
141 sping 1.8
142     <comment>(for layman 1.3)</comment>
143 nightmorph 1.9 # <i>echo "source /var/lib/layman/make.conf" >> /etc/make.conf</i>
144 stuart 1.1 </pre>
145 nightmorph 1.9
146 wrobel 1.2 <note>
147 nightmorph 1.9 Layman will create <path>/usr/local/portage/layman/make.conf</path> once you add
148     your first overlay. But if you do not plan to install an overlay immediately you
149     should ensure that this file actually exists and contains the empty variable
150     <c>PORTDIR_OVERLAY</c>. Otherwise Portage will complain. You can run <c>echo
151     PORTDIR_OVERLAY=\"\" > /usr/portage/local/layman/make.conf</c> in order to have
152     the file created correctly.
153 wrobel 1.2 </note>
154 nightmorph 1.9
155 stuart 1.1 </body>
156     </section>
157     <section>
158 jokey 1.5 <title>Listing The Available Overlays</title>
159 stuart 1.1 <body>
160 nightmorph 1.9
161     <p>
162     To see the list of overlays available, run:
163     </p>
164    
165     <pre caption="Listing the available overlays">
166     # <i>layman -L</i>
167     </pre>
168    
169 stuart 1.1 </body>
170     </section>
171     <section>
172     <title>Installing An Overlay</title>
173     <body>
174 nightmorph 1.9
175     <p>
176     To install an overlay on your computer, run:
177     </p>
178    
179 stuart 1.1 <pre caption="Adding an overlay">
180 nightmorph 1.9 # <i>layman -a &lt;overlay-name&gt;</i>
181 stuart 1.1 </pre>
182 nightmorph 1.9
183     <p>
184     For example, to install <uri link="http://overlays.gentoo.org/proj/php">the PHP
185     overlay</uri>, run:
186     </p>
187    
188 stuart 1.1 <pre caption="Adding the PHP overlay">
189 nightmorph 1.9 # <i>layman -a php</i>
190 stuart 1.1 </pre>
191 nightmorph 1.9
192 stuart 1.1 </body>
193     </section>
194     <section>
195     <title>Installing Packages From An Overlay</title>
196     <body>
197    
198 nightmorph 1.9 <p>
199     After installing an overlay, you can install packages from it by running:
200     </p>
201    
202     <pre caption="Installing a package from an overlay">
203     # <i>emerge -av &lt;category&gt;/&lt;package&gt;</i>
204     </pre>
205    
206     <p>
207     Portage automatically searches your main Portage tree (in
208     <path>/usr/portage</path>) and all of the overlays that you've installed, and
209     picks the latest version of the package that it can find.
210     </p>
211    
212     <p>
213     If Portage isn't picking up the package from the overlay, that's normally
214 stuart 1.1 because the package is marked ~arch, where "arch" is the architecture of your
215 nightmorph 1.9 computer. You'll need to keyword the package as explained in the <uri
216     link="/doc/en/handbook/">Portage Handbook</uri>.
217     </p>
218    
219 stuart 1.1 </body>
220     </section>
221     <section>
222     <title>Updating An Overlay</title>
223     <body>
224 nightmorph 1.9
225     <p>
226     To keep your installed overlays up to date, run:
227     </p>
228    
229     <pre caption="Updating all installed overlays">
230     # <i>layman -S</i>
231 stuart 1.1 </pre>
232 nightmorph 1.9
233     <impo>
234     Please don't run this more than once a day, or you'll put too much strain on
235     Gentoo's infrastructure.
236     </impo>
237    
238 stuart 1.1 </body>
239     </section>
240     </chapter>
241    
242     <chapter>
243     <title>How To Get More Involved</title>
244     <section>
245     <title>Introduction</title>
246     <body>
247    
248 nightmorph 1.9 <p>
249     All Gentoo developers were users of Gentoo before they became developers and
250     still are users. Our users aren't just the reason Gentoo exists today; they're
251     our future volunteers too.
252     </p>
253    
254     <p>
255     If you start contributing to a project, we'll give you write access to the
256 stuart 1.1 project's overlay, and we'll provide mentors to help you contribute.
257 nightmorph 1.9 Eventually, if we like what you do and the way you do it, we'll invite you to go
258     the whole hog and become a full Gentoo developer.
259     </p>
260    
261 stuart 1.1 </body>
262     </section>
263     <section>
264     <title>How To Get Started</title>
265     <body>
266 nightmorph 1.9
267     <p>
268     If you want to contribute to an overlay, the best approach is to build a good
269 stuart 1.1 working relationship with the Gentoo developers who are responsible for the
270 nightmorph 1.9 overlay. You can find out who is responsible for each overlay by going to <uri
271     link="http://overlays.gentoo.org">overlays.gentoo.org's homepage</uri>, and
272     clicking on the link for the overlay in question.
273     </p>
274    
275     <p>
276     Different developers prefer to be contacted in different ways. Some hang out on
277     IRC, and may have their own channels for their projects. Examples of these
278     include the PHP project (#gentoo-php), and the Webapps project (#gentoo-web).
279     Others prefer to be contacted by email only. The only way you'll find out is to
280     try and make contact, and take it from there. Commonly people in #gentoo-bugs on
281     freenode IRC know where to find the people in question.
282     </p>
283 stuart 1.1
284     </body>
285     </section>
286     <section>
287     <title>Working With Subversion</title>
288     <body>
289 nightmorph 1.9
290     <p>
291     <uri link="http://subversion.apache.org">Subversion</uri> is one version control
292     software we use to manage the contents of our overlays. If you have never used
293     Subversion before, the Subversion book is an excellent way to learn Subversion.
294     You can buy it in dead-tree format if you prefer or read it online for free.
295 jokey 1.5 </p>
296 nightmorph 1.9
297 jokey 1.5 </body>
298     </section>
299     <section>
300     <title>Working With Git</title>
301     <body>
302 nightmorph 1.9
303     <p>
304     Git is another version control software we use to manage the contents of our
305     overlays. To get in touch with it, see the tutorial provided on the <uri
306     link="http://www.git-scm.com">homepage</uri>.
307     </p>
308    
309 stuart 1.1 </body>
310     </section>
311     <section>
312     <title>Further Information</title>
313     <body>
314 nightmorph 1.9
315     <p>
316     The Gentoo project (or developer) you're working with should be able to provide
317     you with any further help and assistance that you need.
318     </p>
319    
320 stuart 1.1 </body>
321     </section>
322     </chapter>
323    
324     <chapter>
325     <title>Frequently Asked Questions</title>
326     <section>
327     <body>
328 nightmorph 1.9
329     <p>
330     <b>Q:</b> Do you host overlays for users?
331     </p>
332    
333     <p>
334     <b>A:</b> Yes, we do. Please see <uri
335     link="http://blog.hartwork.org/?p=843">this post</uri> for instructions on how
336     to host your overlay on Gentoo infrastructure.
337     </p>
338    
339 stuart 1.1 </body>
340     </section>
341     </chapter>
342     </guide>

  ViewVC Help
Powered by ViewVC 1.1.20