aboutsummaryrefslogtreecommitdiff
blob: 0de2f6d08ecff43c951b6b5eb7a79b7055723839 (plain)
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
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
<?xml version="1.0"?>
<guide self="ebuild-maintenance/maintenance-tasks/">
<chapter>
<title>Maintenance Tasks</title>

<body>
<p>
This guide aims to explain common everyday ebuild maintenance
routines, as well as other rarer maintenance routines which
developers may not be familiar with.
</p>
</body>

<section>
<title>Adding a new ebuild</title>

<subsection>
<title>What (not) to put in the Gentoo repository</title>
<body>

<p>
Before writing a new ebuild, check
<uri link="https://bugs.gentoo.org/">bugs.gentoo.org</uri>
to see if an ebuild has already been written for the package, but has not yet
been added to the Gentoo repository.  Go to <uri
link="https://bugs.gentoo.org/">bugs.gentoo.org</uri>, choose query and select
Advanced Search; as product select <e>Gentoo Linux</e>, as component select
<e>ebuilds</e>.  In the search field put the name of the ebuild and as status
select all possible fields, then submit the query. For you lazy people, click
<uri link="https://bugs.gentoo.org/query.cgi?format=advanced&amp;product=Gentoo%20Linux&amp;component=New%20Ebuilds&amp;bug_Status=UNCONFIRMED&amp;bug_status=CONFIRMED&amp;bug_status=IN_PROGRESS&amp;bug_status=RESOLVED&amp;bug_status=VERIFIED">here</uri>.
</p>

<p>
In general, the Gentoo repository should only be used for storing
<c>.ebuild</c> files, as well as any relatively small companion
files, such as patches or sample configuration files. These types of
files should be placed in the <c>mycat/mypkg/files</c> directory
to keep the main <c>mycat/mypkg</c> directory uncluttered.
Exceptions to this rule are for larger patch files (we recommend this
for patches above 20KB) which should be distributed as tarballs via the
<uri link="::general-concepts/mirrors/#Suitable Download Hosts">Gentoo
mirror system</uri> so that people do not waste excessive amounts of
bandwidth and hard drive space. Also, you should not add binary
(non-ASCII) files to the git tree. Also, speaking of merging changes,
any patches you add to Portage should generally <e>not</e> be
compressed. This will allow git to merge changes and correctly inform
developers of conflicts.
</p>

<p>
Remember, the packages that you commit must be <e>ready</e> <e>out of the
box</e> for end users when committed as stable.  Make sure that you have a good
set of default settings that will satisfy the majority of systems and
users that will use your package.  If your package is broken, and you are
not sure how to get it to work, check some other distributions that have
done their own versions of the package.  You can check
<uri link="https://www.debian.org/distrib/packages">Debian</uri> or
<uri link="https://src.fedoraproject.org/projects/rpms/*">Fedora</uri> for some
examples.
</p>

<p>
When committing to git, all developers should use <c>repoman commit</c>
instead of <c>git commit</c> to submit their ebuilds.  Before committing,
please run <c>repoman full</c> to make sure you didn't forget something.
</p>

</body>
</subsection>

<subsection>
<title>Initial Architecture Keywords</title>
<body>
<p>
When adding a new ebuild, you should only include <c>KEYWORDS</c> for
architectures on which you have actually tested the ebuild, confirming
that it works as it should and that <c>USE</c> flags are properly
honoured in the resulting package which would be installed. If
possible, you should give the actual library or application thorough
testing as well, since you would be responsible for any breakages for
your architecture(s). Minimal testing such as checking that the
application starts up without any errors should always be performed.
</p>

<p>
If you are adding a user-submitted ebuild, do not assume that the
submitter has done testing on various architectures: often, <c>KEYWORDS</c>
are cloned across packages or generated from documentation in the
source packages, which does not signify that the package does indeed
work on those architectures.
</p>

</body>
</subsection>

<subsection>
<title>The files Directory</title>
<body>

