From: Russ Allbery Date: Sun, 27 Apr 2008 23:55:32 +0000 (-0700) Subject: Clarify support file handling for shared libraries X-Git-Url: https://git.donarmstrong.com/?a=commitdiff_plain;h=5f64051c1ab124d9a973ad949334c46590fa75a9;p=debian%2Fdebian-policy.git 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 cfcdd39..29dc6f4 100644 --- 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 16b662c..1c9a339 100644 --- a/policy.sgml +++ b/policy.sgml @@ -4765,21 +4765,6 @@ Replaces: mail-transport-agent instead.

-

- 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 - /usr/lib, preferably under - /usr/lib/package-name. - If the program is architecture independent, the - recommendation is for it to be placed in a subdirectory of - /usr/share instead, preferably under - /usr/share/package-name. -

- -

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 - - Run-time support programs + + Shared library support files -

- 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. -

+

+ 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. +

-

- Instead, either create another package for the runtime binaries - (this package might typically be named - libraryname-runtime; note the absence - of the soversion in the package name), or if the - development package is small, include them in there. -

+

+ 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 /usr/lib, + preferably under /usr/lib/package-name. + If the program or file is architecture independent, the + recommendation is for it to be placed in a subdirectory of + /usr/share instead, preferably under + /usr/share/package-name. Following the + package-name naming convention ensures that the file + names change when the shared object version changes. +

+ +

+ 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 + libraryname-tools; note the + absence of the soversion in the package name. +

+ +

+ Files and support programs only useful when compiling software + against the library should be included in the development + package for the library. + For example, a package-name-config + script or pkg-config configuration files. + +

diff --git a/upgrading-checklist.html b/upgrading-checklist.html index 7aa9dcb..6c429bd 100644 --- 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]