- 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.
- </footnote>
- For our example, the <tt>zlib1g</tt> <file>symbols</file> file
- would contain:
- <example compact="compact">
- * Build-Depends-Package: zlib1g-dev
- </example>
- (Don't forget the leading space.)