en/glep/glep-0029.txt

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, 18-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 :
1	GLEP: 29
2	Title: USE flag groups
3	Version: $Revision: $
4	Author: Ciaran McCreesh <ciaranm@gentoo.org>
5	Last-Modified: $Date: 2004/08/22 02:02:32 $
6	Status: Draft
7	Type: Standards Track
8	Content-Type: text/x-rst
9	Created: 19-August-2004
10	Post-Date: 21-August-2004, 18-October-2004
11
12	Abstract
13	========
14
15	Currently, USE flags must be selected on a one-by-one basis, making it
16	time-consuming to set up make.conf appropriately for a machine's role.
17
18	Motivation
19	==========
20
21	Many packages have optional support for other packages (for example, the
22	Vim text editor can optionally support perl, python and ruby
23	interpreters). In Gentoo, these optional dependencies can be selected by
24	the user using USE flags. This allows a system appropriate for a given
25	environment to be built -- a server, for example, should not typically
26	have an X11 server or sound support, whereas both would be desirable on
27	most desktop systems.
28
29	With several hundred USE flags available, deciding upon which USE flags to
30	enable and which to disable can take a long time. This GLEP proposes a
31	mechanism for grouping USE flags to simplify selection.
32
33	Specification
34	=============
35
36	Group Specification
37	-------------------
38
39	A group shall consist of one or more USE flags. These groups are defined
40	in ``${PORTDIR}/profiles/use.groups``. It is proposed that uppercase names
41	only are used for groups to keep them visually distinct from normal USE
42	flags, although this should not be enforced programatically. The file
43	should be similar in format to the existing use.* files. In the following,
44	``SOME_GROUP`` and ``OTHER_GROUP`` are group names, and ``flag1`` through
45	``flag5`` are USE flag names:
46
47	::
48
49	SOME_GROUP flag1 flag2 flag3
50	OTHER_GROUP flag2 flag4
51
52	Groups may recursively include other groups. For consistency with GLEP 23
53	[1], it is proposed that group names are prefixed with an 'at' symbol (@):
54
55	::
56
57	GROUP1 flag1
58	GROUP2 flag2 flag3 @GROUP1
59	GROUP3 flag4
60	GROUP4 @GROUP2 @GROUP3 flag5
61
62	The same flag may end up being in a particular group more than once:
63
64	::
65
66	GROUP1 flag1 flag2
67	GROUP2 flag2 flag3
68	GROUP3 @GROUP1 @GROUP2 flag3 flag4
69
70	As with similar files, comments may be included. Lines which begin with a
71	hash symbol (#) are comments.
72
73	::
74
75	# This is a comment
76	FOO bar baz fnord
77
78	Users may create their own groups using ``/etc/portage/use.groups``. This
79	file overrides the profile settings in the case of duplicates.
80
81	Group Descriptions
82	------------------
83
84	Groups shall have a textual description associated with them in the same
85	way as USE flags. The file ``${PORTDIR}/profiles/use.groups.desc``
86	contains these:
87
88	::
89
90	# This is a comment
91	DESKTOP Flags which are appropriate for most desktop systems
92	RECOMMENDED Flags which should be enabled on almost all systems
93
94
95	Using Groups
96	------------
97
98	Groups may be used in ``/etc/make.conf``, ``/etc/portage/package.use`` and
99	other places where USE flags are normally specified. Again, the @ symbol
100	is used. For example, a ``make.conf`` for a desktop system might resemble:
101
102	::
103
104	USE="@DESKTOP @KDE perl alsa dvd"
105
106	Additional Issues
107	-----------------
108
109	Groups should not generally contain negative USE flags, as this would
110	lead to confusion. Groups are intended to specify what will be enabled for
111	a given role, not what will be turned off. For example, if the @KDE group
112	disabled Gnome-related USE flags, and a user used ``USE="@GNOME @KDE"`` to
113	specify that they wanted both Gnome and KDE to be used where applicable,
114	chaos would ensue. However, for the sake of consistency, -flags should be
115	supported even if their use is strongly discouraged.
116
117	It is proposed that ``-@GROUP`` syntax should not be supported. Instead,
118	users wishing to turn most things off could use the ``-*`` USE syntax
119	along with a group (for example, @RECOMMENDED or @MINIMAL) which turned on
120	flags (for example, pam and readline) which should usually be used.
121
122	Adding New Groups
123	-----------------
124
125	The actual groups to be created is beyond the scope of this GLEP, and any
126	group names contained herein should be treated as examples only. Creation
127	of new groups and changing a group's flags should be discussed on the
128	gentoo-dev mailing list as per existing policy for new global USE flags.
129
130	Rationale
131	=========
132
133	USE groups will simplify selecting an appropriate set of USE flags for a
134	system.
135
136	Reference Implementation
137	========================
138
139	TODO
140
141	Backwards Compatability
142	=======================
143
144	The user will not need to make any changes to keep their current setup.
145	Users who are not running a portage version which supports groups can
146	carry on using current syntax with no side-effects.
147
148	Some tools which work with make.conf and / or USE flags (for example,
149	``ufed``) will need to be updated to understand the new group syntax.
150
151	There is currently a dymanic list of USE flags available on the Gentoo
152	website [2]. For consistency, a similar list will be needed for USE
153	groups.
154
155	References
156	==========
157
158	.. [1] GLEP 23: Portage handling of ACCEPT_LICENSE
159	(http://www.gentoo.org/proj/en/glep/glep-0023.html)
160	.. [2] http://www.gentoo.org/dyn/use-index.xml
161
162	Copyright
163	=========
164
165	This document has been placed in the public domain.
166
167	vim: set tw=74 :