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
|
<?xml version="1.0" encoding="UTF-8"?>
<guide self="ebuild-writing/misc-files/patches/">
<chapter>
<title>Patches</title>
<body>
<p>
There is no fixed rule for patch naming. The following are guidelines
only.
</p>
<p>
Small patches (less than, say, a few KBytes) should be added to
<c>${FILESDIR}</c>. If you anticipate having several patches, it often
helps to create version numbered subdirectories <d/> <c>${FILESDIR}/${PV}/</c>
is conventional. Patches are best named <c>${P}-what-it-does.patch</c> (or
<c>.diff</c>), where <c>what-it-does</c> is a two or three word
description of what the patch is for. If the patch is to fix a
specific bug, it is often useful to add in the bug number <d/> for
example, <c>vim-7.0-cron-vars-79981.patch</c>. If the patch is pulled from
upstream's VCS repository, it can help to include the revision
number in the patch name as a suffix to the version part <d/>
<c>fluxbox-0.9.12-3860-menu-backups.patch</c>.
</p>
<p>
Larger patches should be
<uri link="::general-concepts/mirrors/#Suitable Download Hosts">
mirrored</uri>, preferably on the Gentoo Infrastructure. When
mirroring patches, choosing a name that will not cause conflicts is
important — the <c>${P}</c> prefix is highly recommended
here. Mirrored patches are often compressed with <c>xz</c> or
<c>bzip2</c>. Remember to list these patches in <c>SRC_URI</c>. Please
see <uri link="::ebuild-maintenance/new-ebuild/#The files Directory"/>
for more information.
</p>
<note>
Patches included in <c>${FILESDIR}</c> should never be compressed.
</note>
<warning>
Starting from EAPI=6, the patch strip level defaults to <c>-p1</c>.
Although it can be overridden with a <c>eapply -p<strip_level></c>
command, it is highly recommended to adapt the patch itself to work
with the <c>-p1</c> default.
</warning>
<p>
If a package requires many patches, even if they are individually
small, it is often best to create a patch tarball to avoid cluttering
up the tree too much.
</p>
</body>
<section>
<title>Patch descriptions</title>
<body>
<p>
It is possible to include a description with a patch. This is often
helpful when others come to work with your packages, or, indeed when
you come back to take a look at your own package a few months
later. Good things to include in comments are:
</p>
<ul>
<li>
What the patch actually does. Bug numbers are good here.
</li>
<li>
Where the patch came from. For example, is it from an upstream VCS,
something from Bugzilla, or something you wrote?
</li>
<li>
Whether the patch has been sent upstream, if applicable.
</li>
</ul>
<p>
To include the description, simply insert it at the top of the patch
file. The <c>patch</c> tool will ignore leading text until it finds
something that looks like it might be a 'start patching' instruction,
so as long as each description line starts with letters (rather than
numbers, symbols or whitespace) there shouldn't be a
problem. Alternatively, prefix each description line with a hash
(that's <c>#</c>, or 'pound' to the USians) sign. It's also best to
leave a single blank line after the description and before the main
patch.
</p>
<p>
Here's a simple example (<c>023_all_vim-6.3-apache-83565.patch</c>)
from the <c>vim</c> patch tarball:
</p>
<pre>
# Detect Gentoo apache files properly. Gentoo bug 83565.
--- a/runtime/filetype.vim
+++ b/runtime/filetype.vim
@@ -93,6 +93,9 @@
" Gentoo apache config file locations (Gentoo bug #76713)
au BufNewFile,BufRead /etc/apache2/conf/*/* setf apache
+" More Gentoo apache config file locations (Gentoo bug #83565)
+au BufNewFile,BufRead /etc/apache2/{modules,vhosts}.d/*.conf setf apache
+
" XA65 MOS6510 cross assembler
au BufNewFile,BufRead *.a65 setf a65
</pre>
</body>
</section>
<section>
<title>Conditional patching</title>
<body>
<p>
Patching is ideally only done to make the package in question build properly,
and should not be done to modify the runtime behaviour of the package. This is
what USE flags and features of the package are for. As such, it is preferable to
apply patches unconditionally and avoid conditional patching.
</p>
<p>
There are a number of reasons to avoid conditional patching:
</p>
<ul>
<li>
It may go unnoticed that a patch fails to apply, if a package is not being
tested with a given flag
</li>
<li>
More variance is introduced and problems with a package can become much more
difficult to debug
</li>
<li>
Patches should preferably be upstreamed, but conditional patches cannot
</li>
</ul>
<p>
Consider the following example <c>src_prepare()</c> implementation:
</p>
<codesample lang="ebuild">
src_prepare() {
if use threads; then
PATCHES+=( "${FILESDIR}"/${P}-mt.patch )
fi
default
}
</codesample>
<p>
As this patch is only applied when <c>USE="threads"</c> is set, any developer
creating new versions of this package might not detect whether the patch applies
successfully if they don't test with the same flag.
</p>
<p>
Although conditional patching is discouraged it can be unavoidable and as such,
it is not considered a banned practice, but, to the extent possible, patches
should be written such that they affect behaviour correctly based on e.g. build
time definitions and configuration options rather than USE flags directly. This
allows them to be applied unconditionally.
</p>
</body>
</section>
<section>
<title>Clean patch guide</title>
<body>
<p>
"Clean patch" does not refer to the patch itself (as in the changes it makes to
the source code). It refers to all the metadata that exists in the patch to
make it "maintainable".
</p>
</body>
<subsection>
<title>Why</title>
<body>
<p>
This may take more effort "up front", but the amount of effort that it saves
for everyone else in the future more than makes up for it. This refers to other
distributions or upstream maintainers who read the patch, or future Gentoo
maintainers. By keeping all patches "clean", people can quickly and easily
assess a patch without searching through many other files.
</p>
</body>
</subsection>
<subsection>
<title>File naming</title>
<body>
<p>
Your patch name should be short and to the point. When doing a file listing
(e.g., <c>ls files/</c>), it's a lot easier to be able to scan for relevant
patches when they have good keywords in their file names.
</p>
<p>
It should also include the package name and the version it was written against.
This way, people searching for patches or who happen to just stumble across the
file itself have a clue as to what it's for. Stripping out the <c>${PN}</c>
(and to a lesser extent, the <c>${PV}</c>) makes the filename significantly
less useful. The fact the files are typically stored in
<c>${CATEGORY}/${PN}/files/</c> is irrelevant, because the patch may be used
outside Gentoo.
</p>
</body>
</subsection>
<subsection>
<title>How</title>
<body>
<p>
Here's a check list of things to keep in the patch header:
</p>
<ul>
<li>
External references
<ul>
<li>Upstream mailing archives</li>
<li>Upstream bug reports</li>
<li>Upstream commit links</li>
<li>Upstream ChangeLog entries</li>
<li>Gentoo bug reports</li>
</ul>
</li>
<li>
Short/medium explanation
<ul>
<li>Why is the patch needed?</li>
<li>What is it fixing?</li>
<li>Why is it fixing it the way it is?</li>
<li>Proposal for better fixes in the future?</li>
<li>Is it a stop gap measure (workaround)?</li>
<li>How was it regression tested?</li>
<li>
Examples of before/after behaviour
<ul>
<li>How to reproduce bug without patch</li>
<li>How to show bug is fixed after patch</li>
<li>
Maybe upstream fixed it in a different way, so this test can be
used to show that the patch is no longer needed with newer versions
</li>
</ul>
</li>
</ul>
</li>
<li>
Status
<ul>
<li>Was it merged/rejected/postponed/etc. upstream?</li>
<li>Is it distribution-specific?</li>
</ul>
</li>
<li>
Attribution
<ul>
<li>Who found the bug?</li>
<li>Who fixed the bug?</li>
<li>Who wrote the patch?</li>
<li>Who tested the patch?</li>
<li>Who gave advice on the patch?</li>
</ul>
</li>
</ul>
<p>
All this information should be <e>in the patch itself</e>. It should never be
found in something like the ebuild. If you really want to put a comment next
to a patch in an ebuild, then this is about the only thing that is OK
(where 93671 is the Gentoo bug number):
</p>
<codesample lang="ebuild">
PATCHES=(
"${FILESDIR}"/${P}-dont-umask.patch #93671
)
</codesample>
<p>
When documenting these things, it might be useful to use RFC822/Git-style tags
to format the metadata. So when documenting the author, use:
</p>
<pre>
From: Nice Person <foo@cow.example.com>
</pre>
<p>
Or when documenting relevant URLs, use something like:
</p>
<pre>
Bug: https://upstream.example.com/12345
Bug: https://bugs.gentoo.org/9889
</pre>
<p>
And if you want to note your copyright signoff, slap on a Signed-off-by tag:
</p>
<pre>
Signed-off-by: Diligent Developer <larry@gentoo.org>
</pre>
<p>
Finally, your patch should be clear of useless cruft. If it was not taken
straight from an upstream SCM (<c>git format-patch</c> or <c>svn diff -r #</c>
or <c>cvs diff -r 1.123 -r 1.124</c>), then the metadata is useless. So delete
it. This refers to things like the diff command used to produce the patch,
or the timestamps on the files, local revision info, or other similar spam.
Note that the context info (the stuff that comes after the <c>@@</c>) should
be left, as that can be invaluable when applying patches to later versions.
For example:
</p>
<pre>
@@ -80,6 +82,7 @@ case $sys in
^^^^^^^^^^^^ keep this part
</pre>
<p>
Extra points if you make the filename in the <c>---</c>/<c>+++</c> section
consistent and sane. That is, remove different leading <c>backup/paths/</c>
and <c>.orig</c>/<c>.new</c> suffixes. Your patch should be in the <c>-p1</c>
format because this tends to be much more standard than any other <c>-p#</c>.
It is also what <c>eapply</c> understands by default. A good suggestion is to
use either <c>a/</c> and <c>b/</c> (as in <c>git format-patch</c>) or the
package name/version as the leading portion that gets stripped.
</p>
<p>
Also note that <c>patch</c> uses the timestamp info in order to remove empty
files automatically. Alternatively, you can specify the <c>-E</c> option with
<c>eapply</c> if you want to remove an empty file.
</p>
<p>
Removed lines should not appear in the patch because they are commented <d/>
just remove them entirely. Patches show removed lines by prefixing them with
a <c>-</c>, so no information is lost by simply deleting lines rather than
commenting them out (which adds noise). This makes the patch shorter and
more readable.
</p>
<p>
The following function (for your interactive shell, not for the ebuild) will
help deleting these things:
</p>
<codesample lang="ebuild">
scrub_patch() {
sed -i \
-e '/^index /d' \
-e '/^new file mode /d' \
-e '/^Index:/d' \
-e '/^=========/d' \
-e '/^RCS file:/d' \
-e '/^retrieving/d' \
-e '/^diff/d' \
-e '/^Files .* differ$/d' \
-e '/^Only in /d' \
-e '/^Common subdirectories/d' \
-e '/^deleted file mode [0-9]*$/d' \
-e '/^+++/s:\t.*::' \
-e '/^---/s:\t.*::' \
"$@"
}
scrub_patch some-patch-you-found.patch
</codesample>
</body>
</subsection>
<subsection>
<title>Examples</title>
<body>
<p>
This shows a simple explanation and a URL for more info (this patch could do
with some attribution however). No metadata exists from running the <c>diff</c>
command (timestamps, etc.).
</p>
<pre><!-- man-1.6d-fbsd.patch -->
Fixes compilation in FreeBSD.
https://bugs.gentoo.org/138123
--- man-1.6d/gencat/genlib.c
+++ man-1.6d/gencat/genlib.c
@@ -54,7 +54,7 @@
#include <unistd.h>
#endif
-#ifndef __linux__
+#if !defined(__linux__) && !defined(__FreeBSD__)
#include <memory.h>
static int bcopy(src, dst, length)
char *src, *dst;
</pre>
<pre><!-- util-linux-2.12q-dont-umask.patch -->
Don't force umask to 022 or the -o umask option doesn't work.
Patch by Daniel Drake.
https://bugs.gentoo.org/93671
--- mount/mount.c
+++ mount/mount.c
@@ -1491,8 +1491,6 @@ main(int argc, char *argv[]) {
if ((p = strrchr(progname, '/')) != NULL)
progname = p+1;
- umask(022);
-
/* People report that a mount called from init without console
writes error messages to /etc/mtab
Let us try to avoid getting fd's 0,1,2 */
</pre>
<pre><!-- iproute2-2.6.25.20080417-build.patch -->
Don't let target flags bleed into build flags.
Fix by Bertrand Jacquin.
https://bugs.gentoo.org/226035
--- netem/Makefile
+++ netem/Makefile
@@ -2,6 +2,7 @@ DISTGEN = maketable normal pareto paretonormal
DISTDATA = normal.dist pareto.dist paretonormal.dist experimental.dist
HOSTCC ?= $(CC)
+CCOPTS = $(CBUILD_CFLAGS)
LDLIBS += -lm
all: $(DISTGEN) $(DISTDATA)
</pre>
</body>
</subsection>
</section>
</chapter>
</guide>
|
GitWeb