en/glep/glep-0021.txt

GLEP: 21
Title: User-defined Package Sets
Version: $Revision: 1.4 $ 
Last-Modified: $Date: 2007/04/21 03:13:16 $
Author: Tal Peer <coredumb@gentoo.org>,
        Alec Warner <antarus@gentoo.org>
Status: Deferred
Type: Standards Track
Discussed-To: gentoo-portage-dev@lists.gentoo.org
Content-Type: text/x-rst
Created: 22-Feb-2004
Post-History: 6-Mar-2004, 3-Sep-2006

Status
======

Abandoned. Package set support has been added in portage-2.2, but it 
doesn't match the description in this document in many cases, and the
document has several major gaps regarding the behavior and restrictions 
of package sets.

Abstract
========

In Portage, package sets (formerly known as 'classes' or 'targets')
are mere groups of packages, grouped together to allow easier updating
and handling of them. Currently it is impossible to define sets further
than the two default ones: "system" and "world".

Motivation
==========

Over the months, quite a few requests for user-defined sets were
made by users and developers, either by posting bugs, messages to
mailing lists or on IRC. Usually the response is that this is an
awesome idea, but no one ever took the time to actually define it
properly and implement it.

This document offers a specification for the implementation of
user-defined sets using configuration files similar to the current
world/system sets use.

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

