en/glep/glep-0029.txt

GLEP: 29
Title: USE flag groups
Version: $Revision: 1.1 $
Author: Ciaran McCreesh <ciaranm@gentoo.org>
Last-Modified: $Date: 2004/08/22 01:59:24 $
Status: Draft
Type: Standards Track
Content-Type: text/x-rst
Created: 19-August-2004
Post-Date: 21-August-2004

BIG FAT DISCLAIMER: EARLY DRAFT, SEND COMMENTS TO ciaranm. EVERYTHING IN
HERE IS OPEN TO DISCUSSION. THE WRITING STYLE SUCKS. MAY CAUSE CANCER IN
PUPPIES.

Abstract
========

Currently, USE flags must be selected on a one-by-one basis, making it
time-consuming to set up make.conf appropriately for a machine's role.

Motivation
==========

USE flags allow the user to have software built in a manner which is
relevant for their system's role. For example, a desktop user will
probably want to enable optional X support in packages, whereas a server
user will not. However, with several hundred USE flags available, it can
be time consuming to set up make.conf appropriately.

This GLEP proposes a mechanism for grouping USE flags to simplify
selection.

Specification
=============

Group Specification
-------------------

A group shall consist of one or more USE flags. These groups are defined
in ``${PORTDIR}/profiles/use.groups``. It is proposed that uppercase names
only are used for groups to keep them visually distinct from normal USE
flags. The file format is similar to the existing use.* files:

::

        SOME_GROUP flag1 flag2 flag3
        OTHER_GROUP flag2 flag4

Groups may recursively include other groups. For consistency with GLEP 23
[1], it is proposed that group names are prefixed with an 'at' symbol (@):

::

        GROUP1 flag1
        GROUP2 flag2 flag3 @GROUP1
        GROUP3 flag4
        GROUP4 @GROUP2 @GROUP3 flag5

Users may create their own groups using ``/etc/portage/use.groups``. This
file overrides the profile settings in the case of duplicates.

Group Descriptions
------------------

Groups shall have a textual description associated with them in the same
way as USE flags. The file ``${PORTDIR}/profiles/use.groups.desc``
contains these:

::

        DESKTOP Flags which are appropriate for most desktop systems
        RECOMMENDED Flags which should be enabled on almost all systems


Using Groups
------------

Groups may be used in ``/etc/make.conf``, ``/etc/portage/package.use`` and
other places where USE flags are normally specified. Again, the @ symbol
is used. For example, a ``make.conf`` for a desktop system might resemble:

::

        USE="@DESKTOP @KDE perl alsa dvd"

Additional Issues
-----------------

Groups should *not* generally contain negative USE flags, as this would
lead to confusion. Groups are intended to specify what will be enabled for
a given role, not what will be turned off. For example, if the @KDE group
disabled Gnome-related USE flags, and a user used ``USE="@GNOME @KDE"`` to
specify that they wanted both Gnome *and* KDE to be used where applicable,
chaos would ensue. However, for the sake of consistency, -flags should be
supported even if their use is strongly discouraged.

It is proposed that ``-@GROUP`` syntax should *not* be supported. Instead,
users wishing to turn most things off could use the ``-*`` USE syntax
along with a group (for example, @RECOMMENDED) which turned on flags (for
example, pam and readline) which should usually be used.

Adding New Groups
-----------------

The actual groups to be created is beyond the scope of this GLEP, and any
group names contained herein should be treated as examples only. Creation
of new groups and changing a group's flags should be discussed on the
gentoo-dev mailing list as per existing policy for new global USE flags.

Rationale
=========

USE groups will simplify selecting an appropriate set of USE flags for a
system.

Reference Implementation
========================

TODO

Backwards Compatability
=======================

The user will not need to make any changes to keep their current setup.
Users who are not running a portage version which supports groups can
carry on using current syntax with no side-effects.

Some tools which work with make.conf and / or USE flags (for example,
``ufed``) will need to be updated to understand the new group syntax.

There is currently a dymanic list of USE flags available on the Gentoo
website [2]. For consistency, a similar list will be needed for USE
groups.

References
==========

