X-Git-Url: https://git.donarmstrong.com/?a=blobdiff_plain;f=policy.sgml;h=55200064a4ffe8250dceafd2099e7b0555cc3bad;hb=0850327842e8acea3d3a959be46b020da177ba6e;hp=17fb1a35ffcccc03344aedb92fd3efb2749ec71f;hpb=042e857f4ba0155b2bcf47d59cd500527039fd99;p=debian%2Fdebian-policy.git diff --git a/policy.sgml b/policy.sgml index 17fb1a3..5520006 100644 --- a/policy.sgml +++ b/policy.sgml @@ -5494,16 +5494,28 @@ Replaces: mail-transport-agent be placed in a package named librarynamesoversion, where soversion is the version number in - the SONAME of the shared library. - See for detailed information on how to - determine this version. Alternatively, if it would be confusing - to directly append soversion - to libraryname (if, for example, libraryname - itself ends in a number), you should use + the SONAME of the shared library. Alternatively, if it + would be confusing to directly append soversion + to libraryname (if, for + example, libraryname itself ends in a number), you + should use libraryname-soversion instead.

+

+ To determine the soversion, look at + the SONAME of the library, stored in the + ELF SONAME attribute. it is usually of the + form name.so.major-version (for + example, libz.so.1). The version part is the part + which comes after .so., so in that example it + is 1. The soname may instead be of the + form name-major-version.so, such + as libdb-5.1.so, in which case the name would + be libdb and the version would be 5.1. +

+

If you have several shared libraries built from the same source tree, you may lump them all together into a single shared @@ -5539,9 +5551,8 @@ Replaces: mail-transport-agent 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 symbols system - or the shlibs - system. + the symbols + or shlibs system.

@@ -5810,9 +5821,9 @@ Replaces: mail-transport-agent

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

If a package contains a binary or library which links to a @@ -5830,183 +5841,63 @@ Replaces: mail-transport-agent

- shlibs files were the original mechanism for - handling library dependencies. They are documented - in . symbols files, - documented in this section, are recommended for most packages, - since they provide dependency information for each exported - symbol and therefore generate more accurate dependencies for - binaries that do not use symbols from newer versions of the - shared library. However, shlibs files must be used - for udebs. Packages which provide a symbols file - are not required to provide a shlibs file. -

- -

- When a package that contains any shared libraries or compiled - binaries is built, it must run dpkg-shlibdeps on - each shared library and compiled binary to determine the - libraries used and hence the dependencies needed by the - package. - dpkg-shlibdeps will use a program - like objdump or readelf to find the - libraries and the symbols in those libraries directly needed - by the binaries or shared libraries in the package. - + These two mechanisms differ in the degree of detail that they + provide. A symbols file documents every symbol + that is part of the library ABI and, for each, the version of + the package in which it was introduced. This 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 + 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 + on systems with older versions of the shared libraries.

- We say that a binary foo directly uses a - library libbar if it is explicitly linked with that - library (that is, the library is listed in the - ELF NEEDED attribute, caused by adding -lbar - to the link line when the binary is created). Other libraries - that are needed by libbar are - linked indirectly to foo, and the dynamic - linker will load them automatically when it - loads libbar. A package should depend on the libraries - it directly uses, but not the libraries it indirectly uses. The - dependencies for those libraries will automatically pull in the - other libraries. dpkg-shlibdeps will handle this - logic automatically, but package maintainers need to be aware of - this distinction between directly and indirectly using a library - if they have to override its results for some reason. - - A good example of where this helps is the following. We could - update libimlib with a new version that supports a - new graphics format called dgf (but retaining the same major - version number) and depends on libdgf. If we - used ldd to add dependencies for every library - directly or indirectly linked with a binary, every package - that uses libimlib would need to be recompiled so it - would also depend on libdgf or it wouldn't run due to - missing symbols. Since dependencies are only added based on - ELF NEEDED attribute, packages - using libimlib can rely on libimlib itself - having the dependency on libdgf and so they would not - need rebuilding. - + shlibs files also have a flawed representation of + library SONAMEs, making it difficult to use shlibs + files in some unusual corner cases.

- In the following sections, we will first describe where the - various symbols files are to be found, then how to - use dpkg-shlibdeps, and finally - the symbols file format and how to create them if - your package contains a shared library. + symbols files are therefore recommended for most + shared library packages since they provide more accurate + dependencies. For most C libraries, the additional detail + required by symbols files is not too difficult to + 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. udebs + must also use shlibs, since the udeb infrastructure + does not use symbols.

- - The symbols files present on the - system - -

- symbols files for a shared library are normally - provided by the shared library package, but there are several - override paths that are checked first in case that information - is wrong or missing. The following list gives them in the - order in which they are read by dpkg-shlibdeps - The first one that contains the required information is used. - - -

