1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
|
<?xml version="1.0" encoding="UTF-8"?>
<guide self="general-concepts/slotting/">
<chapter>
<title>Slotting</title>
<body>
<p>
Packages can support having multiple versions installed simultaneously. This is
useful for libraries which may have changed interfaces between versions <d/> for
example, the <c>gtk+</c> package can install both versions <c>2.24</c> and <c>3.6</c> in
parallel. This feature is called slotting.
</p>
<p>
Most packages have no need for slotting. These packages specify <c>SLOT="0"</c>
in the ebuilds. This is purely a convention; the package manager does not treat
<c>0</c> any different from other slot values.
</p>
<note>
<c>SLOT</c> is a mandatory variable and must not be empty.
</note>
<p>
Portage permits at most one instance of a package installation <e>per <c>SLOT</c>
value</e>. For example, say we have the following:
</p>
<ul>
<li><c>foo-1.1</c> with <c>SLOT="1"</c></li>
<li><c>foo-1.2</c> with <c>SLOT="1"</c></li>
<li><c>foo-2.0</c> with <c>SLOT="2"</c></li>
<li><c>foo-2.1</c> with <c>SLOT="2"</c></li>
</ul>
<p>
Then the user could have, say, <c>foo-1.2</c> and <c>foo-2.0</c> installed in
parallel, but <e>not</e> <c>foo-1.1</c> and <c>foo-1.2</c>. Note that it is entirely
possible that the user may have <c>foo-2.0</c> installed and no <c>foo-1.x</c> at all.
</p>
<p>
To <c>DEPEND</c> upon a package in a specific slot, refer to
<uri link="::general-concepts/dependencies/#SLOT dependencies"/>.
</p>
</body>
<section>
<title>Sub-slots</title>
<body>
<p>
Sometimes a package installs a library that changes interfaces between versions,
but it's undesirable or inconvenient to allow some of these versions to be installed
simultaneously. In <c>EAPI=5</c> and higher, this situation can be handled by
using sub-slots, which are delimited from the regular slot by a <c>/</c> character,
as in <c>SLOT="slot/subslot"</c>. Packages can
<uri link="::general-concepts/dependencies/#Slot operators">request to be
automatically rebuilt</uri> when the subslot of a runtime dependency changes.
</p>
<p>
If an ebuild does not explicitly declare a sub-slot, the regular slot is used
as the value of the sub-slot by default.
</p>
<p>
You may wish to review the
<uri link="https://wiki.gentoo.org/wiki/Project:Quality_Assurance/Subslots">
QA team's documentation on subslots</uri>.
</p>
<note>
Care must be taken when using sub-slots in a library ebuild for the first time.
Adding sub-slots will trigger rebuilds for all the packages that already use
slot-operator dependencies (e.g. switching from SLOT="0" to SLOT="0/14" in
<c>media-libs/libpng</c> and package <c>foo</c> depends on <c>libpng:0=</c>).
Therefore, it's best if you start using sub-slots in the library when the
existing library interface changes.
</note>
</body>
<subsection>
<title>ABI breakage</title>
<body>
<p>
There are two ways a library can break compatibility with its consumers.
</p>
<dl>
<dd>
ABI (Application Binary Interface): this affects binaries built before the
change. Applications linked against a library pre-ABI break may not work
correctly after the break. These changes are related to internal structure,
such as the size of a <c>struct</c> or the type of an argument (e.g.
integer width). Fixing this requires a <e>rebuild</e> of all consumers.
</dd>
<dd>
API (Application Programming Interface): this affects consumers at compile
time and usually occurs when a library has deprecated and then removed a
function. Fixing this requires a <e>code change</e> in consumers.
</dd>
</dl>
<p>
Note that subslots are not used exclusively for this purpose. While they form
the majority of uses in the Gentoo tree, subslots may have a meaning that
is completely divorced from SONAMEs or ABI breakage. Check the usage in the
relevant packages before using a subslot operator!
</p>
<p>
When made aware of ABI breakage, change the subslot. Note that the subslot does
not have to strictly be the SONAME and therefore could be an arbitrary string
(following naming rules).
</p>
<p>
Be aware that some upstreams may make releases without verifying if binary
compatibility has been broken in a minor release. You should check using
tools like <c>dev-util/libabigail</c> or <e>ABI Laboratory</e> (available
in Gentoo as <c>dev-util/abi-compliance-checker</c> if you prefer the non-web
version).
</p>
<p>
Generally, consumers <e>which link against</e> a library possessing a subslot
that <e>represents SONAME or binary compatibility</e> should subscribe to
it (request to be rebuilt when the subslot changes) with <c>:=</c>. Also, see
the QA Policy Guide for information on
<uri link="https://projects.gentoo.org/qa/policy-guide/dependencies.html#proactive-use-of-slot-operators">
proactively subscribing to subslots</uri> before they are defined.
</p>
</body>
<subsubsection>
<title>General naming of a sub-slot</title>
<body>
<p>
As a simple rule of thumb, the SONAME is usually a function of the library's
linking filename <c>libfoo.so</c> and its <b>first version component</b>.
The remaining version components are useful for ensuring a monotonic upgrade
path of consumers, but aren't incorporated into the library's SONAME, which in
this case would be <c>libfoo.so.1</c>.
</p>
<p>
The SONAME being incremented implies that the library's ABI has been broken.
</p>
<p>
As a result of the aforementioned convention, ebuilds usually expose the current
ABI version as the subslot. For this <e>libfoo</e> example, if the library is
<c>libfoo.so.1.2</c>, the ebuild might set:
</p>
<codesample lang="ebuild">
SLOT="0/1"
</codesample>
<p>
Further, suppose the package <c>foo</c> installs a library whose SONAME is
different for different versions. It would be reasonable to use the SONAME
version as the sub-slot name:
</p>
<ul>
<li><c>foo-1.1</c> installs <c>libfoo.so.5</c> <d/> <c>SLOT="1/5"</c></li>
<li><c>foo-1.2</c> installs <c>libfoo.so.6</c> <d/> <c>SLOT="1/6"</c></li>
<li><c>foo-2.0</c> installs <c>libfoo-2.so.0</c> <d/> <c>SLOT="2/0"</c></li>
<li><c>foo-2.1</c> installs <c>libfoo-2.so.1</c> <d/> <c>SLOT="2/1"</c></li>
</ul>
<p>
Other ebuilds that install binaries which link to <c>libfoo-2</c> (or <c>libfoo</c>)
can then request to be automatically rebuilt when the installed version of
<c>foo:2</c> or <c>foo:1</c> changes sub-slots <d/> for example, when the user
upgrades from <c>foo-2.0</c> to <c>foo-2.1</c>.
</p>
</body>
</subsubsection>
<subsubsection>
<title>Multiple libraries within a single package</title>
<body>
<p>
A package might need to install several libraries. The canonical example
of this is <c>media-video/ffmpeg</c>:
</p>
<codesample lang="ebuild">
# Subslot: <libavutil_major>.<libavcodec_major>.<libavformat_major>
# Since FFmpeg ships several libraries, subslot is kind of limited here.
# Most consumers will use those three libraries, if a "less used" library
# changes its soname, consumers will have to be rebuilt the old way
# (preserve-libs) - which should not be relied upon.
# If, for example, a package does not link to libavformat and only libavformat
# changes its ABI then this package will be rebuilt needlessly. Hence, such a
# package is free _not_ to := depend on FFmpeg but I would strongly encourage
# doing so since such a case is unlikely.
SLOT="0/56.58.58"
</codesample>
<p>
In such cases, make the subslot a composite of the major SONAMEs of each of
the installed libraries. This emphasises a point made above <d/> subslots do
not need to be equal to the exact SONAME of installed libraries, they only need
to represent in some way ABI compatibility.
</p>
</body>
</subsubsection>
</subsection>
</section>
<section>
<title>Slot names</title>
<body>
<p>
Current versions of Portage accept slot and sub-slot names that begin with an
alphanumeric character or <c>_</c>, and contain alphanumerics and <c>_</c>,
<c>-</c>, <c>.</c>, and <c>+</c> characters.
</p>
</body>
</section>
</chapter>
</guide>
|
GitWeb