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

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

Parent Directory Parent Directory | Revision Log Revision Log


Revision 1.5 - (show annotations) (download)
Fri Jun 24 21:36:04 2005 UTC (9 years, 5 months ago) by g2boojum
Branch: MAIN
Changes since 1.4: +8 -3 lines
File MIME type: text/plain
update

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

  ViewVC Help
Powered by ViewVC 1.1.20