Whole document tree

Debian Developer's Reference
Chapter 8 - Porting and Being Ported

Debian supports an ever-increasing number of architectures. Even if you are not a porter, and you don't use any architecture but one, it is part of your duty as a maintainer to be aware of issues of portability. Therefore, even if you are not a porter, you should read most of this chapter.

Porting is the act of building Debian packages for architectures that is different from the original architecture of the package maintainer's binary package. It is a unique and essential activity. In fact, porters do most of the actual compiling of Debian packages. For instance, for a single i386 binary package, there must be a recompile for each architecture, which is amounts to 12 more builds.

8.1 Being Kind to Porters

Porters have a difficult and unique task, since they are required to deal with a large volume of packages. Ideally, every source package should build right out of the box. Unfortunately, this is often not the case. This section contains a checklist of ``gotchas'' often committed by Debian maintainers — common problems which often stymie porters, and make their jobs unnecessarily difficult.

The first and most important watchword is to respond quickly to bug or issues raised by porters. Please treat porters with courtesy, as if they were in fact co-maintainers of your package (which in a way, they are). Please be tolerant of succinct or even unclear bug reports, doing your best to hunt down whatever the problem is.

By far, most of the problems encountered by porters are caused by packaging bugs in the source packages. Here is a checklist of things you should check or be aware of.

1. Make sure that your Build-Depends and Build-Depends-Indep settings in debian/control are set properly. The best way to validate this is to use the debootstrap package to create an unstable chroot environment. Within that chrooted environment, install the build-essential package and any package dependancies mention in Build-Depends and/or Build-Depends-Indep. Finally, try building your package within that chrooted environment.

   See the Debian Policy Manual for instructions on setting build dependencies.

2. Don't set architecture to a value other than ``all'' or ``any'' unless you really mean it. In too many cases, maintainers don't follow the instructions in the Debian Policy Manual. Setting your architecture to ``i386'' is usually incorrect.

3. Make sure your source package is correct. Do dpkg-source -x package.dsc to make sure your source package unpacks properly. Then, in there, try building your package from scratch with dpkg-buildpackage.

4. Make sure you don't ship your source package with the debian/files or debian/substvars files. They should be removed by the `clean' target of debian/rules.

5. Make sure you don't rely on locally installed or hacked configurations or programs. For instance, you should never be calling programs in /usr/local/bin or the like. Try not to rely on programs be setup in a special way. Try building your package on another machine, even if it's the same architecture.

6. Don't depend on the package you're building already being installed (a sub-case of the above issue).

7. Don't rely on the compiler being a certain version, if possible. If not, then make sure your build dependencies reflect the restrictions, although you are probably asking for trouble, since different architectures sometimes standardize on different compilers.

8. Make sure your debian/rules contains separate ``binary-arch'' and ``binary-indep'' targets, as the Debian Packaging Manual requires. Make sure that both targets work independently, that is, that you can call the target without having called the other before. To test this, try to run dpkg-buildpackage -b.

8.2 Guidelines for Porter Uploads

If the package builds out of the box for the architecture to be ported to, you are in luck and your job is easy. This section applies to that case; it describes how to build and upload your binary-only NMU so that it is properly installed into the archive. If you do have to patch the package in order to get it to compile for the other architecture, you are actually doing a source NMU, so consult How to do a source NMU, Section 7.4 instead.

In a binary-only NMU, no real changes are being made to the source. You do not need to touch any of the files in the source package. This includes debian/changelog.

The way to invoke dpkg-buildpackage is as dpkg-buildpackage -B -eporter-email. Of course, set porter-email to your email address. This will do a binary-only build of only the architecture-dependant portions of the package, using the `binary-arch' target in debian/rules.

8.2.1 Recompilation Binary-Only NMU Versioning

Sometimes you need to recompile a package against other packages which have been updated, such as libraries. You do have to bump the version number in this case, so that the version comparison system can function properly. Even so, these are considered binary-only NMUs — there is no need in this case to trigger all other architectures to consider themselves out of date or requiring recompilation.

Such recompilations require special ``magic'' version numbering, so that the archive maintenance tools recognize that, even though there is a new Debian version, there is no corresponding source update. If you get this wrong, the archive maintainers will reject your upload (due to lack of corresponding source code).

The ``magic'' for a recompilation-only NMU is triggered by using the third-level number on the Debian part of the version. For instance, if the latest version you are recompiling against was version ``2.9-3'', your NMU should carry a version of ``2.9-3.0.1''. If the latest version was ``3.4-2.1'', your NMU should have a version number of ``3.4-2.1.1''.

8.2.2 When to do a source NMU if you are a porter

Porters doing a source NMU generally follow the guidelines found in Non-Maintainer Uploads (NMUs), Chapter 7, just like non-porters. However, it is expected that the wait cycle for a porter's source NMU is smaller than for a non-porter, since porters have to cope with a large quantity of packages. Again, the situation varies depending on the distribution they are uploading to.

However, if you are a porter doing an NMU for `unstable', the above guidelines for porting should be followed, with two variations. Firstly, the acceptable waiting period — the time between when the bug is submitted to the BTS and when it is OK to do an NMU — is seven days for porters working on the unstable distribution. This period can be shortened if the problem is critical and imposes hardship on the porting effort, at the discretion of the porter group. (Remember, none of this is Policy, just mutually agreed upon guidelines.)

Secondly, porters doing source NMUs should make sure that the bug they submit to the BTS should be of severity `serious' or greater. This ensures that a single source package can be used to compile every supported Debian architecture by release time. It is very important that we have one version of the binary and source package for all architecture in order to comply with many licenses.

Porters should try to avoid patches which simply kludge around bugs in the current version of the compile environment, kernel, or libc. Sometimes such kludges can't be helped. If you have to kludge around compilers bugs and the like, make sure you #ifdef your work properly; also, document your kludge so that people know to remove it once the external problems have been fixed.

Porters may also have an unofficial location where they can put the results of their work during the waiting period. This helps others running the port have the benefit of the porter's work, even during the waiting period. Of course, such locations have no official blessing or status, so buyer, beware.

8.3 Tools for Porters

There are several tools available for the porting effort. This section contains a brief introduction to these tools; see the package documentation or references for full information.

8.3.1 quinn-diff

quinn-diff is used to locate the differences from one architecture to another. For instance, it could tell you which packages need to be ported for architecture Y, based on architecture X.

8.3.2 buildd

The buildd system is used as a distributed, client-server build distribution system. It is usually used in conjunction with auto-builders, which are ``slave'' hosts which simply check out and attempt to auto-build packages which need to be ported. There is also an email interface to the system, which allows porters to ``check out'' a source package (usually one which cannot yet be autobuilt) and work on it.

buildd is not yet available as a package; however, most porting efforts are either using it currently or planning to use it in the near future. It collects a number of as yet unpackaged components which are currently very useful and in use continually, such as andrea, sbuild and wanna-build.

Some of the data produced by buildd which is generally useful to porters is available on the web at http://buildd.debian.org/. This data includes nightly updated information from andrea (source dependencies) and quinn-diff (packages needing recompilation).

We are very excited about this system, since it potentially has so many uses. Independent development groups can use the system for different sub-flavors of Debian, which may or may not really be of general interest (for instance, a flavor of Debian built with gcc bounds checking). It will also enable Debian to recompile entire distributions quickly.

8.3.3 dpkg-cross

dpkg-cross is a tool for installing libraries and headers for cross-compiling in a way similar to dpkg. Furthermore, the functionality of dpkg-buildpackage and dpkg-shlibdeps is enhanced to support cross-compiling.

Debian Developer's Reference