debian/*/DEBIAN/symbols

- -

- During the package build, if the package itself contains - shared libraries with symbols files, they - will be generated in these staging directories - by dpkg-gensymbols. symbols - files found in the build tree take precedence - over symbols files from other binary - packages. -

- -

- These files must exist - before dpkg-shlibdeps is run or the - dependencies of binaries and libraries from a source - package on other libraries from that same source package - will not be correct. In practice, this means - that dpkg-gensymbols must be run - before dpkg-shlibdeps during the package - build. - An example may clarify. Suppose the source - package foo generates two binary - packages, libfoo2 and foo-runtime. - When building the binary packages, the contents of the - packages are staged in the - directories debian/libfoo2 - and debian/foo-runtime respectively. - (debian/tmp could be used instead of one - of these.) Since libfoo2 provides - the libfoo shared library, it will contain - a symbols file, which will be installed - in debian/libfoo2/DEBIAN/symbols, - eventually to be included as a control file in that - package. When dpkg-shlibdeps is run on - the - executable debian/foo-runtime/usr/bin/foo-prog, - it will examine - the debian/libfoo2/DEBIAN/symbols file to - determine whether foo-prog's library - dependencies are satisfied by any of the libraries - provided by libfoo2. Since those binaries - were linked against the just-built shared library as - part of the build process, the symbols - file for the newly-built libfoo2 must take - precedence over a symbols file for any - other libfoo2 package already installed on - the system. - -

- - - -

- /etc/dpkg/symbols/package.symbols.arch - and /etc/dpkg/symbols/package.symbols -

- -

- Per-system overrides of shared library dependencies. - These files normally do not exist. They are maintained - by the local system administrator and must not be - created by any Debian package. -

- - - -

symbols control files for packages - installed on the system

- -

- The symbols control files for all the - packages currently installed on the system are searched - last. This will be the most common source of shared - library dependency information. These are normally - found in /var/lib/dpkg/info/*.symbols, but - packages should not rely on this and instead should - use dpkg-query --control-path package - symbols if for some reason these files need to be - examined. -

- - -

- -

- Be aware that if a debian/shlibs.local exists in - the source package, it will override any symbols - files. This is the only case where a shlibs is - used despite symbols files being present. See - and - for more information. -

- - - How to use dpkg-shlibdeps and the - symbols files + Generating dependencies on shared libraries + +

+ When a package that contains any shared libraries or compiled + binaries is built, it must run dpkg-shlibdeps on + each shared library and compiled binary to determine the + libraries used and hence the dependencies needed by the + package. + dpkg-shlibdeps will use a program + like objdump or readelf to find + the libraries and the symbols in those libraries directly + needed by the binaries or shared libraries in the package. + + dpkg-shlibdeps will use the symbols + or shlibs files installed by the shared libraries + to generate dependency information. +

If your package contains any compiled binaries or shared @@ -6015,13 +5906,27 @@ Replaces: mail-transport-agent List all of the compiled binaries, libraries, or loadable modules in your package. The easiest way to do this is to use a package helper - framework such as debhelper. If you are - using debhelper, the dh_shlibdeps - program will do this work for you. It will also correctly - handle multi-binary packages. + framework such as debhelper. If you are + using debhelper, + the dh_shlibdeps program will do this work for + you. It will also correctly handle multi-binary packages.

+

+ If you are creating a udeb for use in the Debian Installer, + you will need to specify that dpkg-shlibdeps + should use the dependency line of type udeb by adding + the -tudeb option + dh_shlibdeps from the debhelper suite + will automatically add this option if it knows it is + processing a udeb. + . If there is no dependency line of + type udeb in the shlibs + file, dpkg-shlibdeps will fall back to the + regular dependency line. +

+

This command puts the dependency information into the debian/substvars file, which is then used @@ -6036,8 +5941,9 @@ Replaces: mail-transport-agent specify a different substvars file for each binary package. Again, dh_shlibdeps - and dh_gencontrol will handle all of this for - you if you're using debhelper, including generating + and dh_gencontrol will handle everything except + the control file modification for you if you're + using debhelper, including generating separate substvars files for each binary package and calling dpkg-gencontrol with the appropriate flags. @@ -6048,269 +5954,129 @@ Replaces: mail-transport-agent For more details on dpkg-shlibdeps, see .

- - - - The symbols File Format - -

- The following documents the format of the symbols - control file as included in binary packages. These files are - built from template symbols files in the source - package by dpkg-gensymbols. The template files - support a richer syntax that - allows dpkg-gensymbols to do some of the tedious - work involved in maintaining symbols files, such - as handling C++ symbols or optional symbols that may not exist - on particular architectures. When - writing symbols files for a shared library - package, refer to - for the richer syntax. -

- -

- A symbols may contain one or more entries, one - for each shared library contained in the package corresponding - to that symbols. Each entry has the following - format: -

- -

- -library-soname main-dependency-template -[| alternative-dependency-template] -[...] -[* field-name: field-value] -[...] - symbol minimal-version[ id-of-dependency-template ] - -

- -

- To explain this format, we'll use the the zlib1g - package as an example, which (at the time of writing) installs - the shared library /usr/lib/libz.so.1.2.3.4. - Mandatory lines will be described first, followed by optional - lines. -

- library-soname must contain exactly the value of - the ELF SONAME attribute of the shared library. In - our example, this is libz.so.1. - This can be determined by using the command - -readelf -d /usr/lib/libz.so.1.2.3.4 | grep SONAME - + We say that a binary foo directly uses a + library libbar if it is explicitly linked with that + library (that is, the library is listed in the + ELF NEEDED attribute, caused by adding -lbar + to the link line when the binary is created). Other libraries + that are needed by libbar are + linked indirectly to foo, and the dynamic + linker will load them automatically when it + loads libbar. A package should depend on the + libraries it directly uses, but not the libraries it + indirectly uses. The dependencies for the libraries used + directly will automatically pull in the indirectly-used + libraries. dpkg-shlibdeps will handle this logic + automatically, but package maintainers need to be aware of + this distinction between directly and indirectly using a + library if they have to override its results for some reason. + + A good example of where this helps is the following. We + could update libimlib with a new version that + supports a new revision of a graphics format called dgf (but + retaining the same major version number) and depends on a + new library package libdgf4 instead of + the older libdgf3. If we + used ldd to add dependencies for every library + directly or indirectly linked with a binary, every package + that uses libimlib would need to be recompiled so + it would also depend on libdgf4 in order + to retire the older libdgf3 package. + Since dependencies are only added based on + ELF NEEDED attribute, packages + using libimlib can rely on libimlib itself + having the dependency on an appropriate version + of libdgf and do not need rebuilding.

+ -

- main-dependency-template has the same syntax as a - dependency field in a binary package control file, except that - the string #MINVER# is replaced by a version - restriction like (>= version) or by - nothing if an unversioned dependency is deemed sufficient. - The version restriction will be based on which symbols from - the shared library are referenced and the version at which - they were introduced (see below). In nearly all - cases, main-dependency-template will - be package #MINVER#, - where package is the name of the binary package - containing the shared library. This adds a simple, - possibly-versioned dependency on the shared library package. - In some rare cases, such as when multiple packages provide the - same shared library ABI, the dependency template may need to - be more complex. -

+ + Shared library ABI changes

- In our example, the first line of - the zlib1g symbols file would be: - -libz.so.1 zlib1g #MINVER# - + Maintaining a shared library package using + either symbols or shlibs files + requires being aware of the exposed ABI of the shared library + and any changes to it. Both symbols + and shlibs files record every change to the ABI + of the shared library; symbols files do so per + public symbol, whereas shlibs files record only + the last change for the entire library.

- Each public symbol exported by the shared library must have a - corresponding symbol line, indented by one - space. symbol is the exported symbol (which, for - C++, means the mangled symbol) followed by @ and the - symbol version, or the string Base if there is no - symbol version. minimal-version is the most recent - version of the shared library that changed the behavior of - that symbol, whether by adding it, changing its function - signature (the parameters, their types, or the return type), - or its behavior in a way that is visible to a - caller. id-of-dependency-template is an optional - field that references - an alternative-dependency-template; see below for a - full description. -

- -

- For example, libz.so.1 contains the - symbols compress - and compressBound. compress has no symbol - version and last changed its behavior in upstream - version 1:1.1.4. compressBound has the - symbol version ZLIB_1.2.0, was introduced in upstream - version 1:1.2.0, and has not changed its behavior. - Its symbols file therefore contains the lines: - - compress@Base 1:1.1.4 - compressBound@ZLIB_1.2.0 1:1.2.0 - - Packages using only compress would then get a - dependency of zlib1g (>= 1:1.1.4), but packages - using compressBound would get a dependency - of zlib1g (>= 1:1.2.0). -

- -

- One or more alternative-dependency-template lines - may be provided. These are used in cases where some symbols - in the shared library should use one dependency template while - others should use a different template. The alternative - dependency templates are used only if a symbol line contains - the id-of-dependency-template field. The first - alternative dependency template is numbered 1, the second 2, - and so forth. - An example of where this may be needed is with a library - that implements the libGL interface. All GL implementations - provide the same set of base interfaces, and then may - provide some additional interfaces only used by programs - that require that specific GL implementation. So, for - example, libgl1-mesa-glx may use the - following symbols file: - -libGL.so.1 libgl1 -| libgl1-mesa-glx #MINVER# - publicGlSymbol@Base 6.3-1 - [...] - implementationSpecificSymbol@Base 6.5.2-7 1 - [...] - - Binaries or shared libraries using - only publicGlSymbol would depend only - on libgl1 (which may be provided by multiple - packages), but ones - using implementationSpecificSymbol would get a - dependency on libgl1-mesa-glx (>= 6.5.2-7) - + There are two types of ABI changes: ones that are + backward-compatible and ones that are not. An ABI change is + backward-compatible if any binary 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 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 example, changing a function to accept a new + enum constant not previously used by the library is generally + backward-compatible, but changing the members of a struct that + is passed into library functions is generally not unless the + library takes special precautions to accept old versions of + the data structure.

- Finally, the entry for the library may contain one or more - metadata fields. Currently, the only - supported field-name - is Build-Depends-Package, whose value lists - the library development - package on which packages using this shared library - declare a build dependency. If this field is - present, dpkg-shlibdeps uses it to ensure that - the resulting binary package dependency on the shared library - is at least as strict as the source package dependency on the - shared library development package. - This field should normally not be necessary, since if the - behavior of any symbol has changed, the corresponding - symbol minimal-version should have been - increased. But including it makes the symbols - system more robust by tightening the dependency in cases - where the package using the shared library specifically - requires at least a particular version of the shared library - development package for some reason. - - For our example, the zlib1g symbols file - would contain: - -* Build-Depends-Package: zlib1g-dev - + ABI changes that are not backward-compatible normally require + changing the SONAME of the library and therefore the + shared library package name, which forces rebuilding all + packages using that shared library to update their + dependencies and allow them to use the new version of the + shared library. For more information, + see . The remainder of this + section will deal with backward-compatible changes.

- Also see . -

- - - - Providing a symbols file - -

- If your package provides a shared library, you should arrange - to include a symbols control file following the - format described above in that package. You must include - either a symbols control file or - a shlibs control file. -

- -

- Normally, this is done by creating a symbols in - the source package - named debian/package.symbols - or debian/symbols, possibly - with .arch appended if the symbols - information varies by architecture. This file may use the - extended syntax documented - in . Then, - call dpkg-gensymbols as part of the package build - process. It will create symbols files in the - package staging area based on the binaries and libraries in - the package staging area and the symbols files in - the source package. - If you are - using debhelper, dh_makeshlibs will - take care of calling either dpkg-gensymbols - or generating a shlibs file as appropriate. - -

- -

- Packages that provide symbols files must keep - them up-to-date to ensure correct dependencies in packages - that use the shared libraries. This means updating - the symbols file whenever a new public symbol is - added, changing the minimal-version field whenever - a symbol changes behavior or signature, and changing - the library-soname - and main-dependency-template, and probably all of - the minimal-version fields, when the library - changes SONAME. Removing a public symbol from - the symbols file because it's no longer provided - by the library normally requires changing the SONAME - of the library. See . + Backward-compatible changes require either updating or + recording the minimal-version for that symbol + in symbols files or updating the version in + the dependencies in shlibs files. For + more information on how to do this in the two formats, see + and . Below are general + rules that apply to both files.

- Special care should be taken in updating - the minimal-version field when the behavior of a - public symbol changes. This is easy to neglect, since there - is no automated method of determining such changes, but - failing to update minimal-version in this case may + The easy case is when a public symbol is added. Simply add + the version at which the symbol was introduced + (for symbols files) or update the dependency + version (for shlibs) files. But special care + should be taken to update dependency versions when the + behavior of a public symbol changes. This is easy to neglect, + since there is no automated method of determining such + changes, but failing to update versions in this case may result in binary packages with too-weak dependencies that will fail at runtime, possibly in ways that can cause security vulnerabilities. If the package maintainer believes that a symbol behavior change may have occurred but isn't sure, it's - safer to update the minimal-version of all possibly - affected symbols to the current upstream version rather than - leave them unmodified. This may result in unnecessarily - strict dependencies, but it ensures that packages whose - dependencies are satisfied will work properly. + safer to update the version rather than leave it unmodified. + This may result in unnecessarily strict dependencies, but it + ensures that packages whose dependencies are satisfied will + work properly.

- A common example of when a change - to minimal-version is required is a function that - takes an enum or struct argument that controls what the - function does. For example: + A common example of when a change to the is required is a + function that takes an enum or struct argument that controls + what the function does. For example: -enum library_op { OP_FOO, OP_BAR }; -int library_do_operation(enum library_op); + enum library_op { OP_FOO, OP_BAR }; + int library_do_operation(enum library_op); If a new operation, OP_BAZ, is added, the minimal-version - of library_do_operation must be increased to the + of library_do_operation (for symbols + files) or the version in the dependency for the shared library + (for shlibs files) must be increased to the version at which OP_BAZ was introduced. Otherwise, a binary built against the new version of the library (having detected at compile-time that the library @@ -6321,275 +6087,589 @@ int library_do_operation(enum library_op);

- The minimal-version field normally should not - contain the Debian revision of the package, since the library - behavior is normally fixed for a particular upstream version - and any Debian packaging of that upstream version will have - the same behavior. In the rare case that the library behavior - was changed in a particular Debian revision, - appending ~ to the end of - the minimal-version that includes the Debian - revision is recommended, since this allows backports of the - shared library package using the normal backport versioning - convention to satisfy the dependency. + Dependency versions in either symbols + or shlibs files normally should not contain the + Debian revision of the package, since the library behavior is + normally fixed for a particular upstream version and any + Debian packaging of that upstream version will have the same + behavior. In the rare case that the library behavior was + changed in a particular Debian revision, appending ~ + to the end of the version that includes the Debian revision is + recommended, since this allows backports of the shared library + package using the normal backport versioning convention to + satisfy the dependency.

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

- The shlibs system is an alternative to - the symbols system for declaring dependencies for - shared libraries. It predated the symbols system and - is therefore frequently seen in older packages. It is also - required for udebs, which do not support symbols. -

+

+ In the following sections, we will first describe where the + various symbols files are to be found, then + the symbols file format, and finally how to + create symbols files if your package contains a + shared library. +

-

- shlibs files do not provide as detailed of - information as symbols files. They only provide - information about the library as a whole, not individual - symbols, and therefore have to force tighter dependencies since - they have no way of relaxing dependencies for binaries and - libraries that only use symbols whose behavior has not changed. - Because of this, and because of some problems with - how shlibs files represent the - library SONAME, symbols files are - recommended instead for any shared library package that isn't a - udeb. -

+ + The symbols files present on the + system -

- In the following sections, we will first describe where the - various shlibs files are to be found, then how to - use dpkg-shlibdeps, and finally - the shlibs file format and how to create them if - your package contains a shared library. Much of the information - about shlibs files is the same as - for symbols files, so only the differences will be - mentioned. -

+

+ symbols files for a shared library are normally + provided by the shared library package, but there are + several override paths that are checked first in case that + information is wrong or missing. The following list gives + them in the order in which they are read + by dpkg-shlibdeps The first one that contains + the required information is used. + + +

debian/*/DEBIAN/symbols

