[Date Prev][Date Next] [Thread Prev][Thread Next] [Date Index] [Thread Index]

Re: Bug#571776: document symbols

Hello folks,

I took some time today and wrote a first draft of a new section of Policy
documenting symbols files, and the revisions to shlibs for their
interaction.  Please review.  There's quite a lot of material here,
including details from dpkg-shlibdeps, dpkg-gensymbols, and deb-symbols
documentation as well as additional requirements and recommendations
around how to maintain the minimal-version field.

I tried sending a unified diff, but the new sections are largely
unreadable since they're intermixed with the old sections being removed.
Hence, for review purposes, here are the symbols and shlibs sections in
their entirety, followed by a diff for the changes elsewhere in Policy.
You can also refer to branch bug571776-rra in the Policy repository.

      <sect id="sharedlibs-symbols">
	<heading>Dependencies between the library and other packages -
	the <tt>symbols</tt> system</heading>

	  If a package contains a binary or library which links to a
	  shared library, we must ensure that, when the package is
	  installed on the system, all of the libraries needed are also
	  installed.  These dependencies must be added to the binary
	  package when it is built, since they may change based on which
	  version of a shared library the binary or library was linnked
	  with.  To allow these dependencies to be constructed, shared
	  libraries must provide either a <file>symbols</file> file or
	  a <file>shlibs</file> file, which provide information on the
	  package dependencies required to ensure the presence of this
	  library.  Any package which uses a shared library must use these
	  files to determine the required dependencies when it is built.

	  <file>shlibs</file> files were the original mechanism for
	  handling library dependencies.  They are documented
	  in <ref id="sharedlibs-shlibdeps">.  <file>symbols</file> 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, <file>shlibs</file> files must be used
	  for udebs.  Packages which provide a <file>symbols</file> file
	  are not required to provide a <file>shlibs</file> file.

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

	  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 indirectly uses.  The
	  dependencies for those libraries will automatically pull in the
	  other 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.
	    A good example of where this helps is the following.  We could
	    update <tt>libimlib</tt> with a new version that supports a
	    new graphics format called dgf (but retaining the same major
	    version number) and depends on <tt>libdgf</tt>.  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 <tt>libdgf</tt> or it wouldn't run due to
	    missing symbols.  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 <tt>libdgf</tt> and so they would not
	    need rebuilding.

	  In the following sections, we will first describe where the
	  various <file>symbols</file> files are to be found, then how to
	  use <prgn>dpkg-shlibdeps</prgn>, and finally
	  the <file>symbols</file> file format and how to create them if
	  your package contains a shared library.

	<sect1 id="symbols-paths">
	  <heading>The <file>symbols</file> files present on the

	    <file>symbols</file> 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 <prgn>dpkg-shlibdeps</prgn>
	    The first one that contains the required information is used.

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

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

		  and <file>/etc/dpkg/symbols/<var>package</var>.symbols</file>

		  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.

		<p><file>symbols</file> control files for packages
		installed on the system</p>

		  The <file>symbols</file> 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 <file>/var/lib/dpkg/info/*.symbols</file>, but
		  packages should not rely on this and instead should
		  use <tt>dpkg-query --control-path <var>package</var>
		  symbols</tt> if for some reason these files need to be

	    Be aware that if a <file>debian/shlibs.local</file> exists in
	    the source package, it will override any <file>symbols</file>
	    files.  This is the only case where a <file>shlibs</file> is
	    used despite <file>symbols</file> files being present.  See
	    <ref id="shlibs-paths"> and <ref id="sharedlibs-shlibdeps">
	    for more information.

	<sect1 id="dpkg-shlibdeps">
	  <heading>How to use <prgn>dpkg-shlibdeps</prgn> and the
	    <tt>symbols</tt> files</heading>

	    If your package contains any compiled binaries or shared
	    libraries, put a call to <prgn>dpkg-shlibdeps</prgn> into
	    your <file>debian/rules</file> file in the source package.
	    List all of the compiled binaries, libraries, or loadable
	    modules in your package.  If your source package builds only a
	    single binary package that contains only compiled binaries and
	    libraries (but no scripts) and is not multiarch, you can use a
	    command such as:
	    <example compact="compact">
dpkg-shlibdeps debian/tmp/usr/bin/* debian/tmp/usr/sbin/* \
	    but normally finding all of the binaries is more
	      The easiest way to do this is to use a package helper
	      framework such as <tt>debhelper</tt>.  If you are
	      using <tt>debhelper</tt>, the <prgn>dh_shlibdeps</prgn>
	      program will do this work for you.  It will also correctly
	      handle multi-binary packages.

	    This command puts the dependency information into
	    the <file>debian/substvars</file> file, which is then used
	    by <prgn>dpkg-gencontrol</prgn>.  You will need to place
	    a <tt>${shlibs:Depends}</tt> variable in the <tt>Depends</tt>
	    field in the control file of every binary package built by
	    this source package that contains compiled binaries,
	    libraries, or loadable modules.  If you have multiple binary
	    packages, you will need to call <prgn>dpkg-shlibdeps</prgn> on
	    each one which contains compiled libraries or binaries, using
	    the <tt>-T</tt> option to the <tt>dpkg</tt> utilities to
	    specify a different <file>substvars</file> file for each
	    binary package.<footnote>
	      Again, <prgn>dh_shlibdeps</prgn>
	      and <prgn>dh_gencontrol</prgn> will handle all of this for
	      you if you're using <tt>debhelper</tt>.

	    For more details on <prgn>dpkg-shlibdeps</prgn>,
	    see <manref name="dpkg-shlibdeps" section="1">.

	<sect1 id="symbols">
	  <heading>The <file>symbols</file> File Format</heading>

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

	    A <file>symbols</file> may contain one or more entries, one
	    for each shared library contained in the package corresponding
	    to that <file>symbols</file>.  Each entry has the following

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

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

	    <var>library-soname</var> must contain exactly the value of
	    the ELF <tt>SONAME</tt> attribute of the shared library.  In
	    our example, this is <tt>libz.so.1</tt>.<footnote>
	      This can be determined by using the command
	      <example compact="compact">
readelf -d /usr/lib/libz.so. | grep SONAME

	    <var>main-dependency-template</var> has the same syntax as a
	    dependency field in a binary package control file, except that
	    the string <tt>#MINVER#</tt> is replaced by a version
	    restriction like <tt>(>= <var>version</var>)</tt> 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, <var>main-dependency-template</var> will
	    be <tt><var>package</var> #MINVER#</tt>,
	    where <var>package</var> 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 <tt>zlib1g</tt> <file>symbols</file> file would be:
	    <example compact="compact">
libz.so.1 zlib1g #MINVER#

	    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.

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

	    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:
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 <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>

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

	    Also see <manref name="deb-symbols" section="5">.

	<sect1 id="providing-symbols">
	  <heading>Providing a <file>symbols</file> file</heading>

	    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.

	    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.

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

	    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.

	    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:
enum library_op { OP_FOO, OP_BAR };
int library_do_operation(enum library_op);
	    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

	    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.

      <sect id="sharedlibs-shlibdeps">
	<heading>Dependencies between the library and other packages -
	the <tt>shlibs</tt> system</heading>

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

	  <file>shlibs</file> files do not provide as detailed of
	  information as <file>symbols</file> 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 <file>shlibs</file> files represent the
	  library <tt>SONAME</tt>, <file>symbols</file> files are
	  recommended instead for any shared library package that isn't a

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

	<sect1 id="shlibs-paths">
	  <heading>The <file>shlibs</file> files present on the

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

		  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 <file>shlibs</file> file for a library cannot
		  be used.  This file overrides information obtained from
		  any other source.


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

		<p><file>DEBIAN/shlibs</file> files in the "build

		  When packages are being built,
		  any <file>debian/shlibs</file> files are copied into the
		  control information file area of the temporary build
		  directory and given the name <file>shlibs</file>.  These
		  files give details of any shared libraries included in
		  the same package.

		<p><file>shlibs</file> control files for packages
		  installed on the system</p>

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


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

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

	  <heading>How to use <prgn>dpkg-shlibdeps</prgn> and the
	    <file>shlibs</file> files</heading>

	    Use of <prgn>dpkg-shlibdeps</prgn> with <file>shlibs</file>
	    files is generally the same as with <file>symbols</file>
	    files.  See <ref id="dpkg-shlibdeps">.

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

	<sect1 id="shlibs">
	  <heading>The <file>shlibs</file> File Format</heading>

	    Each <file>shlibs</file> file has the same format.  Lines
	    beginning with <tt>#</tt> are considered to be comments and
	    are ignored.  Each line is of the form:
	    <example compact="compact">
[<var>type</var>: ]<var>library-name</var> <var>soname-version</var> <var>dependencies ...</var>

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

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

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

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

	    <var>dependencies</var> 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 <ref id="depsyntax"> for details.

	    In our example, if the last change to the <tt>zlib1g</tt>
	    package that could change behavior for a client of that
	    library was in version <tt>1:</tt>, then
	    the <tt>shlibs</tt> entry for this library could say:
	    <example compact="compact">
libz 1 zlib1g (>= 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

	    As zlib1g also provides a udeb containing the shared library,
	    there would also be a second line:
	    <example compact="compact">
udeb: libz 1 zlib1g-udeb (>= 1:

	  <heading>Providing a <file>shlibs</file> file</heading>

	    If your package provides a shared library, you need to create
	    a <file>shlibs</file> file following the format described
	    above.  It is usual to call this
	    file <file>debian/shlibs</file> (but if you have multiple
	    binary packages, you might want to call
	    it <file>debian/<var>package</var>.shlibs</file> instead).
	    Then let <file>debian/rules</file> install it in the control
	    information file area:
	    <example compact="compact">
install -m644 debian/shlibs debian/tmp/DEBIAN
	    or, in the case of a multi-binary package:
	    <example compact="compact">
install -m644 debian/<var>package</var>.shlibs debian/<var>package</var>/DEBIAN/shlibs
	    An alternative way of doing this is to create
	    the <file>shlibs</file> file in the control information file
	    area directly from <file>debian/rules</file> without using
	    a <file>debian/shlibs</file> file at all,<footnote>
	      This is what <prgn>dh_makeshlibs</prgn> in
	      the <package>debhelper</package> suite does. If your package
	      also has a udeb that provides a shared
	      library, <prgn>dh_makeshlibs</prgn> can automatically
	      generate the <tt>udeb:</tt> lines if you specify the name of
	      the udeb with the <tt>--add-udeb</tt> option.
	    since the <file>debian/shlibs</file> file itself is ignored by

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

diff --git a/policy.sgml b/policy.sgml
index 79281e9..cca4b6d 100644
--- a/policy.sgml
+++ b/policy.sgml
@@ -840,10 +840,11 @@
 	Among those files are the package maintainer scripts
 	and <file>control</file>, the <qref id="binarycontrolfiles">binary
 	package control file</qref> that contains the control fields for
-	the package.  Other control information files
-	include <qref id="sharedlibs-shlibdeps">the <file>shlibs</file>
-	file</qref> used to store shared library dependency information
-	and the <file>conffiles</file> file that lists the package's
+	the package.  Other control information files include
+	the <qref id="sharedlibs-symbols"><file>symbols</file> file</qref>
+	or <qref id="sharedlibs-shlibdeps"><file>shlibs</file> file</qref>
+	used to store shared library dependency information and
+	the <file>conffiles</file> file that lists the package's
 	configuration files (described in <ref id="config-files">).
@@ -5521,9 +5522,9 @@ 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 <qref id="sharedlibs-shlibdeps"><tt>shlibs</tt>
-	  system</qref> or via symbols files (see
-	  <manref name="deb-symbols" section="5">).
+	  the <qref id="sharedlibs-symbols"><tt>symbols</tt> system</qref>
+	  or the <qref id="sharedlibs-shlibdeps"><tt>shlibs</tt>
+	  system</qref>.
@@ -7702,8 +8153,9 @@ INSTALL = install -s # (or use strip on the files in debian/tmp)
           Although not enforced by the build tools, shared libraries
           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 <qref id="sharedlibs-shlibdeps">shlibs</qref>
-          system and guarantees that all libraries can be safely opened
+          functioning of the <qref id="sharedlibs-symbols">symbols</qref>
+	  and <qref id="sharedlibs-shlibdeps">shlibs</qref>
+          systems and guarantees that all libraries can be safely opened
           with <tt>dlopen()</tt>.  Packagers may wish to use the gcc
           option <tt>-Wl,-z,defs</tt> when building a shared library.
           Since this option enforces symbol resolution at build time,
@@ -10481,89 +10933,6 @@ END-INFO-DIR-ENTRY
-	<sect1 id="pkg-dpkg-shlibdeps">
-	  <heading>
-	    <prgn>dpkg-shlibdeps</prgn> - calculates shared library
-	    dependencies
-	  </heading>
-	  <p>
-	    This program is usually called from <file>debian/rules</file>
-	    just before <prgn>dpkg-gencontrol</prgn> (see <ref
-	    id="pkg-sourcetree">), in the top level of the source tree.
-	  </p>
-	  <p>
-	    Its arguments are executables and shared libraries
-	    <footnote>
-	      <p>
-		They may be specified either in the locations in the
-		source tree where they are created or in the locations
-		in the temporary build tree where they are installed
-		prior to binary package creation.
-	      </p>
-	    </footnote> for which shared library dependencies should
-	    be included in the binary package's control file.
-	  </p>
-	  <p>
-	    If some of the found shared libraries should only
-	    warrant a <tt>Recommends</tt> or <tt>Suggests</tt>, or if
-	    some warrant a <tt>Pre-Depends</tt>, this can be achieved
-	    by using the <tt>-d<var>dependency-field</var></tt> option
-	    before those executable(s).  (Each <tt>-d</tt> option
-	    takes effect until the next <tt>-d</tt>.)
-	  </p>
-	  <p>
-	    <prgn>dpkg-shlibdeps</prgn> does not directly cause the
-	    output control file to be modified.  Instead by default it
-	    adds to the <file>debian/substvars</file> file variable
-	    settings like <tt>shlibs:Depends</tt>.  These variable
-	    settings must be referenced in dependency fields in the
-	    appropriate per-binary-package sections of the source
-	    control file.
-	  </p>
-	  <p>
-	    For example, a package that generates an essential part
-	    which requires dependencies, and optional parts that 
-	    which only require a recommendation, would separate those
-	    two sets of dependencies into two different fields.<footnote>
-		At the time of writing, an example for this was the
-		<package/xmms/ package, with Depends used for the xmms
-		executable, Recommends for the plug-ins and Suggests for
-		even more optional features provided by unzip.
-	    </footnote>
-            It can say in its <file>debian/rules</file>:
-	    <example>
-  dpkg-shlibdeps -dDepends <var>program anotherprogram ...</var> \
-                 -dRecommends <var>optionalpart anotheroptionalpart</var>
-	    </example>
-	    and then in its main control file <file>debian/control</file>:
-	    <example>
-  <var>...</var>
-  Depends: ${shlibs:Depends}
-  Recommends: ${shlibs:Recommends}
-  <var>...</var>
-	    </example>
-	  </p>
-	  <p>
-	    Sources which produce several binary packages with
-	    different shared library dependency requirements can use
-	    the <tt>-p<var>varnameprefix</var></tt> option to override
-	    the default <tt>shlibs:</tt> prefix (one invocation of
-	    <prgn>dpkg-shlibdeps</prgn> per setting of this option).
-	    They can thus produce several sets of dependency
-	    variables, each of the form
-	    <tt><var>varnameprefix</var>:<var>dependencyfield</var></tt>,
-	    which can be referred to in the appropriate parts of the
-	    binary package control files.
-	  </p>
-	</sect1>
 	<sect1 id="pkg-dpkg-distaddfile">
 	    <prgn>dpkg-distaddfile</prgn> - adds a file to

Russ Allbery (rra@debian.org)               <http://www.eyrie.org/~eagle/>

Reply to: