en/glep/glep-0029.html

<?xml version="1.0" encoding="utf-8" ?>
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en">
<!--
This HTML is auto-generated.  DO NOT EDIT THIS FILE!  If you are writing a new
PEP, see http://www.python.org/peps/pep-0001.html for instructions and links
to templates.  DO NOT USE THIS HTML FILE AS YOUR TEMPLATE!
-->
<head>
  <meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
  <meta name="generator" content="Docutils 0.3.3: http://docutils.sourceforge.net/" />
  <title>GLEP 29 -- USE flag groups</title>
  <link rel="stylesheet" href="tools/glep.css" type="text/css" />
</head>
<body bgcolor="white">
<table class="navigation" cellpadding="0" cellspacing="0"
       width="100%" border="0">
<tr><td class="navicon" width="150" height="35">
<a href="http://www.gentoo.org/" title="Gentoo Linux Home Page">
<img src="http://www.gentoo.org/images/gentoo-new.gif" alt="[Gentoo]"
 border="0" width="150" height="35" /></a></td>
<td class="textlinks" align="left">
[<b><a href="http://www.gentoo.org/">Gentoo Linux Home</a></b>]
[<b><a href="http://www.gentoo.org/proj/en/glep">GLEP Index</a></b>]
[<b><a href="./glep-0029.txt">GLEP Source</a></b>]
</td></tr></table>
<div class="document">
<table class="rfc2822 field-list" frame="void" rules="none">
<col class="field-name" />
<col class="field-body" />
<tbody valign="top">
<tr class="field"><th class="field-name">GLEP:</th><td class="field-body">29</td>
</tr>
<tr class="field"><th class="field-name">Title:</th><td class="field-body">USE flag groups</td>
</tr>
<tr class="field"><th class="field-name">Version:</th><td class="field-body">1.4</td>
</tr>
<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>
</tr>
<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>
</tr>
<tr class="field"><th class="field-name">Status:</th><td class="field-body">Draft</td>
</tr>
<tr class="field"><th class="field-name">Type:</th><td class="field-body">Standards Track</td>
</tr>
<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>
</tr>
<tr class="field"><th class="field-name">Created:</th><td class="field-body">19-August-2004</td>
</tr>
<tr class="field"><th class="field-name">Post-Date:</th><td class="field-body">21-August-2004, 18-October-2004, 25-October-2004</td>
</tr>
</tbody>
</table>
<hr />
<div class="contents topic" id="contents">
<p class="topic-title first"><a name="contents">Contents</a></p>
<ul class="simple">
<li><a class="reference" href="#abstract" id="id7" name="id7">Abstract</a></li>
<li><a class="reference" href="#motivation" id="id8" name="id8">Motivation</a></li>
<li><a class="reference" href="#specification" id="id9" name="id9">Specification</a><ul>
<li><a class="reference" href="#group-specification" id="id10" name="id10">Group Specification</a></li>
<li><a class="reference" href="#group-descriptions" id="id11" name="id11">Group Descriptions</a></li>
<li><a class="reference" href="#using-groups" id="id12" name="id12">Using Groups</a></li>
<li><a class="reference" href="#issues-with-flags-and-groups" id="id13" name="id13">Issues with -flags and -&#64;GROUPS</a></li>
<li><a class="reference" href="#adding-new-groups" id="id14" name="id14">Adding New Groups</a></li>
</ul>
</li>
<li><a class="reference" href="#rationale" id="id15" name="id15">Rationale</a></li>
<li><a class="reference" href="#reference-implementation" id="id16" name="id16">Reference Implementation</a></li>
<li><a class="reference" href="#backwards-compatibility" id="id17" name="id17">Backwards Compatibility</a></li>
<li><a class="reference" href="#references" id="id18" name="id18">References</a></li>
<li><a class="reference" href="#copyright" id="id19" name="id19">Copyright</a></li>
</ul>
</div>
<div class="section" id="abstract">
<h1><a class="toc-backref" href="#id7" name="abstract">Abstract</a></h1>
<p>Currently, USE flags must be selected on a one-by-one basis, making it
time-consuming to set up make.conf appropriately for a machine's role.</p>
</div>
<div class="section" id="motivation">
<h1><a class="toc-backref" href="#id8" name="motivation">Motivation</a></h1>
<p>Many packages have optional support for other packages (for example, the
Vim text editor can optionally support perl, python and ruby
interpreters). In Gentoo, these optional dependencies can be selected by
the user using USE flags. This allows a system appropriate for a given
environment to be built -- a server, for example, should not typically
have an X11 server or sound support, whereas both would be desirable on
most desktop systems.</p>
<p>With several hundred USE flags available, deciding upon which USE flags to
enable and which to disable can take a long time. Although the default USE
flag settings are reasonable, they are clearly not appropriate for every
system. In addition, using &quot;-<em>&quot; to disable all default USE flags can be
risky as certain USE flags should not generally be turned off.  This GLEP
proposes a mechanism for grouping USE flags to simplify selection and to
make USE=&quot;-</em>&quot; less dangerous.</p>
</div>
<div class="section" id="specification">
<h1><a class="toc-backref" href="#id9" name="specification">Specification</a></h1>
<div class="section" id="group-specification">
<h2><a class="toc-backref" href="#id10" name="group-specification">Group Specification</a></h2>
<p>A group shall consist of one or more tokens. Each token may be a USE flag,
a -USE flag, a reference to another group or a negative reference to
another group.</p>
<p>These groups are defined in <tt class="literal"><span class="pre">${PORTDIR}/profiles/use.groups</span></tt>. It is
proposed that uppercase names only are used for groups to keep them
visually distinct from normal USE flags (almost all USE flags are
lowercase), although this should not been forced programmatically. The
file should be similar in format to the existing use.* files. In the
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
<tt class="literal"><span class="pre">flag1</span></tt> through <tt class="literal"><span class="pre">flag5</span></tt> are USE flag names:</p>
<pre class="literal-block">
SOME_GROUP flag1 flag2 flag3
OTHER_GROUP flag2 flag4
</pre>
<p>Groups may recursively include other groups. For consistency with GLEP 23
<a class="footnote-reference" href="#id4" id="id1" name="id1">[1]</a>, it is proposed that group names have their name prefixed with an
'at' symbol (&#64;):</p>
<pre class="literal-block">
GROUP1 flag1
GROUP2 flag2 flag3 &#64;GROUP1
GROUP3 flag4
GROUP4 &#64;GROUP2 &#64;GROUP3 flag5
</pre>
<p>The same flag may end up being in a particular group more than once:</p>
<pre class="literal-block">
GROUP1 flag1 flag2
GROUP2 flag2 flag3
GROUP3 &#64;GROUP1 &#64;GROUP2 flag3 flag4
</pre>
<p>As with similar files, comments may be included. Lines which begin with a
hash symbol (#) are comments.</p>
<pre class="literal-block">
# This is a comment
FOO bar baz fnord
</pre>
<p>Users may create their own groups using <tt class="literal"><span class="pre">/etc/portage/use.groups</span></tt>. This
file overrides the profile settings in the case of duplicates.</p>
<p>It should be legal for groups to specify -use flags, although for reasons
discussed below this feature should not generally be used. The syntax is
the same:</p>
<pre class="literal-block">
# This group contains two negative flags
GROUP1 flag1 -flag2 -flag3 flag4
</pre>
<p>Groups may <em>not</em> contain circular group references. The following example
is illegal:</p>
<pre class="literal-block">
# Illegal circular references
GROUP1 &#64;GROUP2 foo
GROUP2 &#64;GROUP1 bar
</pre>
</div>
<div class="section" id="group-descriptions">
<h2><a class="toc-backref" href="#id11" name="group-descriptions">Group Descriptions</a></h2>
<p>Groups shall have a textual description associated with them in the same
way as USE flags. The file <tt class="literal"><span class="pre">${PORTDIR}/profiles/use.groups.desc</span></tt>
contains these:</p>
<pre class="literal-block">
# This is a comment
DESKTOP Flags which are appropriate for most desktop systems
RECOMMENDED Flags which should be enabled on almost all systems
</pre>
</div>
<div class="section" id="using-groups">
<h2><a class="toc-backref" href="#id12" name="using-groups">Using Groups</a></h2>
<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
other places where USE flags are normally specified. They may <em>not</em> be
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>
<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
system might resemble:</p>
<pre class="literal-block">
USE=&quot;&#64;DESKTOP &#64;KDE perl alsa dvd&quot;
</pre>
<p>Groups may be preceded by a -sign to invert their contents (that is, all
'enable' use flags become -flags, and all -flags become enable flags). Be
warned that this feature can cause confusion (see below). Example usage:</p>
<pre class="literal-block">
# We have the following groups defined...
GROUP1 foo bar
GROUP2 -bar baz -fnord
GROUP3 &#64;GROUP1 -&#64;GROUP2 -bar foo
GROUP4 -foo -bar

# And the following...
USE=&quot;-&#64;GROUP3 &#64;GROUP4 bar&quot;

# which resolves to...
USE=&quot;-&#64;GROUP1 &#64;GROUP2 bar -foo -foo -bar bar&quot;
USE=&quot;-foo -bar bar -baz fnord bar -foo -foo -bar bar&quot;
USE=&quot;-baz fnord -foo bar&quot;
</pre>
</div>
<div class="section" id="issues-with-flags-and-groups">
<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>
<p>Earlier drafts of this GLEP did not allow -use flags or <a class="reference" href="mailto:-&#64;GROUPS">-&#64;GROUPS</a>. However,
because of feedback along the lines of &quot;we shouldn't disallow features
just because some users won't understand them&quot; (for example, <a class="footnote-reference" href="#id6" id="id2" name="id2">[3]</a>), these
are now allowed but discouraged.</p>
<p>The problems are best illustrated by example. Say we have the following
groups defined:</p>
<pre class="literal-block">
KDE X kde qt
GNOME X gtk gtk2 gnome
</pre>
<p>A user who wants a KDE desktop but no GNOME may do the following:</p>
<pre class="literal-block">
USE=&quot;&#64;KDE -&#64;GNOME&quot;
</pre>
<p>However, this will not give the desired effect -- the <tt class="literal"><span class="pre">X</span></tt> USE flag will
end up being disabled.</p>
<p>Similarly, -use flags could cause a lot of confusion if misused. If, for
example, the KDE group turned off GNOME things and the GNOME group turned
off KDE things:</p>
<pre class="literal-block">
KDE X kde qt -gtk -gnome
GNOME X gtk gtk2 gnome -kde -qt
</pre>
<p>And a user wished to use both KDE and GNOME on a system, and so had USE
flags as follows:</p>
<pre class="literal-block">
USE=&quot;&#64;KDE &#64;GNOME&quot;
</pre>
<p>They would end up with:</p>
<pre class="literal-block">
USE=&quot;X kde qt -gtk -gnome X gtk gtk2 gnome -kde -qt&quot;
</pre>
<p>Which simplifies:</p>
<pre class="literal-block">
USE=&quot;X gtk gtk2 gnome -kde -qt&quot;
</pre>
<p>This is clearly not the desired effect.</p>
</div>
<div class="section" id="adding-new-groups">
<h2><a class="toc-backref" href="#id14" name="adding-new-groups">Adding New Groups</a></h2>
<p>The actual groups to be created is beyond the scope of this GLEP, and any
group names contained herein should be treated as examples only. Creation
of new groups and changing a group's flags should be discussed on the
gentoo-dev mailing list as per existing policy for new global USE flags.</p>
<p>In particular, any changes involving -flags <em>must</em> be thoroughly discussed
before implementation.</p>
</div>
</div>
<div class="section" id="rationale">
<h1><a class="toc-backref" href="#id15" name="rationale">Rationale</a></h1>
<p>USE groups will simplify selecting an appropriate set of USE flags for a
system.</p>
</div>
<div class="section" id="reference-implementation">
<h1><a class="toc-backref" href="#id16" name="reference-implementation">Reference Implementation</a></h1>
<p>TODO</p>
</div>
<div class="section" id="backwards-compatibility">
<h1><a class="toc-backref" href="#id17" name="backwards-compatibility">Backwards Compatibility</a></h1>
<p>The user will not need to make any changes to keep their current setup.
Users who are not running a portage version which supports groups can
carry on using current syntax with no side-effects.</p>
<p>Some tools which work with make.conf and / or USE flags (for example,
<tt class="literal"><span class="pre">ufed</span></tt>) will need to be updated to understand the new group syntax.</p>
<p>There is currently a dynamic list of USE flags available on the Gentoo
website <a class="footnote-reference" href="#id5" id="id3" name="id3">[2]</a>. For consistency, a similar list will be needed for USE
groups.</p>
</div>
<div class="section" id="references">
<h1><a class="toc-backref" href="#id18" name="references">References</a></h1>
<table class="footnote" frame="void" id="id4" rules="none">
<colgroup><col class="label" /><col /></colgroup>
<tbody valign="top">
<tr><td class="label"><a class="fn-backref" href="#id1" name="id4">[1]</a></td><td>GLEP 23: Portage handling of ACCEPT_LICENSE
(<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>
</tbody>
</table>
<table class="footnote" frame="void" id="id5" rules="none">
<colgroup><col class="label" /><col /></colgroup>
<tbody valign="top">
<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>
</tbody>
</table>
<table class="footnote" frame="void" id="id6" rules="none">
<colgroup><col class="label" /><col /></colgroup>
<tbody valign="top">
<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
(<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>
</tbody>
</table>
</div>
<div class="section" id="copyright">
<h1><a class="toc-backref" href="#id19" name="copyright">Copyright</a></h1>
<p>This document has been placed in the public domain.</p>
<blockquote>
vim: set tw=74 :</blockquote>
</div>
</div>

<hr class="footer" />
<div class="footer">
<a class="reference" href="glep-0029.txt">View document source</a>.
Generated on: 2004-10-25 16:50 UTC.
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.
</div>
</body>
</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
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.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	<tr class="field"><th class="field-name">Version:</th><td class="field-body">1.4</td>
37	</tr>
38	<tr class="field"><th class="field-name">Author:</th><td class="field-body">Ciaran McCreesh <ciaranm at gentoo.org></td>
39	</tr>
40	<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	</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	<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	</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	<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 -@GROUPS</a></li>
65	<li><a class="reference" href="#adding-new-groups" id="id14" name="id14">Adding New Groups</a></li>
66	</ul>
67	</li>
68	<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	</ul>
74	</div>
75	<div class="section" id="abstract">
76	<h1><a class="toc-backref" href="#id7" 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" id="motivation">
81	<h1><a class="toc-backref" href="#id8" 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 "-<em>" 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="-</em>" less dangerous.</p>
96	</div>
97	<div class="section" id="specification">
98	<h1><a class="toc-backref" href="#id9" name="specification">Specification</a></h1>
99	<div class="section" id="group-specification">
100	<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	<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 (@):</p>
118	<pre class="literal-block">
119	GROUP1 flag1
120	GROUP2 flag2 flag3 @GROUP1
121	GROUP3 flag4
122	GROUP4 @GROUP2 @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 @GROUP1 @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="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 @GROUP2 foo
150	GROUP2 @GROUP1 bar
151	</pre>
152	</div>
153	<div class="section" id="group-descriptions">
154	<h2><a class="toc-backref" href="#id11" 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="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" id="using-groups">
165	<h2><a class="toc-backref" href="#id12" name="using-groups">Using Groups</a></h2>
166	<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	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">@</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="@DESKTOP @KDE perl alsa dvd"
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 @GROUP1 -@GROUP2 -bar foo
182	GROUP4 -foo -bar
183
184	# And the following...
185	USE="-@GROUP3 @GROUP4 bar"
186
187	# which resolves to...
188	USE="-@GROUP1 @GROUP2 bar -foo -foo -bar bar"
189	USE="-foo -bar bar -baz fnord bar -foo -foo -bar bar"
190	USE="-baz fnord -foo bar"
191	</pre>
192	</div>
193	<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:-@GROUPS">-@GROUPS</a></a></h2>
195	<p>Earlier drafts of this GLEP did not allow -use flags or <a class="reference" href="mailto:-@GROUPS">-@GROUPS</a>. However,
196	because of feedback along the lines of "we shouldn't disallow features
197	just because some users won't understand them" (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="@KDE -@GNOME"
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="@KDE @GNOME"
222	</pre>
223	<p>They would end up with:</p>
224	<pre class="literal-block">
225	USE="X kde qt -gtk -gnome X gtk gtk2 gnome -kde -qt"
226	</pre>
227	<p>Which simplifies:</p>
228	<pre class="literal-block">
229	USE="X gtk gtk2 gnome -kde -qt"
230	</pre>
231	<p>This is clearly not the desired effect.</p>
232	</div>
233	<div class="section" id="adding-new-groups">
234	<h2><a class="toc-backref" href="#id14" 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" id="rationale">
244	<h1><a class="toc-backref" href="#id15" 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" id="reference-implementation">
249	<h1><a class="toc-backref" href="#id16" name="reference-implementation">Reference Implementation</a></h1>
250	<p>TODO</p>
251	</div>
252	<div class="section" id="backwards-compatibility">
253	<h1><a class="toc-backref" href="#id17" 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="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" id="references">
264	<h1><a class="toc-backref" href="#id18" name="references">References</a></h1>
265	<table class="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="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	<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&m=109813990013812">http://marc.theaimsgroup.com/?l=gentoo-dev&m=109813990013812</a>)</td></tr>
283	</tbody>
284	</table>
285	</div>
286	<div class="section" id="copyright">
287	<h1><a class="toc-backref" href="#id19" 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>
292	</div>
293
294	<hr class="footer" />
295	<div class="footer">
296	<a class="reference" href="glep-0029.txt">View document source</a>.
297	Generated on: 2004-10-25 16:50 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.
299	</div>
300	</body>
301	</html>
302