/[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 - (show annotations) (download) (as text)
Mon Jul 25 01:17:54 2011 UTC (3 years, 5 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 <?xml version="1.0" encoding="UTF-8"?>
2 <!DOCTYPE guide SYSTEM "/dtd/guide.dtd">
3 <!-- $Header: /var/cvsroot/gentoo/xml/htdocs/proj/en/overlays/userguide.xml,v 1.10 2010/11/10 00:36:44 sping Exp $ -->
4
5 <guide>
6 <title>Gentoo Overlays: Users' Guide</title>
7
8 <author title="Author">
9 <mail link="stuart"/>
10 </author>
11 <author title="Author">
12 <mail link="jokey"/>
13 </author>
14 <author title="Editor">
15 <mail link="nightmorph"/>
16 </author>
17
18 <abstract>
19 This guide helps users understand how to use the Gentoo Overlays service.
20 </abstract>
21
22 <!-- The content of this document is licensed under the CC-BY-SA license -->
23 <!-- See http://creativecommons.org/licenses/by-sa/2.5 -->
24 <license/>
25
26 <version>2</version>
27 <date>2011-07-25</date>
28
29 <chapter>
30 <title>Introduction</title>
31 <section>
32 <title>Audience</title>
33 <body>
34
35 <p>
36 This document has been written for all users of Gentoo. If you are a Gentoo
37 developer or Gentoo staff member, and you want to be able to manage your own
38 overlay, please see the <uri link="/proj/en/overlays/devguide.xml">Developers'
39 Guide</uri>.
40 </p>
41
42 </body>
43 </section>
44
45 <section>
46 <title>What Are Overlays?</title>
47 <body>
48
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 </body>
56 </section>
57
58 <section>
59 <title>Why Use Overlays?</title>
60 <body>
61
62 <p>
63 People create overlays for all sorts of reasons. Here are a few of the main
64 ones:
65 </p>
66
67 <ul>
68 <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 </ul>
84
85 </body>
86 </section>
87 <section>
88 <title>What is the Gentoo Overlays Project?</title>
89 <body>
90
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 </body>
98 </section>
99 <section>
100 <title>Are All Official Overlays Hosted On overlays.gentoo.org?</title>
101 <body>
102
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 </body>
109 </section>
110 </chapter>
111
112 <chapter>
113 <title>Getting Started With Overlays</title>
114 <section>
115 <body>
116
117 <p>
118 Use <c>layman</c> to easily install and update overlays over time.
119 </p>
120
121 </body>
122 </section>
123 <section>
124 <title>Installing Layman</title>
125 <body>
126
127 <p>
128 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 </p>
131
132 <pre caption="Installing layman">
133 # <i>emerge layman</i>
134 </pre>
135
136 <pre caption="Telling Portage about layman-fetched repositories">
137 <comment>(for layman 1.1)</comment>
138 # <i>echo "source /usr/portage/local/layman/make.conf" >> /etc/make.conf</i>
139
140 <comment>(for layman 1.2)</comment>
141 # <i>echo "source /usr/local/portage/layman/make.conf" >> /etc/make.conf</i>
142
143 <comment>(for layman 1.3 and later)</comment>
144 # <i>echo "source /var/lib/layman/make.conf" >> /etc/make.conf</i>
145 </pre>
146
147 <note>
148 Layman will create <path>/var/lib/layman/make.conf</path> once you add
149 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 PORTDIR_OVERLAY=\"\" > /var/lib/layman/make.conf</c> in order to have
153 the file created correctly.
154 </note>
155
156 </body>
157 </section>
158 <section>
159 <title>Listing The Available Overlays</title>
160 <body>
161
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 </body>
171 </section>
172 <section>
173 <title>Installing An Overlay</title>
174 <body>
175
176 <p>
177 To install an overlay on your computer, run:
178 </p>
179
180 <pre caption="Adding an overlay">
181 # <i>layman -a &lt;overlay-name&gt;</i>
182 </pre>
183
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 <pre caption="Adding the PHP overlay">
190 # <i>layman -a php</i>
191 </pre>
192
193 </body>
194 </section>
195 <section>
196 <title>Installing Packages From An Overlay</title>
197 <body>
198
199 <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 Portage automatically searches your Gentoo main tree (in
209 <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 because the package is marked ~arch, where "arch" is the architecture of your
216 computer. You'll need to keyword the package as explained in the <uri
217 link="/doc/en/handbook/">Gentoo Handbook</uri>.
218 </p>
219
220 </body>
221 </section>
222 <section>
223 <title>Updating An Overlay</title>
224 <body>
225
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 </pre>
233
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 </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 <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 project's overlay, and we'll provide mentors to help you contribute.
258 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 </body>
263 </section>
264 <section>
265 <title>How To Get Started</title>
266 <body>
267
268 <p>
269 If you want to contribute to an overlay, the best approach is to build a good
270 working relationship with the Gentoo developers who are responsible for the
271 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
285 </body>
286 </section>
287 <section>
288 <title>Working With Subversion</title>
289 <body>
290
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 </p>
297
298 </body>
299 </section>
300 <section>
301 <title>Working With Git</title>
302 <body>
303
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 </body>
311 </section>
312 <section>
313 <title>Further Information</title>
314 <body>
315
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 </body>
322 </section>
323 </chapter>
324
325 <chapter>
326 <title>Frequently Asked Questions</title>
327 <section>
328 <body>
329
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 </body>
341 </section>
342 </chapter>
343 </guide>

  ViewVC Help
Powered by ViewVC 1.1.20