/[gentoo]/xml/htdocs/proj/en/glep/glep-0029.txt
Gentoo

Diff of /xml/htdocs/proj/en/glep/glep-0029.txt

Parent Directory Parent Directory | Revision Log Revision Log | View Patch Patch

Revision 1.3 Revision 1.4
1GLEP: 29 1GLEP: 29
2Title: USE flag groups 2Title: USE flag groups
3Version: $Revision: 1.3 $ 3Version: $Revision: 1.4 $
4Author: Ciaran McCreesh <ciaranm@gentoo.org> 4Author: Ciaran McCreesh <ciaranm@gentoo.org>
5Last-Modified: $Date: 2004/10/18 15:32:10 $ 5Last-Modified: $Date: 2004/10/25 16:57:09 $
6Status: Draft 6Status: Draft
7Type: Standards Track 7Type: Standards Track
8Content-Type: text/x-rst 8Content-Type: text/x-rst
9Created: 19-August-2004 9Created: 19-August-2004
10Post-Date: 21-August-2004, 18-October-2004 10Post-Date: 21-August-2004, 18-October-2004, 25-October-2004
11 11
12Abstract 12Abstract
13======== 13========
14 14
15Currently, USE flags must be selected on a one-by-one basis, making it 15Currently, USE flags must be selected on a one-by-one basis, making it
… …
25environment to be built -- a server, for example, should not typically 25environment to be built -- a server, for example, should not typically
26have an X11 server or sound support, whereas both would be desirable on 26have an X11 server or sound support, whereas both would be desirable on
27most desktop systems. 27most desktop systems.
28 28
29With several hundred USE flags available, deciding upon which USE flags to 29With several hundred USE flags available, deciding upon which USE flags to
30enable and which to disable can take a long time. This GLEP proposes a 30enable and which to disable can take a long time. Although the default USE
31flag settings are reasonable, they are clearly not appropriate for every
32system. In addition, using "-*" to disable all default USE flags can be
33risky as certain USE flags should not generally be turned off. This GLEP
31mechanism for grouping USE flags to simplify selection. 34proposes a mechanism for grouping USE flags to simplify selection and to
35make USE="-*" less dangerous.
32 36
33Specification 37Specification
34============= 38=============
35 39
36Group Specification 40Group Specification
37------------------- 41-------------------
38 42
39A group shall consist of one or more USE flags. These groups are defined 43A group shall consist of one or more tokens. Each token may be a USE flag,
40in ``${PORTDIR}/profiles/use.groups``. It is proposed that uppercase names 44a -USE flag, a reference to another group or a negative reference to
41only are used for groups to keep them visually distinct from normal USE 45another group.
46
47These groups are defined in ``${PORTDIR}/profiles/use.groups``. It is
48proposed that uppercase names only are used for groups to keep them
49visually distinct from normal USE flags (almost all USE flags are
42flags, although this should not be enforced programatically. The file 50lowercase), although this should not been forced programmatically. The
43should be similar in format to the existing use.* files. In the following, 51file should be similar in format to the existing use.* files. In the
44``SOME_GROUP`` and ``OTHER_GROUP`` are group names, and ``flag1`` through 52following, ``SOME_GROUP`` and ``OTHER_GROUP`` are group names, and
45``flag5`` are USE flag names: 53``flag1`` through ``flag5`` are USE flag names:
46 54
47:: 55::
48 56
49 SOME_GROUP flag1 flag2 flag3 57 SOME_GROUP flag1 flag2 flag3
50 OTHER_GROUP flag2 flag4 58 OTHER_GROUP flag2 flag4
51 59
52Groups may recursively include other groups. For consistency with GLEP 23 60Groups may recursively include other groups. For consistency with GLEP 23
53[1], it is proposed that group names are prefixed with an 'at' symbol (@): 61[1]_, it is proposed that group names have their name prefixed with an
62'at' symbol (@):
54 63
55:: 64::
56 65
57 GROUP1 flag1 66 GROUP1 flag1
58 GROUP2 flag2 flag3 @GROUP1 67 GROUP2 flag2 flag3 @GROUP1
… …
76 FOO bar baz fnord 85 FOO bar baz fnord
77 86
78Users may create their own groups using ``/etc/portage/use.groups``. This 87Users may create their own groups using ``/etc/portage/use.groups``. This
79file overrides the profile settings in the case of duplicates. 88file overrides the profile settings in the case of duplicates.
80 89
90It should be legal for groups to specify -use flags, although for reasons
91discussed below this feature should not generally be used. The syntax is
92the same:
93
94::
95
96 # This group contains two negative flags
97 GROUP1 flag1 -flag2 -flag3 flag4
98
99Groups may *not* contain circular group references. The following example
100is illegal:
101
102::
103
104 # Illegal circular references
105 GROUP1 @GROUP2 foo
106 GROUP2 @GROUP1 bar
107
81Group Descriptions 108Group Descriptions
82------------------ 109------------------
83 110
84Groups shall have a textual description associated with them in the same 111Groups shall have a textual description associated with them in the same
85way as USE flags. The file ``${PORTDIR}/profiles/use.groups.desc`` 112way as USE flags. The file ``${PORTDIR}/profiles/use.groups.desc``
… …
94 121
95Using Groups 122Using Groups
96------------ 123------------
97 124
98Groups may be used in ``/etc/make.conf``, ``/etc/portage/package.use`` and 125Groups may be used in ``/etc/make.conf``, ``/etc/portage/package.use`` and
99other places where USE flags are normally specified. Again, the @ symbol 126other places where USE flags are normally specified. They may *not* be
100is used. For example, a ``make.conf`` for a desktop system might resemble: 127used inside ``IUSE`. As before, the @ symbol is used to indicate that a
128group is being referenced. For example, a ``make.conf`` for a KDE desktop
129system might resemble:
101 130
102:: 131::
103 132
104 USE="@DESKTOP @KDE perl alsa dvd" 133 USE="@DESKTOP @KDE perl alsa dvd"
105 134
106Additional Issues 135Groups may be preceded by a -sign to invert their contents (that is, all
107----------------- 136'enable' use flags become -flags, and all -flags become enable flags). Be
137warned that this feature can cause confusion (see below). Example usage:
108 138
109Groups should *not* generally contain negative USE flags, as this would 139::
110lead to confusion. Groups are intended to specify what will be enabled for
111a given role, not what will be turned off. For example, if the @KDE group
112disabled Gnome-related USE flags, and a user used ``USE="@GNOME @KDE"`` to
113specify that they wanted both Gnome *and* KDE to be used where applicable,
114chaos would ensue. However, for the sake of consistency, -flags should be
115supported even if their use is strongly discouraged.
116 140
117It is proposed that ``-@GROUP`` syntax should *not* be supported. Instead, 141 # We have the following groups defined...
118users wishing to turn most things off could use the ``-*`` USE syntax 142 GROUP1 foo bar
119along with a group (for example, @RECOMMENDED or @MINIMAL) which turned on 143 GROUP2 -bar baz -fnord
120flags (for example, pam and readline) which should usually be used. 144 GROUP3 @GROUP1 -@GROUP2 -bar foo
145 GROUP4 -foo -bar
146
147 # And the following...
148 USE="-@GROUP3 @GROUP4 bar"
149
150 # which resolves to...
151 USE="-@GROUP1 @GROUP2 bar -foo -foo -bar bar"
152 USE="-foo -bar bar -baz fnord bar -foo -foo -bar bar"
153 USE="-baz fnord -foo bar"
154
155
156Issues with -flags and -@GROUPS
157-------------------------------
158
159Earlier drafts of this GLEP did not allow -use flags or -@GROUPS. However,
160because of feedback along the lines of "we shouldn't disallow features
161just because some users won't understand them" (for example, [3]_), these
162are now allowed but discouraged.
163
164The problems are best illustrated by example. Say we have the following
165groups defined:
166
167::
168
169 KDE X kde qt
170 GNOME X gtk gtk2 gnome
171
172A user who wants a KDE desktop but no GNOME may do the following:
173
174::
175
176 USE="@KDE -@GNOME"
177
178However, this will not give the desired effect -- the ``X`` USE flag will
179end up being disabled.
180
181Similarly, -use flags could cause a lot of confusion if misused. If, for
182example, the KDE group turned off GNOME things and the GNOME group turned
183off KDE things:
184
185::
186
187 KDE X kde qt -gtk -gnome
188 GNOME X gtk gtk2 gnome -kde -qt
189
190And a user wished to use both KDE and GNOME on a system, and so had USE
191flags as follows:
192
193::
194
195 USE="@KDE @GNOME"
196
197They would end up with:
198
199::
200
201 USE="X kde qt -gtk -gnome X gtk gtk2 gnome -kde -qt"
202
203Which simplifies:
204
205::
206
207 USE="X gtk gtk2 gnome -kde -qt"
208
209This is clearly not the desired effect.
121 210
122Adding New Groups 211Adding New Groups
123----------------- 212-----------------
124 213
125The actual groups to be created is beyond the scope of this GLEP, and any 214The actual groups to be created is beyond the scope of this GLEP, and any
126group names contained herein should be treated as examples only. Creation 215group names contained herein should be treated as examples only. Creation
127of new groups and changing a group's flags should be discussed on the 216of new groups and changing a group's flags should be discussed on the
128gentoo-dev mailing list as per existing policy for new global USE flags. 217gentoo-dev mailing list as per existing policy for new global USE flags.
129 218
219In particular, any changes involving -flags *must* be thoroughly discussed
220before implementation.
221
130Rationale 222Rationale
131========= 223=========
132 224
133USE groups will simplify selecting an appropriate set of USE flags for a 225USE groups will simplify selecting an appropriate set of USE flags for a
134system. 226system.
… …
136Reference Implementation 228Reference Implementation
137======================== 229========================
138 230
139TODO 231TODO
140 232
141Backwards Compatability 233Backwards Compatibility
142======================= 234=======================
143 235
144The user will not need to make any changes to keep their current setup. 236The user will not need to make any changes to keep their current setup.
145Users who are not running a portage version which supports groups can 237Users who are not running a portage version which supports groups can
146carry on using current syntax with no side-effects. 238carry on using current syntax with no side-effects.
147 239
148Some tools which work with make.conf and / or USE flags (for example, 240Some 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. 241``ufed``) will need to be updated to understand the new group syntax.
150 242
151There is currently a dymanic list of USE flags available on the Gentoo 243There is currently a dynamic list of USE flags available on the Gentoo
152website [2]. For consistency, a similar list will be needed for USE 244website [2]_. For consistency, a similar list will be needed for USE
153groups. 245groups.
154 246
155References 247References
156========== 248==========
157 249
158.. [1] GLEP 23: Portage handling of ACCEPT_LICENSE 250.. [1] GLEP 23: Portage handling of ACCEPT_LICENSE
159 (http://www.gentoo.org/proj/en/glep/glep-0023.html) 251 (http://www.gentoo.org/proj/en/glep/glep-0023.html)
160.. [2] http://www.gentoo.org/dyn/use-index.xml 252.. [2] http://www.gentoo.org/dyn/use-index.xml
253.. [3] GLEP 29 discussion on the gentoo-dev mailing list
254 (http://marc.theaimsgroup.com/?l=gentoo-dev&m=109813990013812)
161 255
162Copyright 256Copyright
163========= 257=========
164 258
165This document has been placed in the public domain. 259This document has been placed in the public domain.
Legend:
Removed from v.1.3  
changed lines
  Added in v.1.4
  ViewVC Help
Powered by ViewVC 1.1.13