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
|
<?xml version="1.0" encoding="UTF-8"?>
<guide self="ebuild-maintenance/package-moves/">
<chapter>
<title>Package and Slot Moves</title>
<body>
<p>
This chapter describes the use of package and slot moves. The package update
mechanism is a powerful tool, and needs to be used with caution. In particular,
the following must be noted:
</p>
<ol>
<li>
<uri link="::profiles/updates/">Updates</uri> are <e>not one-shot</e>
operations and they are not stateful. All updates can be reapplied multiple
times to the same system, and all old updates are applied to fresh Gentoo
installations.
</li>
<li>
Once an update entry is created, the old package name (or slot) cannot be
reused for another package. Attempting to reuse it will cause updates to
apply again, to the reused name. This also means that while a package can
be moved back to its previous name, all the names historically used for
a package are reserved to it alone.
</li>
<li>
Updates can only perform one-to-one moves. They cannot be used to merge
packages. Attempting to move two or more packages into a single name may
cause serious problems for users.
</li>
</ol>
</body>
<section>
<title>Moving or renaming a package</title>
<body>
<p>
Moving or renaming a package (sometimes called a "pkgmove" or just "move")
requires several operations. Firstly, verify that the ebuilds will continue to
work correctly after the move. If the category changes, you must verify all
<c>${CATEGORY}</c> uses. If the package name changes, you must verify
<c>${PN}</c>, <c>${P}</c>, etc. Whenever the old value is necessary,
substitute the variable reference with the verbatim text, so that it won't get
affected by the move. Commit the changes separately before moving
the package.
</p>
<p>
Afterwards, move the package files using <c>git mv</c>. Add the move entry
to <c>profiles/updates/</c> in the following format:
</p>
<pre>
move old-category/old-name new-category/new-name
</pre>
<p>
Following the update entry, find all references to the old package name
and update them. These include:
</p>
<ul>
<li>
<uri link="::general-concepts/dependencies/">dependencies</uri>,
<c>optfeature.eclass</c> uses, <c>has_version</c> and <c>best_version</c>
uses in other ebuilds and eclasses
</li>
<li>
all <c>profiles/</c> tree entries (e.g. <c>profiles/package.mask</c>)
</li>
<li>
<c>restrict</c> entries in package <c>metadata.xml</c> files, as well
as <c><pkg/></c> tags
</li>
<li>
news item <c>Display-If-Installed</c>
</li>
<li>
open bug summaries
</li>
<li>
wiki pages
</li>
</ul>
<p>
Preferably, combine all those changes into a single commit to ensure atomicity
during the update.
</p>
</body>
</section>
<section>
<title>Changing ebuild's SLOT</title>
<body>
<p>
The process for changing the ebuild's <c>SLOT</c> (a "slotmove") is very similar to the
previous process. Besides changing the <c>SLOT</c> in the ebuild file, you
also need to create a new entry in <c>profiles/updates/</c> in
the Gentoo repository in the following format:
</p>
<pre>
slotmove app-text/gtkspell 0 2
</pre>
<p>
Make sure that you have fixed all the reverse dependencies and that
you have updated every file in <c>profiles/</c> directory that
happens to contain an entry which may be affected by your change.
</p>
</body>
</section>
<section>
<title>Updating prior update entries when moving the package again</title>
<body>
<p>
When the same package is moved again, the previous update entries should
be updated appropriately. This is meant to make the situation more transparent
to users reading update entries and to ensure that the process is handled
efficiently even if the package manager does not implement updates in a robust
way. This involves the following steps:
</p>
<ol>
<li>
The previous package moves for the package in question must be updated
to reference the final name. That is, rather than the chain A → B → C,
we want to have two update entries: A → C, and B → C.
</li>
<li>
If the package is being moved to a name that it used before, the original
move entry must be removed. That is, rather than the chain A → B → A,
we want to have the reverse entry: B → A. If the package manager did not
move A → B before, we don't want it to touch the package at all.
</li>
<li>
As a combination of the two aforementioned steps, a chain of A → B → C → A
would be replaced by two moves: B → A, and C → A.
</li>
<li>
If the package was slot-moved before, the slot moves should be updated
to use the final package name, and moved after the final package move.
That is, rather than the chain: A:S<sub>1</sub> → A:S<sub>2</sub>, A → B;
we prefer to have the chain: A → B, B:S<sub>1</sub> → B:S<sub>2</sub>.
All package and slot move entries must reside in the same file then, to
guarantee sequential processing.
</li>
</ol>
</body>
</section>
</chapter>
</guide>
|
GitWeb