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

Parent Directory Parent Directory | Revision Log Revision Log

Revision 1.8 - (show annotations) (download) (as text)
Sun Oct 14 17:00:15 2007 UTC (11 years, 4 months ago) by antarus
Branch: MAIN
Changes since 1.7: +4 -251 lines
File MIME type: text/html
Error occurred while calculating annotation data.
the canary on 53 went well, changing the rest

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

  ViewVC Help
Powered by ViewVC 1.1.20