chiark / gitweb /
- Completed Sec "Package with multiple patches",
authorhertzog <hertzog@313b444b-1b9f-4f58-a734-7bb04f332e8d>
Sat, 8 Jun 2002 20:29:29 +0000 (20:29 +0000)
committerhertzog <hertzog@313b444b-1b9f-4f58-a734-7bb04f332e8d>
Sat, 8 Jun 2002 20:29:29 +0000 (20:29 +0000)
  "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

common.ent
debian/changelog
developers-reference.sgml

index f96759e..1d34e0a 100644 (file)
 <!entity upload-queue "<ftppath>/pub/UploadQueue/</ftppath>">
 
 <!entity url-debian-policy "http://&www-debian-org;/doc/debian-policy/">
+<!entity url-perl-policy "http://&www-debian-org;/doc/packaging-manuals/perl-policy/">
+<!entity url-emacs-policy "http://&www-debian-org;/doc/packaging-manuals/debian-emacs-policy/">
+<!entity url-java-policy "http://people.debian.org/~opal/java/policy.html/">
+<!entity url-libpkg-guide "http://www.netfort.gr.jp/~dancer/column/libpkg-guide/">
 <!-- deprecate, this is dead
   <!entity url-pkg-manual "http://&www-debian-org;/doc/packaging-manuals/packaging.html/"> -->
 <!entity url-social-contract "http://&www-debian-org;/social_contract">
 <!entity file-bts-mailing "<file>/usr/share/doc/debian/bug-log-mailserver.txt</file>">
 <!entity file-bts-info "<file>/usr/share/doc/debian/bug-maint-info.txt</file>">
 <!entity file-bts-docs "<file>/usr/share/doc/debian/bug-*</file>">
+<!entity file-python-policy "<file>/usr/share/doc/python/python-policy.txt.gz</file>">
+<!entity file-ocaml-policy "<file>/usr/share/doc/ocaml/ocaml_packaging_policy.gz</file>">
 <!entity file-debian-private-archive "~debian/archive/debian-private/">
 
 <!entity cron-bug-report '0 17 * * fri   echo "index maint <var>address</var>" | mail request@bugs.debian.org'>
index 463858a..d9a282d 100644 (file)
@@ -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
index e794654..ba883c6 100644 (file)
@@ -6,7 +6,7 @@
   <!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 -->
   <!--
@@ -2595,20 +2595,51 @@ You can however decide to not use any helper script, and still write
 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>
@@ -2618,38 +2649,65 @@ at <url id="&url-rules-files;">.
     <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,
@@ -2662,7 +2720,7 @@ at <url id="&url-rules-files;">.
        on a database server but just on the corresponding library.
 
        sympa may be an example package
-       
+-->    
 
     <sect id="misc-advice">
        <heading>Miscellaenous advice</heading>