en/glep/glep-0029.txt

GLEP: 29
Title: USE flag groups
Version: $Revision: $
Author: Ciaran McCreesh <ciaranm@gentoo.org>
Last-Modified: $Date: $
Status: Draft
Type: Standards Track
Content-Type: text/x-rst
Created: 19-August-2004
Post-Date: 21-August-2004, 18-October-2004, 25-October-2004

Abstract
========

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.

Motivation
==========

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.

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 "-*" 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="-*" less dangerous.

Specification
=============

Group Specification
-------------------

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.

These groups are defined in ``${PORTDIR}/profiles/use.groups``. 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, ``SOME_GROUP`` and ``OTHER_GROUP`` are group names, and
``flag1`` through ``flag5`` are USE flag names:

::

        SOME_GROUP flag1 flag2 flag3
        OTHER_GROUP flag2 flag4

Groups may recursively include other groups. For consistency with GLEP 23
[1]_, it is proposed that group names have their name prefixed with an
'at' symbol (@):

::

        GROUP1 flag1
        GROUP2 flag2 flag3 @GROUP1
        GROUP3 flag4
        GROUP4 @GROUP2 @GROUP3 flag5

The same flag may end up being in a particular group more than once:

::

        GROUP1 flag1 flag2
        GROUP2 flag2 flag3
        GROUP3 @GROUP1 @GROUP2 flag3 flag4

