/[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 - (show annotations) (download) (as text)
Tue Jul 13 21:52:27 2010 UTC (4 years, 4 months 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 <?xml version="1.0" encoding="UTF-8"?>
2 <!DOCTYPE guide SYSTEM "/dtd/guide.dtd">
3 <!-- $Header: $ -->
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>1.2</version>
27 <date>2010-07-13</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 To install <c>layman</c>, follow these steps:
129 </p>
130
131 <pre caption="Installing layman">
132 # <i>emerge layman</i>
133 </pre>
134
135 <pre caption="Telling Portage about layman-fetched repositories">
136 <comment>(for layman 1.1)</comment>
137 # <i>echo "source /usr/portage/local/layman/make.conf" >> /etc/make.conf</i>
138
139 <comment>(for layman 1.2)</comment>
140 # <i>echo "source /usr/local/portage/layman/make.conf" >> /etc/make.conf</i>
141
142 <comment>(for layman 1.3)</comment>
143 # <i>echo "source /var/lib/layman/make.conf" >> /etc/make.conf</i>
144 </pre>
145
146 <note>
147 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 </note>
154
155 </body>
156 </section>
157 <section>
158 <title>Listing The Available Overlays</title>
159 <body>
160
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 </body>
170 </section>
171 <section>
172 <title>Installing An Overlay</title>
173 <body>
174
175 <p>
176 To install an overlay on your computer, run:
177 </p>
178
179 <pre caption="Adding an overlay">
180 # <i>layman -a &lt;overlay-name&gt;</i>
181 </pre>
182
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 <pre caption="Adding the PHP overlay">
189 # <i>layman -a php</i>
190 </pre>
191
192 </body>
193 </section>
194 <section>
195 <title>Installing Packages From An Overlay</title>
196 <body>
197
198 <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 because the package is marked ~arch, where "arch" is the architecture of your
215 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 </body>
220 </section>
221 <section>
222 <title>Updating An Overlay</title>
223 <body>
224
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 </pre>
232
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 </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 <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 project's overlay, and we'll provide mentors to help you contribute.
257 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 </body>
262 </section>
263 <section>
264 <title>How To Get Started</title>
265 <body>
266
267 <p>
268 If you want to contribute to an overlay, the best approach is to build a good
269 working relationship with the Gentoo developers who are responsible for the
270 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
284 </body>
285 </section>
286 <section>
287 <title>Working With Subversion</title>
288 <body>
289
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 </p>
296
297 </body>
298 </section>
299 <section>
300 <title>Working With Git</title>
301 <body>
302
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 </body>
310 </section>
311 <section>
312 <title>Further Information</title>
313 <body>
314
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 </body>
321 </section>
322 </chapter>
323
324 <chapter>
325 <title>Frequently Asked Questions</title>
326 <section>
327 <body>
328
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 </body>
340 </section>
341 </chapter>
342 </guide>

  ViewVC Help
Powered by ViewVC 1.1.20