GLEP 29: USE flag groups

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.