From 1c89127a2ec5977bbed95bca31b0f5ca72e1e95a Mon Sep 17 00:00:00 2001 From: Manoj Srivastava Date: Thu, 16 Jun 2005 05:36:41 +0000 Subject: [PATCH] moved all the shared library package arrangement stuff from the files chapter to the shared libraries chapter, closes: #109166 Author: joy Date: 2003/02/16 01:43:19 moved all the shared library package arrangement stuff from the files chapter to the shared libraries chapter, closes: #109166 git-archimport-id: srivasta@debian.org--etch/debian-policy--devel--3.0--patch-179 --- debian/changelog | 1 + policy.sgml | 333 ++++++++++++++++++++++++++--------------------- 2 files changed, 187 insertions(+), 147 deletions(-) diff --git a/debian/changelog b/debian/changelog index e76951a..ca72730 100644 --- a/debian/changelog +++ b/debian/changelog @@ -27,6 +27,7 @@ debian-policy (3.5.9.0) unstable; urgency=low script should start it, closes: #60979. * Rephrased section on configuration files to remove confusing use of "should", closes: #170019. + * Rearranged the shared library information properly, closes: #109166. -- diff --git a/policy.sgml b/policy.sgml index 8b1cab2..4e2c7a0 100644 --- a/policy.sgml +++ b/policy.sgml @@ -3718,9 +3718,50 @@ Replaces: mail-transport-agent

- Firstly, the package should install the shared libraries under - their normal names. For example, the libgdbmg1 - package should install libgdbm.so.1.7.3 as + 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 instead. +

+ + + Run-time shared libraries + +

+ The run-time shared library needs to be placed in a package called + librarynamesoversion, where + soversion is the version number in the + soname of the shared library +

+ 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 + libfoo.so.6, the library package would be + called libfoo6. +

+ . + Alternatively, if it would be confusing to directly append + soversion to libraryname (e.g. because + libraryname itself ends in a number), you may use + libraryname-soversion and + libraryname-soversion-dev + instead. +

+ +

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

+ +

+ The package should install the shared libraries under + their normal names. For example, the libgdbmg1 + package should install libgdbm.so.1.7.3 as /usr/lib/libgdbm.so.1.7.3. The files should not be renamed or re-linked by any prerm or postrm scripts; dpkg will take care @@ -3730,9 +3771,15 @@ Replaces: mail-transport-agent

- Secondly, the package should include the symbolic link that + Shared libraries should not be installed executable, since + the dynamic linker does not require this and trying to + execute a shared library usually results in a core dump. +

+ +

