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

Parent Directory Parent Directory | Revision Log Revision Log

Revision 1.3 - (hide annotations) (download) (as text)
Mon Oct 25 16:57:40 2004 UTC (14 years, 2 months ago) by g2boojum
Branch: MAIN
Changes since 1.2: +138 -61 lines
File MIME type: text/html

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
8     -->
9     <head>
10     <meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
11     <meta name="generator" content="Docutils 0.3.3: 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     <div class="document">
28     <table class="rfc2822 field-list" frame="void" rules="none">
29     <col class="field-name" />
30     <col class="field-body" />
31     <tbody valign="top">
32     <tr class="field"><th class="field-name">GLEP:</th><td class="field-body">29</td>
33     </tr>
34     <tr class="field"><th class="field-name">Title:</th><td class="field-body">USE flag groups</td>
35     </tr>
36 g2boojum 1.3 <tr class="field"><th class="field-name">Version:</th><td class="field-body">1.4</td>
37 g2boojum 1.1 </tr>
38     <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>
39     </tr>
40 g2boojum 1.3 <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">2004/10/25 16:57:09</a></td>
41 g2boojum 1.1 </tr>
42     <tr class="field"><th class="field-name">Status:</th><td class="field-body">Draft</td>
43     </tr>
44     <tr class="field"><th class="field-name">Type:</th><td class="field-body">Standards Track</td>
45     </tr>
46     <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>
47     </tr>
48     <tr class="field"><th class="field-name">Created:</th><td class="field-body">19-August-2004</td>
49     </tr>
50 g2boojum 1.3 <tr class="field"><th class="field-name">Post-Date:</th><td class="field-body">21-August-2004, 18-October-2004, 25-October-2004</td>
51 g2boojum 1.1 </tr>
52     </tbody>
53     </table>
54     <hr />
55     <div class="contents topic" id="contents">
56     <p class="topic-title first"><a name="contents">Contents</a></p>
57     <ul class="simple">
58 g2boojum 1.3 <li><a class="reference" href="#abstract" id="id7" name="id7">Abstract</a></li>
59     <li><a class="reference" href="#motivation" id="id8" name="id8">Motivation</a></li>
60     <li><a class="reference" href="#specification" id="id9" name="id9">Specification</a><ul>
61     <li><a class="reference" href="#group-specification" id="id10" name="id10">Group Specification</a></li>
62     <li><a class="reference" href="#group-descriptions" id="id11" name="id11">Group Descriptions</a></li>
63     <li><a class="reference" href="#using-groups" id="id12" name="id12">Using Groups</a></li>
64     <li><a class="reference" href="#issues-with-flags-and-groups" id="id13" name="id13">Issues with -flags and -&#64;GROUPS</a></li>
65     <li><a class="reference" href="#adding-new-groups" id="id14" name="id14">Adding New Groups</a></li>
66 g2boojum 1.1 </ul>
67     </li>
68 g2boojum 1.3 <li><a class="reference" href="#rationale" id="id15" name="id15">Rationale</a></li>
69     <li><a class="reference" href="#reference-implementation" id="id16" name="id16">Reference Implementation</a></li>
70     <li><a class="reference" href="#backwards-compatibility" id="id17" name="id17">Backwards Compatibility</a></li>
71     <li><a class="reference" href="#references" id="id18" name="id18">References</a></li>
72     <li><a class="reference" href="#copyright" id="id19" name="id19">Copyright</a></li>
73 g2boojum 1.1 </ul>
74     </div>
75     <div class="section" id="abstract">
76 g2boojum 1.3 <h1><a class="toc-backref" href="#id7" name="abstract">Abstract</a></h1>
77 g2boojum 1.1 <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" id="motivation">
81 g2boojum 1.3 <h1><a class="toc-backref" href="#id8" name="motivation">Motivation</a></h1>
82 g2boojum 1.2 <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 g2boojum 1.3 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 g2boojum 1.1 </div>
97     <div class="section" id="specification">
98 g2boojum 1.3 <h1><a class="toc-backref" href="#id9" name="specification">Specification</a></h1>
99 g2boojum 1.1 <div class="section" id="group-specification">
100 g2boojum 1.3 <h2><a class="toc-backref" href="#id10" 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="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="literal"><span class="pre">SOME_GROUP</span></tt> and <tt class="literal"><span class="pre">OTHER_GROUP</span></tt> are group names, and
110     <tt class="literal"><span class="pre">flag1</span></tt> through <tt class="literal"><span class="pre">flag5</span></tt> are USE flag names:</p>
111 g2boojum 1.1 <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 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
117     'at' symbol (&#64;):</p>
118 g2boojum 1.1 <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 g2boojum 1.2 <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 g2boojum 1.1 <p>Users may create their own groups using <tt class="literal"><span class="pre">/etc/portage/use.groups</span></tt>. This
137     file overrides the profile settings in the case of duplicates.</p>
138 g2boojum 1.3 <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 g2boojum 1.1 </div>
153     <div class="section" id="group-descriptions">
154 g2boojum 1.3 <h2><a class="toc-backref" href="#id11" name="group-descriptions">Group Descriptions</a></h2>
155 g2boojum 1.1 <p>Groups shall have a textual description associated with them in the same
156     way as USE flags. The file <tt class="literal"><span class="pre">${PORTDIR}/profiles/use.groups.desc</span></tt>
157     contains these:</p>
158     <pre class="literal-block">
159 g2boojum 1.2 # This is a comment
160 g2boojum 1.1 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" id="using-groups">
165 g2boojum 1.3 <h2><a class="toc-backref" href="#id12" name="using-groups">Using Groups</a></h2>
166 g2boojum 1.1 <p>Groups may be used in <tt class="literal"><span class="pre">/etc/make.conf</span></tt>, <tt class="literal"><span class="pre">/etc/portage/package.use</span></tt> and
167 g2boojum 1.3 other places where USE flags are normally specified. They may <em>not</em> be
168     used inside <tt class="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 g2boojum 1.1 <pre class="literal-block">
172     USE=&quot;&#64;DESKTOP &#64;KDE perl alsa dvd&quot;
173     </pre>
174 g2boojum 1.3 <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 g2boojum 1.1 </div>
193 g2boojum 1.3 <div class="section" id="issues-with-flags-and-groups">
194     <h2><a class="toc-backref" href="#id13" 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="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 g2boojum 1.1 </div>
233     <div class="section" id="adding-new-groups">
234 g2boojum 1.3 <h2><a class="toc-backref" href="#id14" name="adding-new-groups">Adding New Groups</a></h2>
235 g2boojum 1.1 <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 g2boojum 1.3 <p>In particular, any changes involving -flags <em>must</em> be thoroughly discussed
240     before implementation.</p>
241 g2boojum 1.1 </div>
242     </div>
243     <div class="section" id="rationale">
244 g2boojum 1.3 <h1><a class="toc-backref" href="#id15" name="rationale">Rationale</a></h1>
245 g2boojum 1.1 <p>USE groups will simplify selecting an appropriate set of USE flags for a
246     system.</p>
247     </div>
248     <div class="section" id="reference-implementation">
249 g2boojum 1.3 <h1><a class="toc-backref" href="#id16" name="reference-implementation">Reference Implementation</a></h1>
250 g2boojum 1.1 <p>TODO</p>
251     </div>
252 g2boojum 1.3 <div class="section" id="backwards-compatibility">
253     <h1><a class="toc-backref" href="#id17" name="backwards-compatibility">Backwards Compatibility</a></h1>
254 g2boojum 1.1 <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="literal"><span class="pre">ufed</span></tt>) will need to be updated to understand the new group syntax.</p>
259 g2boojum 1.3 <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 g2boojum 1.1 groups.</p>
262     </div>
263     <div class="section" id="references">
264 g2boojum 1.3 <h1><a class="toc-backref" href="#id18" name="references">References</a></h1>
265     <table class="footnote" frame="void" id="id4" rules="none">
266 g2boojum 1.1 <colgroup><col class="label" /><col /></colgroup>
267     <tbody valign="top">
268 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
269 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>
270     </tbody>
271     </table>
272 g2boojum 1.3 <table class="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="footnote" frame="void" id="id6" rules="none">
279 g2boojum 1.1 <colgroup><col class="label" /><col /></colgroup>
280     <tbody valign="top">
281 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
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 g2boojum 1.1 </tbody>
284     </table>
285     </div>
286     <div class="section" id="copyright">
287 g2boojum 1.3 <h1><a class="toc-backref" href="#id19" name="copyright">Copyright</a></h1>
288 g2boojum 1.1 <p>This document has been placed in the public domain.</p>
289     <blockquote>
290     vim: set tw=74 :</blockquote>
291     </div>
292     </div>
294     <hr class="footer" />
295     <div class="footer">
296     <a class="reference" href="glep-0029.txt">View document source</a>.
297 g2boojum 1.3 Generated on: 2004-10-25 16:50 UTC.
298 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.
299     </div>
300     </body>
301     </html>

  ViewVC Help
Powered by ViewVC 1.1.20