The proposed implementation uses a one file per set approach, meaning
each package set is defined in a single file. All set definition files
will reside in a directory ``/etc/portage/sets/`` and each set's name
will be its file name. Therefore, if one defines a set in
/etc/portage/sets/foo-set, the set name will be 'foo-set'. Usual
package naming rules [#NAME-RULES]_ also apply to sets.

As it is impossible to create two or more files with identical names
in the same directory, a theoretic conflict between two different sets
sharing the same name is impossible. However, users may define a
package set whose name conflicts with one more or packages (for ambiguity
resolution, see below).

Syntax for the package list file is the same as the world file syntax,
as described in the Portage manpage [#PORTAGE-MANPAGE]_, with one
addition: sets may not be 'inherited' by other sets, only packages may
be listed. There is no limitation to the number of packages in a set
or to the number of sets a package may belong to.

Using User-defined Sets With Emerge
--------------------------------------

The user-defined sets will be available either directly or using
the --package-set option, As in::

        # Basically the same:
        emerge foo-set
        emerge --package-set foo-set

The --package-set option is introduced to bypass ambiguities, as
illustrated in the next example::

        emerge foo                # Where foo is both a set and a one or more
                                  # existing packages. This will cause emerge to show
                                  # the ambiguity, ask us to be more
                                  # specific, and stop.
        
        emerge --package-set foo  # So we specify that what we actually
                                  # meant was the package set.

        emerge cat-bar/foo        # Or we specify the exact package name.

When running emerge with the --pretend option, sets will be
expanded to the packages they are comprised off in the output, as with
the current system-defined sets.

Only one set may be passed to portage at time, and sets can not
be mixed with ordinary packages. Thus, the following snippets are
all invalid and will result in an error  (assuming ``foo-set`` and 
``bar-set`` are defined as sets)::

        emerge foo-set glibc
        emerge bar-set system
        emerge world foo-set gcc

Compatibility With Other Portage Features
-----------------------------------------

* Dependencies:
  Package sets (both system-defined and user-defined) may not be
  depended on by ordinary packages and eclasses.
    
* package.mask:
  Masking a package set through the ``package.mask`` file is forbidden.
  In order to 'mask' a package set, one should move it away from the
  sets directory.

* package.use:
  USE flags may not be defined for sets in the ``package.use`` file.

Implementation
==============

The implementation of the package sets concept in Portage should be
mostly done in portage.py, and only the interface parts should be
added to emerge itself, to keep the separation between interface and
logic.

The amount of work needed for implementation is not trivial, but not
huge either.

Rationale
=========

The one file per set approach makes it easy to list the sets which are
defined on a system by just listing the ``/etc/portage/sets``
directory contents. Additionally, it makes the set lookup process more
efficient as it only requires to check if a file exists.

I chose the --package-set option over the --set option for explicitly
telling portage to emerge a set mostly because --set implies setting
an environment variable, or such.

Allowing sets' USE flags to be manipulated through the ``package.use``
file would have done more harm than good, for several reasons:

- If a USE flag is turned on (i.e. 'foo') for a set and the same USE
  flag is turned off (i.e. '-foo'), for a package which is part of
  the set, it is unclear which setting should take precedence.

- Similarly, if a USE flag is turned on for a set and the same USE flag
  is turned off for a set that is a subset of the original set, it is
  unclear which setting should take precedence.

- If a USE flag is defined (either off or on) for a set and a package
  that belongs in the set is to be emerged, it is unclear whether the
  USE flag should be defined when emerging the package in question.

Therefore, I have decided it would be better to disallow setting USE
flags for sets.

Backwards Compatibility
=======================

Backwards compatibility with the current situation, in which only two
system-defined sets exist can be kept in one of two ways:

1. Leaving the situation as is - the 'world' and 'system' sets are
   hard-coded in Portage.
2. Distributing default 'system' and 'world' files under the
   ``/etc/portage/sets/`` directory.

Other than that, there are no other backwards compatibility concerns
involved.

References
==========

.. [#NAME-RULES] Gentoo Linux Development Policy - Ebuild Policy
   (http://www.gentoo.org/doc/en/policy.xml#doc_chap3)
   
.. [#PORTAGE-MANPAGE]
   http://www.gentoo.org/cgi-bin/viewcvs.cgi/portage/man/portage.5?root=gentoo-src

Copyright
=========

This document has been placed in the public domain.
1	g2boojum	1.1	GLEP: 21
2			Title: User-defined Package Sets
3	genone	1.5	Version: $Revision: 1.4 $
4			Last-Modified: $Date: 2007/04/21 03:13:16 $
5	g2boojum	1.3	Author: Tal Peer <coredumb@gentoo.org>,
6			Alec Warner <antarus@gentoo.org>
7	antarus	1.4	Status: Deferred
8	g2boojum	1.1	Type: Standards Track
9			Discussed-To: gentoo-portage-dev@lists.gentoo.org
10			Content-Type: text/x-rst
11			Created: 22-Feb-2004
12	g2boojum	1.3	Post-History: 6-Mar-2004, 3-Sep-2006
13
14			Status
15			======
16
17	genone	1.5	Abandoned. Package set support has been added in portage-2.2, but it
18			doesn't match the description in this document in many cases, and the
19			document has several major gaps regarding the behavior and restrictions
20			of package sets.
21	g2boojum	1.1
22			Abstract
23			========
24
25			In Portage, package sets (formerly known as 'classes' or 'targets')
26			are mere groups of packages, grouped together to allow easier updating
27			and handling of them. Currently it is impossible to define sets further
28			than the two default ones: "system" and "world".
29
30			Motivation
31			==========
32
33			Over the months, quite a few requests for user-defined sets were
34			made by users and developers, either by posting bugs, messages to
35			mailing lists or on IRC. Usually the response is that this is an
36			awesome idea, but no one ever took the time to actually define it
37			properly and implement it.
38
39			This document offers a specification for the implementation of
40			user-defined sets using configuration files similar to the current
41			world/system sets use.
42
43			Specification
44			=============
45
46			The proposed implementation uses a one file per set approach, meaning
47			each package set is defined in a single file. All set definition files
48			will reside in a directory ``/etc/portage/sets/`` and each set's name
49			will be its file name. Therefore, if one defines a set in
50			/etc/portage/sets/foo-set, the set name will be 'foo-set'. Usual
51			package naming rules [#NAME-RULES]_ also apply to sets.
52
53			As it is impossible to create two or more files with identical names
54			in the same directory, a theoretic conflict between two different sets
55			sharing the same name is impossible. However, users may define a
56			package set whose name conflicts with one more or packages (for ambiguity
57			resolution, see below).
58
59			Syntax for the package list file is the same as the world file syntax,
60			as described in the Portage manpage [#PORTAGE-MANPAGE]_, with one
61			addition: sets may not be 'inherited' by other sets, only packages may
62			be listed. There is no limitation to the number of packages in a set
63			or to the number of sets a package may belong to.
64
65			Using User-defined Sets With Emerge
66			--------------------------------------
67
68			The user-defined sets will be available either directly or using
69			the --package-set option, As in::
70
71			# Basically the same:
72			emerge foo-set
73			emerge --package-set foo-set
74
75			The --package-set option is introduced to bypass ambiguities, as
76			illustrated in the next example::
77
78			emerge foo # Where foo is both a set and a one or more
79			# existing packages. This will cause emerge to show
80			# the ambiguity, ask us to be more
81			# specific, and stop.
82
83			emerge --package-set foo # So we specify that what we actually
84			# meant was the package set.
85
86			emerge cat-bar/foo # Or we specify the exact package name.
87
88			When running emerge with the --pretend option, sets will be
89			expanded to the packages they are comprised off in the output, as with
90			the current system-defined sets.
91
92			Only one set may be passed to portage at time, and sets can not
93			be mixed with ordinary packages. Thus, the following snippets are
94			all invalid and will result in an error (assuming ``foo-set`` and
95			``bar-set`` are defined as sets)::
96
97			emerge foo-set glibc
98			emerge bar-set system
99			emerge world foo-set gcc
100
101			Compatibility With Other Portage Features
102			-----------------------------------------
103
104			* Dependencies:
105			Package sets (both system-defined and user-defined) may not be
106			depended on by ordinary packages and eclasses.
107
108			* package.mask:
109			Masking a package set through the ``package.mask`` file is forbidden.
110	g2boojum	1.2	In order to 'mask' a package set, one should move it away from the
111			sets directory.
112	g2boojum	1.1
113			* package.use:
114			USE flags may not be defined for sets in the ``package.use`` file.
115
116			Implementation
117			==============
118
119			The implementation of the package sets concept in Portage should be
120			mostly done in portage.py, and only the interface parts should be
121			added to emerge itself, to keep the separation between interface and
122			logic.
123
124			The amount of work needed for implementation is not trivial, but not
125			huge either.
126
127			Rationale
128			=========
129
130			The one file per set approach makes it easy to list the sets which are
131			defined on a system by just listing the ``/etc/portage/sets``
132			directory contents. Additionally, it makes the set lookup process more
133			efficient as it only requires to check if a file exists.
134
135			I chose the --package-set option over the --set option for explicitly
136			telling portage to emerge a set mostly because --set implies setting
137			an environment variable, or such.
138
139			Allowing sets' USE flags to be manipulated through the ``package.use``
140			file would have done more harm than good, for several reasons:
141
142			- If a USE flag is turned on (i.e. 'foo') for a set and the same USE
143			flag is turned off (i.e. '-foo'), for a package which is part of
144			the set, it is unclear which setting should take precedence.
145
146			- Similarly, if a USE flag is turned on for a set and the same USE flag
147			is turned off for a set that is a subset of the original set, it is
148			unclear which setting should take precedence.
149
150			- If a USE flag is defined (either off or on) for a set and a package
151			that belongs in the set is to be emerged, it is unclear whether the
152			USE flag should be defined when emerging the package in question.
153
154			Therefore, I have decided it would be better to disallow setting USE
155			flags for sets.
156
157			Backwards Compatibility
158			=======================
159
160			Backwards compatibility with the current situation, in which only two
161			system-defined sets exist can be kept in one of two ways:
162
163			1. Leaving the situation as is - the 'world' and 'system' sets are
164			hard-coded in Portage.
165			2. Distributing default 'system' and 'world' files under the
166			``/etc/portage/sets/`` directory.
167
168			Other than that, there are no other backwards compatibility concerns
169			involved.
170
171			References
172			==========
173
174			.. [#NAME-RULES] Gentoo Linux Development Policy - Ebuild Policy
175			(http://www.gentoo.org/doc/en/policy.xml#doc_chap3)
176
177			.. [#PORTAGE-MANPAGE]
178			http://www.gentoo.org/cgi-bin/viewcvs.cgi/portage/man/portage.5?root=gentoo-src
179
180			Copyright
181			=========
182
183			This document has been placed in the public domain.