/[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.1 Revision 1.4
1GLEP: 0000 1GLEP: 29
2Title: USE flag groups 2Title: USE flag groups
3Version: $Revision: 1.1 $ 3Version: $Revision: 1.4 $
4Author: Ciaran McCreesh <ciaranm@gentoo.org> 4Author: Ciaran McCreesh <ciaranm@gentoo.org>
5Last-Modified: $Date: 2004/08/22 01:59:24 $ 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
10 10Post-Date: 21-August-2004, 18-October-2004, 25-October-2004
11BIG FAT DISCLAIMER: EARLY DRAFT, SEND COMMENTS TO ciaranm. EVERYTHING IN
12HERE IS OPEN TO DISCUSSION. THE WRITING STYLE SUCKS. MAY CAUSE CANCER IN
13PUPPIES.
14 11
15Abstract 12Abstract
16======== 13========
17 14
18Currently, 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
19time-consuming to set up make.conf appropriately for a machine's role. 16time-consuming to set up make.conf appropriately for a machine's role.
20 17
21Motivation 18Motivation
22========== 19==========
23 20
24USE flags allow the user to have software built in a manner which is 21Many packages have optional support for other packages (for example, the
25relevant for their system's role. For example, a desktop user will 22Vim text editor can optionally support perl, python and ruby
26probably want to enable optional X support in packages, whereas a server 23interpreters). In Gentoo, these optional dependencies can be selected by
27user will not. However, with several hundred USE flags available, it can 24the user using USE flags. This allows a system appropriate for a given
28be time consuming to set up make.conf appropriately. 25environment to be built -- a server, for example, should not typically
26have an X11 server or sound support, whereas both would be desirable on
27most desktop systems.
29 28
29With several hundred USE flags available, deciding upon which USE flags to
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
30This GLEP proposes a mechanism for grouping USE flags to simplify 34proposes a mechanism for grouping USE flags to simplify selection and to
31selection. 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.
42flags. The file format is similar to the existing use.* files: 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
50lowercase), although this should not been forced programmatically. The
51file should be similar in format to the existing use.* files. In the
52following, ``SOME_GROUP`` and ``OTHER_GROUP`` are group names, and
53``flag1`` through ``flag5`` are USE flag names:
43 54
44:: 55::
45 56
46 SOME_GROUP flag1 flag2 flag3 57 SOME_GROUP flag1 flag2 flag3
47 OTHER_GROUP flag2 flag4 58 OTHER_GROUP flag2 flag4
48 59
49Groups may recursively include other groups. For consistency with GLEP 23 60Groups may recursively include other groups. For consistency with GLEP 23
50[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 (@):
51 63
52:: 64::
53 65
54 GROUP1 flag1 66 GROUP1 flag1
55 GROUP2 flag2 flag3 @GROUP1 67 GROUP2 flag2 flag3 @GROUP1
56 GROUP3 flag4 68 GROUP3 flag4
57 GROUP4 @GROUP2 @GROUP3 flag5 69 GROUP4 @GROUP2 @GROUP3 flag5
58 70
71The 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
79As with similar files, comments may be included. Lines which begin with a
80hash symbol (#) are comments.
81
82::
83
84 # This is a comment
85 FOO bar baz fnord
86
59Users may create their own groups using ``/etc/portage/use.groups``. This 87Users may create their own groups using ``/etc/portage/use.groups``. This
60file overrides the profile settings in the case of duplicates. 88file overrides the profile settings in the case of duplicates.
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
61 107
62Group Descriptions 108Group Descriptions
63------------------ 109------------------
64 110
65Groups shall have a textual description associated with them in the same 111Groups shall have a textual description associated with them in the same
66way as USE flags. The file ``${PORTDIR}/profiles/use.groups.desc`` 112way as USE flags. The file ``${PORTDIR}/profiles/use.groups.desc``
67contains these: 113contains these:
68 114
69:: 115::
70 116
117 # This is a comment
71 DESKTOP Flags which are appropriate for most desktop systems 118 DESKTOP Flags which are appropriate for most desktop systems
72 RECOMMENDED Flags which should be enabled on almost all systems 119 RECOMMENDED Flags which should be enabled on almost all systems
73 120
74 121
75Using Groups 122Using Groups
76------------ 123------------
77 124
78Groups 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
79other places where USE flags are normally specified. Again, the @ symbol 126other places where USE flags are normally specified. They may *not* be
80is 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:
81 130
82:: 131::
83 132
84 USE="@DESKTOP @KDE perl alsa dvd" 133 USE="@DESKTOP @KDE perl alsa dvd"
85 134
86Additional Issues 135Groups may be preceded by a -sign to invert their contents (that is, all
87----------------- 136'enable' use flags become -flags, and all -flags become enable flags). Be
137warned that this feature can cause confusion (see below). Example usage:
88 138
89Groups should *not* generally contain negative USE flags, as this would 139::
90lead to confusion. Groups are intended to specify what will be enabled for
91a given role, not what will be turned off. For example, if the @KDE group
92disabled Gnome-related USE flags, and a user used ``USE="@GNOME @KDE"`` to
93specify that they wanted both Gnome *and* KDE to be used where applicable,
94chaos would ensue. However, for the sake of consistency, -flags should be
95supported even if their use is strongly discouraged.
96 140
97It is proposed that ``-@GROUP`` syntax should *not* be supported. Instead, 141 # We have the following groups defined...
98users wishing to turn most things off could use the ``-*`` USE syntax 142 GROUP1 foo bar
99along with a group (for example, @RECOMMENDED) which turned on flags (for 143 GROUP2 -bar baz -fnord
100example, 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.
101 210
102Adding New Groups 211Adding New Groups
103----------------- 212-----------------
104 213
105The 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
106group names contained herein should be treated as examples only. Creation 215group names contained herein should be treated as examples only. Creation
107of 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
108gentoo-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.
109 218
219In particular, any changes involving -flags *must* be thoroughly discussed
220before implementation.
221
110Rationale 222Rationale
111========= 223=========
112 224
113USE 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
114system. 226system.
116Reference Implementation 228Reference Implementation
117======================== 229========================
118 230
119TODO 231TODO
120 232
121Backwards Compatability 233Backwards Compatibility
122======================= 234=======================
123 235
124The 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.
125Users who are not running a portage version which supports groups can 237Users who are not running a portage version which supports groups can
126carry on using current syntax with no side-effects. 238carry on using current syntax with no side-effects.
127 239
128Some 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,
129``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.
130 242
131There 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
132website [2]. For consistency, a similar list will be needed for USE 244website [2]_. For consistency, a similar list will be needed for USE
133groups. 245groups.
134 246
135References 247References
136========== 248==========
137 249
138.. [1] GLEP 23: Portage handling of ACCEPT_LICENSE 250.. [1] GLEP 23: Portage handling of ACCEPT_LICENSE
139 (http://www.gentoo.org/proj/en/glep/glep-0023.html) 251 (http://www.gentoo.org/proj/en/glep/glep-0023.html)
140.. [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)
141 255
142Copyright 256Copyright
143========= 257=========
144 258
145This document has been placed in the public domain. 259This document has been placed in the public domain.

Legend:
Removed from v.1.1  
changed lines
  Added in v.1.4

  ViewVC Help
Powered by ViewVC 1.1.20