From: hertzog Date: Sat, 8 Jun 2002 20:29:29 +0000 (+0000) Subject: - Completed Sec "Package with multiple patches", X-Git-Url: http://www.chiark.greenend.org.uk/ucgi/~ianmdlvl/git?p=developers-reference.git;a=commitdiff_plain;h=e4285cf6103cd328a1f5485f3e6db2a88a2605a2 - Completed Sec "Package with multiple patches", "Multiple binary packages", "Libraries", "Other specific packages", "The wise use of debconf". All those are quite simplistic, they can be improved ... git-svn-id: svn://anonscm.debian.org/ddp/manuals/trunk/developers-reference@1708 313b444b-1b9f-4f58-a734-7bb04f332e8d --- diff --git a/common.ent b/common.ent index f96759e..1d34e0a 100644 --- a/common.ent +++ b/common.ent @@ -39,6 +39,10 @@ /pub/UploadQueue/"> + + + + @@ -132,6 +136,8 @@ /usr/share/doc/debian/bug-log-mailserver.txt"> /usr/share/doc/debian/bug-maint-info.txt"> /usr/share/doc/debian/bug-*"> +/usr/share/doc/python/python-policy.txt.gz"> +/usr/share/doc/ocaml/ocaml_packaging_policy.gz"> address" | mail request@bugs.debian.org'> diff --git a/debian/changelog b/debian/changelog index 463858a..d9a282d 100644 --- a/debian/changelog +++ b/debian/changelog @@ -99,6 +99,10 @@ developers-reference (3.0) unstable; urgency=low "Being kind to porter" too. - Extended Sec "devscripts" with info about "bts" and "uscan". - Completed Sec "Helper scripts". + - Completed Sec "Package with multiple patches", + "Multiple binary packages", "Libraries", "Other specific packages", + "The wise use of debconf". All those are quite simplistic, they + can be improved ... * Antoine Hulin: - update French translation diff --git a/developers-reference.sgml b/developers-reference.sgml index e794654..ba883c6 100644 --- a/developers-reference.sgml +++ b/developers-reference.sgml @@ -6,7 +6,7 @@ %commondata; - + Package with multiple patches

- &FIXME; presentation of "dbs", example package: hello-dbs +Big packages tend to have many upstream bugs that you want to fix within +the Debian package. If you just correct the bug in the source, all the +fixes are directly integrated in the .diff.gz file and you +can't easily differentiate the various patches that you applied. It gets +very messy when you have to update the package to a new upstream version +which integrates some of the fixes (but not all). +

+The good solution is to keep separate patches within the +debian/patches directory and to apply them on the fly at +build time. The package dbs provides an +implementation of such a system, you just have to build-depend on dbs to +be able to use its functionnalities. The package +hello-dbs is a simple example that demonstrates how to +use dbs. +

+Additionnaly, dbs provides facilities to create the patches and to keep +track of what they are for. Multiple binary packages

- &FIXME; dh_install, example of packages with multiple - configure/make cycles - Example packages: vim (custom system) +A single source package will often build several binary packages, either +to provide several flavors of the same software (examples are the +vim-* packages) or to make several small packages instead of a big one +(it's interesting if the user doesn't need all the packages and can thus +save some diskspace). +

+The second case can be easily managed by dh_install (from +debhelper) to move files from the build directory to +the package's temporary trees. +

+The first case is a bit more difficult since it involves multiple recompiles +of the same software but with different configure options. The +vim is an example of how to manage this with an +hand crafted rules file. + Handling debconf translations

@@ -2618,38 +2649,65 @@ at . Specific packaging practices + + Libraries

- &FIXME; http://www.netfort.gr.jp/~dancer/column/libpkg-guide/ +Libraries are always difficult to package for various reasons. The policy +imposes many constraints to ease their maintenance and to make sure +upgrades are as simple as possible when a new upstream version comes out. +A breakage in a library can result in dozens of dependent packages to +break... +

+Good practices for library packaging have been grouped in +. Other specific packages

- &FIXME; perl, python, ocaml, java, emacs. - ocaml: - /usr/share/doc/ocaml/ocaml_packaging_policy.gz - a good example are packages libzip-ocaml{,-dev} - perl: - http://www.debian.org/doc/packaging-manuals/perl-policy/ - libdbd-pg-perl binary package, libmldbm-perl arch all package - emacs: - http://www.debian.org/doc/packaging-manuals/debian-emacs-policy - java: - http://people.debian.org/~opal/java/policy.html/ - python: - /usr/share/doc/python/python-policy.txt.gz in python package +Several subsets of packages have special subpolicies and corresponding +packaging rules and practices : + + +Perl related packages have a , +some examples of packages following that policy are +libdbd-pg-perl (binary perl module) or +libmldbm-perl (arch independent perl module). + +Python related packages have their python policy : +&file-python-policy; (in the python package). + +Emacs related packages have the . + +Java related packages have their . + +Ocaml related packages have their ocaml policy : &file-ocaml-policy; (in +the ocaml package). A good example is the camlzip +source package. + Configuration management The wise use of debconf

- &FIXME; debconf-devel(8) is a MUST read +Debconf is a configuration management system, it is used by all the +various packaging scripts (postinst mainly) to request feedback from the +user in the intent to configure the package. Direct user interactions +must now be avoided in favor of debconf interaction. This will enable +non-interactive installations in the future. +

+Debconf is a great tool but it is often badly used ... many common mistakes +are listed in the manpage. +It is something that you must have read if you decide to use debconf. + Miscellaenous advice