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

Parent Directory Parent Directory | Revision Log Revision Log

Revision 1.4 - (show annotations) (download) (as text)
Fri Jun 24 21:37:07 2005 UTC (13 years, 8 months ago) by g2boojum
Branch: MAIN
Changes since 1.3: +51 -47 lines
File MIME type: text/html

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
8 -->
9 <head>
10 <meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
11 <meta name="generator" content="Docutils 0.3.7: http://docutils.sourceforge.net/" />
12 <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 <table class="rfc2822 docutils field-list" frame="void" rules="none">
28 <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 <tr class="field"><th class="field-name">Version:</th><td class="field-body">1.5</td>
36 </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 <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 </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 <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 </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 <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 </ul>
67 </li>
68 <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 </ul>
74 </div>
75 <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 <div class="section" id="abstract">
80 <h1><a class="toc-backref" href="#id8" name="abstract">Abstract</a></h1>
81 <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 <h1><a class="toc-backref" href="#id9" name="motivation">Motivation</a></h1>
86 <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 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 </div>
101 <div class="section" id="specification">
102 <h1><a class="toc-backref" href="#id10" name="specification">Specification</a></h1>
103 <div class="section" id="group-specification">
104 <h2><a class="toc-backref" href="#id11" name="group-specification">Group Specification</a></h2>
105 <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 <p>These groups are defined in <tt class="docutils literal"><span class="pre">${PORTDIR}/profiles/use.groups</span></tt>. It is
109 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 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 <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 <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 <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 <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 <p>Users may create their own groups using <tt class="docutils literal"><span class="pre">/etc/portage/use.groups</span></tt>. This
141 file overrides the profile settings in the case of duplicates.</p>
142 <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 </div>
157 <div class="section" id="group-descriptions">
158 <h2><a class="toc-backref" href="#id12" name="group-descriptions">Group Descriptions</a></h2>
159 <p>Groups shall have a textual description associated with them in the same
160 way as USE flags. The file <tt class="docutils literal"><span class="pre">${PORTDIR}/profiles/use.groups.desc</span></tt>
161 contains these:</p>
162 <pre class="literal-block">
163 # This is a comment
164 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 <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 other places where USE flags are normally specified. They may <em>not</em> be
172 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 <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 <pre class="literal-block">
176 USE=&quot;&#64;DESKTOP &#64;KDE perl alsa dvd&quot;
177 </pre>
178 <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
188 # And the following...
189 USE=&quot;-&#64;GROUP3 &#64;GROUP4 bar&quot;
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 </div>
197 <div class="section" id="issues-with-flags-and-groups">
198 <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 <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 <p>However, this will not give the desired effect -- the <tt class="docutils literal"><span class="pre">X</span></tt> USE flag will
214 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 </div>
237 <div class="section" id="adding-new-groups">
238 <h2><a class="toc-backref" href="#id15" name="adding-new-groups">Adding New Groups</a></h2>
239 <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 <p>In particular, any changes involving -flags <em>must</em> be thoroughly discussed
244 before implementation.</p>
245 </div>
246 </div>
247 <div class="section" id="rationale">
248 <h1><a class="toc-backref" href="#id16" name="rationale">Rationale</a></h1>
249 <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 <h1><a class="toc-backref" href="#id17" name="reference-implementation">Reference Implementation</a></h1>
254 <p>TODO</p>
255 </div>
256 <div class="section" id="backwards-compatibility">
257 <h1><a class="toc-backref" href="#id18" name="backwards-compatibility">Backwards Compatibility</a></h1>
258 <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 <tt class="docutils literal"><span class="pre">ufed</span></tt>) will need to be updated to understand the new group syntax.</p>
263 <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 groups.</p>
266 </div>
267 <div class="section" id="references">
268 <h1><a class="toc-backref" href="#id19" name="references">References</a></h1>
269 <table class="docutils footnote" frame="void" id="id4" rules="none">
270 <colgroup><col class="label" /><col /></colgroup>
271 <tbody valign="top">
272 <tr><td class="label"><a class="fn-backref" href="#id1" name="id4">[1]</a></td><td>GLEP 23: Portage handling of ACCEPT_LICENSE
273 (<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 <table class="docutils footnote" frame="void" id="id5" rules="none">
277 <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 <table class="docutils footnote" frame="void" id="id6" rules="none">
283 <colgroup><col class="label" /><col /></colgroup>
284 <tbody valign="top">
285 <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 </tbody>
288 </table>
289 </div>
290 <div class="section" id="copyright">
291 <h1><a class="toc-backref" href="#id20" name="copyright">Copyright</a></h1>
292 <p>This document has been placed in the public domain.</p>
293 <blockquote>
294 vim: set tw=74 :</blockquote>
295 </div>
297 </div>
298 <hr class="docutils footer" />
299 <div class="footer">
300 <a class="reference" href="glep-0029.txt">View document source</a>.
301 Generated on: 2005-06-24 21:36 UTC.
302 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