/!\ WARNING: this page is a work in progress documenting a feature that is not yet available in the Debian archive and evolving rapidly. Do not rely on any information you read here when creating official Debian packages!

Converting your package for multiarch

This page is intended to be a one-stop guide for converting library packages to Multiarch. If you find there are issues not documented here, please update this wiki page, or contact debian-devel@lists.debian.org for help.

Why update your library package for multiarch support?

Now that multiarch support is available in the package manager (dpkg 1.16.0 and above; apt 0.8.12 and above), converting your runtime library package to Multi-Arch: same makes it possible for users to install your package for more than one architecture at the same time. This has several benefits:

Issues to be aware of when converting

You might wonder why, if multiarch is so great, the conversion isn't handled automatically by the package helper tools like debhelper and cdbs. The answer is that there is no reliable way to automatically convert a package to multiarch. Careful attention is required on the part of the maintainer to ensure the conversion is done correctly. In particular, you must pay attention to the following issues:

What does the end result look like?

Currently, Debian Policy (9.1.1) provides for multiarch paths only for shared libraries. However, most upstream build systems (such as autoconf, with --libdir) will install shared libraries, support files, and various development files (such as static libraries and .so symlinks) together to the same target directory. It is intended that Debian Policy be amended to permit all of these files to be installed to the multiarch /usr/lib/<triplet> subdirectory.

With that fixed, the changes to packages for multiarch can be summarized as follows:

/usr/lib -> /usr/lib/<triplet>
/usr/lib/<pkgdir> -> /usr/lib/<triplet>/<pkgdir>
/usr/include: no change
/usr/bin: no change
/usr/share: no change
/usr/sbin: no change

Packages that are Multi-Arch: same must adhere quite closely to Debian Policy section 8. In particular, since multiarch doesn't make any changes to the executable paths, a multiarch library package must not include binary executables in /usr/bin or /usr/sbin, since this will cause a conflict among the different architecture versions of a package. See Debian Policy: Shared library support files for advice on dealing with any such executables currently included in your runtime library package.

The end result, then, is a runtime library package that contains only files in the directories /lib/<triplet>, /usr/lib/<triplet>, /usr/share, and possibly /etc (though including configuration files in runtime library packages is generally discouraged). When these are all the files present in your runtime library package, your package can be marked Multi-Arch: same.

/!\ Note that any files in /usr/share or /etc must be byte-for-byte identical across architectures, otherwise file conflicts will result! This means, in particular, that any gzip-compressed files must be compressed with -n to avoid embedded timestamps.

Recipes for converting packages

dh(1) and autotools

By far the simplest package to convert is one that uses autoconf upstream and dh(1) in the Debian packaging.