<!entity % commondata SYSTEM "common.ent" > %commondata;
<!-- CVS revision of this document -->
- <!entity cvs-rev "$Revision: 1.108 $">
+ <!entity cvs-rev "$Revision: 1.109 $">
<!-- if you are translating this document, please notate the CVS
revision of the developers reference here -->
<!--
some very good <file>rules</file> file. Many examples are available
at <url id="&url-rules-files;">.
+<!--
<sect1 id="pkg-mgmt-cvs">Managing a package with CVS
<p>
&FIXME; presentation of cvs-buildpackage, updating sources
via CVS (debian/rules refresh).
+-->
<sect1 id="multiple-patches">Package with multiple patches
<p>
- &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 <file>.diff.gz</file> 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).
+ <p>
+The good solution is to keep separate patches within the
+<file>debian/patches</file> directory and to apply them on the fly at
+build time. The package <package>dbs</package> provides an
+implementation of such a system, you just have to build-depend on dbs to
+be able to use its functionnalities. The package
+<package>hello-dbs</package> is a simple example that demonstrates how to
+use <package>dbs</package>.
+ <p>
+Additionnaly, dbs provides facilities to create the patches and to keep
+track of what they are for.
<sect1 id="multiple-binary">Multiple binary packages
<p>
- &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).
+ <p>
+The second case can be easily managed by <prgn>dh_install</prgn> (from
+<package>debhelper</package>) to move files from the build directory to
+the package's temporary trees.
+ <p>
+The first case is a bit more difficult since it involves multiple recompiles
+of the same software but with different configure options. The
+<package>vim</package> is an example of how to manage this with an
+hand crafted rules file.
+<!-- &FIXME; Find a good debhelper example with multile configure/make
+ cycles -->
<sect1 id="handling-debconf-translations">Handling debconf translations
<p>
<sect id="specific-practices">
<heading>Specific packaging practices</heading>
+<!--
<sect1 id="bpp-kernel">Kernel modules/patches
<p>
&FIXME; Heavy use of kernel-package. provide files in
/etc/modutils/ for module configuration.
-
+-->
+
<sect1 id="bpp-libraries">Libraries
<p>
- &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...
+ <p>
+Good practices for library packaging have been grouped in
+<url id="&url-libpkg-guide;" name="the library packaging guide">.
<sect1 id="bpp-other-specific-practices">Other specific packages
<p>
- &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 :
+<list>
+ <item>
+Perl related packages have a <url name="perl policy" id="&url-perl-policy;">,
+some examples of packages following that policy are
+<package>libdbd-pg-perl</package> (binary perl module) or
+<package>libmldbm-perl</package> (arch independent perl module).
+ <item>
+Python related packages have their python policy :
+&file-python-policy; (in the python package).
+ <item>
+Emacs related packages have the <url id="&url-emacs-policy;"
+name="emacs policy">.
+ <item>
+Java related packages have their <url id="&url-java-policy;"
+name="java policy">.
+ <item>
+Ocaml related packages have their ocaml policy : &file-ocaml-policy; (in
+the ocaml package). A good example is the <package>camlzip</package>
+source package.
+</list>
<sect id="config-mgmt">
<heading>Configuration management</heading>
<sect1 id="config-wise-debconf">The wise use of debconf
<p>
- &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.
+ <p>
+Debconf is a great tool but it is often badly used ... many common mistakes
+are listed in the <manref name="debconf-devel" section="8"> manpage.
+It is something that you must have read if you decide to use debconf.
+<!--
<sect1 id="custom-config-files">Custom configuration files
<p>
&FIXME; speak of "ucf", explain solution with a template,
on a database server but just on the corresponding library.
sympa may be an example package
-
+-->
<sect id="misc-advice">
<heading>Miscellaenous advice</heading>
~ianmdlvl / developers-reference.git / commitdiff