X-Git-Url: http://www.chiark.greenend.org.uk/ucgi/~ianmdlvl/git?a=blobdiff_plain;ds=sidebyside;f=best-pkging-practices.dbk;h=ca1bfb38ffe1ee40eb9538d01e66b17c364f11ab;hb=6af79112dbb3da2664c2e5d4a17daed580b074b6;hp=63b7f87c44284a764154b18c8d440ce5e4c2e8f6;hpb=24edeec3ea3aef827fc6c23b59bafec1f5343593;p=developers-reference.git diff --git a/best-pkging-practices.dbk b/best-pkging-practices.dbk index 63b7f87..ca1bfb3 100644 --- a/best-pkging-practices.dbk +++ b/best-pkging-practices.dbk @@ -1,11 +1,13 @@ + "http://www.oasis-open.org/docbook/xml/4.4/docbookx.dtd" [ + %commondata; +]> Best Packaging Practices Debian's quality is largely due to the Debian Policy, which +url="&url-debian-policy;">Debian Policy, which defines explicit baseline requirements which all Debian packages must fulfill. Yet there is also a shared history of experience which goes beyond the Debian Policy, an accumulation of years of experience in packaging. Many very @@ -78,7 +80,7 @@ Some people feel that vanilla debian/rules files are better, since you don't have to learn the intricacies of any helper system. This decision is completely up to you. Use what works for you. Many examples of vanilla debian/rules files are available at . +url="&url-rules-files;">. @@ -153,7 +155,7 @@ this using an hand-crafted debian/rules file. The following practices are relevant to the debian/control file. They supplement the Policy +url="&url-debian-policy;ch-binary.html#s-descriptions">Policy on package descriptions. @@ -201,8 +203,7 @@ Postscript or postscript. If you are having problems writing your description, you may wish to send it -along to debian-l10n-english@lists.debian.org and request -feedback. +along to &email-debian-l10n-english; and request feedback. @@ -278,10 +279,10 @@ it. Both ispell and aspell have special modes for checking debian/control files: - -d american -g debian/control +ispell -d american -g debian/control - -d en -D -c debian/control +aspell -d en -D -c debian/control Users usually expect these questions to be answered in the package description: @@ -341,7 +342,7 @@ added at the end of description, using the following format: Note the spaces prepending the line, which serves to break the lines correctly. To see an example of how this displays, see . +url="&url-eg-desc-upstream-info;">. If there is no home page for the software, this should naturally be left out. @@ -349,11 +350,11 @@ If there is no home page for the software, this should naturally be left out. Note that we expect this field will eventually be replaced by a proper debian/control field understood by dpkg -and packages.debian.org. If you don't want to bother +and &packages-host;. If you don't want to bother migrating the home page from the description to this field, you should probably wait until that is available. Please make sure that this line matches the regular expression /^ Homepage: [^ ]*$/, as this allows -packages.debian.org to parse it correctly. +&packages-host; to parse it correctly. @@ -427,7 +428,7 @@ the URL is in the svn:// scheme (instead of Best practices for <filename>debian/changelog</filename> The following practices supplement the Policy +url="&url-debian-policy;ch-docs.html#s-changelogs">Policy on changelog files.
@@ -582,7 +583,7 @@ as it will not be automatically checked during build as the changelog is. Here is an example of a real NEWS.Debian file: - (3.0pl1-74) unstable; urgency=low +cron (3.0pl1-74) unstable; urgency=low The checksecurity script is no longer included with the cron package: it now has its own package, checksecurity. If you liked the @@ -613,7 +614,7 @@ NEWS.Debian file in your package. No news is good news! FIXME: presentation of cvs-buildpackage, updating sources via CVS (debian/rules refresh). -"http://www.debian.org/devel/cvs_packages" +"&url-devel-docs;cvs_packages"
--> @@ -626,7 +627,7 @@ Maintainer scripts include the files debian/postinst, debian/postrm. These scripts take care of any package installation or deinstallation setup which isn't handled merely by the creation or removal of files and directories. The following instructions supplement the -Debian Policy. +Debian Policy. Maintainer scripts must be idempotent. That means that you need to make sure @@ -661,27 +662,12 @@ maintainer script. If you need to check for the existence of a command, you should use something like - - [ -x /usr/sbin/install-docs ]; then ... - +if [ -x /usr/sbin/install-docs ]; then ... If you don't wish to hard-code the path of a command in your maintainer script, the following POSIX-compliant shell function may help: - -() { - OLDIFS=$IFS - IFS=: - for p in $PATH; do - if [ -x $p/$* ]; then - IFS=$OLDIFS - return 0 - fi - done - IFS=$OLDIFS - return 1 -} - +&example-pathfind; You can use this function to search $PATH for a command name, passed as an argument. It returns true (zero) if the command was found, @@ -753,8 +739,8 @@ Most Debian package maintainers are not native English speakers. So, writing properly phrased templates may not be easy for them. -Please use (and abuse) debian-l10n-english@lists.debian.org -mailing list. Have your templates proofread. +Please use (and abuse) &email-debian-l10n-english; mailing +list. Have your templates proofread. Badly written templates give a poor image of your package, of your work...or @@ -796,15 +782,15 @@ translations and request them for updates. If in doubt, you may also contact the translation team for a given language -(debian-l10n-xxxxx@lists.debian.org), or the -debian-i18n@lists.debian.org mailing list. +(debian-l10n-xxxxx@&lists-host;), or the +&email-debian-i18n; mailing list. -Calls for translations posted to debian-i18n@lists.debian.org -with the debian/po/templates.pot file attached or -referenced in a URL are encouraged. Be sure to mentions in these calls for new -translations which languages you have existing translations for, in order to -avoid duplicate work. +Calls for translations posted to &email-debian-i18n; with the +debian/po/templates.pot file attached or referenced in a +URL are encouraged. Be sure to mentions in these calls for new translations +which languages you have existing translations for, in order to avoid duplicate +work. @@ -831,10 +817,8 @@ Put all incomplete PO files out of the way. You can check the completeness by using (needs the gettext package installed): - - i in debian/po/*po; do echo -n $i: ; msgfmt -o /dev/null ---statistics $i; done - +for i in debian/po/*po; do echo -n $i: ; msgfmt -o /dev/null +--statistics $i; done @@ -860,9 +844,7 @@ modified in translations. You can see this by running the above again use the following command: - - i in debian/po/*po; do msgattrib --output-file=$i --clear-fuzzy $i; done - +for i in debian/po/*po; do msgattrib --output-file=$i --clear-fuzzy $i; done @@ -1206,7 +1188,7 @@ using English. Example, taken from the geneweb package templates: -: geneweb/lang +Template: geneweb/lang Type: select __Choices: Afrikaans (af), Bulgarian (bg), Catalan (ca), Chinese (zh), Czech (cs), Danish (da), Dutch (nl), English (en), Esperanto (eo), Estonian (et), Finnish (fi), French (fr), German (de), Hebrew (he), Icelandic (is), Italian (it), Latvian (lv), Norwegian (no), Polish (pl), Portuguese (pt), Romanian (ro), Russian (ru), Spanish (es), Swedish (sv) # This is the default choice. Translators may put their own language here @@ -1300,13 +1282,12 @@ differences between two versions of the documentation, so, for instance, they can see what needs to be retranslated. It is recommended that the translated documentation maintain a note about what source control revision the translation is based on. An interesting system is provided by doc-check in the boot-floppies package, which shows an overview of -the translation status for any given language, using structured comments for -the current revision of the file to be translated and, for a translated file, -the revision of the original file the translation is based on. You might wish -to adapt and provide that in your CVS area. +url="&url-i18n-doc-check;">doc-check in the +boot-floppies package, which shows an +overview of the translation status for any given language, using structured +comments for the current revision of the file to be translated and, for a +translated file, the revision of the original file the translation is based on. +You might wish to adapt and provide that in your CVS area. If you maintain XML or SGML documentation, we suggest that you isolate any @@ -1337,7 +1318,7 @@ Keeping autoconf's config.sub and especially on more volatile architectures. Some very good packaging practices for any package using autoconf and/or automake have been synthesized in -/usr/share/doc/autotools-dev/README.Debian.gz from the +&file-bpp-autotools; from the autotools-dev package. You're strongly encouraged to read this file and to follow the given recommendations. @@ -1353,7 +1334,7 @@ library can result in dozens of dependent packages breaking. Good practices for library packaging have been grouped in the library +url="&url-libpkg-guide;">the library packaging guide. @@ -1362,7 +1343,7 @@ packaging guide. Documentation Be sure to follow the Policy on +url="&url-debian-policy;ch-docs.html">Policy on documentation. @@ -1395,7 +1376,7 @@ packaging rules and practices: Perl related packages have a Perl +url="&url-perl-policy;">Perl policy, some examples of packages following that policy are libdbd-pg-perl (binary perl module) or libmldbm-perl (arch independent perl module). @@ -1404,30 +1385,30 @@ role="package">libmldbm-perl (arch independent perl module). Python related packages have their python policy; see -/usr/share/doc/python/python-policy.txt.gz in the -python package. +&file-python-policy; in the python package. Emacs related packages have the emacs +url="&url-emacs-policy;">emacs policy. Java related packages have their java +url="&url-java-policy;">java policy. Ocaml related packages have their own policy, found in -/usr/share/doc/ocaml/ocaml_packaging_policy.gz from the -ocaml package. A good example is the -camlzip source package. +&file-ocaml-policy; from the ocaml package. A good example is the camlzip source package. @@ -1440,7 +1421,7 @@ in the sgml-base-doc package. Lisp packages should register themselves with common-lisp-controller, about which see -/usr/share/doc/common-lisp-controller/README.packaging. +&file-lisp-controller;. @@ -1495,12 +1476,12 @@ If you need a certain locale during build, you can create a temporary file via this trick: -If you set LOCPATH to the equivalent of /usr/lib/locale, and LC_ALL to the name +If you set LOCPATH to the equivalent of /usr/lib/locale, and LC_ALL to the name of the locale you generate, you should get what you want without being root. Something like this: -=debian/tmpdir/usr/lib/locale +LOCALE_PATH=debian/tmpdir/usr/lib/locale LOCALE_NAME=en_IN LOCALE_CHARSET=UTF-8 @@ -1530,18 +1511,8 @@ description. So, when you are creating such a package, please make sure to add this text to your short description. If you are looking for examples, just run: - - --cache search .|grep dummy - - -or - - --cache search .|grep transitional - - -. +apt-cache search .|grep dummy or +apt-cache search .|grep transitional. @@ -1585,7 +1556,7 @@ tarballs as pristine source. Its strategy is equivalent to the following: It unpacks the tarball in an empty temporary directory by doing - path/to/<packagename>_<upstream-version>.orig.tar.gz | tar xf - +zcat path/to/<packagename>_<upstream-version>.orig.tar.gz | tar xf - @@ -1648,7 +1619,7 @@ repackaged source was obtained, and how this can be reproduced in the get-orig-source target in your debian/rules file that repeats the process, as described in the Policy Manual, Main +url="&url-debian-policy;ch-source.html#s-debianrules">Main building script: debian/rules. @@ -1718,9 +1689,10 @@ 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 -file: perl -ne 'print(pack u, $$_);' -$(file) > $(file).uuencoded uudecode-file: perl -ne 'print(unpack u, $$_);' -$(file).uuencoded > $(file) . The file would then be +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. @@ -1788,7 +1760,7 @@ Note that the Debian package should depend on the package that it provides debugging symbols for, and this dependency should be versioned. For example: -: libfoo-dbg (= ${binary:Version}) +Depends: libfoo-dbg (= ${binary:Version})