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
|
<?xml version="1.0"?>
<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>,
preferrable 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>bzip2</c>. Remember to list these patches in
<c>SRC_URI</c>.
</p>
<note>
Patches included in <c>${FILESDIR}</c> should never be compressed.
</note>
<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>
<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. Is it an upstream VCS pull,
something from Bugzilla, 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.
--- runtime/filetype.vim.orig 2005-03-25 01:44:12.000000000 +0000
+++ runtime/filetype.vim 2005-03-25 01:45:15.000000000 +0000
@@ -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>Adding Patches to the tree</title>
<body>
<p>
When adding a patch to the tree be sure to check that the patch doesn't have
Git keywords in it that will be expanded (such as <c>$Id$</c>). If the patch
contains these, it will break manifests unless you add it to the tree
correctly. In the case that it does have the keywords, you should remove them.
Afterwards they can be added like every other file:
</p>
<pre>
git add files/${P}-the-cool-patch.patch
</pre>
</body>
</section>
</body>
</chapter>
</guide>
|
GitWeb