[[symbols]]
==== Library symbols

The symbols support in *dpkg* introduced in Debian *lenny* (5.0, May 2009) helps us to manage the backward ABI compatibility of the library package with the same package name.  The *DEBIAN/symbols* file in the binary package provides the minimal version associated with each symbol.

An oversimplified method for the library packaging is as follows.

* Extract the old *DEBIAN/symbols* file of the immediate previous binary package with the ``*dpkg-deb -e*'' command.
** Alternatively, the *mc* command may be used to extract the *DEBIAN/symbols* file.
* Copy it to the *debian/*'binarypackage'*.symbols* file.
** If this is the first package, use an empty content file instead.
* Build the binary package.
** If the *dpkg-gensymbols* command warns about some new symbols:
*** Extract the updated *DEBIAN/symbols* file with the ``*dpkg-deb -e*'' command.
*** Trim the Debian revision such as *-1* in it.
*** Copy it to the *debian/*'binarypackage'*.symbols* file.
*** Re-build the binary package.
** If the *dpkg-gensymbols* command does not warn about new symbols:
*** You are done with the library packaging.

For the details, you should read the following primary references.

* https://www.debian.org/doc/debian-policy/#the-symbols-system[8.6.3 The symbols system] of the ``Debian Policy Manual''
* *dh_makeshlibs*(1)
* *dpkg-gensymbols*(1)
* *dpkg-shlibdeps*(1)
* *deb-symbols*(5)

Yous should also check:

* Debian wiki https://wiki.debian.org/UsingSymbolsFiles[UsingSymbolsFiles]
* Debian wiki https://wiki.debian.org/Projects/ImprovedDpkgShlibdeps[Projects/ImprovedDpkgShlibdeps]
* Debian kde team https://pkg-kde.alioth.debian.org/symbolfiles.html[Working with symbols files]
* <<autotools-multi>>
* <<cmake-multi>>

TIP: For C++ libraries and other cases where the tracking of symbols is problematic, follow https://www.debian.org/doc/debian-policy/#the-shlibs-system[8.6.4 The shlibs system] of the ``Debian Policy Manual'', instead.  Please make sure to erase the empty *debian/*'binarypackage'*.symbols* file generated by the *debmake* command.  For this case, the *DEBIAN/shlibs* file is used.

[[lib-trans]]
==== Library transition

When you package a new library package version which affects other packages, you must file a transition bug report against the *release.debian.org* pseudo package using the *reportbug* command with the https://ben.debian.net/#_query_language[ben file] and wait for the approval for its upload from the https://wiki.debian.org/Teams/ReleaseTeam[Release Team].

Release team has the https://release.debian.org/transitions/[transition tracker].  See https://wiki.debian.org/Teams/ReleaseTeam/Transitions[Transitions].

CAUTION: Please make sure to rename binary packages as in <<libnames>>.

