[ previous ] [ Copyright Notice ] [ Contents ] [ next ]

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 which 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 one i386 binary package, there has to be a recompile for each architecture, which is around five 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 more 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).

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. 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 Packaging Manual. Setting your architecture to ``i386'' is usually incorrect.
  2. 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.
  3. 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.
  4. 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.
  5. Don't depend on the package your building already being installed (a sub-case of the above issue).
  6. Don't rely on egcc being available; don't rely on gcc being a certain version.
  7. 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 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 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.

Sometimes you need to recompile a packages against other packages which have been updated, such as libraries. You do have to bump the version number in this case, so that the upgrade system can function properly. Even so, these are considered binary-only NMUs -- there is no need in this case for all architectures to recompile. You should set the version number as in the case of NMU versioning, but add a ``.0.'' before the the NMU version. For instance, a recompile-only NMU of the source package ``foo_1.3-1'' would be numbered ``foo_1.3-1.0.1''.

The way to invoke dpkg-buildpackage is as dpkg-buildpackage -B -mporter-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 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. Crucial fixes (i.e., changes need to get a source package to compile for a released-targeted architecture) can be uploaded with no waiting period for the `frozen' distribution.

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 `important' 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.


[ previous ] [ Copyright Notice ] [ Contents ] [ next ]
Debian Developer's Reference
ver. 2.7.2, 16 April, 2000
Adam Di Carlo, current maintainer aph@debian.org
Christian Schwarz schwarz@debian.org
Ian Jackson ijackson@gnu.ai.mit.edu