/[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.4 - (show annotations) (download)
Mon Oct 25 16:57:09 2004 UTC (10 years ago) by g2boojum
Branch: MAIN
Changes since 1.3: +125 -31 lines
File MIME type: text/plain
update

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

  ViewVC Help
Powered by ViewVC 1.1.20