<p>
As noted earlier, under each package subdirectory is
a <c>files/</c> directory. Any patches, configuration files, or
other ancillary files your package might require should be added to
this directory; any files bigger than 20KB-or-so should go to the
mirrors to lower the amount of (unneeded) files our users have to
download. You may want to consider naming patches you create yourself
just to get your package to build with a version-specific name, such
as <c>mypkg-1.0-gentoo.diff</c>, or more
simply, <c>1.0-gentoo.diff</c>.  Also note that the
<c>gentoo</c> extension informs people that this patch was created
by us, the Gentoo Linux developers, rather than having been grabbed from a
mailing list or somewhere else. Again, you should not compress these
patches.
</p>

<p>
Consider prefixing or suffixing (such as <c>mypkg-1.0</c>) every file
you put into the <c>files/</c> directory, so that the files used for
each individual version on an ebuild are distinguishable from one another, and
so that the changes between different revisions are visible.  This is generally
a really good idea :).  You may want to use a different suffix if you wish to
convey more meaning with the patch name.
</p>

<p>
If you have many files that should go into the <c>files/</c> directory,
consider creating subdirectories such as <c>files/1.0/</c> and putting the
relevant files in the appropriate subdirectory.  If you use this method,
you do not need to add version information to the names of the files,
which is often more convenient.
</p>

</body>
</subsection>
</section>

<section>
<title>Stabilizing ebuilds</title>
<body>

<p>
Only architecture maintainers for a given architecture should mark packages as
stable on that architecture. The maintainer of the package should always be
contacted just in case there are reasons not to do so. The exception to this
is if you are part of an architecture team, in which case you may mark the
package stable for that architecture. If you are not part of an architecture
team, you should consult the guidelines below; if the architecture you are
looking for is not listed then please consult the relevant lead.
</p>

<p>
You should <e>never</e> stabilize packages on architectures for which you
cannot test and instead you should file a bug to the relevant architecture
team, such as <c>sparc@gentoo.org</c> asking them to stabilize the ebuild.
Alternatively, you may be able to find Gentoo developers on IRC who could help
you with your request.
</p>

<p>
It is best to not use <c>arch-maintainers@gentoo.org</c>, adding architecture
teams onto a bug's CC list individually instead. That way teams can remove
themselves from the list when they are done, giving a clear indication
of which teams still have to stabilize a package.
</p>

</body>
</section>

<section>
<title>Stabilization rules</title>
<body>

<p>
SPARC: You must have prior permission from the arch lead. Usually we expect
you to be on the sparc alias for QA reasons, although other arrangements
can be made if you will only be working with a small group of packages.
</p>

<p>
ALPHA: Maintainers may keyword their own packages but are reminded to inform
the Alpha team if they can help out with testing and keywording packages so
the team can keep an eye out for possible keywording mistakes.
</p>

<p>
Exotic architectures (like alpha, ia64, sparc, hppa, ppc*) are short
on manpower, so it's best if you avoid opening stabilization bugs for
them unless it is absolutely necessary (eg, a reverse dependency for
your package). More about keywording policies can be found in the
<uri link="::keywording">keywording</uri> section.
</p>
<p>
Some architectures (like m68k, mips, s390, sh) do not maintain a
stable keyword. So there is no use in marking a package stable for one
of these architectures.
</p>
</body>
</section>

<section>
<title>Upgrading ebuilds</title>
<body>

<p>
New ebuilds should rarely go in with "<c>arch</c>" keywords and even if they do
not, the package <e>must</e> be tested on any architectures listed in the
<c>KEYWORDS</c> variable of the new ebuild.
</p>

<p>
Exceptions to the no "<c>arch</c>" rule are major bug fixes, or
security fixes. If the previous version of the ebuild
contains <c>KEYWORDS</c> which you cannot test for, you should
downgrade them: turn any "<c>arch</c>" keyword to "<c>~arch</c>". If you
think that your package may not work at all even on "<c>~arch</c>"
then it is best to leave the keyword out and request testing from the
relevant team: if you are to do this, you must file a bug to the team
in question.
</p>

<p>
If a new version introduces new dependencies which are not available
on some architectures, then you should file a bug or ask on IRC before
you upgrade the package. If you really need to get the ebuild added in
a hurry, for example, for a security fix, then you should drop
any <c>KEYWORDS</c> which are causing problems and CC the relevant
architectures on the bug <d/> you should file a new bug to the
architecture in question regarding this if no bug is already
available.
</p>

