/[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 - (show annotations) (download) (as text)
Sat Apr 6 11:04:20 2013 UTC (12 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 <?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.11 2011/07/25 01:17:54 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 <author title="Editor">
18 <mail link="dastergon"/>
19 </author>
20
21 <abstract>
22 This guide helps users understand how to use the Gentoo Overlays service.
23 </abstract>
24
25 <!-- The content of this document is licensed under the CC-BY-SA license -->
26 <!-- See http://creativecommons.org/licenses/by-sa/2.5 -->
27 <license/>
28
29 <version>2</version>
30 <date>2013-04-06</date>
31
32 <chapter>
33 <title>Introduction</title>
34 <section>
35 <title>Audience</title>
36 <body>
37
38 <p>
39 This document has been written for all users of Gentoo. If you are a Gentoo
40 developer or Gentoo staff member, and you want to be able to manage your own
41 overlay, please see the <uri link="/proj/en/overlays/devguide.xml">Developers'
42 Guide</uri>.
43 </p>
44
45 </body>
46 </section>
47
48 <section>
49 <title>What Are Overlays?</title>
50 <body>
51
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 </body>
59 </section>
60
61 <section>
62 <title>Why Use Overlays?</title>
63 <body>
64
65 <p>
66 People create overlays for all sorts of reasons. Here are a few of the main
67 ones:
68 </p>
69
70 <ul>
71 <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 </ul>
87
88 </body>
89 </section>
90 <section>
91 <title>What is the Gentoo Overlays Project?</title>
92 <body>
93
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 </body>
101 </section>
102 <section>
103 <title>Are All Official Overlays Hosted On overlays.gentoo.org?</title>
104 <body>
105
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 </body>
112 </section>
113 </chapter>
114
115 <chapter>
116 <title>Getting Started With Overlays</title>
117 <section>
118 <body>
119
120 <p>
121 Use <c>layman</c> to easily install and update overlays over time.
122 </p>
123
124 </body>
125 </section>
126 <section>
127 <title>Installing Layman</title>
128 <body>
129
130 <p>
131 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 </p>
134
135 <pre caption="Installing layman">
136 # <i>emerge layman</i>
137 </pre>
138
139 <pre caption="Telling Portage about layman-fetched repositories">
140 <comment>(for layman 1.1)</comment>
141 # <i>echo "source /usr/portage/local/layman/make.conf" >> /etc/portage/make.conf</i>
142
143 <comment>(for layman 1.2)</comment>
144 # <i>echo "source /usr/local/portage/layman/make.conf" >> /etc/portage/make.conf</i>
145
146 <comment>(for layman 1.3 and later)</comment>
147 # <i>echo "source /var/lib/layman/make.conf" >> /etc/portage/make.conf</i>
148 </pre>
149
150 <note>
151 Layman will create <path>/var/lib/layman/make.conf</path> once you add
152 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 PORTDIR_OVERLAY=\"\" > /var/lib/layman/make.conf</c> in order to have
156 the file created correctly.
157 </note>
158
159 </body>
160 </section>
161 <section>
162 <title>Listing The Available Overlays</title>
163 <body>
164
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 </body>
174 </section>
175 <section>
176 <title>Installing An Overlay</title>
177 <body>
178
179 <p>
180 To install an overlay on your computer, run:
181 </p>
182
183 <pre caption="Adding an overlay">
184 # <i>layman -a &lt;overlay-name&gt;</i>
185 </pre>
186
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 <pre caption="Adding the PHP overlay">
193 # <i>layman -a php</i>
194 </pre>
195
196 </body>
197 </section>
198 <section>
199 <title>Installing Packages From An Overlay</title>
200 <body>
201
202 <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 Portage automatically searches your Gentoo main tree (in
212 <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 because the package is marked ~arch, where "arch" is the architecture of your
219 computer. You'll need to keyword the package as explained in the <uri
220 link="/doc/en/handbook/">Gentoo Handbook</uri>.
221 </p>
222
223 </body>
224 </section>
225 <section>
226 <title>Updating An Overlay</title>
227 <body>
228
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 </pre>
236
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 </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 <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 project's overlay, and we'll provide mentors to help you contribute.
261 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 </body>
266 </section>
267 <section>
268 <title>How To Get Started</title>
269 <body>
270
271 <p>
272 If you want to contribute to an overlay, the best approach is to build a good
273 working relationship with the Gentoo developers who are responsible for the
274 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
288 </body>
289 </section>
290 <section>
291 <title>Working With Subversion</title>
292 <body>
293
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 </p>
300
301 </body>
302 </section>
303 <section>
304 <title>Working With Git</title>
305 <body>
306
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 </body>
314 </section>
315 <section>
316 <title>Further Information</title>
317 <body>
318
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 </body>
325 </section>
326 </chapter>
327
328 <chapter>
329 <title>Frequently Asked Questions</title>
330 <section>
331 <body>
332
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 </body>
344 </section>
345 </chapter>
346 </guide>

  ViewVC Help
Powered by ViewVC 1.1.20