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

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

  ViewVC Help
Powered by ViewVC 1.1.20