<p>
If there are no new dependencies, do not remove keywords if your
commit fails with repoman <d/> please try a full <c>git pull</c> and if
you still have problems, then commit with <c>repoman -I</c> and file a
bug to the broken architecture, noting it in your git commit message.
</p>

<warning>
When committing, make sure that you reference any bugs in the
commit message. Failing to do so is considered
to be in very poor taste and may result in disciplinary action.
</warning>

</body>
</section>

<section>
<title>Moving a package</title>
<body>

<p>
Moving a package in the tree requires several operations. Firstly,
the package directory needs to be moved to the correct category
using <c>git mv</c>. After this, a new entry needs to be added to
the latest file in <c>profiles/updates/</c> in the
following format:
</p>

<pre>
move old-category/package-name new-category/package-name
</pre>

<p>
Following the update entry, ebuilds that have a
<uri link="::general-concepts/dependencies">dependency</uri>
to this package (in other words, the reverse dependencies of
the package to be moved) need to be updated properly.
</p>

<p>
Next is checking the files under <c>profiles/</c> such as
<c>profiles/package.mask</c> and update them to reflect the ebuild
move. Various eclasses automatically provide some of the dependencies upon
inherit, so the files under <c>eclass/</c> should be checked and updated
properly. If the package metadata.xml has tags with <c>restrict</c>
attribute, they should be updated to reflect the move. The
metadata.xml for various packages may contain references to the
package being moved using the <c>&lt;pkg&gt;</c> tag which need to be
updated accordingly as well. Lastly, the titles of the open bugs
related to the package should be updated.
</p>

<p>
Here is an example where the package
<c>net-misc/fwbuilder</c> is transparently moved to
<c>net-firewall/fwbuilder</c>:
</p>

<ol>
  <li>Issue <c>git mv net-misc/fwbuilder net-firewall/fwbuilder</c></li>
  <li>
    <p>
      Add the following entry to the latest file in
      <c>profile/updates/</c>:
    </p>
    <p><c>move net-misc/fwbuilder net-firewall/fwbuilder</c></p>
  </li>
  <li>Update the reverse dependencies of the package</li>
  <li>
    Update <c>profiles/package.mask</c> and other related files under
    <c>profiles/</c>
  </li>
  <li>Check the eclasses that may be referencing the package</li>
  <li>
    Update all the
    <uri link="::ebuild-writing/misc-files/metadata">metadata.xml</uri>
    files which contain a reference to this package using the
    <c>&lt;pkg&gt;</c> tag or the <c>restrict</c> attribute.
  </li>
  <li>
    Stage all the changed files using <c>git add</c>. For example: <c>git add
    profiles/package.mask</c>
  </li>
  <li>
    Commit all the changes in one commit using: <c>git commit --gpg-sign --signoff</c>
  </li>
  <li>
    Update any <uri link="::general-concepts/news">news items</uri>
    referencing the package in a <c>Display-If-Installed</c> header
    or in the item's body (and increment their <c>Revision</c>).
  </li>
  <li>Update any open bugs related to the package</li>
</ol>

<p>
It is very important to commit all the changes in a single commit to ensure
that no breakage occurs. The commit message should follow a format similar
to the following:
</p>

<pre>
commit 7a699bcdce5c1412c02a2aa7717a31bc17c49058
Author: Miroslav Šulc &lt;fordfrog@gentoo.org&gt;
Date:   Wed Dec 18 19:56:03 2019 +0100

  media-libs/libclxclient: moved to x11-libs/libclxclient

  Signed-off-by: Miroslav Šulc &lt;fordfrog@gentoo.org&gt;
</pre>

</body>
</section>

<section>
<title>Changing ebuild's SLOT</title>
<body>
<p>
The process for changing the ebuild's SLOT is very similar to the
previous process.  Besides changing the SLOT 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>Removing ebuilds</title>
<body>

<p>
When removing an ebuild make sure that no dependencies in Portage are broken
due to the removal <d/> additionally, your git commit message should explain
clearly why the ebuild is being removed from the git repository.
</p>

