(debian-policy.info)The symbols File Format

---

Next: Providing a symbols file Prev: The symbols files present on the system Up: The symbols system

---

Enter node , (file) or (file)node

8.6.3.2 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 dpkg-gensymbols(1) 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 ‘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’.
(1)

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

In our example, the first line of the ‘zlib1g’ ‘symbols’ file would be:

     libz.so.1 zlib1g #MINVER#

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 changing 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 on ‘zlib1g
(>= 1:1.1.4)’, but packages using ‘compressBound’ would get a dependency
on ‘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.  (2)

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 Note: 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.  (3) For our example, the ‘zlib1g’
‘symbols’ file would contain:

     * Build-Depends-Package: zlib1g-dev

Also see ‘deb-symbols(5)’.

   ---------- Footnotes ----------

   (1) This can be determined by using the command

     readelf -d /usr/lib/libz.so.1.2.3.4 | grep SONAME

   (2) 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)’.

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