From: Russ Allbery Date: Sun, 12 Aug 2012 21:14:23 +0000 (-0700) Subject: Further wording changes on top of Jonathan Nieder's work X-Git-Url: https://git.donarmstrong.com/?p=debian%2Fdebian-policy.git;a=commitdiff_plain;h=8fc92535f6ccb673d7afeae1353118151f5186c3 Further wording changes on top of Jonathan Nieder's work Add a footnote explaining what a "reasonable" program is. Clarify the shlibs versioning text. Other minor textual changes for clarity. --- diff --git a/policy.sgml b/policy.sgml index 0965b76..fa1c39a 100644 --- a/policy.sgml +++ b/policy.sgml @@ -5978,11 +5978,11 @@ Built-Using: grub2 (= 1.99-9), loadlin (= 1.6e-1) whether new library interfaces are available and can be called). To allow these dependencies to be constructed, shared libraries must provide either a symbols file or - a shlibs file, which provides information on the + a shlibs file. These provide information on the package dependencies required to ensure the presence of interfaces provided by this library. Any package with binaries - or libraries linking to a shared library must use these files - to determine the required dependencies when it is built. Other + or libraries linking to a shared library must use these files to + determine the required dependencies when it is built. Other packages which use a shared library (for example using dlopen()) should compute appropriate dependencies using these files at build time as well. @@ -5990,21 +5990,25 @@ Built-Using: grub2 (= 1.99-9), loadlin (= 1.6e-1)

The two mechanisms differ in the degree of detail that they - provide. A symbols file documents for each symbol - exported by a library the minimal version of the package any - binary using this symbol will need, which is typically the - version of the package in which the symbol was introduced. - This permits detailed analysis of the symbols used by a + provide. A symbols file documents, for each symbol + exported by a library, the minimal version of the package any + binary using this symbol will need. This is typically the + version of the package in which the symbol was introduced. This + information permits detailed analysis of the symbols used by a particular package and construction of an accurate dependency, but it requires the package maintainer to track more information - about the shared library. A shlibs file, in - contrast, only documents the last time the library ABI changed - in any way. It only provides information about the library as a - whole, not individual symbols. When a package is built using a - shared library with only a shlibs file, the generated - dependency will require a version of the shared library equal to - or newer than the version of the last ABI change. This - generates unnecessarily restrictive dependencies compared + about the shared library. +

+ +

+ A shlibs file, in contrast, only documents the last + time the library ABI changed in any way. It only provides + information about the library as a whole, not individual + symbols. When a package is built using a shared library with + only a shlibs file, the generated dependency will + require a version of the shared library equal to or newer than + the version of the last ABI change. This generates + unnecessarily restrictive dependencies compared to symbols files if none of the symbols used by the package have changed. This, in turn, may make upgrades needlessly complex and unnecessarily restrict use of the package @@ -6012,12 +6016,15 @@ Built-Using: grub2 (= 1.99-9), loadlin (= 1.6e-1)

- shlibs files also have a flawed representation of + shlibs files also only support a limited range of library SONAMEs, making it difficult to use shlibs files in some unusual corner cases. - libfooN.shlibs says 'libfoo N' instead of the actual SONAME, - so if the SONAME doesn't match one of the two expected - formats (libfoo-N.so or libfoo.so.N) it can't be represented. + A shlibs file represents an SONAME as a library + name and version number, such as libfoo VERSION, + instead of recording the actual SONAME. If the SONAME doesn't + match one of the two expected formats + (libfoo-VERSION.so or libfoo.so.VERSION), it + cannot be represented.

@@ -6029,8 +6036,9 @@ Built-Using: grub2 (= 1.99-9), loadlin (= 1.6e-1) maintain. However, maintaining exhaustive symbols information for a C++ library can be quite onerous, so shlibs files may be more appropriate for most C++ libraries. Libraries - with a corresponding udeb must also provide shlibs, - since the udeb infrastructure does not use symbols. + with a corresponding udeb must also provide + a shlibs file, since the udeb infrastructure does + not use symbols files.

@@ -6089,10 +6097,10 @@ Built-Using: grub2 (= 1.99-9), loadlin (= 1.6e-1) binaries, libraries, or loadable modules. If you have multiple binary packages, you will need to call dpkg-shlibdeps on each one which contains - compiled libraries or binaries, for example using the - -T option to the dpkg utilities to specify a - different substvars file for each binary - package. + compiled libraries or binaries. For example, you could use + the -T option to the dpkg utilities to + specify a different substvars file for each + binary package. Again, dh_shlibdeps and dh_gencontrol will handle everything except the addition of the variable to the control file for you if @@ -6166,7 +6174,18 @@ Built-Using: grub2 (= 1.99-9), loadlin (= 1.6e-1) backward-compatible if any reasonable program or library that was linked with the previous version of the shared library will still work correctly with the new version of the shared - library. Adding new symbols to the shared library is a + library. + An example of an "unreasonable" program is one that uses + library interfaces that are documented as internal and + unsupported. If the only programs or libraries affected by + a change are "unreasonable" ones, other techniques, such as + declaring Breaks relationships with affected + packages or treating their usage of the library as bugs in + those packages, may be appropriate instead of changing the + SONAME. However, the default approach is to change the + SONAME for any change to the ABI that could break a program. + + Adding new symbols to the shared library is a backward-compatible change. Removing symbols from the shared library is not. Changing the behavior of a symbol may or may not be backward-compatible depending on the change; for