+ +

+ During the package build, if the package itself + contains shared libraries with symbols + files, they will be generated in these staging + directories + by dpkg-gensymbols. symbols + files found in the build tree take precedence + over symbols files from other binary + packages. +

+ +

+ These files must exist + before dpkg-shlibdeps is run or the + dependencies of binaries and libraries from a source + package on other libraries from that same source + package will not be correct. In practice, this means + that dpkg-gensymbols must be run + before dpkg-shlibdeps during the package + build. + An example may clarify. Suppose the source + package foo generates two binary + packages, libfoo2 and foo-runtime. + When building the binary packages, the contents of + the packages are staged in the + directories debian/libfoo2 + and debian/foo-runtime respectively. + (debian/tmp could be used instead of + one of these.) Since libfoo2 provides + the libfoo shared library, it will contain + a symbols file, which will be installed + in debian/libfoo2/DEBIAN/symbols, + eventually to be included as a control file in that + package. When dpkg-shlibdeps is run on + the + executable debian/foo-runtime/usr/bin/foo-prog, + it will examine + the debian/libfoo2/DEBIAN/symbols file + to determine whether foo-prog's library + dependencies are satisfied by any of the libraries + provided by libfoo2. Since those binaries + were linked against the just-built shared library as + part of the build process, the symbols + file for the newly-built libfoo2 must take + precedence over a symbols file for any + other libfoo2 package already installed on + the system. + +

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

