/[gentoo]/xml/htdocs/proj/en/glep/glep-0029.txt

Diff of /xml/htdocs/proj/en/glep/glep-0029.txt

Parent Directory | Revision Log | View Patch Patch

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

 Legend:



Removed from v.1.2
 


changed lines


 
Added in v.1.6
 Legend:



Removed from v.1.2
 


changed lines


 
Added in v.1.6
-Removed from v.1.2
+Added in v.1.6

	ViewVC Help
Powered by ViewVC 1.1.20