.. [1] GLEP 23: Portage handling of ACCEPT_LICENSE
       (http://www.gentoo.org/proj/en/glep/glep-0023.html)
.. [2] http://www.gentoo.org/dyn/use-index.xml

Copyright
=========

This document has been placed in the public domain.

 vim: set tw=74 :
1	g2boojum	1.2	GLEP: 29
2	g2boojum	1.1	Title: USE flag groups
3	g2boojum	1.2	Version: $Revision: 1.1 $
4	g2boojum	1.1	Author: Ciaran McCreesh <ciaranm@gentoo.org>
5	g2boojum	1.2	Last-Modified: $Date: 2004/08/22 01:59:24 $
6	g2boojum	1.1	Status: Draft
7			Type: Standards Track
8			Content-Type: text/x-rst
9			Created: 19-August-2004
10	g2boojum	1.2	Post-Date: 21-August-2004
11	g2boojum	1.1
12			BIG FAT DISCLAIMER: EARLY DRAFT, SEND COMMENTS TO ciaranm. EVERYTHING IN
13			HERE IS OPEN TO DISCUSSION. THE WRITING STYLE SUCKS. MAY CAUSE CANCER IN
14			PUPPIES.
15
16			Abstract
17			========
18
19			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
22			Motivation
23			==========
24
25			USE flags allow the user to have software built in a manner which is
26			relevant for their system's role. For example, a desktop user will
27			probably want to enable optional X support in packages, whereas a server
28			user will not. However, with several hundred USE flags available, it can
29			be time consuming to set up make.conf appropriately.
30
31			This GLEP proposes a mechanism for grouping USE flags to simplify
32			selection.
33
34			Specification
35			=============
36
37			Group Specification
38			-------------------
39
40			A group shall consist of one or more USE flags. These groups are defined
41			in ``${PORTDIR}/profiles/use.groups``. It is proposed that uppercase names
42			only are used for groups to keep them visually distinct from normal USE
43			flags. The file format is similar to the existing use.* files:
44
45			::
46
47			SOME_GROUP flag1 flag2 flag3
48			OTHER_GROUP flag2 flag4
49
50			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 (@):
52
53			::
54
55			GROUP1 flag1
56			GROUP2 flag2 flag3 @GROUP1
57			GROUP3 flag4
58			GROUP4 @GROUP2 @GROUP3 flag5
59
60			Users may create their own groups using ``/etc/portage/use.groups``. This
61			file overrides the profile settings in the case of duplicates.
62
63			Group Descriptions
64			------------------
65
66			Groups shall have a textual description associated with them in the same
67			way as USE flags. The file ``${PORTDIR}/profiles/use.groups.desc``
68			contains these:
69
70			::
71
72			DESKTOP Flags which are appropriate for most desktop systems
73			RECOMMENDED Flags which should be enabled on almost all systems
74
75
76			Using Groups
77			------------
78
79			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
81			is used. For example, a ``make.conf`` for a desktop system might resemble:
82
83			::
84
85			USE="@DESKTOP @KDE perl alsa dvd"
86
87			Additional Issues
88			-----------------
89
90			Groups should not generally contain negative USE flags, as this would
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
98			It is proposed that ``-@GROUP`` syntax should not be supported. Instead,
99			users wishing to turn most things off could use the ``-*`` USE syntax
100			along with a group (for example, @RECOMMENDED) which turned on flags (for
101			example, pam and readline) which should usually be used.
102
103			Adding New Groups
104			-----------------
105
106			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
108			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.
110
111			Rationale
112			=========
113
114			USE groups will simplify selecting an appropriate set of USE flags for a
115			system.
116
117			Reference Implementation
118			========================
119
120			TODO
121
122			Backwards Compatability
123			=======================
124
125			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
127			carry on using current syntax with no side-effects.
128
129			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.
131
132			There is currently a dymanic list of USE flags available on the Gentoo
133			website [2]. For consistency, a similar list will be needed for USE
134			groups.
135
136			References
137			==========
138
139			.. [1] GLEP 23: Portage handling of ACCEPT_LICENSE
140			(http://www.gentoo.org/proj/en/glep/glep-0023.html)
141			.. [2] http://www.gentoo.org/dyn/use-index.xml
142
143			Copyright
144			=========
145
146			This document has been placed in the public domain.
147
148			vim: set tw=74 :