<p>
If you need to remove ebuilds, make sure you do not accidentally remove
the newest/only stable ebuild for any architecture. If you would like to
get a newer version marked stable, then please file a bug or ask on IRC.
</p>

<p>
You should also not cause an unnecessary downgrade for any "<c>~arch</c>"
when removing ebuilds <d/> instead, it is best to get the newest version
marked "<c>~arch</c>" first and then remove redundant versions of the ebuild.
</p>

</body>
</section>

<section>
<title>Removing a package</title>
<body>

<p>
When removing packages follow these steps:
</p>

<ol>
  <li>
    Make sure that no dependencies in the Gentoo repository are broken due to
    the removal
  </li>
  <li>Send last rites to gentoo-dev-announce and gentoo-dev</li>
  <li>Mask the package</li>
  <li>Wait 30 days (or more)</li>
  <li>Remove from the git tree unless the reason for removal has been fixed</li>
  <li>
    Remove any references to the package from other ebuilds, e.g.,
    use-conditional dependencies. Blockers are the only exception to this.
  </li>
  <li>Remove package.mask and any package.use.mask entries</li>
  <li>
    Remove the <c>&lt;pkg&gt;</c> tags referencing this package in the
    <uri link="::ebuild-writing/misc-files/metadata">metadata.xml</uri>
    files of other packages.
  </li>
  <li>Close open bugs as WONTFIX</li>
</ol>

<p>
Here is a list of commands that will delete <c>dev-util/pmk</c>
from the tree:
</p>

<pre>
# cd dev-qt
# git rm -rf qtphonon
# git commit --gpg-sign
</pre>

<p>
An example commit message is shown below:
</p>

<pre>
commit b97eb6d43f45dfd5b739638928db22d3f3392685
Author: Michael Palimaka &lt;kensington@gentoo.org&gt;
Date:   Tue Oct 3 21:43:03 2017 +1100

  dev-qt/qtphonon: remove last rited package

  Closes: https://bugs.gentoo.org/629144
</pre>

</body>
</section>

<section>
<title>Conflicting files</title>
<body>

<p>
When you encounter a package that is trying to install files that are
already provided by another package (detectable with
<c>FEATURES=collision-protect</c> for example) you have to fix this
situation before you can commit the ebuild or, if you encounter this
with an existing package, file a bug about that package (see below for
a few exceptions). The reason file conflicts are critical is because
if "foo" provides the file <c>/usr/bin/example</c> and "bar" is
going to overwrite it, and later "bar" is unmerged, Portage will remove
<c>/usr/bin/example</c> and it is therefore likely it will break
"foo".
</p>

<p>
The most obvious fix is to add a blocking dependency to both packages
that want to install that file, so they can't be installed at the same
time. But unless there are also other reasons for those packages to
block each other you should avoid this if possible and rather fix the
package, which could include one or more of the following steps:
</p>

<ul>
  <li>Make "foo" (R)DEPEND on "bar" and not install the conflicting
  file.</li>
  <li>Remove conflicting files from "foo" in <c>src_install</c>
  or <c>pkg_preinst</c>.</li>
  <li>Move conflicting files into a new subpackage and make "foo" and
  "bar" both (R)DEPEND on that package.</li>
  <li>Change the location where "foo" or "bar" installs conflicting
  files.</li>
</ul>

<p>
In some cases conflicting files can't be really fixed or aren't
critical, currently known exceptions are Perl module manpages
(overwriting the ones from Perl itself) and <c>CONFIG_PROTECT</c>'ed
files (which should still be fixed, but aren't critical as Portage
won't overwrite them).
</p>

</body>
</section>

<section>
<title>Homepage unavailable</title>
<body>

<p>
If the <c>HOMEPAGE</c> of your package seems to be unavailable or it
never existed at all, please set the HOMEPAGE variable in every ebuild
to <uri link="https://wiki.gentoo.org/wiki/No_homepage">
https://wiki.gentoo.org/wiki/No_homepage</uri>
</p>

</body>
</section>
</chapter>
</guide>