/[gentoo]/xml/htdocs/proj/en/glep/glep-0029.html
Gentoo

Contents of /xml/htdocs/proj/en/glep/glep-0029.html

Parent Directory Parent Directory | Revision Log Revision Log


Revision 1.7 - (show annotations) (download) (as text)
Thu Jan 25 03:26:26 2007 UTC (7 years, 6 months ago) by antarus
Branch: MAIN
Changes since 1.6: +3 -3 lines
File MIME type: text/html
Fix headers in all current gleps

1 <?xml version="1.0" encoding="utf-8" ?>
2 <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
3 <html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en">
4 <!--
5 This HTML is auto-generated. DO NOT EDIT THIS FILE! If you are writing a new
6 PEP, see http://www.python.org/peps/pep-0001.html for instructions and links
7 to templates. DO NOT USE THIS HTML FILE AS YOUR TEMPLATE!
8 -->
9 <head>
10 <meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
11 <meta name="generator" content="Docutils 0.4: http://docutils.sourceforge.net/" />
12 <title>GLEP 29 -- USE flag groups</title>
13 <style type="text/css">
14
15 /*
16 :Author: David Goodger
17 :Contact: goodger@users.sourceforge.net
18 :date: $Date: 2006/10/10 20:25:14 $
19 :version: $Revision: 1.6 $
20 :copyright: This stylesheet has been placed in the public domain.
21
22 Default cascading style sheet for the PEP HTML output of Docutils.
23 */
24
25 .first {
26 margin-top: 0 }
27
28 .last {
29 margin-bottom: 0 }
30
31 .navigation {
32 width: 100% ;
33 background: #cc99ff ;
34 margin-top: 0px ;
35 margin-bottom: 0px }
36
37 .navigation .navicon {
38 width: 150px ;
39 height: 35px }
40
41 .navigation .textlinks {
42 padding-left: 1em ;
43 text-align: left }
44
45 .navigation td, .navigation th {
46 padding-left: 0em ;
47 padding-right: 0em ;
48 vertical-align: middle }
49
50 .rfc2822 {
51 margin-top: 0.5em ;
52 margin-left: 0.5em ;
53 margin-right: 0.5em ;
54 margin-bottom: 0em }
55
56 .rfc2822 td {
57 text-align: left }
58
59 .rfc2822 th.field-name {
60 text-align: right ;
61 font-family: sans-serif ;
62 padding-right: 0.5em ;
63 font-weight: bold ;
64 margin-bottom: 0em }
65
66 a.toc-backref {
67 text-decoration: none ;
68 color: black }
69
70 body {
71 margin: 0px ;
72 margin-bottom: 1em ;
73 padding: 0px }
74
75 dd {
76 margin-bottom: 0.5em }
77
78 div.section {
79 margin-left: 1em ;
80 margin-right: 1em ;
81 margin-bottom: 1.5em }
82
83 div.section div.section {
84 margin-left: 0em ;
85 margin-right: 0em ;
86 margin-top: 1.5em }
87
88 div.abstract {
89 margin: 2em 5em }
90
91 div.abstract p.topic-title {
92 font-weight: bold ;
93 text-align: center }
94
95 div.attention, div.caution, div.danger, div.error, div.hint,
96 div.important, div.note, div.tip, div.warning {
97 margin: 2em ;
98 border: medium outset ;
99 padding: 1em }
100
101 div.attention p.admonition-title, div.caution p.admonition-title,
102 div.danger p.admonition-title, div.error p.admonition-title,
103 div.warning p.admonition-title {
104 color: red ;
105 font-weight: bold ;
106 font-family: sans-serif }
107
108 div.hint p.admonition-title, div.important p.admonition-title,
109 div.note p.admonition-title, div.tip p.admonition-title {
110 font-weight: bold ;
111 font-family: sans-serif }
112
113 div.figure {
114 margin-left: 2em }
115
116 div.footer, div.header {
117 font-size: smaller }
118
119 div.footer {
120 margin-left: 1em ;
121 margin-right: 1em }
122
123 div.system-messages {
124 margin: 5em }
125
126 div.system-messages h1 {
127 color: red }
128
129 div.system-message {
130 border: medium outset ;
131 padding: 1em }
132
133 div.system-message p.system-message-title {
134 color: red ;
135 font-weight: bold }
136
137 div.topic {
138 margin: 2em }
139
140 h1 {
141 font-family: sans-serif ;
142 font-size: large }
143
144 h2 {
145 font-family: sans-serif ;
146 font-size: medium }
147
148 h3 {
149 font-family: sans-serif ;
150 font-size: small }
151
152 h4 {
153 font-family: sans-serif ;
154 font-style: italic ;
155 font-size: small }
156
157 h5 {
158 font-family: sans-serif;
159 font-size: x-small }
160
161 h6 {
162 font-family: sans-serif;
163 font-style: italic ;
164 font-size: x-small }
165
166 .section hr {
167 width: 75% }
168
169 ol.simple, ul.simple {
170 margin-bottom: 1em }
171
172 ol.arabic {
173 list-style: decimal }
174
175 ol.loweralpha {
176 list-style: lower-alpha }
177
178 ol.upperalpha {
179 list-style: upper-alpha }
180
181 ol.lowerroman {
182 list-style: lower-roman }
183
184 ol.upperroman {
185 list-style: upper-roman }
186
187 p.caption {
188 font-style: italic }
189
190 p.credits {
191 font-style: italic ;
192 font-size: smaller }
193
194 p.label {
195 white-space: nowrap }
196
197 p.topic-title {
198 font-family: sans-serif ;
199 font-weight: bold }
200
201 pre.line-block {
202 font-family: serif ;
203 font-size: 100% }
204
205 pre.literal-block, pre.doctest-block {
206 margin-left: 2em ;
207 margin-right: 2em ;
208 background-color: #eeeeee }
209
210 span.classifier {
211 font-family: sans-serif ;
212 font-style: oblique }
213
214 span.classifier-delimiter {
215 font-family: sans-serif ;
216 font-weight: bold }
217
218 span.interpreted {
219 font-family: sans-serif }
220
221 span.option-argument {
222 font-style: italic }
223
224 span.pre {
225 white-space: pre }
226
227 span.problematic {
228 color: red }
229
230 table {
231 margin-top: 0.5em ;
232 margin-bottom: 0.5em }
233
234 td, th {
235 padding-left: 0.5em ;
236 padding-right: 0.5em ;
237 vertical-align: top }
238
239 td.num {
240 text-align: right }
241
242 th.field-name {
243 font-weight: bold ;
244 text-align: left ;
245 white-space: nowrap }
246
247 h1 tt, h2 tt, h3 tt, h4 tt, h5 tt, h6 tt {
248 font-size: 100% }
249
250 tt {
251 background-color: #eeeeee }
252
253 ul.auto-toc {
254 list-style-type: none }
255
256 </style>
257 </head>
258 <body bgcolor="white">
259 <table class="navigation" cellpadding="0" cellspacing="0"
260 width="100%" border="0">
261 <tr><td class="navicon" width="150" height="35">
262 <a href="http://www.gentoo.org/" title="Gentoo Linux Home Page">
263 <img src="http://www.gentoo.org/images/gentoo-new.gif" alt="[Gentoo]"
264 border="0" width="150" height="35" /></a></td>
265 <td class="textlinks" align="left">
266 [<b><a href="http://www.gentoo.org/">Gentoo Linux Home</a></b>]
267 [<b><a href="http://www.gentoo.org/proj/en/glep/">GLEP Index</a></b>]
268 [<b><a href="http://www.gentoo.org/proj/en/glep/glep-0029.txt">GLEP Source</a></b>]
269 </td></tr></table>
270 <table class="rfc2822 docutils field-list" frame="void" rules="none">
271 <col class="field-name" />
272 <col class="field-body" />
273 <tbody valign="top">
274 <tr class="field"><th class="field-name">GLEP:</th><td class="field-body">29</td>
275 </tr>
276 <tr class="field"><th class="field-name">Title:</th><td class="field-body">USE flag groups</td>
277 </tr>
278 <tr class="field"><th class="field-name">Version:</th><td class="field-body">1.6</td>
279 </tr>
280 <tr class="field"><th class="field-name">Author:</th><td class="field-body">Ciaran McCreesh &lt;ciaranm&#32;&#97;t&#32;gentoo.org&gt;</td>
281 </tr>
282 <tr class="field"><th class="field-name">Last-Modified:</th><td class="field-body"><a class="reference" href="http://www.gentoo.org/cgi-bin/viewcvs.cgi/xml/htdocs/proj/en/glep/glep-0029.txt?cvsroot=gentoo">2005/11/07 22:26:59</a></td>
283 </tr>
284 <tr class="field"><th class="field-name">Status:</th><td class="field-body">Draft</td>
285 </tr>
286 <tr class="field"><th class="field-name">Type:</th><td class="field-body">Standards Track</td>
287 </tr>
288 <tr class="field"><th class="field-name">Content-Type:</th><td class="field-body"><a class="reference" href="glep-0002.html">text/x-rst</a></td>
289 </tr>
290 <tr class="field"><th class="field-name">Created:</th><td class="field-body">19-Aug-2004</td>
291 </tr>
292 <tr class="field"><th class="field-name">Post-History:</th><td class="field-body">21-Aug-2004, 18-Oct-2004, 25-Oct-2004, 24-Jul-2005</td>
293 </tr>
294 </tbody>
295 </table>
296 <hr />
297 <div class="contents topic">
298 <p class="topic-title first"><a id="contents" name="contents">Contents</a></p>
299 <ul class="simple">
300 <li><a class="reference" href="#status" id="id7" name="id7">Status</a></li>
301 <li><a class="reference" href="#abstract" id="id8" name="id8">Abstract</a></li>
302 <li><a class="reference" href="#motivation" id="id9" name="id9">Motivation</a></li>
303 <li><a class="reference" href="#specification" id="id10" name="id10">Specification</a><ul>
304 <li><a class="reference" href="#group-specification" id="id11" name="id11">Group Specification</a></li>
305 <li><a class="reference" href="#group-descriptions" id="id12" name="id12">Group Descriptions</a></li>
306 <li><a class="reference" href="#using-groups" id="id13" name="id13">Using Groups</a></li>
307 <li><a class="reference" href="#issues-with-flags-and-groups" id="id14" name="id14">Issues with -flags and -&#64;GROUPS</a></li>
308 <li><a class="reference" href="#adding-new-groups" id="id15" name="id15">Adding New Groups</a></li>
309 </ul>
310 </li>
311 <li><a class="reference" href="#rationale" id="id16" name="id16">Rationale</a></li>
312 <li><a class="reference" href="#reference-implementation" id="id17" name="id17">Reference Implementation</a></li>
313 <li><a class="reference" href="#backwards-compatibility" id="id18" name="id18">Backwards Compatibility</a></li>
314 <li><a class="reference" href="#references" id="id19" name="id19">References</a></li>
315 <li><a class="reference" href="#copyright" id="id20" name="id20">Copyright</a></li>
316 </ul>
317 </div>
318 <div class="section">
319 <h1><a class="toc-backref" href="#id7" id="status" name="status">Status</a></h1>
320 <p>Withdrawn by request of the author.</p>
321 </div>
322 <div class="section">
323 <h1><a class="toc-backref" href="#id8" id="abstract" name="abstract">Abstract</a></h1>
324 <p>Currently, USE flags must be selected on a one-by-one basis, making it
325 time-consuming to set up make.conf appropriately for a machine's role.</p>
326 </div>
327 <div class="section">
328 <h1><a class="toc-backref" href="#id9" id="motivation" name="motivation">Motivation</a></h1>
329 <p>Many packages have optional support for other packages (for example, the
330 Vim text editor can optionally support perl, python and ruby
331 interpreters). In Gentoo, these optional dependencies can be selected by
332 the user using USE flags. This allows a system appropriate for a given
333 environment to be built -- a server, for example, should not typically
334 have an X11 server or sound support, whereas both would be desirable on
335 most desktop systems.</p>
336 <p>With several hundred USE flags available, deciding upon which USE flags to
337 enable and which to disable can take a long time. Although the default USE
338 flag settings are reasonable, they are clearly not appropriate for every
339 system. In addition, using &quot;-<em>&quot; to disable all default USE flags can be
340 risky as certain USE flags should not generally be turned off. This GLEP
341 proposes a mechanism for grouping USE flags to simplify selection and to
342 make USE=&quot;-</em>&quot; less dangerous.</p>
343 </div>
344 <div class="section">
345 <h1><a class="toc-backref" href="#id10" id="specification" name="specification">Specification</a></h1>
346 <div class="section">
347 <h2><a class="toc-backref" href="#id11" id="group-specification" name="group-specification">Group Specification</a></h2>
348 <p>A group shall consist of one or more tokens. Each token may be a USE flag,
349 a -USE flag, a reference to another group or a negative reference to
350 another group.</p>
351 <p>These groups are defined in <tt class="docutils literal"><span class="pre">${PORTDIR}/profiles/use.groups</span></tt>. It is
352 proposed that uppercase names only are used for groups to keep them
353 visually distinct from normal USE flags (almost all USE flags are
354 lowercase), although this should not been forced programmatically. The
355 file should be similar in format to the existing use.* files. In the
356 following, <tt class="docutils literal"><span class="pre">SOME_GROUP</span></tt> and <tt class="docutils literal"><span class="pre">OTHER_GROUP</span></tt> are group names, and
357 <tt class="docutils literal"><span class="pre">flag1</span></tt> through <tt class="docutils literal"><span class="pre">flag5</span></tt> are USE flag names:</p>
358 <pre class="literal-block">
359 SOME_GROUP flag1 flag2 flag3
360 OTHER_GROUP flag2 flag4
361 </pre>
362 <p>Groups may recursively include other groups. For consistency with GLEP 23
363 <a class="footnote-reference" href="#id4" id="id1" name="id1">[1]</a>, it is proposed that group names have their name prefixed with an
364 'at' symbol (&#64;):</p>
365 <pre class="literal-block">
366 GROUP1 flag1
367 GROUP2 flag2 flag3 &#64;GROUP1
368 GROUP3 flag4
369 GROUP4 &#64;GROUP2 &#64;GROUP3 flag5
370 </pre>
371 <p>The same flag may end up being in a particular group more than once:</p>
372 <pre class="literal-block">
373 GROUP1 flag1 flag2
374 GROUP2 flag2 flag3
375 GROUP3 &#64;GROUP1 &#64;GROUP2 flag3 flag4
376 </pre>
377 <p>As with similar files, comments may be included. Lines which begin with a
378 hash symbol (#) are comments.</p>
379 <pre class="literal-block">
380 # This is a comment
381 FOO bar baz fnord
382 </pre>
383 <p>Users may create their own groups using <tt class="docutils literal"><span class="pre">/etc/portage/use.groups</span></tt>. This
384 file overrides the profile settings in the case of duplicates.</p>
385 <p>It should be legal for groups to specify -use flags, although for reasons
386 discussed below this feature should not generally be used. The syntax is
387 the same:</p>
388 <pre class="literal-block">
389 # This group contains two negative flags
390 GROUP1 flag1 -flag2 -flag3 flag4
391 </pre>
392 <p>Groups may <em>not</em> contain circular group references. The following example
393 is illegal:</p>
394 <pre class="literal-block">
395 # Illegal circular references
396 GROUP1 &#64;GROUP2 foo
397 GROUP2 &#64;GROUP1 bar
398 </pre>
399 </div>
400 <div class="section">
401 <h2><a class="toc-backref" href="#id12" id="group-descriptions" name="group-descriptions">Group Descriptions</a></h2>
402 <p>Groups shall have a textual description associated with them in the same
403 way as USE flags. The file <tt class="docutils literal"><span class="pre">${PORTDIR}/profiles/use.groups.desc</span></tt>
404 contains these:</p>
405 <pre class="literal-block">
406 # This is a comment
407 DESKTOP Flags which are appropriate for most desktop systems
408 RECOMMENDED Flags which should be enabled on almost all systems
409 </pre>
410 </div>
411 <div class="section">
412 <h2><a class="toc-backref" href="#id13" id="using-groups" name="using-groups">Using Groups</a></h2>
413 <p>Groups may be used in <tt class="docutils literal"><span class="pre">/etc/make.conf</span></tt>, <tt class="docutils literal"><span class="pre">/etc/portage/package.use</span></tt> and
414 other places where USE flags are normally specified. They may <em>not</em> be
415 used inside <tt class="docutils literal"><span class="pre">IUSE`.</span> <span class="pre">As</span> <span class="pre">before,</span> <span class="pre">the</span> <span class="pre">&#64;</span> <span class="pre">symbol</span> <span class="pre">is</span> <span class="pre">used</span> <span class="pre">to</span> <span class="pre">indicate</span> <span class="pre">that</span> <span class="pre">a</span>
416 <span class="pre">group</span> <span class="pre">is</span> <span class="pre">being</span> <span class="pre">referenced.</span> <span class="pre">For</span> <span class="pre">example,</span> <span class="pre">a</span> <span class="pre">``make.conf</span></tt> for a KDE desktop
417 system might resemble:</p>
418 <pre class="literal-block">
419 USE=&quot;&#64;DESKTOP &#64;KDE perl alsa dvd&quot;
420 </pre>
421 <p>Groups may be preceded by a -sign to invert their contents (that is, all
422 'enable' use flags become -flags, and all -flags become enable flags). Be
423 warned that this feature can cause confusion (see below). Example usage:</p>
424 <pre class="literal-block">
425 # We have the following groups defined...
426 GROUP1 foo bar
427 GROUP2 -bar baz -fnord
428 GROUP3 &#64;GROUP1 -&#64;GROUP2 -bar foo
429 GROUP4 -foo -bar
430
431 # And the following...
432 USE=&quot;-&#64;GROUP3 &#64;GROUP4 bar&quot;
433
434 # which resolves to...
435 USE=&quot;-&#64;GROUP1 &#64;GROUP2 bar -foo -foo -bar bar&quot;
436 USE=&quot;-foo -bar bar -baz fnord bar -foo -foo -bar bar&quot;
437 USE=&quot;-baz fnord -foo bar&quot;
438 </pre>
439 </div>
440 <div class="section">
441 <h2><a id="issues-with-flags-and-groups" name="issues-with-flags-and-groups">Issues with -flags and <a class="reference" href="mailto:-&#64;GROUPS">-&#64;GROUPS</a></a></h2>
442 <p>Earlier drafts of this GLEP did not allow -use flags or <a class="reference" href="mailto:-&#64;GROUPS">-&#64;GROUPS</a>. However,
443 because of feedback along the lines of &quot;we shouldn't disallow features
444 just because some users won't understand them&quot; (for example, <a class="footnote-reference" href="#id6" id="id2" name="id2">[3]</a>), these
445 are now allowed but discouraged.</p>
446 <p>The problems are best illustrated by example. Say we have the following
447 groups defined:</p>
448 <pre class="literal-block">
449 KDE X kde qt
450 GNOME X gtk gtk2 gnome
451 </pre>
452 <p>A user who wants a KDE desktop but no GNOME may do the following:</p>
453 <pre class="literal-block">
454 USE=&quot;&#64;KDE -&#64;GNOME&quot;
455 </pre>
456 <p>However, this will not give the desired effect -- the <tt class="docutils literal"><span class="pre">X</span></tt> USE flag will
457 end up being disabled.</p>
458 <p>Similarly, -use flags could cause a lot of confusion if misused. If, for
459 example, the KDE group turned off GNOME things and the GNOME group turned
460 off KDE things:</p>
461 <pre class="literal-block">
462 KDE X kde qt -gtk -gnome
463 GNOME X gtk gtk2 gnome -kde -qt
464 </pre>
465 <p>And a user wished to use both KDE and GNOME on a system, and so had USE
466 flags as follows:</p>
467 <pre class="literal-block">
468 USE=&quot;&#64;KDE &#64;GNOME&quot;
469 </pre>
470 <p>They would end up with:</p>
471 <pre class="literal-block">
472 USE=&quot;X kde qt -gtk -gnome X gtk gtk2 gnome -kde -qt&quot;
473 </pre>
474 <p>Which simplifies:</p>
475 <pre class="literal-block">
476 USE=&quot;X gtk gtk2 gnome -kde -qt&quot;
477 </pre>
478 <p>This is clearly not the desired effect.</p>
479 </div>
480 <div class="section">
481 <h2><a class="toc-backref" href="#id15" id="adding-new-groups" name="adding-new-groups">Adding New Groups</a></h2>
482 <p>The actual groups to be created is beyond the scope of this GLEP, and any
483 group names contained herein should be treated as examples only. Creation
484 of new groups and changing a group's flags should be discussed on the
485 gentoo-dev mailing list as per existing policy for new global USE flags.</p>
486 <p>In particular, any changes involving -flags <em>must</em> be thoroughly discussed
487 before implementation.</p>
488 </div>
489 </div>
490 <div class="section">
491 <h1><a class="toc-backref" href="#id16" id="rationale" name="rationale">Rationale</a></h1>
492 <p>USE groups will simplify selecting an appropriate set of USE flags for a
493 system.</p>
494 </div>
495 <div class="section">
496 <h1><a class="toc-backref" href="#id17" id="reference-implementation" name="reference-implementation">Reference Implementation</a></h1>
497 <p>TODO</p>
498 </div>
499 <div class="section">
500 <h1><a class="toc-backref" href="#id18" id="backwards-compatibility" name="backwards-compatibility">Backwards Compatibility</a></h1>
501 <p>The user will not need to make any changes to keep their current setup.
502 Users who are not running a portage version which supports groups can
503 carry on using current syntax with no side-effects.</p>
504 <p>Some tools which work with make.conf and / or USE flags (for example,
505 <tt class="docutils literal"><span class="pre">ufed</span></tt>) will need to be updated to understand the new group syntax.</p>
506 <p>There is currently a dynamic list of USE flags available on the Gentoo
507 website <a class="footnote-reference" href="#id5" id="id3" name="id3">[2]</a>. For consistency, a similar list will be needed for USE
508 groups.</p>
509 </div>
510 <div class="section">
511 <h1><a class="toc-backref" href="#id19" id="references" name="references">References</a></h1>
512 <table class="docutils footnote" frame="void" id="id4" rules="none">
513 <colgroup><col class="label" /><col /></colgroup>
514 <tbody valign="top">
515 <tr><td class="label"><a class="fn-backref" href="#id1" name="id4">[1]</a></td><td>GLEP 23: Portage handling of ACCEPT_LICENSE
516 (<a class="reference" href="http://www.gentoo.org/proj/en/glep/glep-0023.html">http://www.gentoo.org/proj/en/glep/glep-0023.html</a>)</td></tr>
517 </tbody>
518 </table>
519 <table class="docutils footnote" frame="void" id="id5" rules="none">
520 <colgroup><col class="label" /><col /></colgroup>
521 <tbody valign="top">
522 <tr><td class="label"><a class="fn-backref" href="#id3" name="id5">[2]</a></td><td><a class="reference" href="http://www.gentoo.org/dyn/use-index.xml">http://www.gentoo.org/dyn/use-index.xml</a></td></tr>
523 </tbody>
524 </table>
525 <table class="docutils footnote" frame="void" id="id6" rules="none">
526 <colgroup><col class="label" /><col /></colgroup>
527 <tbody valign="top">
528 <tr><td class="label"><a class="fn-backref" href="#id2" name="id6">[3]</a></td><td>GLEP 29 discussion on the gentoo-dev mailing list
529 (<a class="reference" href="http://marc.theaimsgroup.com/?l=gentoo-dev&amp;m=109813990013812">http://marc.theaimsgroup.com/?l=gentoo-dev&amp;m=109813990013812</a>)</td></tr>
530 </tbody>
531 </table>
532 </div>
533 <div class="section">
534 <h1><a class="toc-backref" href="#id20" id="copyright" name="copyright">Copyright</a></h1>
535 <p>This document has been placed in the public domain.</p>
536 <blockquote>
537 vim: set tw=74 :</blockquote>
538 </div>
539
540 </div>
541 <div class="footer">
542 <hr class="footer" />
543 <a class="reference" href="glep-0029.txt">View document source</a>.
544 Generated on: 2006-10-10 20:23 UTC.
545 Generated by <a class="reference" href="http://docutils.sourceforge.net/">Docutils</a> from <a class="reference" href="http://docutils.sourceforge.net/rst.html">reStructuredText</a> source.
546
547 </div>
548 </body>
549 </html>

  ViewVC Help
Powered by ViewVC 1.1.20