+ The run-time library package should include the symbolic link that ldconfig would create for the shared libraries. - For example, the libgdbmg1 package should include + For example, the libgdbmg1 package should include a symbolic link from /usr/lib/libgdbm.so.1 to libgdbm.so.1.7.3. This is needed so that the dynamic linker (for example ld.so or @@ -3754,23 +3801,16 @@ Replaces: mail-transport-agent .deb depended on the behavior of the underlying file system. Some file systems (such as reiserfs) reorder the files so that the order of creation is forgotten. - Starting with release 1.7.0, dpkg - will reorder the files itself as necessary when building a + Since version 1.7.0, dpkg + reorders the files itself as necessary when building a package. Thus it is no longer important to concern oneself with the order of file creation.

-

- Thirdly, the associated development package should contain a - symlink for the shared library without a version number. For - example, the libgdbmg1-dev package should include a - symlink from /usr/lib/libgdbm.so to - libgdbm.so.1.7.3. This symlink is needed by the - linker (ld) when compiling packages, as it will - only look for libgdbm.so when compiling dynamically. -

+ + ldconfig

Any package installing shared libraries in one of the default @@ -3789,7 +3829,11 @@ Replaces: mail-transport-agent

must use ldconfig to update the shared library - system. The package must call ldconfig in the + system. +

+ +

+ The package must call ldconfig in the postinst script if the first argument is configure; the postinst script may optionally invoke ldconfig at other times. The @@ -3837,10 +3881,109 @@ Replaces: mail-transport-agent

+ - - Handling shared library dependencies - the - shlibs system + + + + Run-time support programs + +

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

+ +

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

+ + + + Static libraries + +

+ The static library (libraryname.a) + is usually provided in addition to the shared version. + It is placed into the development package (see below). +

+ +

+ In some cases, it is acceptable for a library to be + available in static form only; these cases include: + + libraries for languages whose shared library support + is immature or unstable + libraries whose interfaces are in flux or under + development (commonly the case when the library's + major version number is zero, or where the ABI breaks + across patchlevels) + libraries which are explicitly intended to be + available only in static form by their upstream + author(s) + +

+ + + Development files + +

+ The development files associated to a shared library need to be + placed in a package called + librarynamesoversion-dev, + or if you prefer only to support one development version at a + time, libraryname-dev. +

+ +

+ In case several development versions of a library exist, you may + need to use dpkg's Conflicts mechanism (see + ) to ensure that the user only installs one + development version at a time (as different development versions are + likely to have the same header files in them, which would cause a + filename clash if both were installed). +

+ +

+ The development package should contain a symlink for the associated + shared library without a version number. For example, the + libgdbmg1-dev package should include a symlink + from /usr/lib/libgdbm.so to + libgdbm.so.1.7.3. This symlink is needed by the linker + (ld) when compiling packages, as it will only look for + libgdbm.so when compiling dynamically. +

+ + + + Dependencies between the packages of the same library + +

+ Typically the development version should also have an exact + version dependency on the runtime library, to make sure that + compilation and linking happens correctly. The + ${Source-Version} substitution variable can be + useful for this purpose. +

+ +

+ Packages which use the shared library should have a + dependency on the name of the shared library package, + librarynamesoversion. When + the soname changes you can have both versions of the library + installed while migrating from the old library to the new. +

+ + + + Dependencies between the library and other packages - + the shlibs system

If a package contains a binary or library which links to a @@ -3922,10 +4065,9 @@ Replaces: mail-transport-agent shlibs file format and how to create them if your package contains a shared library.

- - The shlibs files present on the system - + + The shlibs files present on the system

There are several places where shlibs files are @@ -4015,9 +4157,9 @@ Replaces: mail-transport-agent

- + - + How to use dpkg-shlibdeps and the shlibs files @@ -4065,10 +4207,10 @@ dpkg-shlibdeps debian/tmp/usr/bin/* debian/tmp/usr/sbin/* \ For more details on this and other options, see .

- + - The shlibs File Format - + + The shlibs File Format

Each shlibs file has the same format. Lines @@ -4129,9 +4271,9 @@ libz 1 zlib1g (>= 1:1.1.3) the dynamic linker about using older shared libraries with newer binaries.

- + - + Providing a shlibs file

@@ -4169,9 +4311,9 @@ install -m644 debian/shlibs.package debian/package/DEBIAN/ dpkg-shlibdeps is called on any of the binary packages.

- + - + Writing the debian/shlibs.local file

@@ -4234,7 +4376,10 @@ libbar 1 bar1 (>= 1.0-1) on bar1 to help ensure that others do not have the same problem building your package.)

+ + + The Operating System @@ -5625,45 +5770,16 @@ endif - + Libraries

- In general, libraries must have a shared version in the - library package (lib*) and a static - version in the development package (lib*-dev). - The shared version must be compiled with -fPIC, - and the static version must not be. In other words, each source - unit (*.c, for example, for C files) will need to be - compiled twice. + The shared version of a library must be compiled with + -fPIC, and the static version must not be. In other + words, each source unit (*.c, for example, for C files) + will need to be compiled twice.

-

- In some cases, it is acceptable for a library to be - available in static form only; these cases include: - - -

libraries for languages whose shared library support - is immature or unstable

- - -

- libraries whose interfaces are in flux or under - development (commonly the case when the library's - major version number is zero, or where the ABI breaks - across patchlevels) -

- - -

- libraries which are explicitly intended to be - available only in static form by their upstream - author(s)

- - - If a library is available only in static form, then it must follow - the conventions for a development package. -

You must specify the gcc option -D_REENTRANT @@ -5672,8 +5788,7 @@ endif

- Note that all installed shared libraries should be - stripped with + All installed shared libraries should be stripped with strip --strip-unneeded your-lib @@ -5776,91 +5891,15 @@ strip --strip-unneeded your-lib

+ Shared libraries - -

- Packages involving shared libraries should be split up - into several binary packages.

- -

- For a straightforward library which has a development - environment and a runtime kit including just shared - libraries you need to create two packages: - librarynamesoversion, where - soversion is the version number in the - soname of the shared library -

- 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 - libfoo.so.6, the library package would be - called libfoo6. -

- - and librarynamesoversion-dev. - Alternatively, if it would be confusing to directly append - soversion to libraryname (e.g. because - libraryname itself ends in a number), you may use - libraryname-soversion and - libraryname-soversion-dev - instead. -

- -

- If you prefer only to support one development version at a - time you may name the development package - libraryname-dev; otherwise you may need - to use dpkg's Conflicts mechanism (see ) to ensure that the user only installs one - development version at a time (as different development - versions are likely to have the same header files in them, - which would cause a filename clash if both were installed). - Typically the development version should also have an exact - version dependency on the runtime library, to make sure that - compilation and linking happens correctly. The - ${Source-Version} substitution variable can be - useful for this purpose. -

- -

- Packages which use the shared library should have a - dependency on the name of the shared library package, - librarynamesoversion. When - the soname changes you can have both versions of the library - installed while migrating from the old library to the new. -

- -

- 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. Instead, either create a third - 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 you may - include them in there. -

-

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

- -

- Shared libraries should not be installed executable, since - the dynamic linker does not require this and trying to - execute a shared library usually results in a core dump. + This section has moved to .

+ Scripts -- 2.39.5