1 |
GLEP: 21 |
2 |
Title: User-defined Package Sets |
3 |
Version: $Revision: 1.5 $ |
4 |
Last-Modified: $Date: 2007/10/21 11:42:57 $ |
5 |
Author: Tal Peer <coredumb@gentoo.org>, |
6 |
Alec Warner <antarus@gentoo.org> |
7 |
Status: Final |
8 |
Type: Standards Track |
9 |
Discussed-To: gentoo-portage-dev@lists.gentoo.org |
10 |
Content-Type: text/x-rst |
11 |
Created: 22-Feb-2004 |
12 |
Post-History: 6-Mar-2004, 3-Sep-2006 |
13 |
|
14 |
Status |
15 |
====== |
16 |
|
17 |
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 |
|
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 |
In order to 'mask' a package set, one should move it away from the |
111 |
sets directory. |
112 |
|
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. |
184 |
|