(debian-policy.info)Shared library ABI changes

---

Next: The symbols system Prev: Generating dependencies on shared libraries Up: Dependencies between the library and other packages

---

Enter node , (file) or (file)node

8.6.2 Shared library ABI changes
--------------------------------

Maintaining a shared library package using either ‘symbols’ or ‘shlibs’
files requires being aware of the exposed ABI of the shared library and
any changes to it.  Both ‘symbols’ and ‘shlibs’ files record every
change to the ABI of the shared library; ‘symbols’ files do so per
public symbol, whereas ‘shlibs’ files record only the last change for
the entire library.

There are two types of ABI changes: ones that are backward-compatible
and ones that are not.  An ABI change is backward-compatible if any
reasonable program or library that was linked with the previous version
of the shared library will still work correctly with the new version of
the shared library.  (1) Adding new symbols to the shared library is a
backward-compatible change.  Removing symbols from the shared library is
not.  Changing the behavior of a symbol may or may not be
backward-compatible depending on the change; for example, changing a
function to accept a new enum constant not previously used by the
library is generally backward-compatible, but changing the members of a
struct that is passed into library functions is generally not unless the
library takes special precautions to accept old versions of the data
structure.

ABI changes that are not backward-compatible normally require changing
the ‘SONAME’ of the library and therefore the shared library package
name, which forces rebuilding all packages using that shared library to
update their dependencies and allow them to use the new version of the
shared library.  For more information, see Note: Run-time shared
libraries.  The remainder of this section will deal with
backward-compatible changes.

Backward-compatible changes require either updating or recording the
minimal-version for that symbol in ‘symbols’ files or updating the
version in the dependencies in ‘shlibs’ files.  For more information on
how to do this in the two formats, see *note The symbols File Format:
111. and Note: The shlibs File Format.  Below are general rules
that apply to both files.

The easy case is when a public symbol is added.  Simply add the version
at which the symbol was introduced (for ‘symbols’ files) or update the
dependency version (for ‘shlibs’) files.  But special care should be
taken to update dependency versions 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 versions 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 version rather
than leave it 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 the dependency version 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, ‘OP_BAZ’, is added, the minimal-version of
‘library_do_operation’ (for ‘symbols’ files) or the version in the
dependency for the shared library (for ‘shlibs’ files) must be increased
to the version at which ‘OP_BAZ’ was introduced.  Otherwise, a binary
built against the new version of the library (having detected at
compile-time that the library supports ‘OP_BAZ’) may be installed with a
shared library that doesn’t support ‘OP_BAZ’ and will fail at runtime
when it tries to pass ‘OP_BAZ’ into this function.

Dependency versions in either ‘symbols’ or ‘shlibs’ files 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 ‘~’ to the end of the version 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.

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

   (1) An example of an “unreasonable” program is one that uses library
interfaces that are documented as internal and unsupported.  If the only
programs or libraries affected by a change are “unreasonable” ones,
other techniques, such as declaring ‘Breaks’ relationships with affected
packages or treating their usage of the library as bugs in those
packages, may be appropriate instead of changing the SONAME. However,
the default approach is to change the SONAME for any change to the ABI
that could break a program.