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 x86 binary package, there has to be a recompile for each architecture, which is around five more builds.
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.
debian/files
or debian/substvars
files.
They should be removed by the `clean' target of
debian/rules
.
/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.
egcc
being available; don't rely on
gcc
being a certain version.
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
.
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
.
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.
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.
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.
buildd
buildd
is not yet available! However, it collects a number
of as yet unpackaged components which are currently in production
(such as debbuild
and wanna-build
.
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.
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.
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.