/[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.12 - (hide annotations) (download) (as text)
Sat Apr 6 11:04:20 2013 UTC (16 months, 2 weeks ago) by dastergon
Branch: MAIN
CVS Tags: HEAD
Changes since 1.11: +8 -5 lines
File MIME type: application/xml
fixed deprecated references to /etc/make.conf, wrt #445192

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

  ViewVC Help
Powered by ViewVC 1.1.20