diff options
author | 2017-09-14 23:14:39 +0200 | |
---|---|---|
committer | 2017-10-09 12:08:51 +0200 | |
commit | c6fe2071a2e83be2203196ad7f9459941821a034 (patch) | |
tree | d81e1d9898c05917e05203af9803b581dff0d915 /glep-0029.rst | |
parent | glep-0045: Mark Final since GLEP 1 now uses ISO 8601 dates (diff) | |
download | glep-c6fe2071a2e83be2203196ad7f9459941821a034.tar.gz glep-c6fe2071a2e83be2203196ad7f9459941821a034.tar.bz2 glep-c6fe2071a2e83be2203196ad7f9459941821a034.zip |
Rename all GLEPs to .rst
Diffstat (limited to 'glep-0029.rst')
-rw-r--r-- | glep-0029.rst | 268 |
1 files changed, 268 insertions, 0 deletions
diff --git a/glep-0029.rst b/glep-0029.rst new file mode 100644 index 0000000..d6b001b --- /dev/null +++ b/glep-0029.rst @@ -0,0 +1,268 @@ +GLEP: 29 +Title: USE flag groups +Version: $Revision$ +Author: Ciaran McCreesh <ciaranm@gentoo.org> +Last-Modified: $Date$ +Status: Withdrawn +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 work is licensed under the Creative Commons Attribution-ShareAlike 3.0 +Unported License. To view a copy of this license, visit +http://creativecommons.org/licenses/by-sa/3.0/. + + vim: set tw=74 : |