From 260e873d2a43fbdd75bdfa4bc6f7d6b7a109a47c Mon Sep 17 00:00:00 2001
From: Russ Allbery <rra@debian.org>
Date: Mon, 3 Dec 2007 01:56:10 +0000
Subject: [PATCH] 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
---
 debian/changelog         |  2 ++
 policy.sgml              | 43 ++++++++++++++++++++++++++++++++++------
 upgrading-checklist.html |  4 ++++
 3 files changed, 43 insertions(+), 6 deletions(-)

diff --git a/debian/changelog b/debian/changelog
index c0e88af..0a6f506 100644
--- 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 5412107..702247f 100644
--- 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 4fec738..24378fb 100644
--- 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]
-- 
2.39.2