As with similar files, comments may be included. Lines which begin with a
hash symbol (#) are comments.

::

        # This is a comment
        FOO bar baz fnord

Users may create their own groups using ``/etc/portage/use.groups``. This
file overrides the profile settings in the case of duplicates.

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:

::

        # This group contains two negative flags
        GROUP1 flag1 -flag2 -flag3 flag4

Groups may *not* contain circular group references. The following example
is illegal:

::

        # Illegal circular references
        GROUP1 @GROUP2 foo
        GROUP2 @GROUP1 bar

Group Descriptions
------------------

Groups shall have a textual description associated with them in the same
way as USE flags. The file ``${PORTDIR}/profiles/use.groups.desc``
contains these:

::

        # This is a comment
        DESKTOP Flags which are appropriate for most desktop systems
        RECOMMENDED Flags which should be enabled on almost all systems


Using Groups
------------

Groups may be used in ``/etc/make.conf``, ``/etc/portage/package.use`` and
other places where USE flags are normally specified. They may *not* be
used inside ``IUSE`. As before, the @ symbol is used to indicate that a
group is being referenced. For example, a ``make.conf`` for a KDE desktop
system might resemble:

::

        USE="@DESKTOP @KDE perl alsa dvd"

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:

::

        # We have the following groups defined...
        GROUP1 foo bar
        GROUP2 -bar baz -fnord
        GROUP3 @GROUP1 -@GROUP2 -bar foo
        GROUP4 -foo -bar

        # And the following...
        USE="-@GROUP3 @GROUP4 bar"

        # which resolves to...
        USE="-@GROUP1 @GROUP2 bar -foo -foo -bar bar"
        USE="-foo -bar bar -baz fnord bar -foo -foo -bar bar"
        USE="-baz fnord -foo bar"


Issues with -flags and -@GROUPS
-------------------------------

Earlier drafts of this GLEP did not allow -use flags or -@GROUPS. However,
because of feedback along the lines of "we shouldn't disallow features
just because some users won't understand them" (for example, [3]_), these
are now allowed but discouraged.

The problems are best illustrated by example. Say we have the following
groups defined:

::

        KDE X kde qt
        GNOME X gtk gtk2 gnome

A user who wants a KDE desktop but no GNOME may do the following:

::

        USE="@KDE -@GNOME"

However, this will not give the desired effect -- the ``X`` USE flag will
end up being disabled.

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:

::

        KDE X kde qt -gtk -gnome
        GNOME X gtk gtk2 gnome -kde -qt

And a user wished to use both KDE and GNOME on a system, and so had USE
flags as follows:

::

        USE="@KDE @GNOME"

They would end up with:

::

        USE="X kde qt -gtk -gnome X gtk gtk2 gnome -kde -qt"

Which simplifies:

::

        USE="X gtk gtk2 gnome -kde -qt"

This is clearly not the desired effect.

Adding New Groups
-----------------

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.

In particular, any changes involving -flags *must* be thoroughly discussed
before implementation.

Rationale
=========

USE groups will simplify selecting an appropriate set of USE flags for a
system.

Reference Implementation
========================

TODO

Backwards Compatibility
=======================

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.

Some tools which work with make.conf and / or USE flags (for example,
``ufed``) will need to be updated to understand the new group syntax.

There is currently a dynamic list of USE flags available on the Gentoo
website [2]_. For consistency, a similar list will be needed for USE
groups.

References
==========

.. [1] GLEP 23: Portage handling of ACCEPT_LICENSE
       (http://www.gentoo.org/proj/en/glep/glep-0023.html)
.. [2] http://www.gentoo.org/dyn/use-index.xml
.. [3] GLEP 29 discussion on the gentoo-dev mailing list
       (http://marc.theaimsgroup.com/?l=gentoo-dev&m=109813990013812)

Copyright
=========

This document has been placed in the public domain.

 vim: set tw=74 :
1	GLEP: 29
2	Title: USE flag groups
3	Version: $Revision: $
4	Author: Ciaran McCreesh <ciaranm@gentoo.org>
5	Last-Modified: $Date: $
6	Status: Draft
7	Type: Standards Track
8	Content-Type: text/x-rst
9	Created: 19-August-2004
10	Post-Date: 21-August-2004, 18-October-2004, 25-October-2004
11
12	Abstract
13	========
14
15	Currently, USE flags must be selected on a one-by-one basis, making it
16	time-consuming to set up make.conf appropriately for a machine's role.
17
18	Motivation
19	==========
20
21	Many packages have optional support for other packages (for example, the
22	Vim text editor can optionally support perl, python and ruby
23	interpreters). In Gentoo, these optional dependencies can be selected by
24	the user using USE flags. This allows a system appropriate for a given
25	environment to be built -- a server, for example, should not typically
26	have an X11 server or sound support, whereas both would be desirable on
27	most desktop systems.
28
29	With several hundred USE flags available, deciding upon which USE flags to
30	enable and which to disable can take a long time. Although the default USE
31	flag settings are reasonable, they are clearly not appropriate for every
32	system. In addition, using "-*" to disable all default USE flags can be
33	risky as certain USE flags should not generally be turned off. This GLEP
34	proposes a mechanism for grouping USE flags to simplify selection and to
35	make USE="-*" less dangerous.
36
37	Specification
38	=============
39
40	Group Specification
41	-------------------
42
43	A group shall consist of one or more tokens. Each token may be a USE flag,
44	a -USE flag, a reference to another group or a negative reference to
45	another group.
46
47	These groups are defined in ``${PORTDIR}/profiles/use.groups``. It is
48	proposed that uppercase names only are used for groups to keep them
49	visually distinct from normal USE flags (almost all USE flags are
50	lowercase), although this should not been forced programmatically. The
51	file should be similar in format to the existing use.* files. In the
52	following, ``SOME_GROUP`` and ``OTHER_GROUP`` are group names, and
53	``flag1`` through ``flag5`` are USE flag names:
54
55	::
56
57	SOME_GROUP flag1 flag2 flag3
58	OTHER_GROUP flag2 flag4
59
60	Groups may recursively include other groups. For consistency with GLEP 23
61	[1]_, it is proposed that group names have their name prefixed with an
62	'at' symbol (@):
63
64	::
65
66	GROUP1 flag1
67	GROUP2 flag2 flag3 @GROUP1
68	GROUP3 flag4
69	GROUP4 @GROUP2 @GROUP3 flag5
70
71	The same flag may end up being in a particular group more than once:
72
73	::
74
75	GROUP1 flag1 flag2
76	GROUP2 flag2 flag3
77	GROUP3 @GROUP1 @GROUP2 flag3 flag4
78
79	As with similar files, comments may be included. Lines which begin with a
80	hash symbol (#) are comments.
81
82	::
83
84	# This is a comment
85	FOO bar baz fnord
86
87	Users may create their own groups using ``/etc/portage/use.groups``. This
88	file overrides the profile settings in the case of duplicates.
89
90	It should be legal for groups to specify -use flags, although for reasons
91	discussed below this feature should not generally be used. The syntax is
92	the same:
93
94	::
95
96	# This group contains two negative flags
97	GROUP1 flag1 -flag2 -flag3 flag4
98
99	Groups may not contain circular group references. The following example
100	is illegal:
101
102	::
103
104	# Illegal circular references
105	GROUP1 @GROUP2 foo
106	GROUP2 @GROUP1 bar
107
108	Group Descriptions
109	------------------
110
111	Groups shall have a textual description associated with them in the same
112	way as USE flags. The file ``${PORTDIR}/profiles/use.groups.desc``
113	contains these:
114
115	::
116
117	# This is a comment
118	DESKTOP Flags which are appropriate for most desktop systems
119	RECOMMENDED Flags which should be enabled on almost all systems
120
121
122	Using Groups
123	------------
124
125	Groups may be used in ``/etc/make.conf``, ``/etc/portage/package.use`` and
126	other places where USE flags are normally specified. They may not be
127	used inside ``IUSE`. As before, the @ symbol is used to indicate that a
128	group is being referenced. For example, a ``make.conf`` for a KDE desktop
129	system might resemble:
130
131	::
132
133	USE="@DESKTOP @KDE perl alsa dvd"
134
135	Groups may be preceded by a -sign to invert their contents (that is, all
136	'enable' use flags become -flags, and all -flags become enable flags). Be
137	warned that this feature can cause confusion (see below). Example usage:
138
139	::
140
141	# We have the following groups defined...
142	GROUP1 foo bar
143	GROUP2 -bar baz -fnord
144	GROUP3 @GROUP1 -@GROUP2 -bar foo
145	GROUP4 -foo -bar
146
147	# And the following...
148	USE="-@GROUP3 @GROUP4 bar"
149
150	# which resolves to...
151	USE="-@GROUP1 @GROUP2 bar -foo -foo -bar bar"
152	USE="-foo -bar bar -baz fnord bar -foo -foo -bar bar"
153	USE="-baz fnord -foo bar"
154
155
156	Issues with -flags and -@GROUPS
157	-------------------------------
158
159	Earlier drafts of this GLEP did not allow -use flags or -@GROUPS. However,
160	because of feedback along the lines of "we shouldn't disallow features
161	just because some users won't understand them" (for example, [3]_), these
162	are now allowed but discouraged.
163
164	The problems are best illustrated by example. Say we have the following
165	groups defined:
166
167	::
168
169	KDE X kde qt
170	GNOME X gtk gtk2 gnome
171
172	A user who wants a KDE desktop but no GNOME may do the following:
173
174	::
175
176	USE="@KDE -@GNOME"
177
178	However, this will not give the desired effect -- the ``X`` USE flag will
179	end up being disabled.
180
181	Similarly, -use flags could cause a lot of confusion if misused. If, for
182	example, the KDE group turned off GNOME things and the GNOME group turned
183	off KDE things:
184
185	::
186
187	KDE X kde qt -gtk -gnome
188	GNOME X gtk gtk2 gnome -kde -qt
189
190	And a user wished to use both KDE and GNOME on a system, and so had USE
191	flags as follows:
192
193	::
194
195	USE="@KDE @GNOME"
196
197	They would end up with:
198
199	::
200
201	USE="X kde qt -gtk -gnome X gtk gtk2 gnome -kde -qt"
202
203	Which simplifies:
204
205	::
206
207	USE="X gtk gtk2 gnome -kde -qt"
208
209	This is clearly not the desired effect.
210
211	Adding New Groups
212	-----------------
213
214	The actual groups to be created is beyond the scope of this GLEP, and any
215	group names contained herein should be treated as examples only. Creation
216	of new groups and changing a group's flags should be discussed on the
217	gentoo-dev mailing list as per existing policy for new global USE flags.
218
219	In particular, any changes involving -flags must be thoroughly discussed
220	before implementation.
221
222	Rationale
223	=========
224
225	USE groups will simplify selecting an appropriate set of USE flags for a
226	system.
227
228	Reference Implementation
229	========================
230
231	TODO
232
233	Backwards Compatibility
234	=======================
235
236	The user will not need to make any changes to keep their current setup.
237	Users who are not running a portage version which supports groups can
238	carry on using current syntax with no side-effects.
239
240	Some tools which work with make.conf and / or USE flags (for example,
241	``ufed``) will need to be updated to understand the new group syntax.
242
243	There is currently a dynamic list of USE flags available on the Gentoo
244	website [2]_. For consistency, a similar list will be needed for USE
245	groups.
246
247	References
248	==========
249
250	.. [1] GLEP 23: Portage handling of ACCEPT_LICENSE
251	(http://www.gentoo.org/proj/en/glep/glep-0023.html)
252	.. [2] http://www.gentoo.org/dyn/use-index.xml
253	.. [3] GLEP 29 discussion on the gentoo-dev mailing list
254	(http://marc.theaimsgroup.com/?l=gentoo-dev&m=109813990013812)
255
256	Copyright
257	=========
258
259	This document has been placed in the public domain.
260
261	vim: set tw=74 :