| View previous topic :: View next topic |
| Author |
Message |
ciaranm
Retired Dev
Joined: 19 Jul 2003
Posts: 1719
Location: In Hiding
|
 Posted: Sun Aug 22, 2004 3:36 pm Post subject: GLEP 29 Draft: Use Flag Grouping |
 |
|
Ok, following a recent thread on gentoo-user [1] and some random discussions with jstubbs in #gentoo-dev, I've finally gotten around to writing up the USE groups proposal that's been flying the ether around for a while.
This is a *very* early draft, and everything is subject to change. In particular, Stuart has some interesting ideas for 'per-package' USE groups. Right now I can't see a sane way to implement this, but he is welcome to try to convince me otherwise 
You can read the nice pretty HTML version at [2].
Feedback encouraged.
[1]: http://marc.theaimsgroup.com/?t=109285655600002&r=2&w=2
[2]: http://www.gentoo.org/proj/en/glep/glep-0029.html |
|
| Back to top |
|
 |
ciaranm
Retired Dev
Joined: 19 Jul 2003
Posts: 1719
Location: In Hiding
|
| Posted: Sun Oct 17, 2004 2:31 pm Post subject: |
|
|
Updated version. Feedback still encouraged, preferably on the gentoo-dev mailing list rather than here (unfortunately we're supposed to post GLEPs to the forums too  )
| Code: |
GLEP: 29
Title: USE flag groups
Version: $Revision: $
Author: Ciaran McCreesh <ciaranm@gentoo.org>
Last-Modified: $Date: 2004/08/22 02:02:32 $
Status: Draft
Type: Standards Track
Content-Type: text/x-rst
Created: 19-August-2004
Post-Date: 21-August-2004, 17-October-2004
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
Copyright
=========
This document has been placed in the public domain.
vim: set tw=74 :
|
|
|
| Back to top |
|
|
ciaranm
Retired Dev
Joined: 19 Jul 2003
Posts: 1719
Location: In Hiding
|
| Posted: Sun Oct 24, 2004 3:09 pm Post subject: |
|
|
Updated again. Please provide feedback via gentoo-dev if at all possible, but replies here will be read too.
| Code: |
GLEP: 29
Title: USE flag groups
Version: $Revision: $
Author: Ciaran McCreesh <ciaranm@gentoo.org>
Last-Modified: $Date: $
Status: Draft
Type: Standards Track
Content-Type: text/x-rst
Created: 19-August-2004
Post-Date: 21-August-2004, 18-October-2004, 24-October-2004
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 :
|
|
|
| Back to top |
|
|
|
|
You cannot post new topics in this forum
You cannot reply to topics in this forum
You cannot edit your posts in this forum
You cannot delete your posts in this forum
You cannot vote in polls in this forum
|
|
Portage & Programming
