| … | |
… | |
| 17 | <abstract>This guide helps developers understand how to use the Gentoo |
17 | <abstract>This guide helps developers understand how to use the Gentoo |
| 18 | Overlays service.</abstract> |
18 | Overlays service.</abstract> |
| 19 | |
19 | |
| 20 | <license/> |
20 | <license/> |
| 21 | |
21 | |
| 22 | <version>2.0</version> |
22 | <version>2.3</version> |
| 23 | <date>2008-10-12</date> |
23 | <date>2009-01-18</date> |
| 24 | |
24 | |
| 25 | <chapter> |
25 | <chapter> |
| 26 | <title>Introduction</title> |
26 | <title>Introduction</title> |
| 27 | |
27 | |
| 28 | <section> |
28 | <section> |
| … | |
… | |
| 31 | <p>This document has been written for Gentoo developers and Gentoo staff members. If you are a Gentoo user, or you just want to start downloading and using overlays, please see <uri link="/proj/en/overlays/userguide.xml">the Gentoo Overlays User Guide</uri> instead.</p> |
31 | <p>This document has been written for Gentoo developers and Gentoo staff members. If you are a Gentoo user, or you just want to start downloading and using overlays, please see <uri link="/proj/en/overlays/userguide.xml">the Gentoo Overlays User Guide</uri> instead.</p> |
| 32 | </body> |
32 | </body> |
| 33 | </section> |
33 | </section> |
| 34 | |
34 | |
| 35 | <section> |
35 | <section> |
| 36 | <title>What is overlays.gentoo.org?</title> |
|
|
| 37 | <body> |
|
|
| 38 | <p><uri link="http://overlays.gentoo.org">overlays.gentoo.org</uri> provides social workspaces to allow Gentoo projects, developers and users to collaborate together on tomorrow's Gentoo packages. We do this by hosting overlays for Gentoo projects, and overlays for Gentoo developers.</p> |
|
|
| 39 | </body> |
|
|
| 40 | </section> |
|
|
| 41 | |
|
|
| 42 | <section> |
|
|
| 43 | <title>Who Can Use overlays.gentoo.org?</title> |
36 | <title>Who Can Use overlays.gentoo.org?</title> |
| 44 | <body> |
37 | <body> |
| 45 | <p>Any Gentoo project, or Gentoo developer, can have their own overlay hosted on overlays.gentoo.org, with the RSS feed from the changelog included on <uri link="http://overlays.gentoo.org">the overlays.gentoo.org homepage</uri>.</p> |
38 | <p>Any Gentoo project, or Gentoo developer, can have their own overlay hosted on (git.)overlays.gentoo.org, with the RSS feed from the changelog included on <uri link="http://overlays.gentoo.org">the overlays.gentoo.org planet</uri>.</p> |
| 46 | |
39 | |
| 47 | <p>Any Gentoo staff member or user (ie, anyone who doesn't have write access to |
40 | <p>Any User can download and use the contents of any hosted |
| 48 | the main Portage package tree) can download and use the contents of any hosted |
|
|
| 49 | overlay. If you choose, you can also give users write access to your |
41 | overlay. If you choose, you can also give users write access to your |
| 50 | overlay.</p> |
42 | overlay.</p> |
| 51 | </body> |
43 | </body> |
| 52 | </section> |
44 | </section> |
| 53 | |
45 | |
| 54 | <section> |
46 | <section> |
| 55 | <title>What Does overlays.gentoo.org Give Me?</title> |
47 | <title>What Does overlays.gentoo.org Give Me?</title> |
| 56 | <body> |
48 | <body> |
| 57 | <p>The overlays.gentoo.org service currently provides:</p> |
49 | <p>The (git.)overlays.gentoo.org service currently provides:</p> |
| 58 | <ul> |
50 | <ul> |
| 59 | <li><uri link="http://trac.edgewall.com">Trac</uri> (a wiki w/ integrated subversion browser), for quickly creating and maintaining documentation about your overlay</li> |
51 | <li><uri link="http://trac.edgewall.com">Trac</uri> (a wiki w/ integrated subversion browser), for quickly creating and maintaining documentation about your Subversion based overlay</li> |
| 60 | <li><uri link="http://subversion.tigris.org">Subversion</uri> - a centralised version control system</li> |
|
|
| 61 | <li>Publishing the changelog for your overlay on <uri link="http://overlays.gentoo.org/">the o.g.o homepage</uri>, so that everyone who's interested can see what's going on</li> |
52 | <li>Publishing the changelog for your overlay on <uri link="http://overlays.gentoo.org/">the o.g.o homepage</uri>, so that everyone who's interested can see what's going on</li> |
| 62 | <li><uri link="http://git.or.cz">Git</uri> - Fast Version Control System</li> |
|
|
| 63 | <li><uri link="http://git.or.cz/gitwiki/Gitweb">gitweb</uri> - provides full-fledged web interface for viewing Git repositories.</li> |
53 | <li><uri link="http://git.or.cz/gitwiki/Gitweb">gitweb</uri> - provides full-fledged web interface for viewing Git repositories.</li> |
| 64 | </ul> |
54 | </ul> |
| 65 | |
55 | |
| 66 | <p>... all hosted on secure, backed-up Gentoo infrastructure, administered by |
56 | <p>... all hosted on secure, backed-up Gentoo infrastructure, administered by |
| 67 | <uri link="/proj/en/infrastructure">the Gentoo Infrastructure team</uri> (hardware / base OS) and <uri link="/proj/en/overlays">the Gentoo Overlays team</uri> |
57 | <uri link="/proj/en/infrastructure">the Gentoo Infrastructure team</uri> (hardware / base OS) and <uri link="/proj/en/overlays">the Gentoo Overlays team</uri> |
| … | |
… | |
| 112 | |
102 | |
| 113 | <warn>If you're not happy with users using your overlay, and / or if you don't want |
103 | <warn>If you're not happy with users using your overlay, and / or if you don't want |
| 114 | users bothering you about your overlay, then don't use o.g.o to host your |
104 | users bothering you about your overlay, then don't use o.g.o to host your |
| 115 | overlay.</warn> |
105 | overlay.</warn> |
| 116 | |
106 | |
| 117 | <p>The other thing we need to say is that o.g.o is for hosting overlays. You |
107 | <p>o.g.o used to have restrictions of not being the $UPSTREAM for packages. |
| 118 | can't use it to be $UPSTREAM for your packages. If that's the kind of hosting |
108 | This restriction has been adjusted. We do offer hosting as the $UPSTREAM now, |
| 119 | you need, you can use services such as <uri link="http://www.sourceforge.net/">SourceForge.net</uri>, <uri link="http://www.berlios.de">Berlios</uri>, or |
109 | but only for packages that are Gentoo-specific or important to the running of |
|
|
110 | Gentoo. Other hosting may be more suitable, some services in this vein are: |
|
|
111 | <uri link="http://www.sourceforge.net/">SourceForge.net</uri>, <uri |
|
|
112 | link="http://www.berlios.de">Berlios</uri>, or Patrick's <uri |
| 120 | Patrick's <uri link="http://www.gentooexperimental.org">GentooExperimental.org</uri>.</p> |
113 | link="http://www.gentooexperimental.org">GentooExperimental.org</uri>.</p> |
| 121 | </body> |
114 | </body> |
| 122 | </section> |
115 | </section> |
| 123 | </chapter> |
116 | </chapter> |
| 124 | |
117 | |
| 125 | <chapter> |
118 | <chapter> |
| … | |
… | |
| 137 | </section> |
130 | </section> |
| 138 | |
131 | |
| 139 | <section> |
132 | <section> |
| 140 | <title>Project Overlays</title> |
133 | <title>Project Overlays</title> |
| 141 | <body> |
134 | <body> |
| 142 | <p>"Project" overlays are overlays for official Gentoo projects. A good |
135 | <p>"Project" overlays are overlays for official Gentoo projects. An example is <uri link="http://overlays.gentoo.org/proj/php">the PHP Overlay</uri>.</p> |
| 143 | example is <uri link="http://overlays.gentoo.org/proj/php">the PHP Overlay</uri>.</p> |
|
|
| 144 | |
136 | |
| 145 | <p>An official Gentoo project is a project that has a project page on |
137 | <p>An official Gentoo project is a project that has a project page on |
| 146 | www.gentoo.org, and that has an elected lead. (This definition comes from <uri link="http://www.gentoo.org/proj/en/glep/glep-0039.html">the |
138 | www.gentoo.org, and that has an elected lead. (This definition comes from the |
| 147 | metastructure document</uri>, which is Gentoo's governing document). The project |
139 | metastructure document). The project lead(s) are responsible for the project overlay, including its contents, and any problems it causes other Gentoo projects and developers.</p> |
| 148 | lead(s) are responsible for the project overlay, including its contents, and |
|
|
| 149 | any problems it causes other Gentoo projects and developers.</p> |
|
|
| 150 | |
140 | |
| 151 | <p>To request a SVN project overlay, the project's lead just needs to pop into |
141 | <p>To request a SVN project overlay, the project's lead just needs to pop into |
| 152 | #gentoo-overlays on IRC and ask for an overlay to be created. Or, if he/she |
142 | #gentoo-overlays on IRC and ask for an overlay to be created. Or, if he/she |
| 153 | prefers, drop an email to overlays@gentoo.org. We'll take care of the rest, |
143 | prefers, drop an email to overlays@gentoo.org. We'll take care of the rest, |
| 154 | including granting write access to all the members of your project (as listed |
144 | including granting write access to all the members of your project (as listed |
| … | |
… | |
| 165 | <li>create an o.g.o account for you if you don't already have one</li> |
155 | <li>create an o.g.o account for you if you don't already have one</li> |
| 166 | <li>give you write access to your overlay's Trac wiki and Subversion |
156 | <li>give you write access to your overlay's Trac wiki and Subversion |
| 167 | repository</li> |
157 | repository</li> |
| 168 | <li>give write access to all project members who already have an o.g.o |
158 | <li>give write access to all project members who already have an o.g.o |
| 169 | account</li> |
159 | account</li> |
| 170 | <li>contact all of the other project members, and sort out their access</li> |
|
|
| 171 | </ul> |
160 | </ul> |
| 172 | |
161 | |
| 173 | <p>For an Git request, we will:</p> |
162 | <p>For an Git request, we will:</p> |
| 174 | <ul> |
163 | <ul> |
| 175 | <li>create your overlay (git, gitweb, no trac)</li> |
164 | <li>create your overlay (git, gitweb, no trac)</li> |
| 176 | <li>add your overlay's RSS feed to the o.g.o homepage</li> |
165 | <li>add your overlay's RSS feed to the o.g.o homepage</li> |
| 177 | <li>create an git.o.g.o account for you if you don't already have one</li> |
166 | <li>create an git.o.g.o account for you if you don't already have one</li> |
| 178 | <li>give you write access to your overlays Git repository</li> |
167 | <li>give you write access to your overlays Git repository</li> |
| 179 | <li>give write access to all project members who already have an o.g.o account</li> |
168 | <li>give write access to all project members who already have an o.g.o account</li> |
| 180 | <li>contact all of the other project members, and sort out their access</li> |
|
|
| 181 | </ul> |
169 | </ul> |
| 182 | |
|
|
| 183 | |
170 | |
| 184 | </body> |
171 | </body> |
| 185 | </section> |
172 | </section> |
| 186 | |
173 | |
| 187 | <section> |
174 | <section> |
| 188 | <title>Developer Overlays</title> |
175 | <title>Developer Overlays</title> |
| 189 | <body> |
176 | <body> |
| 190 | |
177 | |
| 191 | <p>"Developer" overlays are overlays owned by individual Gentoo developers. One |
178 | <p>"Developer" overlays are overlays owned by individual Gentoo developers. One |
| 192 | example is <uri link="http://overlays.gentoo.org/dev/tcort">tcort's overlay</uri>.</p> |
179 | example is <uri link="http://overlays.gentoo.org/dev/beandog">beandog's overlay</uri>.</p> |
| 193 | |
180 | |
| 194 | <p>If you have an @gentoo.org email address, and you've passed the ebuild quiz, |
181 | <p>If you have an @gentoo.org email address, and you've passed the ebuild quiz, |
| 195 | then you can have your own developer overlay on o.g.o.</p> |
182 | then you can have your own developer overlay on o.g.o.</p> |
| 196 | |
183 | |
| 197 | <p>To request a SVN developer overlay, just pop into #gentoo-overlays on IRC |
184 | <p>To request a SVN developer overlay, just pop into #gentoo-overlays on IRC |
| … | |
… | |
| 224 | <section> |
211 | <section> |
| 225 | <title>A Word About Accounts</title> |
212 | <title>A Word About Accounts</title> |
| 226 | <body> |
213 | <body> |
| 227 | <p>Because o.g.o is designed to support a blend of both Gentoo developers and |
214 | <p>Because o.g.o is designed to support a blend of both Gentoo developers and |
| 228 | Gentoo users, we don't create 'real' system-level accounts on the o.g.o host. |
215 | Gentoo users, we don't create 'real' system-level accounts on the o.g.o host. |
| 229 | All access is currently through Apache, and is managed by Apache htpasswd and |
216 | </p> |
| 230 | htgroup files.</p> |
|
|
| 231 | |
217 | |
| 232 | <impo>You do *not* have SSH access to o.g.o.</impo> |
218 | <impo>You do *not* have SSH access to o.g.o.</impo> |
| 233 | </body> |
219 | </body> |
| 234 | </section> |
220 | </section> |
| 235 | </chapter> |
221 | </chapter> |
| … | |
… | |
| 290 | <p>Your overlay comes with <uri link="http://trac.edgewall.com">Trac</uri>. Trac is a wiki, a subversion repository browser, and a bug tracking system that's |
276 | <p>Your overlay comes with <uri link="http://trac.edgewall.com">Trac</uri>. Trac is a wiki, a subversion repository browser, and a bug tracking system that's |
| 291 | very popular with open source developers.</p> |
277 | very popular with open source developers.</p> |
| 292 | |
278 | |
| 293 | <p>We have disabled the bug tracking system in Trac. Use <uri link="http://bugs.gentoo.org">Gentoo's bugzilla</uri> for bug tracking your overlay.</p> |
279 | <p>We have disabled the bug tracking system in Trac. Use <uri link="http://bugs.gentoo.org">Gentoo's bugzilla</uri> for bug tracking your overlay.</p> |
| 294 | |
280 | |
| 295 | <p>Your overlay's RSS feed - the one that is shown on <uri link="http://overlays.gentoo.org">the o.g.o homepage</uri> - comes from Trac's Timeline page.</p> |
281 | <p>Your overlay's RSS feed - the one that is shown on <uri link="http://overlays.gentoo.org">the o.g.o homepage</uri> - comes from Trac's Timeline page or GitWeb's summary.</p> |
| 296 | |
|
|
| 297 | <p>We have installed several Trac plugins, which we hope will make your wiki even |
|
|
| 298 | more useful to you. If you come across any additional plugins that you'd like |
|
|
| 299 | to see installed, please let us know, and we'll take a look at them.</p> |
|
|
| 300 | |
|
|
| 301 | <ul> |
|
|
| 302 | <li><e>LayOnTrac</e> - lists the packages from the overlay.</li> |
|
|
| 303 | <li><uri link="http://muness.textdriven.com/trac/wiki/tags/Setup">TracTags</uri> - displays a tag cloud</li> |
|
|
| 304 | <li><uri link="http://trac.edgewall.org/wiki/WebAdmin">TracWebAdmin</uri> - provides web-based admin panel for Trac</li> |
|
|
| 305 | </ul> |
|
|
| 306 | |
|
|
| 307 | <p>We have installed several Trac macros, which we hope will make your wiki even more useful to you. If you come across any additional macros that you'd like to see installed, please let us know, and we'll take a look at them.</p> |
|
|
| 308 | |
|
|
| 309 | <ul> |
|
|
| 310 | <li><uri link="http://trac-hacks.org/wiki/AddCommentMacro">AddComment</uri> - allows visitors to add comments to the bottom of your pages</li> |
|
|
| 311 | <li><uri link="http://trac-hacks.org/wiki/FootNoteMacro">FootNote</uri> - adds support for adding footnotes to a page</li> |
|
|
| 312 | <li><uri link="http://trac-hacks.org/wiki/TocMacro">TOC</uri> - adds support for publishing a Table of Contents on a page</li> |
|
|
| 313 | </ul> |
|
|
| 314 | |
282 | |
| 315 | </body> |
283 | </body> |
| 316 | </section> |
284 | </section> |
| 317 | |
285 | |
| 318 | <section> |
286 | <section> |
| 319 | <title>Getting Started With Subversion</title> |
287 | <title>Getting Started With Subversion</title> |
| 320 | <body> |
288 | <body> |
| 321 | <p>Your overlay comes with <uri link="http://subversion.tigris.org">Subversion</uri>, a modern alternative to CVS. The advantages of Subversion over CVS include real versioning of directories, full changeset support, and it's much easier to do branching if you need to. The main disadvantage of Subversion is that it is slower than CVS, and that a local Subversion checkout requires more disk space.</p> |
289 | <p>The advantages of Subversion over CVS include real versioning of directories, full changeset support, and it's much easier to do branching if you need to. The main disadvantage of Subversion is that it is slower than CVS, and that a local Subversion checkout requires more disk space.</p> |
| 322 | |
290 | |
| 323 | <p>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> |
291 | <p>If you have never used Subversion before, the online book is an excellent way to learn Subversion. You can buy it in dead-tree format too if you prefer.</p> |
| 324 | |
292 | |
| 325 | <p>Here are some basic commands to get you started.</p> |
293 | <p>Here are some basic commands to get you started.</p> |
| 326 | <pre caption="Checking out your overlay">svn co https://overlays.gentoo.org/proj/php</pre> |
294 | <pre caption="Checking out your overlay">svn co https://overlays.gentoo.org/proj/php</pre> |
| 327 | <pre caption="Seeing which files need committing">svn status</pre> |
295 | <pre caption="Seeing which files need committing">svn status</pre> |
| 328 | <pre caption="Adding files to your overlay">svn add my.ebuild</pre> |
296 | <pre caption="Adding files to your overlay">svn add my.ebuild</pre> |
| … | |
… | |
| 335 | <title>Layman</title> |
303 | <title>Layman</title> |
| 336 | <body> |
304 | <body> |
| 337 | <p>We are telling users to use layman to download and manage your overlay. |
305 | <p>We are telling users to use layman to download and manage your overlay. |
| 338 | layman is a utility written by <mail link="wrobel@gentoo.org">Gunnar Wrobel</mail> which makes it very easy for users to work with overlays.</p> |
306 | layman is a utility written by <mail link="wrobel@gentoo.org">Gunnar Wrobel</mail> which makes it very easy for users to work with overlays.</p> |
| 339 | |
307 | |
| 340 | <p>To get started with using layman, see <uri link="http://www.gentoo.org/news/en/gwn/20060522-newsletter.xml">Gentoo Weekly News for 22nd May</uri>, <uri link="http://gentoo-wiki.com/TIP_Overlays#layman">this article on Gentoo-Wiki.com</uri>, or the man page that comes with layman.</p> |
308 | <p> |
|
|
309 | To get started with using layman, see <uri |
|
|
310 | link="http://layman.sourceforge.net/">the homepage documentation</uri>, the <uri |
|
|
311 | link="http://www.gentoo.org/news/en/gwn/20060522-newsletter.xml">Gentoo Weekly |
|
|
312 | News for 22nd May</uri> or read <c>man layman</c>. |
|
|
313 | </p> |
| 341 | </body> |
314 | </body> |
| 342 | </section> |
315 | </section> |
| 343 | |
316 | |
| 344 | <section> |
317 | <section> |
| 345 | <title>Auto-Sync From Portage</title> |
318 | <title>Auto-Sync From Portage</title> |
| … | |
… | |
| 394 | <body> |
367 | <body> |
| 395 | <p>One of the key features of o.g.o is that people who do not have write access |
368 | <p>One of the key features of o.g.o is that people who do not have write access |
| 396 | to the Gentoo Portage package tree can have write access to one or more |
369 | to the Gentoo Portage package tree can have write access to one or more |
| 397 | overlays. Several Gentoo projects have found that this is a great way to train |
370 | overlays. Several Gentoo projects have found that this is a great way to train |
| 398 | and evaluate potential Gentoo developers in a safe environment.</p> |
371 | and evaluate potential Gentoo developers in a safe environment.</p> |
| 399 | |
|
|
| 400 | <p>At the moment, only the Overlays team can update the access control lists for |
|
|
| 401 | overlays.gentoo.org. We will provide a web-based tool for managing the access |
|
|
| 402 | control lists at a later date. But, for now, if you need a change made, |
|
|
| 403 | please drop by #gentoo-overlays on IRC for assistance.</p> |
|
|
| 404 | </body> |
372 | </body> |
| 405 | </section> |
373 | </section> |
| 406 | |
374 | |
| 407 | <section> |
375 | <section> |
| 408 | <title>Project Overlays: Giving Write Access To Team Members</title> |
376 | <title>Project Overlays: Giving Write Access To Team Members</title> |
| … | |
… | |
| 490 | <body> |
458 | <body> |
| 491 | <p>Everyone has full read access to every overlay. We recommend that you |
459 | <p>Everyone has full read access to every overlay. We recommend that you |
| 492 | use</p> |
460 | use</p> |
| 493 | <pre caption="Install layman"> |
461 | <pre caption="Install layman"> |
| 494 | emerge layman |
462 | emerge layman |
| 495 | echo 'source /usr/portage/local/layman/layman.conf' >> /etc/make.conf |
463 | echo 'source /var/lib/layman/layman.conf' >> /etc/make.conf |
| 496 | </pre> |
464 | </pre> |
| 497 | |
465 | |
| 498 | <note> |
466 | <note> |
| 499 | Layman will create "/usr/portage/local/layman/make.conf" once you add |
467 | Layman will create "/var/lib/layman/make.conf" once you add |
| 500 | your first overlay. But if you do not plan to install an overlay |
468 | your first overlay. But if you do not plan to install an overlay |
| 501 | immediately you should ensure that this file actually exists and |
469 | immediately you should ensure that this file actually exists and |
| 502 | contains the empty variable "PORTDIR_OVERLAY". Otherwise portage will |
470 | contains the empty variable "PORTDIR_OVERLAY". Otherwise portage will |
| 503 | complain. You can run "echo PORTDIR_OVERLAY=\"\" > |
471 | complain. You can run "echo PORTDIR_OVERLAY=\"\" > |
| 504 | /usr/portage/local/layman/make.conf" in order to have the file created |
472 | /var/lib/layman/make.conf" in order to have the file created |
| 505 | correctly. |
473 | correctly. |
| 506 | </note> |
474 | </note> |
| 507 | |
475 | |
| 508 | <p>After that, to view the list of overlays, use</p> |
476 | <p>After that, to view the list of overlays, use</p> |
| 509 | |
477 | |
| … | |
… | |
| 546 | soon as possible.</li> |
514 | soon as possible.</li> |
| 547 | </ul> |
515 | </ul> |
| 548 | |
516 | |
| 549 | <p>Q: Why can't I edit the access control list directly?</p> |
517 | <p>Q: Why can't I edit the access control list directly?</p> |
| 550 | <ul> |
518 | <ul> |
| 551 | <li>A: (SVN) The access control list currently lives in htpasswd / htgroup files used |
519 | <li>A: (SVN) The access control list currently lives in htpasswd format. Only o.g.o admin staff members have ssh access to the o.g.o box.</li> |
| 552 | by Apache. Only o.g.o admin staff have ssh access into the o.g.o box.</li> |
|
|
| 553 | <li>A: (Git) The access control list currently lives in the gitosis-admin repository, |
520 | <li>A: (Git) The access control list currently lives in the gitosis-admin repository, which is writable only by the o.g.o staff.</li> |
| 554 | which is writable only by the o.g.o staff.</li> |
|
|
| 555 | </ul> |
521 | </ul> |
| 556 | </body> |
522 | </body> |
| 557 | </section> |
523 | </section> |
| 558 | |
524 | |
| 559 | <section> |
525 | <section> |
Parent Directory
| 
Revision Log
| 
Patch