X-Git-Url: http://www.chiark.greenend.org.uk/ucgi/~ianmdlvl/git?p=developers-reference.git;a=blobdiff_plain;f=best-pkging-practices.dbk;h=32d5115f885ef7133b7b27c8a5a2e3d6f37e432d;hp=ab10d0337d92bc5cace050243f0e1f6ff4f594ac;hb=f67750abdac139d21380c34ca0ba540e09e03153;hpb=df930334712cc8854f9bf5b374140a9aa9a66f80 diff --git a/best-pkging-practices.dbk b/best-pkging-practices.dbk index ab10d03..32d5115 100644 --- a/best-pkging-practices.dbk +++ b/best-pkging-practices.dbk @@ -96,18 +96,24 @@ diffs (e.g., from .diff.gz) and work out which patch sets to back out as a unit as bugs are fixed upstream. -Unfortunately, the packaging system as such currently doesn't provide for -separating the patches into several files. Nevertheless, there are ways to -separate patches: the patch files are shipped within the Debian patch file -(.diff.gz), usually within the -debian/ directory. The only difference is that they -aren't applied immediately by dpkg-source, -but by the build -rule of debian/rules, -through a dependency on the patch rule. -Conversely, they are reverted in -the clean rule, -through a dependency on the unpatch rule. +Fortunately, with the source format “3.0 (quilt)” it is now possible to +keep patches separate without having to modify debian/rules +to setup a patch system. Patches are stored in debian/patches/ +and when the source package is unpacked patches listed in +debian/patches/series are automatically applied. +As the name implies, patches can be managed with quilt. + + +When using the older source “1.0”, it's also possible to separate patches +but a dedicated patch system must be used: the patch files are shipped +within the Debian patch file (.diff.gz), usually +within the debian/ directory. The only difference is +that they aren't applied immediately by dpkg-source, +but by the build rule of +debian/rules, through a dependency on the +patch rule. Conversely, they are reverted in the +clean rule, through a dependency on the +unpatch rule. quilt is the recommended tool for this. @@ -1484,6 +1490,20 @@ role="package">doc-base on installation. See the doc-base package documentation for more information. + +Debian policy (section 12.1) directs that manual pages should accompany every +program, utility, and function, and suggests them for other objects like +configuration files. If the work you are packaging does not have such manual +pages, consider writing them for inclusion in your package, and submitting them +upstream. + + +The manpages do not need to be written directly in the troff format. Popular +source formats are Docbook, POD and reST, which can be converted using +xsltproc, pod2man and +rst2man respectively. To a lesser extent, the +help2manprogram can also be used to write a stub. +
@@ -1647,7 +1667,7 @@ upstream source. Pristine source The defining characteristic of a pristine source tarball is that the -.orig.tar.gz file is byte-for-byte identical to a tarball officially +.orig.tar.{gz,bz2} file is byte-for-byte identical to a tarball officially distributed by the upstream author. We cannot prevent upstream authors from changing the tarball they distribute without also incrementing the version number, so there can be no guarantee that a pristine @@ -1657,7 +1677,7 @@ identical to something that upstream once did distribute. If a difference arises later (say, if upstream notices that he wasn't using maximal compression in his original distribution and then re-gzips it), that's just too bad. Since there is no good -way to upload a new .orig.tar.gz for the same version, there is not even any +way to upload a new .orig.tar.{gz,bz2} for the same version, there is not even any point in treating this situation as a bug. This makes it possible to use checksums to easily verify that all changes between Debian's version and upstream's are contained in the Debian diff. Also, if the original @@ -1711,11 +1731,11 @@ gzipped tar at all, or if upstream's tarball contains non-DFSG-free material that you must remove before uploading. -In these cases the developer must construct a suitable .orig.tar.gz +In these cases the developer must construct a suitable .orig.tar.{gz,bz2} file himself. We refer to such a tarball as a repackaged upstream source. Note that a repackaged upstream source is different from a Debian-native package. A repackaged source still comes with Debian-specific -changes in a separate .diff.gz and still has a version +changes in a separate .diff.gz or .debian.tar.{gz,bz2} and still has a version number composed of <upstream-version> and <debian-revision>. @@ -1729,14 +1749,14 @@ archive. Use your own discretion here, but be prepared to defend your decision if you repackage source that could have been pristine. -A repackaged .orig.tar.gz +A repackaged .orig.tar.{gz,bz2} -must be documented in the resulting source package. +should be documented in the resulting source package. Detailed information on how the repackaged source was obtained, -and on how this can be reproduced must be provided in +and on how this can be reproduced should be provided in debian/copyright. It is also a good idea to provide a get-orig-source target in your debian/rules file that repeats the process, as described @@ -1752,8 +1772,7 @@ come from the upstream author(s), or whose contents has been changed by you. As a special exception, if the omission of non-free files would lead to the source failing to build without assistance from the Debian diff, it might be appropriate to instead edit the files, omitting only the -non-free parts of them, and/or explain the situation in a README.Debian-source - +non-free parts of them, and/or explain the situation in a README.source file in the root of the source tree. But in that case please also urge the upstream author to make the non-free components easier seperable from the rest of the source. @@ -1785,47 +1804,24 @@ distinguish pristine tarballs from repackaged ones. -should be gzipped with maximal compression. +should be gzipped or bzipped with maximal compression. - -The canonical way to meet the latter two points is to let dpkg-source --b construct the repackaged tarball from an unpacked directory. -
-Changing binary files in <literal>diff.gz</literal> +Changing binary files Sometimes it is necessary to change binary files contained in the original -tarball, or to add binary files that are not in it. If this is done by simply -copying the files into the debianized source tree, -dpkg-source will not be able to handle this. On the other -hand, according to the guidelines given above, you cannot include such a -changed binary file in a repackaged orig.tar.gz. Instead, -include the file in the debian directory in -uuencoded (or similar) form The file should -have a name that makes it clear which binary file it encodes. Usually, some -postfix indicating the encoding should be appended to the original filename. -Note that you don't need to depend on sharutils to get the uudecode -program if you use perl's pack function. -The code could look like - -&example-uu; -. The file would then be -decoded and copied to its place during the build process. Thus the change will -be visible quite easy. - - -Some packages use dbs to manage patches to their upstream -source, and always create a new orig.tar.gz file that -contains the real orig.tar.gz in its toplevel directory. -This is questionable with respect to the preference for pristine source. On -the other hand, it is easy to modify or add binary files in this case: Just put -them into the newly created orig.tar.gz file, besides the -real one, and copy them to the right place during the build process. +tarball, or to add binary files that are not in it. This is fully supported +when using source packages in “3.0 (quilt)” format, see the +dpkg-source1 +manual page for details. When using the older format “1.0”, binary files +can't be stored in the .diff.gz so you must store +an uuencoded (or similar) version of the file(s) +and decode it at build time in debian/rules (and move +it in its official location).