Appendix A. Advanced packaging
Prev     

Appendix A. Advanced packaging

Table of Contents

A.1. Shared libraries
A.2. Managing debian/package.symbols
A.3. Multiarch
A.4. Building a shared library package
A.5. Native Debian package

The rewrite of this tutorial document with updated contents and more practical examples is available as Guide for Debian Maintainers. Please use this new tutorial as the primary tutorial document.

Here are some hints and pointers for advanced packaging topics that you are most likely to deal with. You are strongly advised to read all the references suggested here.

You may need to manually edit the packaging template files generated by the dh_make command to address topics covered in this chapter. The newer debmake command should address these topics better.

A.1. Shared libraries

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

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 enable access to them from the linked executables.

  • The SONAME of a shared library libfoo.so.1: objdump -p libfoo.so.1 | grep SONAME [87]

  • 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 [88]

  • libfoo1: the library package for the shared library libfoo.so.1 with the SONAME ABI version 1.[89]

  • The package maintainer scripts of the library package must call ldconfig under the specific circumstances to create the necessary symbolic links for the SONAME.[90]

  • libfoo1-dbg: the debugging symbols package that contains the debugging symbols for the shared library package libfoo1.

  • libfoo-dev: the development package that contains the header files etc. for the shared library libfoo.so.1.[91]

  • Debian packages should not contain *.la Libtool archive files in general.[92]

  • Debian packages should not use RPATH in general.[93]

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

A.2. Managing debian/package.symbols

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

Here is a rough example of how to create the libfoo1 package from 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 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. [96] 

      $ 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 that 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 proper updated symbols file from the generated binary package of the shared library. [97] 

    $ 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. [98]

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

A.3. 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:

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 the $(DEB_HOST_MULTIARCH) variable using the dpkg-architecture(1) command for each binary package build. For example, the path to install multiarch libraries are changed as follows:[99]

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

  • 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

A.4. Building a shared library package

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

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 of differences generated by the data byte order and by the compression algorithm.

A.5. Native Debian package

If a package is maintained only for Debian or possibly only for local use, its source may contain all the debian/* files in it. There are 2 ways to package it.

You can make the upstream tarball by excluding the debian/* files and package it as a non-native Debian package as in Section 2.1, “Debian package building workflow”. This is the normal way, which some people encourage using.

The alternative is the workflow of the native Debian package.

  • Create a native Debian source package in the 3.0 (native) format using a single compressed tar file in which all files are included.

    • package_version.tar.gz
    • package_version.dsc

  • Build Debian binary packages from the native Debian source package.

    • package_version_arch.deb

For example, if you have source files in ~/mypackage-1.0 without the debian/* files, you can create a native Debian package by issuing the dh_make command as follows: 

$ cd ~/mypackage-1.0
$ dh_make --native

Then the debian directory and its contents are created just like in Section 2.8, “Initial non-native Debian package”. This does not create a tarball, since this is a native Debian package. But that is the only difference. The rest of the packaging activities are practically the same.

After execution of the dpkg-buildpackage command, you will see the following files in the parent directory:

  • mypackage_1.0.tar.gz

    This is the source code tarball created from the mypackage-1.0 directory by the dpkg-source command. (Its suffix is not orig.tar.gz.)

  • mypackage_1.0.dsc

    This is a summary of the contents of the source code, as in the non-native Debian package. (There is no Debian revision.)

  • mypackage_1.0_i386.deb

    This is your completed binary package, as in the non-native Debian package. (There is no Debian revision.)

  • mypackage_1.0_i386.changes

    This file describes all the changes made in the current package version as in the non-native Debian package. (There is no Debian revision.)


[87] Alternatively: readelf -d libfoo.so.1 | grep SONAME

[88] Alternatively: readelf -d libfoo.so.1 | grep NEEDED

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

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

[96] 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

[97] 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

[99] Old special purpose library paths such as /lib32/ and /lib64/ are not used anymore.

[100] 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/.

Prev     
Chapter 9. Uploading the package  Home