diff options
Diffstat (limited to 'ebuild-writing/misc-files/patches/text.xml')
| -rw-r--r-- | ebuild-writing/misc-files/patches/text.xml | 104 |
1 files changed, 104 insertions, 0 deletions
diff --git a/ebuild-writing/misc-files/patches/text.xml b/ebuild-writing/misc-files/patches/text.xml new file mode 100644 index 0000000..905b514 --- /dev/null +++ b/ebuild-writing/misc-files/patches/text.xml @@ -0,0 +1,104 @@ +<?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 CVS / SVN 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 mirrored. 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 CVS/SVN 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> +</body> +</chapter> +</guide> |