+ /etc/dpkg/symbols/package.symbols.arch + and /etc/dpkg/symbols/package.symbols +

+ +

+ Per-system overrides of shared library dependencies. + These files normally do not exist. They are + maintained by the local system administrator and must + not be created by any Debian package. +

+ -

- There are several places where shlibs files are - found. The following list gives them in the order in which - they are read by dpkg-shlibdeps. (The first one - which gives the required information is used.) - - -

debian/shlibs.local

+ +

symbols control files for packages + installed on the system

+ +

+ The symbols control files for all the + packages currently installed on the system are + searched last. This will be the most common source of + shared library dependency information. These are + normally found + in /var/lib/dpkg/info/*.symbols, but + packages should not rely on this and instead should + use dpkg-query --control-path package + symbols if for some reason these files need to be + examined. +

+ + +

-

- This lists overrides for this package. This file should - normally not be used, but may be needed temporarily in - unusual situations to work around bugs in other - packages, or in unusual cases where the normally - declared dependency information in the - installed shlibs file for a library cannot - be used. This file overrides information obtained from - any other source. -

- +

+ Be aware that if a debian/shlibs.local exists + in the source package, it will override + any symbols files. This is the only case where + a shlibs is used despite symbols + files being present. See + and for more information. +

+ - -

/etc/dpkg/shlibs.override

+ + The symbols File Format -

- This lists global overrides. This list is normally - empty. It is maintained by the local system - administrator. -

- +

+ The following documents the format of + the symbols control file as included in binary + packages. These files are built from + template symbols files in the source package + by dpkg-gensymbols. The template files support + a richer syntax that allows dpkg-gensymbols to + do some of the tedious work involved in + maintaining symbols files, such as handling C++ + symbols or optional symbols that may not exist on particular + architectures. When writing symbols files for + a shared library package, refer + to for the + richer syntax. +

- -

DEBIAN/shlibs files in the "build - directory"

+

+ A symbols may contain one or more entries, one + for each shared library contained in the package + corresponding to that symbols. Each entry has + the following format: +

-

- These files are generated as part of the package build - process and staged for inclusion as control files in the - binary packages being built. They provide details of - any shared libraries included in the same package. -

- +

+ + library-soname main-dependency-template + [| alternative-dependency-template] + [...] + [* field-name: field-value] + [...] + symbol minimal-version[ id-of-dependency-template ] + +

- -

shlibs control files for packages - installed on the system

+

+ To explain this format, we'll use the the zlib1g + package as an example, which (at the time of writing) + installs the shared + library /usr/lib/libz.so.1.2.3.4. Mandatory + lines will be described first, followed by optional lines. +

-

- The shlibs control files for all the - packages currently installed on the system. These are - normally found - in /var/lib/dpkg/info/*.symbols, but - packages should not rely on this and instead should - use dpkg-query --control-path package - shlibs if for some reason these files need to be - examined. -

- +

+ library-soname must contain exactly the value of + the ELF SONAME attribute of the shared library. In + our example, this is libz.so.1. + This can be determined by using the command + + readelf -d /usr/lib/libz.so.1.2.3.4 | grep SONAME + + +

- -

/etc/dpkg/shlibs.default

+

+ main-dependency-template has the same syntax as a + dependency field in a binary package control file, except + that the string #MINVER# is replaced by a version + restriction like (>= version) or by + nothing if an unversioned dependency is deemed sufficient. + The version restriction will be based on which symbols from + the shared library are referenced and the version at which + they were introduced (see below). In nearly all + cases, main-dependency-template will + be package #MINVER#, + where package is the name of the binary package + containing the shared library. This adds a simple, + possibly-versioned dependency on the shared library package. + In some rare cases, such as when multiple packages provide + the same shared library ABI, the dependency template may + need to be more complex. +

-

- This file lists any shared libraries whose packages have - failed to provide correct shlibs files. It - was used when the shlibs setup was first - introduced, but it is now normally empty. It is - maintained by the dpkg maintainer. -

- - -

+

+ In our example, the first line of + the zlib1g symbols file would be: + + libz.so.1 zlib1g #MINVER# + +

-

- If a symbols file for a shared library package - is available, dpkg-shlibdeps will always use it - in preference to a shlibs, with the exception - of debian/shlibs.local. The latter overrides any - other shlibs or symbols files. -

- +

+ Each public symbol exported by the shared library must have + a corresponding symbol line, indented by one + space. symbol is the exported symbol (which, for + C++, means the mangled symbol) followed by @ and + the symbol version, or the string Base if there is + no symbol version. minimal-version is the most + recent version of the shared library that changed the + behavior of that symbol, whether by adding it, changing its + function signature (the parameters, their types, or the + return type), or its behavior in a way that is visible to a + caller. id-of-dependency-template is an optional + field that references + an alternative-dependency-template; see below for + a full description. +

- - How to use dpkg-shlibdeps and the - shlibs files +

+ For example, libz.so.1 contains the + symbols compress + and compressBound. compress has no symbol + version and last changed its behavior in upstream + version 1:1.1.4. compressBound has the + symbol version ZLIB_1.2.0, was introduced in + upstream version 1:1.2.0, and has not changed its + behavior. Its symbols file therefore contains + the lines: + + compress@Base 1:1.1.4 + compressBound@ZLIB_1.2.0 1:1.2.0 + + Packages using only compress would then get a + dependency of zlib1g (>= 1:1.1.4), but packages + using compressBound would get a dependency + of zlib1g (>= 1:1.2.0). +

-

- Use of dpkg-shlibdeps with shlibs - files is generally the same as with symbols - files. See . -

+

+ One or more alternative-dependency-template lines + may be provided. These are used in cases where some symbols + in the shared library should use one dependency template + while others should use a different template. The + alternative dependency templates are used only if a symbol + line contains the id-of-dependency-template + field. The first alternative dependency template is + numbered 1, the second 2, and so forth. + An example of where this may be needed is with a library + that implements the libGL interface. All GL + implementations provide the same set of base interfaces, + and then may provide some additional interfaces only used + by programs that require that specific GL implementation. + So, for example, libgl1-mesa-glx may use the + following symbols file: + + libGL.so.1 libgl1 + | libgl1-mesa-glx #MINVER# + publicGlSymbol@Base 6.3-1 + [...] + implementationSpecificSymbol@Base 6.5.2-7 1 + [...] + + Binaries or shared libraries using + only publicGlSymbol would depend only + on libgl1 (which may be provided by multiple + packages), but ones + using implementationSpecificSymbol would get a + dependency on libgl1-mesa-glx (>= 6.5.2-7) + +

-

- If you are creating a udeb for use in the Debian Installer, - you will need to specify that dpkg-shlibdeps - should use the dependency line of type udeb by - adding the -tudeb option - dh_shlibdeps from the debhelper suite - will automatically add this option if it knows it is - processing a udeb. - . If there is no dependency line of - type udeb in the shlibs - file, dpkg-shlibdeps will fall back to the - regular dependency line. -

+

+ Finally, the entry for the library may contain one or more + metadata fields. Currently, the only + supported field-name + is Build-Depends-Package, whose value lists + the library development + package on which packages using this shared library + declare a build dependency. If this field is + present, dpkg-shlibdeps uses it to ensure that + the resulting binary package dependency on the shared + library is at least as strict as the source package + dependency on the shared library development + package. + This field should normally not be necessary, since if the + behavior of any symbol has changed, the corresponding + symbol minimal-version should have been + increased. But including it makes the symbols + system more robust by tightening the dependency in cases + where the package using the shared library specifically + requires at least a particular version of the shared + library development package for some reason. + + For our example, the zlib1g symbols + file would contain: + + * Build-Depends-Package: zlib1g-dev + +

+ +

+ Also see . +

+ + + + Providing a symbols file + +

+ If your package provides a shared library, you should + arrange to include a symbols control file + following the format described above in that package. You + must include either a symbols control file or + a shlibs control file. +

+ +

+ Normally, this is done by creating a symbols in + the source package + named debian/package.symbols + or debian/symbols, possibly + with .arch appended if the symbols + information varies by architecture. This file may use the + extended syntax documented in . Then, call dpkg-gensymbols as + part of the package build process. It will + create symbols files in the package staging + area based on the binaries and libraries in the package + staging area and the symbols files in the + source package. + If you are + using debhelper, dh_makeshlibs will + take care of calling either dpkg-gensymbols + or generating a shlibs file as appropriate. + +

+ +

+ Packages that provide symbols files must keep + them up-to-date to ensure correct dependencies in packages + that use the shared libraries. This means updating + the symbols file whenever a new public symbol + is added, changing the minimal-version field + whenever a symbol changes behavior or signature in a + backward-compatible way (see ), + and changing the library-soname + and main-dependency-template, and probably all of + the minimal-version fields, when the library + changes SONAME. Removing a public symbol from + the symbols file because it's no longer + provided by the library normally requires changing + the SONAME of the library. + See for more information + on SONAMEs. +

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

- Each shlibs file has the same format. Lines - beginning with # are considered to be comments and - are ignored. Each line is of the form: - -[type: ]library-name soname-version dependencies ... - + The shlibs system is an simpler alternative to + the symbols system for declaring dependencies for + shared libraries. It may be more appropriate for C++ + libraries and other cases where tracking individual symbols is + too difficult. It predated the symbols system and is + therefore frequently seen in older packages. It is also + required for udebs, which do not support symbols.

- We will explain this by reference to the example of the - zlib1g package, which (at the time of writing) - installs the shared - library /usr/lib/libz.so.1.2.3.4. + In the following sections, we will first describe where the + various shlibs files are to be found, then how to + use dpkg-shlibdeps, and finally + the shlibs file format and how to create them.

-

- type is an optional element that indicates the type - of package for which the line is valid. The only type - currently in use is udeb. The colon and space after - the type are required. -

+ + The shlibs files present on the + system -

- library-name is the name of the shared library, in - this case libz. (This must match the name part of - the soname, see below.) -

+

+ There are several places where shlibs files are + found. The following list gives them in the order in which + they are read by dpkg-shlibdeps. (The first + one which gives the required information is used.) + + +

debian/shlibs.local

+ +

+ This lists overrides for this package. This file + should normally not be used, but may be needed + temporarily in unusual situations to work around bugs + in other packages, or in unusual cases where the + normally declared dependency information in the + installed shlibs file for a library + cannot be used. This file overrides information + obtained from any other source. +

+ -

- soname-version is the version part of the - ELF SONAME attribute of the library. - The SONAME is the thing that must exactly match for - the library to be recognized by the dynamic linker, and is - usually of the - form name.so.major-version, in - our example, libz.so.1. - The version part is the part which comes after - .so., so in our case, it is 1. The soname - may instead be of the - form name-major-version.so, - such as libdb-5.1.so, in which case the name would - be libdb and the version would be 5.1. -

+ +

/etc/dpkg/shlibs.override

-

- dependencies has the same syntax as a dependency - field in a binary package control file. It should give - details of which packages are required to satisfy a binary - built against the version of the library contained in the - package. See for details. -

+

+ This lists global overrides. This list is normally + empty. It is maintained by the local system + administrator. +

+ -

- In our example, if the last change to the zlib1g - package that could change behavior for a client of that - library was in version 1:1.2.3.3.dfsg-1, then - the shlibs entry for this library could say: - -libz 1 zlib1g (>= 1:1.2.3.3.dfsg-1) - - This version restriction must be new enough that any binary - built against the current version of the library will work - with any version of the shared library that satisfies that - dependency. -

+ +

DEBIAN/shlibs files in the "build + directory"

+ +

+ These files are generated as part of the package build + process and staged for inclusion as control files in + the binary packages being built. They provide details + of any shared libraries included in the same package. +

+ -

- As zlib1g also provides a udeb containing the shared library, - there would also be a second line: - -udeb: libz 1 zlib1g-udeb (>= 1:1.2.3.3.dfsg-1) - -

- + +

shlibs control files for packages + installed on the system

+ +

+ The shlibs control files for all the + packages currently installed on the system. These are + normally found + in /var/lib/dpkg/info/*.symbols, but + packages should not rely on this and instead should + use dpkg-query --control-path package + shlibs if for some reason these files need to be + examined. +

+ - - Providing a shlibs file - -

- To provide a shlibs file for a shared library - binary package, create a shlibs file following - the format described above and place it in - the DEBIAN directory for that package during the - build. It will then be included as a control file for that - package - This is what dh_makeshlibs in - the debhelper suite does. If your package - also has a udeb that provides a shared - library, dh_makeshlibs can automatically - generate the udeb: lines if you specify the name of - the udeb with the --add-udeb option. - . -

+ +

/etc/dpkg/shlibs.default

+ +

+ This file lists any shared libraries whose packages + have failed to provide correct shlibs + files. It was used when the shlibs setup + was first introduced, but it is now normally empty. + It is maintained by the dpkg maintainer. +

+ + +

-

- Since dpkg-shlibdeps reads - the DEBIAN/shlibs files in all of the binary - packages being built from this source package, all of - the DEBIAN/shlibs files should be installed - before dpkg-shlibdeps is called on any of the - binary packages. -

+

+ If a symbols file for a shared library package + is available, dpkg-shlibdeps will always use it + in preference to a shlibs, with the exception + of debian/shlibs.local. The latter overrides + any other shlibs or symbols files. +

+ + + + The shlibs File Format + +

+ Each shlibs file has the same format. Lines + beginning with # are considered to be comments and + are ignored. Each line is of the form: + + [type: ]library-name soname-version dependencies ... + +

+ +

+ We will explain this by reference to the example of the + zlib1g package, which (at the time of writing) + installs the shared + library /usr/lib/libz.so.1.2.3.4. +

+ +

+ type is an optional element that indicates the + type of package for which the line is valid. The only type + currently in use is udeb. The colon and space + after the type are required. +

+ +

+ library-name is the name of the shared library, + in this case libz. (This must match the name part + of the soname, see below.) +

+ +

+ soname-version is the version part of the + ELF SONAME attribute of the library, determined the + same way that the soversion component of the + recommended shared library package name is determined. + See for the details. +

+ +

+ dependencies has the same syntax as a dependency + field in a binary package control file. It should give + details of which packages are required to satisfy a binary + built against the version of the library contained in the + package. See for details on the + syntax, and for details on how + to maintain the dependency version constraint. +

+ +

+ In our example, if the last change to the zlib1g + package that could change behavior for a client of that + library was in version 1:1.2.3.3.dfsg-1, then + the shlibs entry for this library could say: + + libz 1 zlib1g (>= 1:1.2.3.3.dfsg-1) + + This version restriction must be new enough that any binary + built against the current version of the library will work + with any version of the shared library that satisfies that + dependency. +

+ +

+ As zlib1g also provides a udeb containing the shared + library, there would also be a second line: + + udeb: libz 1 zlib1g-udeb (>= 1:1.2.3.3.dfsg-1) + +

+ + + + Providing a shlibs file + +

+ To provide a shlibs file for a shared library + binary package, create a shlibs file following + the format described above and place it in + the DEBIAN directory for that package during + the build. It will then be included as a control file for + that package + This is what dh_makeshlibs in + the debhelper suite does. If your + package also has a udeb that provides a shared + library, dh_makeshlibs can automatically + generate the udeb: lines if you specify the name + of the udeb with the --add-udeb option. + . +

+ +

+ Since dpkg-shlibdeps reads + the DEBIAN/shlibs files in all of the binary + packages being built from this source package, all of + the DEBIAN/shlibs files should be installed + before dpkg-shlibdeps is called on any of the + binary packages. +

+ @@ -8188,7 +8268,7 @@ INSTALL = install -s # (or use strip on the files in debian/tmp) must be linked against all libraries that they use symbols from in the same way that binaries are. This ensures the correct functioning of the symbols - and shlibs + and shlibs systems and guarantees that all libraries can be safely opened with dlopen(). Packagers may wish to use the gcc option -Wl,-z,defs when building a shared library.