Document the type field in shlibs and its use with udebs

The shlibs file syntax now supports an optional type field specifying
the type of packages to which the line applies.  Currently, the only
supported type is udeb.  Include documentation of the syntax, the use
with udeb, and an example.  Based on a patch from Frans Pop with input
from Raphael Hertzog.

git-archimport-id: rra@debian.org--lenny/debian-policy--devel--3.7--patch-15

diff --git a/debian/changelog b/debian/changelog
index c0e88af8e0d72f12c5f122226bcdffce94d370f6..0a6f506835035b81e68c494c6fb9c182a0535986 100644 (file)
--- a/debian/changelog
+++ b/debian/changelog
@@ -26,6 +26,8 @@ debian-policy (3.7.3.0) UNRELEASED; urgency=low
   * Bug fix: "822-date is deprecated (use date -R instead)"  (Closes: #448035).
   * Bug fix: "5.6.17 (Urgency) should list emergency, maybe a normative
     list?"                                                   (Closes: #412634).
+  * Bug fix: "[PROPOSAL] Document support of package types in shlibs
+    files", thanks to Franz Pop and Raphaël Hertzog          (Closes: #363133).
   
  --
 

diff --git a/policy.sgml b/policy.sgml
index 5412107098c982e42af77335b6151a5ec2deade0..702247f051d95e58427da708f51fa9eb06a904e9 100644 (file)
--- a/policy.sgml
+++ b/policy.sgml
@@ -4957,6 +4957,19 @@ dpkg-shlibdeps debian/tmp/usr/bin/* debian/tmp/usr/sbin/* \
          utilities to specify a different <file>substvars</file> file.
        </p>
 
+       <p>
+         If you are creating a udeb for use in the Debian Installer, you
+         will need to specify that <prgn>dpkg-shlibdeps</prgn> should use
+         the dependency line of type <tt>udeb</tt> by adding
+         <tt>-tudeb</tt> as option<footnote>
+             <prgn>dh_shlibdeps</prgn> from the <tt>debhelper</tt> suite
+             will automatically add this option if it knows it is
+             processing a udeb.
+         </footnote>. If there is no dependency line of type <tt>udeb</tt>
+         in the <file>shlibs</file> file, <prgn>dpkg-shlibdeps</prgn> will
+         fall back to the regular dependency line.
+       </p>
+
        <p>
          For more details on dpkg-shlibdeps, please see
          <ref id="pkg-dpkg-shlibdeps"> and
@@ -4972,7 +4985,7 @@ dpkg-shlibdeps debian/tmp/usr/bin/* debian/tmp/usr/sbin/* \
          beginning with <tt>#</tt> are considered to be comments and
          are ignored.  Each line is of the form:
          <example compact="compact">
-<var>library-name</var> <var>soname-version-number</var> <var>dependencies ...</var>
+[<var>type</var>: ]<var>library-name</var> <var>soname-version</var> <var>dependencies ...</var>
          </example>
        </p>
 
@@ -4982,6 +4995,13 @@ dpkg-shlibdeps debian/tmp/usr/bin/* debian/tmp/usr/sbin/* \
          installs the shared library <file>/usr/lib/libz.so.1.1.3</file>.
        </p>
 
+       <p>
+         <var>type</var> is an optional element that indicates the type
+         of package for which the line is valid. The only type currently
+         in use is <tt>udeb</tt>. The colon and space after the type are
+         required.
+       </p>
+
        <p>
          <var>library-name</var> is the name of the shared library,
          in this case <tt>libz</tt>.  (This must match the name part
@@ -4989,10 +5009,10 @@ dpkg-shlibdeps debian/tmp/usr/bin/* debian/tmp/usr/sbin/* \
        </p>
 
        <p>
-         <var>soname-version-number</var> is the version part of the
-         soname of the library.  The soname is the thing that must
-         exactly match for the library to be recognized by the
-         dynamic linker, and is usually of the form
+         <var>soname-version</var> is the version part of the soname of
+         the library.  The soname is the thing that must exactly match
+         for the library to be recognized by the dynamic linker, and is
+         usually of the form
          <tt><var>name</var>.so.<var>major-version</var></tt>, in our
          example, <tt>libz.so.1</tt>.<footnote>
              This can be determined using the command
@@ -5024,6 +5044,14 @@ libz 1 zlib1g (>= 1:1.1.3)
          the dynamic linker about using older shared libraries with
          newer binaries.
        </p>
+
+       <p>
+         As zlib1g also provides a udeb containing the shared library,
+         there would also be a second line:
+         <example compact="compact">
+udeb: libz 1 zlib1g-udeb (>= 1:1.1.3)
+         </example>
+       </p>
       </sect1>
 
       <sect1>
@@ -5048,7 +5076,10 @@ install -m644 debian/shlibs.<var>package</var> debian/<var>package</var>/DEBIAN/
          <file>debian/rules</file> without using a <file>debian/shlibs</file>
          file at all,<footnote>
              This is what <prgn>dh_makeshlibs</prgn> in the
-             <tt>debhelper</tt> suite does.
+             <tt>debhelper</tt> suite does. If your package also has a udeb
+             that provides a shared library, <prgn>dh_makeshlibs</prgn> can
+             automatically generate the <tt>udeb:</tt> lines if you specify
+             the name of the udeb with the <tt>--add-udeb</tt> option.
          </footnote>
          since the <file>debian/shlibs</file> file itself is ignored by
          <prgn>dpkg-shlibdeps</prgn>.

diff --git a/upgrading-checklist.html b/upgrading-checklist.html
index 4fec7388bbfda722dba242002dc20d9204452013..24378fbfa078d6812ab4b1c67762777b35f44d70 100644 (file)
--- a/upgrading-checklist.html
+++ b/upgrading-checklist.html
@@ -70,6 +70,10 @@ picking your way through this list.
        in parentheses.                                           [5.6.1]
      * The acceptable values for the Urgency field are low, medium, high,
        critical, or emergency.                                   [5.6.17]
+     * The shlibs file now allows an optional type field, indicating the
+       type of package for which the line is valid.  The only currently
+       supported type is udeb, used with packages for the Debian
+       Installer.                                                [8.6]
 3.7.2.2                        Oct 2006
      * Maintainer scripts must not be world writeable (up from a
        should to a must)                                         [6.1]