=== Shared library

==== Basics of the shared library

Before packaging shared libraries, you should read the following primary references in detail.

* ``Debian Policy Manual, 8 Shared libraries''
* ``Debian Policy Manual, 9.1.1 File System Structure''
* ``Debian Policy Manual, 10.2 Libraries''

Here are some oversimplified hints for you to get started.

* Shared libraries are ELF object files containing compiled code.
* Shared libraries are distributed as *+++*+++.so* files. (Neither *+++*+++.a* files nor *+++*+++.la* files)
* Shared libraries are mainly used to share common codes among multiple executables with the ld mechanism.
* Shared libraries are sometimes used to provide multiple plugins to an executable with the dlopen mechanism.
* Shared libraries export symbols which represent compiled objects such as variables, functions, and classes; and enables access to them from the linked executables.
* The SONAME of a shared library 'libfoo'*.so.i*'1': "*objdump -p* 'libfoo'*.so.*'1' *| grep SONAME*" footnote:[Alternatively: "*readelf -d* 'libfoo'*.so.*'1' *| grep SONAME*"]
* The SONAME of a shared library usually matches the library file name (but not always).

* The SONAME of shared libraries linked to */usr/bin/*'foo': "*objdump -p /usr/bin/*'foo' *| grep NEEDED*" footnote:[Alternatively: "*readelf -d* 'libfoo'*.so.*'1' *| grep NEEDED*"]
* 'libfoo1': the library package for the shared library 'libfoo'*.so.*'1' with the SONAME ABI version 1.[91]
* The package maintainer scripts of the library package must call ldconfig under the specific circumstances to create the necessary symbolic links for the SONAME.[92]
* 'libfoo1'*-dbg*: the debugging symbols package which contains the debugging symbols for the shared library package 'libfoo1'.
* 'libfoo'*-dev*: the development package which contains the header files etc. for the shared library *libfoo.so.1*.[93]
* Debian package should not contain *.la Libtool archive files in general.[94]
* Debian package should not use RPATH in general.[95]

Although it is somewhat outdated and is only a secondary reference, ``Debian Library Packaging Guide'' may still be useful.

When packaging the shared library package, one needs to be careful to accommodate the future major library upgrades.  Its corresponding debug package may contain the major library version as a part of the package name while other corresponding packages should not contain them.  For example:

* *libfoo-1.0.tar.gz* : the upstream source package tarball
* *libfoo* : the upstream source package name
* *libfoo1* : the library binary package name
* *libfoo1-dbg* : the debug symbol binary package name
* *libfoo-dev* :  the development binary package
* *libfoo-doc* : the documentation binary package
* *libfoo-utils* : the executable binary package
* ...

=== *debian/*'package'*.symbols*

When you package a shared library 'libfoo1', you should create *debian/*'libfoo1'*.symbols* file to manage the minimal version associated to each symbol for backward-compatible ABI changes under the same SONAME of the library for the same shared library package name.[96] You should read the following primary references in detail.

Debian Policy Manual, 8.6.3 "The symbols system"[97]

* *dh_makeshlibs*(1) 
* *dpkg-gensymbols*(1) 
* *dpkg-shlibdeps*(1) 
* *deb-symbols*(5)

Here is a rough example to create the 'libfoo1' package to the upstream version 1.3 with the proper *debian/*'libfoo1'*.symbols* file.

Prepare the skeleton debianized source tree using the upstream `libfoo-1.3'*.tar.gz* file.

If this is the first packaging of the 'libfoo1' package, create the *debian/*'libfoo1'*.symbols* file with empty content.

If the previous upstream version 1.2 was packaged as the libfoo1 package with the proper *debian/*'libfoo1'*.symbols* in its source package, use it again.

If the previous upstream version 1.2 was not packaged with the *debian/*'libfoo1'*.symbols*, create it as the symbols file from all available binary packages of the same shared library package name containing the same SONAME of the library, for example, versions 1.1-1 and 1.2-1. [98]

----
 $ dpkg-deb -x libfoo1_1.1-1.deb libfoo1_1.1-1
 $ dpkg-deb -x libfoo1_1.2-1.deb libfoo1_1.2-1
 $ : > symbols
 $ dpkg-gensymbols -v1.1 -plibfoo1 -Plibfoo1_1.1-1 -Osymbols
 $ dpkg-gensymbols -v1.2 -plibfoo1 -Plibfoo1_1.2-1 -Osymbols
----

Make trial builds of the source tree with tools such as debuild and pdebuild. (If this fails due to missing symbols etc., there were some backward-incompatible ABI changes which require you to bump the shared library package name to something like libfoo1a and you should start over again.)

----
 $ cd libfoo-1.3
 $ debuild
 ...
dpkg-gensymbols: warning: some new symbols appeared in the symbols file: ...
 see diff output below
--- debian/libfoo1.symbols (libfoo1_1.3-1_amd64)
+++ dpkg-gensymbolsFE5gzx        2012-11-11 02:24:53.609667389 +0900
@@ -127,6 +127,7 @@
  foo_get_name@Base 1.1
  foo_get_longname@Base 1.2
  foo_get_type@Base 1.1
+ foo_get_longtype@Base 1.3-1
  foo_get_symbol@Base 1.1
  foo_get_rank@Base 1.1
  foo_new@Base 1.1
...
----

If you see the diff printed by the dpkg-gensymbols as above, extract the updated proper symbols file from the generated binary package of the shared library. [99]

----
$ cd ..
$ dpkg-deb -R  libfoo1_1.3_amd64.deb libfoo1-tmp
$ sed -e 's/1\.3-1/1\.3/' libfoo1-tmp/DEBIAN/symbols \
        >libfoo-1.3/debian/libfoo1.symbols
----

Build release packages with tools such as debuild and pdebuild.

----
$ cd libfoo-1.3
$ debuild clean
$ debuild
...
----

In addition to the above examples, we need to check the ABI compatibility further and bump versions for some symbols manually as needed. [100]

Although it is only a secondary reference, Debian wiki UsingSymbolsFiles and its linked web pages may be useful.

=== Multiarch

The multiarch feature introduced to Debian wheezy integrates support for cross-architecture installation of binary packages (particularly i386<->amd64, but also other combinations) in dpkg and apt. You should read the following references in detail.

 Ubuntu wiki MultiarchSpec (upstream)

Debian wiki Multiarch/Implementation (Debian situation)

It uses the triplet such as i386-linux-gnu and x86_64-linux-gnu for the install path of shared libraries. The actual triplet path is dynamically set into $(DEB_HOST_MULTIARCH) value by dpkg-architecture(1) for each build. For example, the path to install multiarch libraries are changed as follows.[101]

Old path	i386 multiarch path	amd64 multiarch path
/lib/	/lib/i386-linux-gnu/	/lib/x86_64-linux-gnu/
/usr/lib/	/usr/lib/i386-linux-gnu/	/usr/lib/x86_64-linux-gnu/
Here are some typical multiarch package split scenario examples for the followings:

a library source libfoo-1.tar.gz

a tool source bar-1.tar.gz written in a compiled language

a tool source baz-1.tar.gz written in an interpreted language

----
Package	Architecture:	Multi-Arch:	Package content
libfoo1	any	same	 the shared library, co-installable
libfoo1-dbg	any	same	 the shared library debug symbols, co-installable
libfoo-dev	any	same	 the shared library header files etc., co-installable
libfoo-tools	any	foreign	 the run-time support programs, not co-installable
libfoo-doc	all	foreign	 the shared library documentation files
bar	any	foreign	 the compiled program files, not co-installable
bar-doc	all	foreign	 the documentation files for the program
baz	all	foreign	 the interpreted program files
----

Please note that the development package should contain a symlink for the associated shared library without a version number. E.g.: /usr/lib/x86_64-linux-gnu/libfoo.so -> libfoo.so.1

=== Building a shared library package

You can build a Debian library package enabling the multiarch support using dh(1) as follows.

* Update debian/control.
** Add "*Build-Depends: debhelper (>=9)*" for the source package section.
** Add "*Pre-Depends: $\{misc:Pre-Depends}*" for each shared library binary package.
** Add *Multi-Arch:* stanza for each binary package section.
* Set *debian/compat* to "*9*".
* Adjust the path from the normal */usr/lib/* to the multiarch */usr/lib/$(DEB_HOST_MULTIARCH)/* for all packaging scripts.
** Call "*DEB_HOST_MULTIARCH ?= $(shell dpkg-architecture -qDEB_HOST_MULTIARCH)*" in *debian/rules* to set *DEB_HOST_MULTIARCH* variable, first.
** Replace */usr/lib/* with */usr/lib/$(DEB_HOST_MULTIARCH)/* in *debian/rules*.
** If *./configure* is used in the part of *override_dh_auto_configure* target in *debian/rules*, make sure to replace it with "*dh_auto_configure --*" . [102]
* Replace all occurrences of */usr/lib/* with */usr/lib/\*/* in *debian/*'foo'*.install* files.
* Generate files like *debian/*'foo'*.links* from *debian/*'foo'*.links.in* dynamically by adding a script to *override_dh_auto_configure* target in *debian/rules*.

----
override_dh_auto_configure:
        dh_auto_configure
        sed 's/@DEB_HOST_MULTIARCH@/$(DEB_HOST_MULTIARCH)/g' \
                debian/foo.links.in > debian/foo.links
----

Please make sure to verify that the shared library package contains only the expected files, and that your *-dev* package still works.

All files installed simultaneously as the multiarch package to the same file path should have exactly the same file content. You must be careful on differences generated by the data byte order and by the compression algorithm.



[91] See Debian Policy Manual, 8.1 "Run-time shared libraries".

[92] See Debian Policy Manual, 8.1.1 "ldconfig".

[93] See Debian Policy Manual, 8.3 "Static libraries" and Debian Policy Manual, 8.4 "Development files".

[94] See Debian wiki ReleaseGoals/LAFileRemoval.

[95] See Debian wiki RpathIssue.

[96] Backward-incompatible ABI changes normally require you to update the SONAME of the library and the shared library package name to new ones.

[97] For C++ libraries and other cases where tracking individual symbols is too difficult, follow Debian Policy Manual, 8.6.4 "The shlibs system", instead.

[98] All previous versions of Debian packages are available at http://snapshot.debian.org/. The Debian revision is dropped from the version to make it easier to backport the package: 1.1 << 1.1-1~bpo70+1 << 1.1-1 and 1.2 << 1.2-1~bpo70+1 << 1.2-1

[99] The Debian revision is dropped from the version to make it easier to backport the package: 1.3 << 1.3-1~bpo70+1 << 1.3-1

[100] See Debian Policy Manual, 8.6.2 "Shared library ABI changes".

[101] Old special purpose library paths such as /lib32/ and /lib64/ are not used any more.

[102] Alternatively, you can add --libdir=\$${prefix}/lib/$(DEB_HOST_MULTIARCH) and --libexecdir=\$${prefix}/lib/$(DEB_HOST_MULTIARCH) arguments to ./configure. Please note that --libexecdir specifies the default path to install executable programs run by other programs rather than by users. Its Autotools default is /usr/libexec/ but its Debian default is /usr/lib/.

