- In our example, the first line of
- the <tt>zlib1g</tt> <file>symbols</file> file would be:
- <example compact="compact">
-libz.so.1 zlib1g #MINVER#
- </example>
- </p>
-
- <p>
- Each public symbol exported by the shared library must have a
- corresponding symbol line, indented by one
- space. <var>symbol</var> is the exported symbol (which, for
- C++, means the mangled symbol) followed by <tt>@</tt> and the
- symbol version, or the string <tt>Base</tt> if there is no
- symbol version. <var>minimal-version</var> 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. <var>id-of-dependency-template</var> is an optional
- field that references
- an <var>alternative-dependency-template</var>; see below for a
- full description.
- </p>
-
- <p>
- For example, <tt>libz.so.1</tt> contains the
- symbols <tt>compress</tt>
- and <tt>compressBound</tt>. <tt>compress</tt> has no symbol
- version and last changed its behavior in upstream
- version <tt>1:1.1.4</tt>. <tt>compressBound</tt> has the
- symbol version <tt>ZLIB_1.2.0</tt>, was introduced in upstream
- version <tt>1:1.2.0</tt>, and has not changed its behavior.
- Its <file>symbols</file> file therefore contains the lines:
- <example compact="compact">
- compress@Base 1:1.1.4
- compressBound@ZLIB_1.2.0 1:1.2.0
- </example>
- Packages using only <tt>compress</tt> would then get a
- dependency of <tt>zlib1g (>= 1:1.1.4)</tt>, but packages
- using <tt>compressBound</tt> would get a dependency
- of <tt>zlib1g (>= 1:1.2.0)</tt>.
- </p>
-
- <p>
- One or more <var>alternative-dependency-template</var> 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 <var>id-of-dependency-template</var> field. The first
- alternative dependency template is numbered 1, the second 2,
- and so forth.<footnote>
- 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 <file>symbols</file> file:
- <example>
-libGL.so.1 libgl1
-| libgl1-mesa-glx #MINVER#
- publicGlSymbol@Base 6.3-1
- [...]
- implementationSpecificSymbol@Base 6.5.2-7 1
- [...]
- </example>
- Binaries or shared libraries using
- only <tt>publicGlSymbol</tt> would depend only
- on <tt>libgl1</tt> (which may be provided by multiple
- packages), but ones
- using <tt>implementationSpecificSymbol</tt> would get a
- dependency on <tt>libgl1-mesa-glx (>= 6.5.2-7)</tt>
- </footnote>
- </p>
-
- <p>
- Finally, the entry for the library may contain one or more
- metadata fields. Currently, the only
- supported <var>field-name</var>
- is <tt>Build-Depends-Package</tt>, whose value lists
- the <qref id="sharedlibs-dev">library development
- package</qref> on which packages using this shared library
- declare a build dependency. If this field is
- present, <prgn>dpkg-shlibdeps</prgn> 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.<footnote>
- This field should normally not be necessary, since if the
- behavior of any symbol has changed, the corresponding
- symbol <var>minimal-version</var> should have been
- increased. But including it makes the <tt>symbols</tt>
- 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.
+ We say that a binary <tt>foo</tt> <em>directly</em> uses a
+ library <tt>libbar</tt> if it is explicitly linked with that
+ library (that is, the library is listed in the
+ ELF <tt>NEEDED</tt> attribute, caused by adding <tt>-lbar</tt>
+ to the link line when the binary is created). Other libraries
+ that are needed by <tt>libbar</tt> are
+ linked <em>indirectly</em> to <tt>foo</tt>, and the dynamic
+ linker will load them automatically when it
+ loads <tt>libbar</tt>. A package should depend on the
+ libraries it directly uses, but not the libraries it only uses
+ indirectly. The dependencies for the libraries used
+ directly will automatically pull in the indirectly-used
+ libraries. <prgn>dpkg-shlibdeps</prgn> 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.
+ <footnote>
+ A good example of where this helps is the following. We
+ could update <tt>libimlib</tt> 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 <package>libdgf4</package> instead of
+ the older <package>libdgf3</package>. If we
+ used <prgn>ldd</prgn> to add dependencies for every library
+ directly or indirectly linked with a binary, every package
+ that uses <tt>libimlib</tt> would need to be recompiled so
+ it would also depend on <package>libdgf4</package> in order
+ to retire the older <package>libdgf3</package> package.
+ Since dependencies are only added based on
+ ELF <tt>NEEDED</tt> attribute, packages
+ using <tt>libimlib</tt> can rely on <tt>libimlib</tt> itself
+ having the dependency on an appropriate version
+ of <tt>libdgf</tt> and do not need rebuilding.