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

Contents

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. This GLEP proposes a mechanism for grouping USE flags to simplify selection.

Specification

Group Specification

A group shall consist of one or more USE flags. 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, although this should not be enforced programatically. 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 are 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.

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. Again, the @ symbol is used. For example, a make.conf for a desktop system might resemble:

USE="@DESKTOP @KDE perl alsa dvd"

Additional Issues

Groups should not generally contain negative USE flags, as this would lead to confusion. Groups are intended to specify what will be enabled for a given role, not what will be turned off. For example, if the @KDE group disabled Gnome-related USE flags, and a user used USE="@GNOME @KDE" to specify that they wanted both Gnome and KDE to be used where applicable, chaos would ensue. However, for the sake of consistency, -flags should be supported even if their use is strongly discouraged.

It is proposed that -@GROUP syntax should not be supported. Instead, users wishing to turn most things off could use the -* USE syntax along with a group (for example, @RECOMMENDED or @MINIMAL) which turned on flags (for example, pam and readline) which should usually be used.

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.

Rationale

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

Reference Implementation

TODO

Backwards Compatability

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 dymanic 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