Rename all GLEPs to .rst

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 :