en/glep/glep-0029.txt

GLEP: 29
Title: USE flag groups
Version: $Revision: 1.5 $
Author: Ciaran McCreesh <ciaranm@gentoo.org>
Last-Modified: $Date: 2005/06/24 21:36:04 $
Status: Draft
Type: Standards Track
Content-Type: text/x-rst
Created: 19-Aug-2004
Post-History: 21-Aug-2004, 18-Oct-2004, 25-Oct-2004, 24-Jul-2005

Status
======

Withdrawn by request of the author.

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