Clarify support file handling for shared libraries

Combine the discussion of run-time support files for shared libraries
in a renamed section.  Be explicit that shared library packages may not
contain any file whose name does not change when the soname changes,
and be clearer about when files should be put into versioned directories
in the shared library package and when files should go into a separate
package.  Files useful only when compiling against the library should
go into the -devel package (and other run-time support programs should
not).

Suggest -tools instead of -runtime for the package containing support
files or binaries built against a library and usable by any version of
the library.  Thanks, Raphael Hertzog.

diff --git a/debian/changelog b/debian/changelog
index cfcdd39726202b99b7d600d0dac9b2f88446f87c..29dc6f4844cc50eff1a957195a5d3e41a2aeaa49 100644 (file)
--- a/debian/changelog
+++ b/debian/changelog
@@ -32,6 +32,8 @@ debian-policy (3.7.4.0) unstable; urgency=low
     Küster                                                   (Closes: #403391).
   * Bug fix: "debconf specification should allow underscores in template
     names", thanks to Colin Watson                           (Closes: #473761).
+  * Bug fix: "clarify handling of run-time and compile-time support programs",
+    thanks to Goswin Brederlow and Raphael Hertzog           (Closes: #367984).
   * Bug fix: "Examples of dpkg frontends should mention apt now", thanks
     to Josh Triplett                                         (Closes: #455602).
   * Bug fix: "Minor typos and wording suggestions", thanks to Michael

diff --git a/policy.sgml b/policy.sgml
index 16b662c5490985f90d6b5473bfdd757e33e56407..1c9a3394764304c9f15d42ff93329c302cfeae1a 100644 (file)
--- a/policy.sgml
+++ b/policy.sgml
@@ -4765,21 +4765,6 @@ Replaces: mail-transport-agent
        instead.
       </p>
 
-        <p>                                                                 
-          If your package includes run-time support programs that            
-          do not need to be invoked manually by users, but are               
-          nevertheless required  for the package to function, then it        
-          is recommended that these programs are placed                      
-          (if they are binary) in a subdirectory of                          
-          <file>/usr/lib</file>, preferably under                            
-          <file>/usr/lib/</file><var>package-name</var>.                     
-          If the program is architecture independent, the                    
-          recommendation is for it to be placed in a subdirectory of         
-          <file>/usr/share</file> instead, preferably under                  
-          <file>/usr/share/</file><var>package-name</var>.                     
-        </p>                                                                 
-                                                                            
-
       <p>
        If you have several shared libraries built from the same
        source tree you may lump them all together into a single
@@ -4922,24 +4907,50 @@ Replaces: mail-transport-agent
 
       </sect>
 
-      <sect id="sharedlibs-runtime-progs">
-       <heading>Run-time support programs</heading>
+      <sect id="sharedlibs-support-files">
+       <heading>Shared library support files</heading>
 
-      <p>
-       If your package has some run-time support programs which use
-       the shared library you must not put them in the shared
-       library package.  If you do that then you won't be able to
-       install several versions of the shared library without
-       getting filename clashes.
-      </p>
+       <p>
+         If your package contains files whose names do not change with
+         each change in the library shared object version, you must not
+         put them in the shared library package.  Otherwise, several
+         versions of the shared library cannot be installed at the same
+         time without filename clashes, making upgrades and transitions
+         unnecessarily difficult.
+       </p>
 
-      <p>
-       Instead, either create another package for the runtime binaries
-       (this package might typically be named
-       <package><var>libraryname</var>-runtime</package>; note the absence
-       of the <var>soversion</var> in the package name), or if the
-       development package is small, include them in there.
-      </p>
+       <p>
+         It is recommended that supporting files and run-time support
+         programs that do not need to be invoked manually by users, but
+         are nevertheless required for the package to function, be placed
+         (if they are binary) in a subdirectory of <file>/usr/lib</file>,
+         preferably under <file>/usr/lib/</file><var>package-name</var>.
+         If the program or file is architecture independent, the
+         recommendation is for it to be placed in a subdirectory of
+         <file>/usr/share</file> instead, preferably under
+         <file>/usr/share/</file><var>package-name</var>.  Following the
+         <var>package-name</var> naming convention ensures that the file
+         names change when the shared object version changes.
+       </p>
+
+       <p>
+         Run-time support programs that use the shared library but are
+         not required for the library to function or files used by the
+         shared library that can be used by any version of the shared
+         library package should instead be put in a separate package.
+         This package might typically be named
+         <package><var>libraryname</var>-tools</package>; note the
+         absence of the <var>soversion</var> in the package name.
+       </p>
+
+       <p>
+         Files and support programs only useful when compiling software
+         against the library should be included in the development
+         package for the library.<footnote>
+           For example, a <file><var>package-name</var>-config</file>
+           script or <package>pkg-config</package> configuration files.
+         </footnote>
+       </p>
       </sect>
 
       <sect id="sharedlibs-static">

diff --git a/upgrading-checklist.html b/upgrading-checklist.html
index 7aa9dcbadca97e7f0e452e5ef850ec816c4a860a..6c429bd05b29e4579904114810ca8277b561f674 100644 (file)
--- a/upgrading-checklist.html
+++ b/upgrading-checklist.html
@@ -84,6 +84,10 @@ picking your way through this list.
        prevents installation of the breaking package unless the package
        named in Breaks is deconfigured first.  This field should not be
        used until the dpkg in Debian stable supports it.         [6.5, 6.6, 7]
+     * Clarify which files should go into a shared library package, into a
+       separate package, or into the -dev package.  Suggest -tools instead
+       of -runtime for runtime support programs, since that naming is more
+       common in Debian.                                         [8.1, 8.2]
      * Files in /etc/cron.{hourly,daily,weekly,monthly} must be
        configuration files (upgraded from should).  Mention the hourly
        directory.                                                [9.5]