Bug#509933: versioning SONAMEs of shared libraries is not clearly recommended
Emilio Pozuelo Monfort poch...@gmail.com writes: On 13/07/10 04:11, Russ Allbery wrote: +p + The run-time shared library must be placed in a package + whose name changes whenever the ttSONAME/tt of the shared + library changes. This allows several versions of the shared + library to be installed at the same time, allowing installation + of the new version of the shared library without immediately + breaking binaries that depend on the old version. Normally, the Should this also mention that every file's absolute path in that package should change whenever the SONAME changes (either because the file is versioned or because it's in a versioned path), with the exception of /usr/share/doc/$package? We already did, which is the only reason why it's not in this patch. It's in the next section down: 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 + Every time the shared library ABI changes in a way that may + break binaries linked against older versions of the shared + library, the ttSONAME/tt of the library and the + corresponding name for the binary package containing the runtime + shared library should change. Normally, this means Any reason this is a should and not a must? Yeah, there have been cases where we've decided to fix the breakage without changing the SONAME. For example, upstream MIT Kerberos removed some symbols from libkrb5 without changing the SONAME, but those symbols were never prototyped in the headers and had been documented as private. Rather than diverging from upstream's SONAME, we looked through the whole distribution to find anything that was using those symbols, fixed bugs in four other packages, and went forward without an SONAME change. This normally isn't what you want to do, but there are cases where portability of SONAMEs between distributions is particularly important (consider libraries such as libpng, libz, or the X libraries, for instance), and it's occasionally worth handling breakage in other ways. Seconded. Thanks! This has now been merged for the next release. -- Russ Allbery (r...@debian.org) http://www.eyrie.org/~eagle/ -- To UNSUBSCRIBE, email to debian-bugs-dist-requ...@lists.debian.org with a subject of unsubscribe. Trouble? Contact listmas...@lists.debian.org
Bug#509933: versioning SONAMEs of shared libraries is not clearly recommended
Hi, On 13/07/10 04:11, Russ Allbery wrote: Russ Allbery r...@debian.org writes: There was a lot of background information missing from Policy, which in my opinion made it unnecessarily difficult to understand the motivation and implications of the various Policy requirements. Here's a first draft of a patch to add much more information about how shared libraries work, better motivate the requirements already present (and tighten some of the language), and add a should-level requirement to change the SONAME if the library ABI changes. Objections, sections, or other review? Here's an updated version of this patch taking into account the various review and wording suggestions. diff --git a/policy.sgml b/policy.sgml index 7736ddb..415aff9 100644 --- a/policy.sgml +++ b/policy.sgml @@ -5106,55 +5106,134 @@ Replaces: mail-transport-agent /p p - Packages involving shared libraries should be split up into - several binary packages. This section mostly deals with how - this separation is to be accomplished; rules for files within - the shared library packages are in ref id=libraries instead. + This section deals only with public shared libraries: shared + libraries that are placed in directories searched by the dynamic + linker by default or which are intended to be linked against + normally and possibly used by other, independent packages. Shared + libraries that are internal to a particular package or that are + only loaded as dynamic modules are not covered by this section and + are not subject to its requirements. /p - sect id=sharedlibs-runtime - headingRun-time shared libraries/heading + p + A shared library is identified by the ttSONAME/tt attribute + stored in its dynamic section. When a binary is linked against a + shared library, the ttSONAME/tt of the shared library is + recorded in the binary's ttNEEDED/tt section so that the + dynamic linker knows that library must be loaded at runtime. The + shared library file's full name (which usually contains additional + version information not needed in the ttSONAME/tt) is + therefore normally not referenced directly. Instead, the shared + library is loaded by its ttSONAME/tt, which exists on the file + system as a symlink pointing to the full name of the shared + library. This symlink must be provided by the + package. ref id=sharedlibs-runtime describes how to do this. + footnote + This is a convention of shared library versioning, but not a + requirement. Some libraries use the ttSONAME/tt as the full + library file name instead and therefore do not need a symlink. + Most, however, encode additional information about + backwards-compatible revisions as a minor version number in the + file name. The ttSONAME/tt itself only changes when + binaries linked with the earlier version of the shared library + may no longer work, but the filename may change with each + release of the library. See ref id=sharedlibs-runtime for + more information. + /footnote + /p p - The run-time shared library needs to be placed in a package -whose name changes whenever the shared object version -changes.footnote -p - Since it is common place to install several versions of a - package that just provides shared libraries, it is a - good idea that the library package should not - contain any extraneous non-versioned files, unless they - happen to be in versioned directories./p - /footnote - The most common mechanism is to place it in a package -called -packagevarlibraryname/varvarsoversion/var/package, -where filevarsoversion/var/file is the version number -in the soname of the shared libraryfootnote - The soname is the shared object name: it's the thing - that has to match exactly between building an executable - and running it for the dynamic linker to be able run the - program. For example, if the soname of the library is - filelibfoo.so.6/file, the library package would be - called filelibfoo6/file. - /footnote. - Alternatively, if it would be confusing to directly append - varsoversion/var to varlibraryname/var (e.g. because - varlibraryname/var itself ends in a number), you may use - packagevarlibraryname/var-varsoversion/var/package and - packagevarlibraryname/var-varsoversion/var-dev/package - instead. + When linking a binary or another shared library against a shared + library, the ttSONAME/tt for that shared library is not yet + known. Instead, the shared library is found by looking for a file + matching
Bug#509933: versioning SONAMEs of shared libraries is not clearly recommended
On Sun, Jul 18, 2010 at 18:27:33 +0200, Emilio Pozuelo Monfort wrote: On 13/07/10 04:11, Russ Allbery wrote: [...] + sect id=sharedlibs-runtime + headingRun-time shared libraries/heading + + p + The run-time shared library must be placed in a package + whose name changes whenever the ttSONAME/tt of the shared + library changes. This allows several versions of the shared + library to be installed at the same time, allowing installation + of the new version of the shared library without immediately + breaking binaries that depend on the old version. Normally, the Should this also mention that every file's absolute path in that package should change whenever the SONAME changes (either because the file is versioned or because it's in a versioned path), with the exception of /usr/share/doc/$package? That's not much of an exception, since $package usually changes when the SONAME does. [...] + p + Every time the shared library ABI changes in a way that may + break binaries linked against older versions of the shared + library, the ttSONAME/tt of the library and the + corresponding name for the binary package containing the runtime + shared library should change. Normally, this means Any reason this is a should and not a must? There are other ways to handle ABI changes, see e.g. libapt-pkg, where the binary package name never changes. And in cases where upstream doesn't bump the SONAME, using a debian-specific SONAME may not always be the best plan. Cheers, Julien signature.asc Description: Digital signature
Bug#509933: versioning SONAMEs of shared libraries is not clearly recommended
On Mon, 12 Jul 2010, Russ Allbery wrote: Russ Allbery r...@debian.org writes: There was a lot of background information missing from Policy, which in my opinion made it unnecessarily difficult to understand the motivation and implications of the various Policy requirements. Here's a first draft of a patch to add much more information about how shared libraries work, better motivate the requirements already present (and tighten some of the language), and add a should-level requirement to change the SONAME if the library ABI changes. Objections, sections, or other review? Here's an updated version of this patch taking into account the various review and wording suggestions. Seconded with the small typo fix below: + The ttSONAME/tt and binary package name need not, and indeed + normally should not, change if new interfaces are added but none + are removed or changed, since this will not break binaries + linked against the old shared library. Correct versioning of + dependencies on the newer shared library by binaries that use + the new interfaces is handled via + the qref id=sharedlibs-shlibdepsttshilbs/tt s/shilbs/shlibs/ + system/qref or via symbols files (see + manref name=deb-symbols section=5). + /p Cheers, -- Raphaël Hertzog Follow the Debian Revolution ▶ http://RaphaelHertzog.com (English) ▶ http://RaphaelHertzog.fr (Français) -- To UNSUBSCRIBE, email to debian-bugs-dist-requ...@lists.debian.org with a subject of unsubscribe. Trouble? Contact listmas...@lists.debian.org
Bug#509933: versioning SONAMEs of shared libraries is not clearly recommended
Raphael Hertzog hert...@debian.org writes: I'm not sure the ldconfig bit is relevant here. Simply state that the symlink must be provided by the package (created is confusing, it might mean created by the postinst through the ldconfig call). If you want to speak of ldconfig you can put it in a footnote saying that the symlink might be updated by ldconfig and that the real location is cached to optimize the work of the dynamic loader ld.so. We go into ldconfig later, so I think you're right. I pulled the reference to ldconfig in this section. and you might want to state shlibs or symbols Added a reference pointing to deb-symbols(5) for right now until someone has a chance to write up symbols for inclusion into Policy. Thanks! -- Russ Allbery (r...@debian.org) http://www.eyrie.org/~eagle/ -- To UNSUBSCRIBE, email to debian-bugs-dist-requ...@lists.debian.org with a subject of unsubscribe. Trouble? Contact listmas...@lists.debian.org
Bug#509933: versioning SONAMEs of shared libraries is not clearly recommended
Mike Hommey m...@glandium.org writes: Please note that while not having a version in the SONAME didn't work well with shlibs, it does work well with symbols file. Now, I've been wondering for a while if we shouldn't relax our rules on SONAMEs considering the above, for libraries whose ABI doesn't change in an incompatible way. Here, I'm obviously thinking about libnspr4 and libnss3 (and I'm unsure there are more such cases): the libraries never have incompatible ABI changes, are really intended to be named as such (i.e. use -lnspr4 and not -lnspr), and are shipped without a SO version in other distributions. In other words, in the case of libnspr4 and libnss3, the only tangible reason to have a SO version and therefore being partly incompatible with other distros, is to accomodate the shlibs system, that isn't even used when symbols files are available (with a recent enough dpkg ; iirc, lenny's dpkg is fine) I see that there's further discussion of this, and I didn't want you to think that I was ignoring it. I think this is something we should look at once we add information about symbols files to Policy, including what to do with shlibs files when you have symbols files. There's another bug open about that at the moment, I think. I'm going to duck this problem for this particular work, though, since it's a larger discussion and this particular patch doesn't make things any worse for this case than it was before. -- Russ Allbery (r...@debian.org) http://www.eyrie.org/~eagle/ -- To UNSUBSCRIBE, email to debian-bugs-dist-requ...@lists.debian.org with a subject of unsubscribe. Trouble? Contact listmas...@lists.debian.org
Bug#509933: versioning SONAMEs of shared libraries is not clearly recommended
Steve Langasek vor...@debian.org writes: On Thu, Jul 08, 2010 at 10:10:51AM -0700, Russ Allbery wrote: - sect id=sharedlibs-runtime -headingRun-time shared libraries/heading + p +A shared library must be uniquely identified by an ttSONAME/tt +attribute stored in its dynamic section. This wording is going to cause problems down the line. $ objdump -p /lib/libc.so.6 /lib/i686/cmov/libc.so.6 |grep SONAME SONAME libc.so.6 SONAME libc.so.6 $ $ objdump -p /lib/libc.so.6 /lib32/libc.so.6 |grep SONAME SONAME libc.so.6 SONAME libc.so.6 $ And multiarch further increases the frequency of non-unique SONAMEs on the system. So more explanation is needed of what 'unique' actually means here. After further consideration, I don't think uniquely was really adding anything here, so I just rephrased this to: A shared library is identified by the ttSONAME/tt attribute stored in its dynamic section. which I think still gets the basic point across. +against a shared library, the ttSONAME/tt of the shared +library is recorded in the binary's ttNEEDED/tt section so +that the dynamic linker knows that library must be loaded at +runtime. The full name of the shared library (which usually I would say the shared library's full file name, as I consider the SONAME to *be* the name of the library :) Changed. I would write this footnote as: This is a convention of shared library versioning, but not a requirement. Some libraries use the ttSONAME/tt as the full library file name instead. Most, however, encode additional information about backwards-compatible revisions as a minor version number in the file name. The ttSONAME/tt itself only changes when binaries linked with the earlier version of the shared library may no longer work, but the filename may change with each release of the library. See ref id=sharedlibs-runtime for more information. Thanks, this is much better. Applied with some tweaks. +as a symlink pointing to the shared library.footnote + Some shared libraries have no version information in + their ttSONAME/tt and therefore need no symlink since the + file found when linking is the same as the library name. This + is highly unusual, however, and means the shared library cannot + be versioned. It is used only for very special situations where + the shared library provides a tiny set of symbols and must not + be versioned for some reason. +/footnote I don't think this footnote adds anything. Why document that it's possible to create shared libraries that don't follow policy? There are shared libraries in Debian that don't have version information in their name, but they're all really weird special cases that, for the purposes of this section, probably aren't public shared libraries. (libmemusage.so, for example.) So I think I concur and dropped the footnote. -p - Since it is common place to install several versions of a - package that just provides shared libraries, it is a - good idea that the library package should not - contain any extraneous non-versioned files, unless they - happen to be in versioned directories./p I don't see anywhere else that this recommendation is retained in this patch. The existing wording is rough, but I think it needs to be pointed out that shared lib packages can't contain other files in unversioned paths without running into Breaks/Replaces pain. This whole paragraph was just an inferior restatement of something that was already stated much more clearly in the next section, so I just deleted it since we're about to make a stronger and more complete statement. See Policy 8.2. -- Russ Allbery (r...@debian.org) http://www.eyrie.org/~eagle/ -- To UNSUBSCRIBE, email to debian-bugs-dist-requ...@lists.debian.org with a subject of unsubscribe. Trouble? Contact listmas...@lists.debian.org
Bug#509933: versioning SONAMEs of shared libraries is not clearly recommended
Russ Allbery r...@debian.org writes: There was a lot of background information missing from Policy, which in my opinion made it unnecessarily difficult to understand the motivation and implications of the various Policy requirements. Here's a first draft of a patch to add much more information about how shared libraries work, better motivate the requirements already present (and tighten some of the language), and add a should-level requirement to change the SONAME if the library ABI changes. Objections, sections, or other review? Here's an updated version of this patch taking into account the various review and wording suggestions. diff --git a/policy.sgml b/policy.sgml index 7736ddb..415aff9 100644 --- a/policy.sgml +++ b/policy.sgml @@ -5106,55 +5106,134 @@ Replaces: mail-transport-agent /p p - Packages involving shared libraries should be split up into - several binary packages. This section mostly deals with how - this separation is to be accomplished; rules for files within - the shared library packages are in ref id=libraries instead. + This section deals only with public shared libraries: shared + libraries that are placed in directories searched by the dynamic + linker by default or which are intended to be linked against + normally and possibly used by other, independent packages. Shared + libraries that are internal to a particular package or that are + only loaded as dynamic modules are not covered by this section and + are not subject to its requirements. /p - sect id=sharedlibs-runtime - headingRun-time shared libraries/heading + p + A shared library is identified by the ttSONAME/tt attribute + stored in its dynamic section. When a binary is linked against a + shared library, the ttSONAME/tt of the shared library is + recorded in the binary's ttNEEDED/tt section so that the + dynamic linker knows that library must be loaded at runtime. The + shared library file's full name (which usually contains additional + version information not needed in the ttSONAME/tt) is + therefore normally not referenced directly. Instead, the shared + library is loaded by its ttSONAME/tt, which exists on the file + system as a symlink pointing to the full name of the shared + library. This symlink must be provided by the + package. ref id=sharedlibs-runtime describes how to do this. + footnote + This is a convention of shared library versioning, but not a + requirement. Some libraries use the ttSONAME/tt as the full + library file name instead and therefore do not need a symlink. + Most, however, encode additional information about + backwards-compatible revisions as a minor version number in the + file name. The ttSONAME/tt itself only changes when + binaries linked with the earlier version of the shared library + may no longer work, but the filename may change with each + release of the library. See ref id=sharedlibs-runtime for + more information. + /footnote + /p p - The run-time shared library needs to be placed in a package -whose name changes whenever the shared object version -changes.footnote -p - Since it is common place to install several versions of a - package that just provides shared libraries, it is a - good idea that the library package should not - contain any extraneous non-versioned files, unless they - happen to be in versioned directories./p - /footnote - The most common mechanism is to place it in a package -called -packagevarlibraryname/varvarsoversion/var/package, -where filevarsoversion/var/file is the version number -in the soname of the shared libraryfootnote - The soname is the shared object name: it's the thing - that has to match exactly between building an executable - and running it for the dynamic linker to be able run the - program. For example, if the soname of the library is - filelibfoo.so.6/file, the library package would be - called filelibfoo6/file. - /footnote. - Alternatively, if it would be confusing to directly append - varsoversion/var to varlibraryname/var (e.g. because - varlibraryname/var itself ends in a number), you may use - packagevarlibraryname/var-varsoversion/var/package and - packagevarlibraryname/var-varsoversion/var-dev/package - instead. + When linking a binary or another shared library against a shared + library, the ttSONAME/tt for that shared library is not yet + known. Instead, the shared library is found by looking for a file + matching the library name with
Bug#509933: versioning SONAMEs of shared libraries is not clearly recommended
On Sat, Jul 10, 2010 at 12:36:14PM -0700, Steve Langasek wrote: It's not that these libraries will never have incompatible ABI changes, it's that they encode the ABI information in a non-standard way - the '4' in libnspr4 and the '3' in libnss3 do represent the sover, they just do it in a manner that's gratuitously incompatible with how all other Unix libraries have been versioned since time immemorial. If we're going to relax the rules for sonames, I think they should be relaxed only to accomodate this particular case of the so version being on the lefthand side of the .so extension with no delimiter before it. I.e., let a shlibs file of 'libnspr 4 libnspr4-0d' do the right thing, but don't allow shlibs files with an empty version field. I'm not totally sure it would be a good idea to modify shlibs to work that way, and it would somehow feel wrong that a library you link with -lnspr4 is described as libnspr and not libnspr4 in the shlibs. I just think the rule should be relaxed, but the implementation should be done with symbols files. BTW, are there any other libraries with the same problem, where compatibility with other distros may be important? (which btw, in the case of nss and nspr, is even more important since part of these libs are part of the LSB, which is why the .so symlinks are in the library package and not the -dev package ; but it would still be better that binaries built on debian could work on other systems, too, which is not the case atm) Cheers, Mike -- To UNSUBSCRIBE, email to debian-bugs-dist-requ...@lists.debian.org with a subject of unsubscribe. Trouble? Contact listmas...@lists.debian.org
Bug#509933: versioning SONAMEs of shared libraries is not clearly recommended
On Thu, Jul 08, 2010 at 10:10:51AM -0700, Russ Allbery wrote: - sect id=sharedlibs-runtime - headingRun-time shared libraries/heading + p + A shared library must be uniquely identified by an ttSONAME/tt + attribute stored in its dynamic section. This wording is going to cause problems down the line. $ objdump -p /lib/libc.so.6 /lib/i686/cmov/libc.so.6 |grep SONAME SONAME libc.so.6 SONAME libc.so.6 $ $ objdump -p /lib/libc.so.6 /lib32/libc.so.6 |grep SONAME SONAME libc.so.6 SONAME libc.so.6 $ And multiarch further increases the frequency of non-unique SONAMEs on the system. So more explanation is needed of what 'unique' actually means here. When a binary is linked + against a shared library, the ttSONAME/tt of the shared + library is recorded in the binary's ttNEEDED/tt section so + that the dynamic linker knows that library must be loaded at + runtime. The full name of the shared library (which usually I would say the shared library's full file name, as I consider the SONAME to *be* the name of the library :) + contains additional version information not needed in + the ttSONAME/tt is therefore not referenced directly. + Instead, the shared library is loaded by its ttSONAME/tt, + which exists on the file system as a symlink pointing to the full + name of the shared library.footnote + Some unusual libraries have an ttSONAME/tt which matches the + full library name, but normally there is a minor revision that + changes even though the ABI has not changed in a + backward-incompatible way. The ttSONAME/tt only changes + when binaries linked with the earlier version of the shared + library may no longer work. See ref id=sharedlibs-runtime + for more information. + /footnote I would write this footnote as: This is a convention of shared library versioning, but not a requirement. Some libraries use the ttSONAME/tt as the full library file name instead. Most, however, encode additional information about backwards-compatible revisions as a minor version number in the file name. The ttSONAME/tt itself only changes when binaries linked with the earlier version of the shared library may no longer work, but the filename may change with each release of the library. See ref id=sharedlibs-runtime for more information. + When linking a binary or another shared library against a shared + library, the ttSONAME/tt for that shared library is not yet + known. Instead, the shared library is found by library name + with tt.so/tt appended. This file exists on the file system + as a symlink pointing to the shared library.footnote + Some shared libraries have no version information in + their ttSONAME/tt and therefore need no symlink since the + file found when linking is the same as the library name. This + is highly unusual, however, and means the shared library cannot + be versioned. It is used only for very special situations where + the shared library provides a tiny set of symbols and must not + be versioned for some reason. + /footnote I don't think this footnote adds anything. Why document that it's possible to create shared libraries that don't follow policy? -p - Since it is common place to install several versions of a - package that just provides shared libraries, it is a - good idea that the library package should not - contain any extraneous non-versioned files, unless they - happen to be in versioned directories./p I don't see anywhere else that this recommendation is retained in this patch. The existing wording is rough, but I think it needs to be pointed out that shared lib packages can't contain other files in unversioned paths without running into Breaks/Replaces pain. + + p - If you have several shared libraries built from the same - source tree you may lump them all together into a single - shared library package, provided that you change all of - their sonames at once (so that you don't get filename - clashes if you try to install different versions of the - combined shared libraries package). + If you have several shared libraries built from the same source + tree, you may lump them all together into a single shared + library package provided that all of their ttSONAME/tts will + always change together. Be aware that this is not normally the + case, and if the ttSONAME/tts do not change together, + upgrading such a merged shared library package will be + unnecessarily difficult because of file conflicts with the old + version of the package. When in doubt, always split shared + library packages so that each
Bug#509933: versioning SONAMEs of shared libraries is not clearly recommended
On Fri, Jul 09, 2010 at 05:09:05PM +0200, Mike Hommey wrote: On Thu, Jul 08, 2010 at 10:10:51AM -0700, Russ Allbery wrote: Russ Allbery r...@debian.org writes: I read through the shared library sections of Policy a few times last night and can't find anywhere where Policy unambiguously recommends always including a version in SONAME for public libraries. If you don't have a version, you can't represent the library in the shlibs format, so there's an implicit recommendation, but I think it would be better to make it explicit. Please note that while not having a version in the SONAME didn't work well with shlibs, it does work well with symbols file. FSVO well that encompasses fails to prevent uninformed maintainers from shipping shared libraries that lack any sensible ABI management and breaking upgrades in future releases. (Not referring to your packages here; I mean that this will be a problem in the archive in general.) Now, I've been wondering for a while if we shouldn't relax our rules on SONAMEs considering the above, for libraries whose ABI doesn't change in an incompatible way. Here, I'm obviously thinking about libnspr4 and libnss3 (and I'm unsure there are more such cases): the libraries never have incompatible ABI changes, are really intended to be named as such (i.e. use -lnspr4 and not -lnspr), and are shipped without a SO version in other distributions. In other words, in the case of libnspr4 and libnss3, the only tangible reason to have a SO version and therefore being partly incompatible with other distros, is to accomodate the shlibs system, that isn't even used when symbols files are available (with a recent enough dpkg ; iirc, lenny's dpkg is fine) It's not that these libraries will never have incompatible ABI changes, it's that they encode the ABI information in a non-standard way - the '4' in libnspr4 and the '3' in libnss3 do represent the sover, they just do it in a manner that's gratuitously incompatible with how all other Unix libraries have been versioned since time immemorial. If we're going to relax the rules for sonames, I think they should be relaxed only to accomodate this particular case of the so version being on the lefthand side of the .so extension with no delimiter before it. I.e., let a shlibs file of 'libnspr 4 libnspr4-0d' do the right thing, but don't allow shlibs files with an empty version field. -- Steve Langasek Give me a lever long enough and a Free OS Debian Developer to set it on, and I can move the world. Ubuntu Developerhttp://www.debian.org/ slanga...@ubuntu.com vor...@debian.org signature.asc Description: Digital signature
Bug#509933: versioning SONAMEs of shared libraries is not clearly recommended
On Thu, 08 Jul 2010, Russ Allbery wrote: Objections, sections, or other review? Looks mostly good, I have some fixes and suggestions below. - sect id=sharedlibs-runtime - headingRun-time shared libraries/heading + p + A shared library must be uniquely identified by an ttSONAME/tt s/an/a/ ? (I saw it several times, sounds odd to me but maybe I miss something) + attribute stored in its dynamic section. When a binary is linked + against a shared library, the ttSONAME/tt of the shared + library is recorded in the binary's ttNEEDED/tt section so + that the dynamic linker knows that library must be loaded at + runtime. The full name of the shared library (which usually + contains additional version information not needed in + the ttSONAME/tt is therefore not referenced directly. Missing ) after SONAME. + Instead, the shared library is loaded by its ttSONAME/tt, + which exists on the file system as a symlink pointing to the full + name of the shared library.footnote + Some unusual libraries have an ttSONAME/tt which matches the + full library name, but normally there is a minor revision that + changes even though the ABI has not changed in a + backward-incompatible way. The ttSONAME/tt only changes + when binaries linked with the earlier version of the shared + library may no longer work. See ref id=sharedlibs-runtime + for more information. + /footnote + This symlink is updated and its location cached + by prgnldconfig/prgn, but must also be created by the + package. ref id=sharedlibs-runtime describes how to do this. I'm not sure the ldconfig bit is relevant here. Simply state that the symlink must be provided by the package (created is confusing, it might mean created by the postinst through the ldconfig call). If you want to speak of ldconfig you can put it in a footnote saying that the symlink might be updated by ldconfig and that the real location is cached to optimize the work of the dynamic loader ld.so. [...] + The ttSONAME/tt and binary package name need not, and indeed + normally should not, change if new interfaces are added but none + are removed or changed, since this will not break binaries + linked against the old shared library. Correct versioning of + dependencies on the newer shared library by binaries that use + the new interfaces is handled via + the qref id=sharedlibs-shlibdepsttshilbs/tt + system/qref. s/shilbs/shlibs/ and you might want to state shlibs or symbols Cheers, -- Raphaël Hertzog Follow the Debian Revolution ▶ http://RaphaelHertzog.com (English) ▶ http://RaphaelHertzog.fr (Français) -- To UNSUBSCRIBE, email to debian-bugs-dist-requ...@lists.debian.org with a subject of unsubscribe. Trouble? Contact listmas...@lists.debian.org
Bug#509933: versioning SONAMEs of shared libraries is not clearly recommended
On Thu, Jul 08, 2010 at 10:10:51AM -0700, Russ Allbery wrote: Russ Allbery r...@debian.org writes: I read through the shared library sections of Policy a few times last night and can't find anywhere where Policy unambiguously recommends always including a version in SONAME for public libraries. If you don't have a version, you can't represent the library in the shlibs format, so there's an implicit recommendation, but I think it would be better to make it explicit. Please note that while not having a version in the SONAME didn't work well with shlibs, it does work well with symbols file. Now, I've been wondering for a while if we shouldn't relax our rules on SONAMEs considering the above, for libraries whose ABI doesn't change in an incompatible way. Here, I'm obviously thinking about libnspr4 and libnss3 (and I'm unsure there are more such cases): the libraries never have incompatible ABI changes, are really intended to be named as such (i.e. use -lnspr4 and not -lnspr), and are shipped without a SO version in other distributions. In other words, in the case of libnspr4 and libnss3, the only tangible reason to have a SO version and therefore being partly incompatible with other distros, is to accomodate the shlibs system, that isn't even used when symbols files are available (with a recent enough dpkg ; iirc, lenny's dpkg is fine) Mike -- To UNSUBSCRIBE, email to debian-bugs-dist-requ...@lists.debian.org with a subject of unsubscribe. Trouble? Contact listmas...@lists.debian.org
Bug#509933: Pronunciation of initialisms (was: Bug#509933: versioning SONAMEs of shared libraries is not clearly recommended)
Raphael Hertzog hert...@debian.org writes: On Thu, 08 Jul 2010, Russ Allbery wrote: + A shared library must be uniquely identified by an ttSONAME/tt s/an/a/ ? (I saw it several times, sounds odd to me but maybe I miss something) Like Russ, it sounds fine to me. That's probably because we pronounce the initialism “SONAME” as “ess oh name”, which starts with a vowel sound and hence takes the indefinite article “an”; while you might be treating it as an acronym. URL:http://en.wikipedia.org/wiki/Initialism -- \ “We have met the enemy and he is us.” —Walt Kelly, _Pogo_ | `\1971-04-22 | _o__) | Ben Finney b...@benfinney.id.au -- To UNSUBSCRIBE, email to debian-bugs-dist-requ...@lists.debian.org with a subject of unsubscribe. Trouble? Contact listmas...@lists.debian.org
Bug#509933: versioning SONAMEs of shared libraries is not clearly recommended
Russ Allbery r...@debian.org writes: I read through the shared library sections of Policy a few times last night and can't find anywhere where Policy unambiguously recommends always including a version in SONAME for public libraries. If you don't have a version, you can't represent the library in the shlibs format, so there's an implicit recommendation, but I think it would be better to make it explicit. There was a lot of background information missing from Policy, which in my opinion made it unnecessarily difficult to understand the motivation and implications of the various Policy requirements. Here's a first draft of a patch to add much more information about how shared libraries work, better motivate the requirements already present (and tighten some of the language), and add a should-level requirement to change the SONAME if the library ABI changes. Objections, sections, or other review? diff --git a/policy.sgml b/policy.sgml index 7736ddb..2d535d3 100644 --- a/policy.sgml +++ b/policy.sgml @@ -5106,55 +5106,138 @@ Replaces: mail-transport-agent /p p - Packages involving shared libraries should be split up into - several binary packages. This section mostly deals with how - this separation is to be accomplished; rules for files within - the shared library packages are in ref id=libraries instead. + This section deals only with public shared libraries: shared + libraries that are placed in directories searched by the dynamic + linker by default or which are intended to be linked against + normally and possibly used by other, independent packages. Shared + libraries that are internal to a particular package or that are + only loaded as dynamic modules are not covered by this section and + are not subject to its requirements. /p - sect id=sharedlibs-runtime - headingRun-time shared libraries/heading + p + A shared library must be uniquely identified by an ttSONAME/tt + attribute stored in its dynamic section. When a binary is linked + against a shared library, the ttSONAME/tt of the shared + library is recorded in the binary's ttNEEDED/tt section so + that the dynamic linker knows that library must be loaded at + runtime. The full name of the shared library (which usually + contains additional version information not needed in + the ttSONAME/tt is therefore not referenced directly. + Instead, the shared library is loaded by its ttSONAME/tt, + which exists on the file system as a symlink pointing to the full + name of the shared library.footnote + Some unusual libraries have an ttSONAME/tt which matches the + full library name, but normally there is a minor revision that + changes even though the ABI has not changed in a + backward-incompatible way. The ttSONAME/tt only changes + when binaries linked with the earlier version of the shared + library may no longer work. See ref id=sharedlibs-runtime + for more information. + /footnote + This symlink is updated and its location cached + by prgnldconfig/prgn, but must also be created by the + package. ref id=sharedlibs-runtime describes how to do this. + /p p - The run-time shared library needs to be placed in a package -whose name changes whenever the shared object version -changes.footnote -p - Since it is common place to install several versions of a - package that just provides shared libraries, it is a - good idea that the library package should not - contain any extraneous non-versioned files, unless they - happen to be in versioned directories./p - /footnote - The most common mechanism is to place it in a package -called -packagevarlibraryname/varvarsoversion/var/package, -where filevarsoversion/var/file is the version number -in the soname of the shared libraryfootnote - The soname is the shared object name: it's the thing - that has to match exactly between building an executable - and running it for the dynamic linker to be able run the - program. For example, if the soname of the library is - filelibfoo.so.6/file, the library package would be - called filelibfoo6/file. - /footnote. - Alternatively, if it would be confusing to directly append - varsoversion/var to varlibraryname/var (e.g. because - varlibraryname/var itself ends in a number), you may use - packagevarlibraryname/var-varsoversion/var/package and - packagevarlibraryname/var-varsoversion/var-dev/package - instead. + When linking a binary or another shared library against a shared + library, the ttSONAME/tt for that shared library is
Bug#509933: versioning SONAMEs of shared libraries is not clearly recommended
Russ Allbery wrote: Package: debian-policy Version: 3.8.0.1 Severity: minor I read through the shared library sections of Policy a few times last night and can't find anywhere where Policy unambiguously recommends always including a version in SONAME for public libraries. If you don't have a version, you can't represent the library in the shlibs format, so there's an implicit recommendation, but I think it would be better to make it explicit. I think the first sentence of 8.1 with the footnote 47 give an answer, but: a footnote (IMO) is not normative, and a a good idea is too weak. [8.1] The run-time shared library needs to be placed in a package whose name changes whenever the shared object version changes.[47] [47] Since it is common place to install several versions of a package that just provides shared libraries, it is a good idea that the library package should not contain any extraneous non-versioned files, unless they happen to be in versioned directories. ciao cate -- To UNSUBSCRIBE, email to debian-bugs-dist-requ...@lists.debian.org with a subject of unsubscribe. Trouble? Contact listmas...@lists.debian.org
Bug#509933: versioning SONAMEs of shared libraries is not clearly recommended
Giacomo A. Catenazzi c...@debian.org writes: Russ Allbery wrote: I read through the shared library sections of Policy a few times last night and can't find anywhere where Policy unambiguously recommends always including a version in SONAME for public libraries. If you don't have a version, you can't represent the library in the shlibs format, so there's an implicit recommendation, but I think it would be better to make it explicit. I think the first sentence of 8.1 with the footnote 47 give an answer, but: a footnote (IMO) is not normative, and a a good idea is too weak. [8.1] The run-time shared library needs to be placed in a package whose name changes whenever the shared object version changes.[47] [47] Since it is common place to install several versions of a package that just provides shared libraries, it is a good idea that the library package should not contain any extraneous non-versioned files, unless they happen to be in versioned directories. Oh, hm, yes, there's a stricter statement of the same thing now in section 8.2: 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. I should fix the footnote to make that consistent. I don't know if we should make a special case for the kdeinit libraries, or in general how we should deal with that. -- Russ Allbery (r...@debian.org) http://www.eyrie.org/~eagle/ -- To UNSUBSCRIBE, email to debian-bugs-dist-requ...@lists.debian.org with a subject of unsubscribe. Trouble? Contact listmas...@lists.debian.org
Bug#509933: versioning SONAMEs of shared libraries is not clearly recommended
Package: debian-policy Version: 3.8.0.1 Severity: minor I read through the shared library sections of Policy a few times last night and can't find anywhere where Policy unambiguously recommends always including a version in SONAME for public libraries. If you don't have a version, you can't represent the library in the shlibs format, so there's an implicit recommendation, but I think it would be better to make it explicit. Note from: http://lintian.debian.org/tags/shlib-missing-in-control-file.html that KDE in particular has a ton of unversioned shared libraries, all of which appear to be private libraries for particular applications and hence already should be in a subdirectory of /usr/lib per existing Policy. The other cases where shared libraries aren't versioned (which are currently caught by that Lintian tag but soon will be caught by a new one) are similar cases of misplaced plugins and private libraries, as near as I can tell, with a few special cases. I doubt this makes sense as a must since there are weird edge cases like libSegFault, but I think a should is warranted. You need to really know what you're doing if you're packaging a public shared library without a version in the SONAME. -- System Information: Debian Release: lenny/sid APT prefers testing APT policy: (990, 'testing'), (500, 'unstable'), (1, 'experimental') Architecture: i386 (i686) Kernel: Linux 2.6.26-1-686 (SMP w/1 CPU core) Locale: LANG=en_US.UTF-8, LC_CTYPE=en_US.UTF-8 (charmap=UTF-8) Shell: /bin/sh linked to /bin/bash debian-policy depends on no packages. debian-policy recommends no packages. Versions of packages debian-policy suggests: ii doc-base 0.8.18 utilities to manage online documen -- no debconf information -- To UNSUBSCRIBE, email to debian-bugs-dist-requ...@lists.debian.org with a subject of unsubscribe. Trouble? Contact listmas...@lists.debian.org
