debdiff and dpkg-depcheck, closes: #172897

git-svn-id: svn://anonscm.debian.org/ddp/manuals/trunk/developers-reference@2156 313b444b-1b9f-4f58-a734-7bb04f332e8d

diff --git a/debian/changelog b/debian/changelog
index b6a9212e09ff7e7dbbbab97d2ee75818bf448308..a7a69fb3ac90549cdc6d7c71d620c9d92c44b7fd 100644 (file)
--- a/debian/changelog
+++ b/debian/changelog
@@ -12,6 +12,8 @@ developers-reference (3.3) unstable; urgency=low
       architecture-independent data bundled with programs
     - added best practices on debian/changelog files, based on a patch
       kindly provided by Daniel Kobras, closes: #166388.
+    - described debdiff and dpkg-depcheck, and linked to them from the
+      right places in the document, closes: #172897.
   * Adam Di Carlo:
     - update (c) year
     - convert to debhelper (compat mode 4); maintainer scripts no longer

diff --git a/developers-reference.sgml b/developers-reference.sgml
index 55daee1b4fb1e84155c4a4100d2ad11cb5cb9b79..07cc7af3b37b9c351e465de252049262df5896bc 100644 (file)
--- a/developers-reference.sgml
+++ b/developers-reference.sgml
@@ -6,7 +6,7 @@
   <!entity % commondata  SYSTEM "common.ent" > %commondata;
 
   <!-- CVS revision of this document -->
-  <!entity cvs-rev "$Revision: 1.172 $">
+  <!entity cvs-rev "$Revision: 1.173 $">
   <!-- if you are translating this document, please notate the CVS
        revision of the developers reference here -->
   <!--
@@ -1483,6 +1483,9 @@ to emit errors (they will start with <tt>E</tt>).
                <p>
 For more information on <prgn>lintian</prgn>, see <ref id="lintian">.
              <item>
+Optionally run <ref id="debdiff"> to analyze changes from an older version,
+if one exists.
+             <item>
 Downgrade the package to the previous version (if one exists) &mdash; this
 tests the <file>postrm</file> and <file>prerm</file> scripts.
              <item>
@@ -2140,9 +2143,9 @@ fix can break seemingly unrelated features in subtle ways.
 Review and test your changes as much as possible.  Check the
 differences from the previous version repeatedly
 (<prgn>interdiff</prgn> from the <package>patchutils</package> package
-and <prgn>debdiff</prgn> from <package>devscripts</package> are useful tools for
-this).
-
+and <prgn>debdiff</prgn> from <package>devscripts</package> are useful
+tools for this, see <ref id="debdiff">).
+<p>
 When packaging the fix, keep the following points in mind:
 
 <list>
@@ -2421,13 +2424,17 @@ Make sure that your <tt>Build-Depends</tt> and
 <tt>Build-Depends-Indep</tt> settings in <file>debian/control</file>
 are set properly.  The best way to validate this is to use the
 <package>debootstrap</package> package to create an unstable chroot
-environment.  Within that chrooted environment, install the
+environment (see <ref id="debootstrap">).
+Within that chrooted environment, install the
 <package>build-essential</package> package and any package
 dependencies mentioned in <tt>Build-Depends</tt> and/or
 <tt>Build-Depends-Indep</tt>.  Finally, try building your package
 within that chrooted environment.  These steps can be automated
 by the use of the <prgn>pbuilder</prgn> program which is provided by
-the package of the same name.
+the package of the same name (see <ref id="pbuilder">).
+               <p>
+If you can't set up a proper chroot, <prgn>dpkg-depcheck</prgn> may be
+of assistance (see <ref id="dpkg-depcheck">).
                <p>
 See the <url id="&url-debian-policy;" name="Debian Policy
 Manual"> for instructions on setting build dependencies.
@@ -3897,8 +3904,33 @@ packages at <url id="&url-lintian;">. Those reports contain the latest
 <package>lintian</package> but has a different set of checks.  Its
 written in Python rather than Perl.</p>
         </sect1>
+
+        <sect1 id="debdiff">
+          <heading><package>debdiff</package></heading>
+          <p>
+<prgn>debdiff</prgn> (from the <package>devscripts</package> package)
+compares file lists and control files of two packages. It is a simple
+regression test, as it will help you notice if the number of binary
+packages has changed since the last upload, or if something's changed
+in the control file. Of course, some of the changes it reports will be
+all right, but it can help you prevent various accidents.
+         <p>
+You can run it over a pair of binary packages:
+<example>
+debdiff package_1-1_arch.deb package_2-1_arch.deb
+</example>
+         <p>
+Or even a pair of changes files:
+<example>
+debdiff package_1-1_arch.changes package_2-1_arch.changes
+</example>
+         <p>
+For more information please see <manref name="debdiff" section="1">.
+        </sect1>
+
       </sect>
 
+
       <sect id="tools-helpers">
         <heading>Helpers for <file>debian/rules</file></heading>
        <p>
@@ -4147,6 +4179,29 @@ directory of your package.  For instance, when editing
 <file>debian/changelog</file>, there are handy functions for
 finalizing a version and listing the package's current bugs.</p>
         </sect1>
+
+        <sect1 id="dpkg-depcheck">
+          <heading><package>dpkg-depcheck</package></heading>
+          <p>
+<prgn>dpkg-depcheck</prgn> (from the <package>devscripts</package> package)
+runs a command under <prgn>strace</prgn> to determine all the packages that
+were used by the said command.
+         <p>
+For Debian packages, this is useful when you have to compose a
+<tt>Build-Depends</tt> line for your new package: running the build
+process through <prgn>dpkg-depcheck</prgn> will provide you with a
+good first approximation of the build-dependencies. For example:
+<example>
+dpkg-depcheck -b debian/rules build
+</example>
+         <p>
+<prgn>dpkg-depcheck</prgn> can also be used to check for run-time
+dependencies, especially if your package uses exec(2) to run other
+programs.
+         <p>
+For more information please see <manref name="dpkg-depcheck" section="1">.
+        </sect1>
+
       </sect>