/[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.3 - (show annotations) (download) (as text)
Wed Oct 11 21:22:49 2006 UTC (8 years, 1 month ago) by stuart
Branch: MAIN
Changes since 1.2: +1 -1 lines
File MIME type: application/xml
Fixed name of layman config file in user guide

1 <?xml version="1.0" encoding="UTF-8"?>
2 <!DOCTYPE guide SYSTEM "/dtd/guide.dtd">
3
4 <guide link="/proj/en/overlays/userguide.xml">
5 <title>Gentoo Overlays: Users' Guide</title>
6
7 <author title="Author">
8 <mail link="stuart@gentoo.org">Stuart Herbert</mail>
9 </author>
10
11 <abstract>This guide helps users understand how to use the Gentoo Overlays service</abstract>
12
13 <license/>
14
15 <version>1.0</version>
16 <date>2006-07-30</date>
17
18 <chapter>
19 <title>Introduction</title>
20 <section>
21 <title>Audience</title>
22 <body>
23 <p>This document has been written for all users of Gentoo. If you are a Gentoo
24 developer or Gentoo staff member, and you want to be able to manage your own
25 overlay, please see the <uri link="/proj/en/overlays/devguide.xml">Developers' Guide</uri>.</p>
26 </body>
27 </section>
28
29 <section>
30 <title>What Are Overlays?</title>
31 <body>
32 <p>"Overlays" are package trees for Portage. They contain additional ebuilds for Gentoo. They are maintained by Gentoo developers, but are distributed separately from the main Portage tree.</p>
33 </body>
34 </section>
35
36 <section>
37 <title>Why Use Overlays?</title>
38 <body>
39 <p>People create overlays for all sorts of reasons. Here are a few of the main
40 ones:</p>
41 <ul>
42 <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>
43 <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>
44 <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>
45 </ul>
46 </body>
47 </section>
48
49 <section>
50 <title>What Is overlays.gentoo.org?</title>
51 <body>
52 <p><uri link="http://overlays.gentoo.org">overlays.gentoo.org</uri> provides social workspaces to allow Gentoo projects,
53 developers and users to collaborate together on tomorrow's Gentoo packages.
54 We do this by host overlays for Gentoo projects, and overlays for Gentoo
55 developers.</p>
56 </body>
57 </section>
58
59 <section>
60 <title>Are All Official Overlays Hosted On overlays.gentoo.org?</title>
61 <body>
62 <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>
63 </body>
64 </section>
65 </chapter>
66
67 <chapter>
68 <title>Getting Started With Overlays</title>
69 <section>
70 <body>
71 <p>Use Gunnar Wrobel's layman to easily install and update overlays over
72 time.</p>
73 </body>
74 </section>
75
76 <section>
77 <title>Installing Layman</title>
78 <body>
79 <p>To install layman, follow these steps:</p>
80 <pre caption="Installing layman">
81 <i>emerge layman</i>
82 <i>echo "source /usr/portage/local/layman/make.conf" >> /etc/make.conf</i>
83 </pre>
84 <note>
85 Layman will create "/usr/portage/local/layman/make.conf" once you
86 add your first overlay. But if you do not plan to install an overlay
87 immediately you should ensure that this file actually
88 exists. Otherwise portage will complain. It does not need to have any
89 content so you can run "touch /usr/portage/local/layman/make.conf".
90 </note>
91 </body>
92 </section>
93
94 <section>
95 <title>Listing The Overlays Available</title>
96 <body>
97 <p>To see the list of overlays available, run:</p>
98 <pre caption="Listing the available overlays">layman -L</pre>
99 </body>
100 </section>
101
102 <section>
103 <title>Installing An Overlay</title>
104 <body>
105 <p>To install an overlay on your computer, run:</p>
106 <pre caption="Adding an overlay">
107 layman -a &lt;overlay-name&gt;
108 </pre>
109 <p>For example, to install <uri link="http://overlays.gentoo.org/proj/php">the PHP overlay</uri>, run:</p>
110 <pre caption="Adding the PHP overlay">
111 layman -a php
112 </pre>
113 </body>
114 </section>
115
116 <section>
117 <title>Installing Packages From An Overlay</title>
118 <body>
119 <p>After installing an overlay, you can install packages from it by running:</p>
120 <pre caption="Installing A Package From An Overlay">
121 emerge -av &lt;category&gt;/&lt;package&gt;
122 </pre>
123 <p>Portage automatically searches your main Portage tree (in /usr/portage), and
124 all of the overlays that you've installed, and picks the latest version of the
125 package that it can find.</p>
126
127 <p>If Portage isn't picking up the package from the overlay, that's normally
128 because the package is marked ~arch, where "arch" is the architecture of your
129 computer (normally x86).</p>
130 </body>
131 </section>
132
133 <section>
134 <title>Updating An Overlay</title>
135 <body>
136 <p>To keep your installed overlays up to date, run:</p>
137 <pre caption="Updating All Installed Overlays">
138 layman --sync ALL
139 </pre>
140 <p>Please don't run this more than once a day, or you'll put too much strain on
141 Gentoo's infrastructure.</p>
142 </body>
143 </section>
144 </chapter>
145
146 <chapter>
147 <title>How To Get More Involved</title>
148
149 <section>
150 <title>Introduction</title>
151 <body>
152 <p>All Gentoo developers were users of Gentoo before they became developers. Our users aren't just the reason Gentoo exists today; they're our future volunteers too.</p>
153
154 <p>If you start contributing to a project, we'll give you write access to the
155 project's overlay, and we'll provide mentors to help you contribute.
156 Eventually, if we like what you do and the way you do it, we'll invite you to
157 go the whole hog and become a full Gentoo developer, with a nice shiny
158 @gentoo.org email address.</p>
159 </body>
160 </section>
161
162 <section>
163 <title>How To Get Started</title>
164 <body>
165 <p>If you want to contribute to an overlay, the best approach is to build a good
166 working relationship with the Gentoo developers who are responsible for the
167 overlay. You can find out who is responsible for each overlay by going to
168 <uri link="http://overlays.gentoo.org">overlays.gentoo.org's homepage</uri>, and clicking on the link for the overlay in question.</p>
169
170 <p>Different developers preferred to be contacted in different ways. Some hang
171 out on IRC, and may have their own channels for their projects. Examples of
172 these include the PHP project (#gentoo-php), and the Webapps project
173 (#gentoo-web). Others prefer to be contacted by email only. The only way
174 you'll find out is to try and make contact, and take it from there.</p>
175 </body>
176 </section>
177
178 <section>
179 <title>Working With Subversion</title>
180 <body>
181 <p>You'll need to get comfortable working with Subversion. Subversion is the
182 version control software we use to manage the contents of our overlays. If you have never used Subversion before, the <uri link="http://svnbook.red-bean.com/">online book</uri> is an excellent way to learn Subversion. You can buy it in dead-tree format too if you prefer.</p>
183 </body>
184 </section>
185
186 <section>
187 <title>Further Information</title>
188 <body>
189 <p>The Gentoo project (or developer) you're working with should be able to
190 provide you with any further help and assistance that you need.</p>
191 </body>
192 </section>
193 </chapter>
194
195 <chapter>
196 <title>Frequently Asked Questions</title>
197 <section>
198 <body>
199 <p>Q: Do you host overlays for users?</p>
200 <ul>
201 <li>A: No, we do not. If you want an overlay of your own on o.g.o, you must first become a Gentoo developer.</li>
202 </ul>
203 </body>
204 </section>
205 </chapter>
206 </guide>

  ViewVC Help
Powered by ViewVC 1.1.20