+ <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.
+ </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 space before the <tt>*</tt> so that it will
+ be parsed as part of the entry for that library.)
+ </p>
+
+ <p>
+ Also see <manref name="deb-symbols" section="5">.
+ </p>
+ </sect1>
+
+ <sect1 id="providing-symbols">
+ <heading>Providing a <file>symbols</file> file</heading>
+
+ <p>
+ If your package provides a shared library, you should arrange
+ to include a <file>symbols</file> control file following the
+ format described above in that package. You must include
+ either a <file>symbols</file> control file or
+ a <file>shlibs</file> control file.
+ </p>
+
+ <p>
+ Normally, this is done by creating a <file>symbols</file> in
+ the source package
+ named <file>debian/<var>package</var>.symbols</file>
+ or <file>debian/symbols</file>, possibly
+ with <file>.<var>arch</var></file> appended if the symbols
+ information varies by architecture. This file may use the
+ extended syntax documented
+ in <manref name="dpkg-gensymbols" section="1">. Then,
+ call <prgn>dpkg-gensymbols</prgn> as part of the package build
+ process. It will create <file>symbols</file> files in the
+ package staging area based on the binaries and libraries in
+ the package staging area and the <file>symbols</file> files in
+ the source package.<footnote>
+ If you are
+ using <tt>debhelper</tt>, <prgn>dh_makeshlibs</prgn> will
+ take care of calling either <prgn>dpkg-gensymbols</prgn>
+ or generating a <file>shlibs</file> file as appropriate.
+ </footnote>
+ </p>
+
+ <p>
+ Packages that provide <file>symbols</file> files must keep
+ them up-to-date to ensure correct dependencies in packages
+ that use the shared libraries. This means updating
+ the <file>symbols</file> file whenever a new public symbol is
+ added, changing the <var>minimal-version</var> field whenever
+ a symbol changes behavior or signature, and changing
+ the <var>library-soname</var>
+ and <var>main-dependency-template</var>, and probably all of
+ the <var>minimal-version</var> fields, when the library
+ changes <tt>SONAME</tt>. Removing a public symbol from
+ the <file>symbols</file> file because it's no longer provided
+ by the library normally requires changing the <tt>SONAME</tt>
+ of the library. See <ref id="sharedlibs-runtime">.
+ </p>
+
+ <p>
+ Special care should be taken in updating
+ the <var>minimal-version</var> 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 <var>minimal-version</var> 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 <var>minimal-version</var> 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.
+ </p>
+
+ <p>
+ A common example of when a change
+ to <var>minimal-version</var> is required is a function that
+ takes an enum or struct argument that controls what the
+ function does. For example:
+ <example>
+enum library_op { OP_FOO, OP_BAR };
+int library_do_operation(enum library_op);
+ </example>
+ If a new operation, <tt>OP_BAZ</tt>, is added,
+ the <var>minimal-version</var>
+ of <tt>library_do_operation</tt> must be increased to the
+ version at which <tt>OP_BAZ</tt> was introduced. Otherwise, a
+ binary built against the new version of the library (having
+ detected at compile-time that the library
+ supports <tt>OP_BAZ</tt>) may be installed with a shared
+ library that doesn't support <tt>OP_BAZ</tt> and will fail at
+ runtime when it tries to pass <tt>OP_BAZ</tt> into this
+ function.
+ </p>
+
+ <p>
+ The <var>minimal-version</var> 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 <tt>~</tt> to the end of
+ the <var>minimal-version</var> 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.
+ </p>
+ </sect1>
+ </sect>
+
+ <sect id="sharedlibs-shlibdeps">
+ <heading>Dependencies between the library and other packages -
+ the <tt>shlibs</tt> system</heading>