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