<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 <urilink="/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>

<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

<urilink="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 <urilink="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>