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

1 g2boojum 1.2 GLEP: 29
2 g2boojum 1.1 Title: USE flag groups
3 g2boojum 1.3 Version: $Revision: $
4 g2boojum 1.1 Author: Ciaran McCreesh <ciaranm@gentoo.org>
5 g2boojum 1.4 Last-Modified: $Date: $
6 g2boojum 1.1 Status: Draft
7     Type: Standards Track
8     Content-Type: text/x-rst
9     Created: 19-August-2004
10 g2boojum 1.4 Post-Date: 21-August-2004, 18-October-2004, 25-October-2004
11 g2boojum 1.1
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 g2boojum 1.3 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 g2boojum 1.4 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 g2boojum 1.1
37     Specification
38     =============
39    
40     Group Specification
41     -------------------
42    
43 g2boojum 1.4 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 g2boojum 1.1
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 g2boojum 1.4 [1]_, it is proposed that group names have their name prefixed with an
62     'at' symbol (@):
63 g2boojum 1.1
64     ::
65    
66     GROUP1 flag1
67     GROUP2 flag2 flag3 @GROUP1
68     GROUP3 flag4
69     GROUP4 @GROUP2 @GROUP3 flag5
70    
71 g2boojum 1.3 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 g2boojum 1.1 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 g2boojum 1.4 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 g2boojum 1.1 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 g2boojum 1.3 # This is a comment
118 g2boojum 1.1 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 g2boojum 1.4 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 g2boojum 1.1
131     ::
132    
133     USE="@DESKTOP @KDE perl alsa dvd"
134    
135 g2boojum 1.4 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 g2boojum 1.1
209 g2boojum 1.4 This is clearly not the desired effect.
210 g2boojum 1.1
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 g2boojum 1.4 In particular, any changes involving -flags *must* be thoroughly discussed
220     before implementation.
221    
222 g2boojum 1.1 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 g2boojum 1.4 Backwards Compatibility
234 g2boojum 1.1 =======================
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 g2boojum 1.4 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 g2boojum 1.1 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 g2boojum 1.4 .. [3] GLEP 29 discussion on the gentoo-dev mailing list
254     (http://marc.theaimsgroup.com/?l=gentoo-dev&m=109813990013812)
255 g2boojum 1.1
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