/[gentoo]/xml/htdocs/proj/en/overlays/userguide.xml
Gentoo

Diff of /xml/htdocs/proj/en/overlays/userguide.xml

Parent Directory Parent Directory | Revision Log Revision Log | View Patch Patch

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

Legend:
Removed from v.1.8  
changed lines
  Added in v.1.9

  ViewVC Help
Powered by ViewVC 1.1.20