/[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.5 - (hide annotations) (download)
Fri Jun 24 21:36:04 2005 UTC (9 years, 3 months ago) by g2boojum
Branch: MAIN
Changes since 1.4: +8 -3 lines
File MIME type: text/plain
update

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

  ViewVC Help
Powered by ViewVC 1.1.20