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

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

  ViewVC Help
Powered by ViewVC 1.1.20