/[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.4 - (hide annotations) (download) (as text)
Fri Jun 24 21:37:07 2005 UTC (9 years ago) by g2boojum
Branch: MAIN
Changes since 1.3: +51 -47 lines
File MIME type: text/html
updates

1 g2boojum 1.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 g2boojum 1.4 <meta name="generator" content="Docutils 0.3.7: http://docutils.sourceforge.net/" />
12 g2boojum 1.1 <title>GLEP 29 -- USE flag groups</title>
13     <link rel="stylesheet" href="tools/glep.css" type="text/css" />
14     </head>
15     <body bgcolor="white">
16     <table class="navigation" cellpadding="0" cellspacing="0"
17     width="100%" border="0">
18     <tr><td class="navicon" width="150" height="35">
19     <a href="http://www.gentoo.org/" title="Gentoo Linux Home Page">
20     <img src="http://www.gentoo.org/images/gentoo-new.gif" alt="[Gentoo]"
21     border="0" width="150" height="35" /></a></td>
22     <td class="textlinks" align="left">
23     [<b><a href="http://www.gentoo.org/">Gentoo Linux Home</a></b>]
24     [<b><a href="http://www.gentoo.org/proj/en/glep">GLEP Index</a></b>]
25     [<b><a href="./glep-0029.txt">GLEP Source</a></b>]
26     </td></tr></table>
27 g2boojum 1.4 <table class="rfc2822 docutils field-list" frame="void" rules="none">
28 g2boojum 1.1 <col class="field-name" />
29     <col class="field-body" />
30     <tbody valign="top">
31     <tr class="field"><th class="field-name">GLEP:</th><td class="field-body">29</td>
32     </tr>
33     <tr class="field"><th class="field-name">Title:</th><td class="field-body">USE flag groups</td>
34     </tr>
35 g2boojum 1.4 <tr class="field"><th class="field-name">Version:</th><td class="field-body">1.5</td>
36 g2boojum 1.1 </tr>
37     <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>
38     </tr>
39 g2boojum 1.4 <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/xml/htdocs/proj/en/glep/glep-0029.txt?cvsroot=gentoo">2005/06/24 21:36:04</a></td>
40 g2boojum 1.1 </tr>
41     <tr class="field"><th class="field-name">Status:</th><td class="field-body">Draft</td>
42     </tr>
43     <tr class="field"><th class="field-name">Type:</th><td class="field-body">Standards Track</td>
44     </tr>
45     <tr class="field"><th class="field-name">Content-Type:</th><td class="field-body"><a class="reference" href="glep-0012.html">text/x-rst</a></td>
46     </tr>
47     <tr class="field"><th class="field-name">Created:</th><td class="field-body">19-August-2004</td>
48     </tr>
49 g2boojum 1.4 <tr class="field"><th class="field-name">Post-Date:</th><td class="field-body">21-August-2004, 18-October-2004, 25-October-2004, 24-July-2005</td>
50 g2boojum 1.1 </tr>
51     </tbody>
52     </table>
53     <hr />
54     <div class="contents topic" id="contents">
55     <p class="topic-title first"><a name="contents">Contents</a></p>
56     <ul class="simple">
57 g2boojum 1.4 <li><a class="reference" href="#status" id="id7" name="id7">Status</a></li>
58     <li><a class="reference" href="#abstract" id="id8" name="id8">Abstract</a></li>
59     <li><a class="reference" href="#motivation" id="id9" name="id9">Motivation</a></li>
60     <li><a class="reference" href="#specification" id="id10" name="id10">Specification</a><ul>
61     <li><a class="reference" href="#group-specification" id="id11" name="id11">Group Specification</a></li>
62     <li><a class="reference" href="#group-descriptions" id="id12" name="id12">Group Descriptions</a></li>
63     <li><a class="reference" href="#using-groups" id="id13" name="id13">Using Groups</a></li>
64     <li><a class="reference" href="#issues-with-flags-and-groups" id="id14" name="id14">Issues with -flags and -&#64;GROUPS</a></li>
65     <li><a class="reference" href="#adding-new-groups" id="id15" name="id15">Adding New Groups</a></li>
66 g2boojum 1.1 </ul>
67     </li>
68 g2boojum 1.4 <li><a class="reference" href="#rationale" id="id16" name="id16">Rationale</a></li>
69     <li><a class="reference" href="#reference-implementation" id="id17" name="id17">Reference Implementation</a></li>
70     <li><a class="reference" href="#backwards-compatibility" id="id18" name="id18">Backwards Compatibility</a></li>
71     <li><a class="reference" href="#references" id="id19" name="id19">References</a></li>
72     <li><a class="reference" href="#copyright" id="id20" name="id20">Copyright</a></li>
73 g2boojum 1.1 </ul>
74     </div>
75 g2boojum 1.4 <div class="section" id="status">
76     <h1><a class="toc-backref" href="#id7" name="status">Status</a></h1>
77     <p>Withdrawn by request of the author.</p>
78     </div>
79 g2boojum 1.1 <div class="section" id="abstract">
80 g2boojum 1.4 <h1><a class="toc-backref" href="#id8" name="abstract">Abstract</a></h1>
81 g2boojum 1.1 <p>Currently, USE flags must be selected on a one-by-one basis, making it
82     time-consuming to set up make.conf appropriately for a machine's role.</p>
83     </div>
84     <div class="section" id="motivation">
85 g2boojum 1.4 <h1><a class="toc-backref" href="#id9" name="motivation">Motivation</a></h1>
86 g2boojum 1.2 <p>Many packages have optional support for other packages (for example, the
87     Vim text editor can optionally support perl, python and ruby
88     interpreters). In Gentoo, these optional dependencies can be selected by
89     the user using USE flags. This allows a system appropriate for a given
90     environment to be built -- a server, for example, should not typically
91     have an X11 server or sound support, whereas both would be desirable on
92     most desktop systems.</p>
93     <p>With several hundred USE flags available, deciding upon which USE flags to
94 g2boojum 1.3 enable and which to disable can take a long time. Although the default USE
95     flag settings are reasonable, they are clearly not appropriate for every
96     system. In addition, using &quot;-<em>&quot; to disable all default USE flags can be
97     risky as certain USE flags should not generally be turned off. This GLEP
98     proposes a mechanism for grouping USE flags to simplify selection and to
99     make USE=&quot;-</em>&quot; less dangerous.</p>
100 g2boojum 1.1 </div>
101     <div class="section" id="specification">
102 g2boojum 1.4 <h1><a class="toc-backref" href="#id10" name="specification">Specification</a></h1>
103 g2boojum 1.1 <div class="section" id="group-specification">
104 g2boojum 1.4 <h2><a class="toc-backref" href="#id11" name="group-specification">Group Specification</a></h2>
105 g2boojum 1.3 <p>A group shall consist of one or more tokens. Each token may be a USE flag,
106     a -USE flag, a reference to another group or a negative reference to
107     another group.</p>
108 g2boojum 1.4 <p>These groups are defined in <tt class="docutils literal"><span class="pre">${PORTDIR}/profiles/use.groups</span></tt>. It is
109 g2boojum 1.3 proposed that uppercase names only are used for groups to keep them
110     visually distinct from normal USE flags (almost all USE flags are
111     lowercase), although this should not been forced programmatically. The
112     file should be similar in format to the existing use.* files. In the
113 g2boojum 1.4 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
114     <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>
115 g2boojum 1.1 <pre class="literal-block">
116     SOME_GROUP flag1 flag2 flag3
117     OTHER_GROUP flag2 flag4
118     </pre>
119     <p>Groups may recursively include other groups. For consistency with GLEP 23
120 g2boojum 1.3 <a class="footnote-reference" href="#id4" id="id1" name="id1">[1]</a>, it is proposed that group names have their name prefixed with an
121     'at' symbol (&#64;):</p>
122 g2boojum 1.1 <pre class="literal-block">
123     GROUP1 flag1
124     GROUP2 flag2 flag3 &#64;GROUP1
125     GROUP3 flag4
126     GROUP4 &#64;GROUP2 &#64;GROUP3 flag5
127     </pre>
128 g2boojum 1.2 <p>The same flag may end up being in a particular group more than once:</p>
129     <pre class="literal-block">
130     GROUP1 flag1 flag2
131     GROUP2 flag2 flag3
132     GROUP3 &#64;GROUP1 &#64;GROUP2 flag3 flag4
133     </pre>
134     <p>As with similar files, comments may be included. Lines which begin with a
135     hash symbol (#) are comments.</p>
136     <pre class="literal-block">
137     # This is a comment
138     FOO bar baz fnord
139     </pre>
140 g2boojum 1.4 <p>Users may create their own groups using <tt class="docutils literal"><span class="pre">/etc/portage/use.groups</span></tt>. This
141 g2boojum 1.1 file overrides the profile settings in the case of duplicates.</p>
142 g2boojum 1.3 <p>It should be legal for groups to specify -use flags, although for reasons
143     discussed below this feature should not generally be used. The syntax is
144     the same:</p>
145     <pre class="literal-block">
146     # This group contains two negative flags
147     GROUP1 flag1 -flag2 -flag3 flag4
148     </pre>
149     <p>Groups may <em>not</em> contain circular group references. The following example
150     is illegal:</p>
151     <pre class="literal-block">
152     # Illegal circular references
153     GROUP1 &#64;GROUP2 foo
154     GROUP2 &#64;GROUP1 bar
155     </pre>
156 g2boojum 1.1 </div>
157     <div class="section" id="group-descriptions">
158 g2boojum 1.4 <h2><a class="toc-backref" href="#id12" name="group-descriptions">Group Descriptions</a></h2>
159 g2boojum 1.1 <p>Groups shall have a textual description associated with them in the same
160 g2boojum 1.4 way as USE flags. The file <tt class="docutils literal"><span class="pre">${PORTDIR}/profiles/use.groups.desc</span></tt>
161 g2boojum 1.1 contains these:</p>
162     <pre class="literal-block">
163 g2boojum 1.2 # This is a comment
164 g2boojum 1.1 DESKTOP Flags which are appropriate for most desktop systems
165     RECOMMENDED Flags which should be enabled on almost all systems
166     </pre>
167     </div>
168     <div class="section" id="using-groups">
169 g2boojum 1.4 <h2><a class="toc-backref" href="#id13" name="using-groups">Using Groups</a></h2>
170     <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
171 g2boojum 1.3 other places where USE flags are normally specified. They may <em>not</em> be
172 g2boojum 1.4 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>
173 g2boojum 1.3 <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
174     system might resemble:</p>
175 g2boojum 1.1 <pre class="literal-block">
176     USE=&quot;&#64;DESKTOP &#64;KDE perl alsa dvd&quot;
177     </pre>
178 g2boojum 1.3 <p>Groups may be preceded by a -sign to invert their contents (that is, all
179     'enable' use flags become -flags, and all -flags become enable flags). Be
180     warned that this feature can cause confusion (see below). Example usage:</p>
181     <pre class="literal-block">
182     # We have the following groups defined...
183     GROUP1 foo bar
184     GROUP2 -bar baz -fnord
185     GROUP3 &#64;GROUP1 -&#64;GROUP2 -bar foo
186     GROUP4 -foo -bar
187    
188     # And the following...
189     USE=&quot;-&#64;GROUP3 &#64;GROUP4 bar&quot;
190    
191     # which resolves to...
192     USE=&quot;-&#64;GROUP1 &#64;GROUP2 bar -foo -foo -bar bar&quot;
193     USE=&quot;-foo -bar bar -baz fnord bar -foo -foo -bar bar&quot;
194     USE=&quot;-baz fnord -foo bar&quot;
195     </pre>
196 g2boojum 1.1 </div>
197 g2boojum 1.3 <div class="section" id="issues-with-flags-and-groups">
198 g2boojum 1.4 <h2><a class="toc-backref" href="#id14" name="issues-with-flags-and-groups">Issues with -flags and <a class="reference" href="mailto:-&#64;GROUPS">-&#64;GROUPS</a></a></h2>
199 g2boojum 1.3 <p>Earlier drafts of this GLEP did not allow -use flags or <a class="reference" href="mailto:-&#64;GROUPS">-&#64;GROUPS</a>. However,
200     because of feedback along the lines of &quot;we shouldn't disallow features
201     just because some users won't understand them&quot; (for example, <a class="footnote-reference" href="#id6" id="id2" name="id2">[3]</a>), these
202     are now allowed but discouraged.</p>
203     <p>The problems are best illustrated by example. Say we have the following
204     groups defined:</p>
205     <pre class="literal-block">
206     KDE X kde qt
207     GNOME X gtk gtk2 gnome
208     </pre>
209     <p>A user who wants a KDE desktop but no GNOME may do the following:</p>
210     <pre class="literal-block">
211     USE=&quot;&#64;KDE -&#64;GNOME&quot;
212     </pre>
213 g2boojum 1.4 <p>However, this will not give the desired effect -- the <tt class="docutils literal"><span class="pre">X</span></tt> USE flag will
214 g2boojum 1.3 end up being disabled.</p>
215     <p>Similarly, -use flags could cause a lot of confusion if misused. If, for
216     example, the KDE group turned off GNOME things and the GNOME group turned
217     off KDE things:</p>
218     <pre class="literal-block">
219     KDE X kde qt -gtk -gnome
220     GNOME X gtk gtk2 gnome -kde -qt
221     </pre>
222     <p>And a user wished to use both KDE and GNOME on a system, and so had USE
223     flags as follows:</p>
224     <pre class="literal-block">
225     USE=&quot;&#64;KDE &#64;GNOME&quot;
226     </pre>
227     <p>They would end up with:</p>
228     <pre class="literal-block">
229     USE=&quot;X kde qt -gtk -gnome X gtk gtk2 gnome -kde -qt&quot;
230     </pre>
231     <p>Which simplifies:</p>
232     <pre class="literal-block">
233     USE=&quot;X gtk gtk2 gnome -kde -qt&quot;
234     </pre>
235     <p>This is clearly not the desired effect.</p>
236 g2boojum 1.1 </div>
237     <div class="section" id="adding-new-groups">
238 g2boojum 1.4 <h2><a class="toc-backref" href="#id15" name="adding-new-groups">Adding New Groups</a></h2>
239 g2boojum 1.1 <p>The actual groups to be created is beyond the scope of this GLEP, and any
240     group names contained herein should be treated as examples only. Creation
241     of new groups and changing a group's flags should be discussed on the
242     gentoo-dev mailing list as per existing policy for new global USE flags.</p>
243 g2boojum 1.3 <p>In particular, any changes involving -flags <em>must</em> be thoroughly discussed
244     before implementation.</p>
245 g2boojum 1.1 </div>
246     </div>
247     <div class="section" id="rationale">
248 g2boojum 1.4 <h1><a class="toc-backref" href="#id16" name="rationale">Rationale</a></h1>
249 g2boojum 1.1 <p>USE groups will simplify selecting an appropriate set of USE flags for a
250     system.</p>
251     </div>
252     <div class="section" id="reference-implementation">
253 g2boojum 1.4 <h1><a class="toc-backref" href="#id17" name="reference-implementation">Reference Implementation</a></h1>
254 g2boojum 1.1 <p>TODO</p>
255     </div>
256 g2boojum 1.3 <div class="section" id="backwards-compatibility">
257 g2boojum 1.4 <h1><a class="toc-backref" href="#id18" name="backwards-compatibility">Backwards Compatibility</a></h1>
258 g2boojum 1.1 <p>The user will not need to make any changes to keep their current setup.
259     Users who are not running a portage version which supports groups can
260     carry on using current syntax with no side-effects.</p>
261     <p>Some tools which work with make.conf and / or USE flags (for example,
262 g2boojum 1.4 <tt class="docutils literal"><span class="pre">ufed</span></tt>) will need to be updated to understand the new group syntax.</p>
263 g2boojum 1.3 <p>There is currently a dynamic list of USE flags available on the Gentoo
264     website <a class="footnote-reference" href="#id5" id="id3" name="id3">[2]</a>. For consistency, a similar list will be needed for USE
265 g2boojum 1.1 groups.</p>
266     </div>
267     <div class="section" id="references">
268 g2boojum 1.4 <h1><a class="toc-backref" href="#id19" name="references">References</a></h1>
269     <table class="docutils footnote" frame="void" id="id4" rules="none">
270 g2boojum 1.1 <colgroup><col class="label" /><col /></colgroup>
271     <tbody valign="top">
272 g2boojum 1.3 <tr><td class="label"><a class="fn-backref" href="#id1" name="id4">[1]</a></td><td>GLEP 23: Portage handling of ACCEPT_LICENSE
273 g2boojum 1.1 (<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>
274     </tbody>
275     </table>
276 g2boojum 1.4 <table class="docutils footnote" frame="void" id="id5" rules="none">
277 g2boojum 1.3 <colgroup><col class="label" /><col /></colgroup>
278     <tbody valign="top">
279     <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>
280     </tbody>
281     </table>
282 g2boojum 1.4 <table class="docutils footnote" frame="void" id="id6" rules="none">
283 g2boojum 1.1 <colgroup><col class="label" /><col /></colgroup>
284     <tbody valign="top">
285 g2boojum 1.3 <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
286     (<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>
287 g2boojum 1.1 </tbody>
288     </table>
289     </div>
290     <div class="section" id="copyright">
291 g2boojum 1.4 <h1><a class="toc-backref" href="#id20" name="copyright">Copyright</a></h1>
292 g2boojum 1.1 <p>This document has been placed in the public domain.</p>
293     <blockquote>
294     vim: set tw=74 :</blockquote>
295     </div>
296 g2boojum 1.4
297 g2boojum 1.1 </div>
298 g2boojum 1.4 <hr class="docutils footer" />
299 g2boojum 1.1 <div class="footer">
300     <a class="reference" href="glep-0029.txt">View document source</a>.
301 g2boojum 1.4 Generated on: 2005-06-24 21:36 UTC.
302 g2boojum 1.1 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.
303     </div>
304     </body>
305     </html>

  ViewVC Help
Powered by ViewVC 1.1.20