Porting is the act of building Debian packages for architectures that are
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
-<literal>i386</literal> binary package, there must be a recompile for each
-architecture, which amounts to &number-of-arches; more builds.
+the actual compiling of Debian packages. For instance, when a maintainer
+uploads a (portable) source packages with binaries for the <literal>i386
+</literal> architecture, it will be built for each of the other architectures,
+amounting to &number-of-arches; more builds.
</para>
<section id="kind-to-porters">
<title>Being kind to porters</title>
</listitem>
<listitem>
<para>
-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 <ulink url="&url-debian-policy;">Debian Policy
-Manual</ulink>. Setting your architecture to ``i386'' is usually incorrect.
+Don't set architecture to a value other than <literal>all</literal> or
+<literal>any</literal> unless you really mean it. In too many cases,
+maintainers don't follow the instructions in the <ulink
+url="&url-debian-policy;">Debian Policy Manual</ulink>. Setting your
+architecture to only one architecture (such as <literal>i386</literal>
+or <literal>amd64</literal>) is usually incorrect.
</para>
</listitem>
<listitem>
<para>
Make sure you don't ship your source package with the
<filename>debian/files</filename> or <filename>debian/substvars</filename>
-files. They should be removed by the `clean' target of
+files. They should be removed by the <literal>clean</literal> target of
<filename>debian/rules</filename>.
</para>
</listitem>
<listitem>
<para>
Don't depend on the package you're building being installed already (a sub-case
-of the above issue).
+of the above issue). There are, of course, exceptions to this rule, but be
+aware that any case like this needs manual bootstrapping and cannot be done
+by automated package builders.
</para>
</listitem>
<listitem>
</listitem>
<listitem>
<para>
-Make sure your debian/rules contains separate ``binary-arch'' and
-``binary-indep'' targets, as the Debian Policy 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
-<literal>dpkg-buildpackage -B</literal>.
+Make sure your debian/rules contains separate <literal>binary-arch</literal>
+and <literal>binary-indep</literal> targets, as the Debian Policy 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 <command>dpkg-buildpackage -B</command>.
</para>
</listitem>
</orderedlist>
-m<replaceable>porter-email</replaceable></literal>. Of course, set
<replaceable>porter-email</replaceable> to your email address. This will do a
binary-only build of only the architecture-dependent portions of the package,
-using the `binary-arch' target in <filename>debian/rules</filename>.
+using the <literal>binary-arch</literal> target in <filename>debian/rules
+</filename>.
</para>
<para>
If you are working on a Debian machine for your porting efforts and you need to
bad compiler, ...). Then you may just need to recompile it in an updated
environment. However, you have to bump the version number in this case, so
that the old bad package can be replaced in the Debian archive
-(<command>katie</command> refuses to install new packages if they don't have a
+(<command>dak</command> refuses to install new packages if they don't have a
version number greater than the currently available one).
</para>
<para>
You have to make sure that your binary-only NMU doesn't render the package
uninstallable. This could happen when a source package generates
-arch-dependent and arch-independent packages that depend on each other via
-$(Source-Version).
+arch-dependent and arch-independent packages that have inter-dependencies
+generated using dpkg's substitution variable <literal>$(Source-Version)
+</literal>.
</para>
<para>
Despite the required modification of the changelog, these are called
</para>
<para>
The ``magic'' for a recompilation-only NMU is triggered by using a suffix
-appended to the package version number, following the form b<number>.
+appended to the package version number, following the form <literal>
+b<replaceable>number<replaceable>.
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+b1''. If the latest
-version was ``3.4+b1'' (i.e, a native package with a previous recompilation
-NMU), your NMU should have a version number of ``3.4+b2''. <footnote><para> In
-the past, such NMUs used the third-level number on the Debian part of the
-revision to denote their recompilation-only status; however, this syntax was
-ambiguous with native packages and did not allow proper ordering of
-recompile-only NMUs, source NMUs, and security NMUs on the same package, and
-has therefore been abandoned in favor of this new syntax. </para> </footnote>
+<literal>2.9-3<literal>, your binary-only NMU should carry a version of
+<literal>2.9-3+b1</literal>. If the latest version was <literal>3.4+b1
+</literal> (i.e, a native package with a previous recompilation NMU), your
+binary-only NMU should have a version number of <literal>3.4+b2</literal>.
+<footnote><para> In the past, such NMUs used the third-level number on the
+Debian part of the revision to denote their recompilation-only status;
+however, this syntax was ambiguous with native packages and did not allow
+proper ordering of recompile-only NMUs, source NMUs, and security NMUs on
+the same package, and has therefore been abandoned in favor of this new syntax.
+</para> </footnote>
</para>
<para>
Similar to initial porter uploads, the correct way of invoking
</para>
<para>
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.
+to the BTS should be of severity <literal>serious</literal> 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 architectures in order to
+comply with many licenses.
</para>
<para>
Porters should try to avoid patches which simply kludge around bugs in the
</para>
</section>
-<section id="buildd">
-<title><systemitem role="package">buildd</systemitem></title>
+<section id="wanna-build">
+<title><systemitem role="package">wanna-build</systemitem></title>
<para>
-The <systemitem role="package">buildd</systemitem> system is used as a
+The <systemitem role="package">wanna-build</systemitem> system is used as a
distributed, client-server build distribution system. It is usually used in
-conjunction with <literal>build daemons</literal>, 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 auto-built)
-and work on it.
+conjunction with build daemons running the <systemitem role="package">buildd
+</systemitem> program. <literal>Build daemons</literal> are ``slave'' hosts
+which contact the central <systemitem role="package"> wanna-build</systemitem>
+system to receive a list of packages that need to be built.
</para>
<para>
-<systemitem role="package">buildd</systemitem> 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. The actual automated builder is
-packaged as <systemitem role="package">sbuild</systemitem>, see its description
-in <xref linkend="sbuild"/> . The complete <systemitem
-role="package">buildd</systemitem> system also collects a number of as yet
-unpackaged components which are currently very useful and in use continually,
-such as <command>andrea</command> and <command>wanna-build</command>.
+<systemitem role="package">wanna-build</systemitem> is not yet available as a
+package; however, all Debian porting efforts are using it for automated
+package building. The tool used to do the actual package builds, <systemitem
+role="package">sbuild</systemitem> is available as a package, see its
+description in <xref linkend="sbuild"/> . Please note that the packaged
+version is not the same as the one used on build daemons, but it is close
+enough to reproduce problems.
</para>
<para>
-Some of the data produced by <systemitem role="package">buildd</systemitem>
-which is generally useful to porters is available on the web at <ulink
-url="&url-buildd;"></ulink>. This data includes nightly updated
-information from <command>andrea</command> (source dependencies) and
-<systemitem role="package">quinn-diff</systemitem> (packages needing
-recompilation).
+Most of the data produced by <systemitem role="package">wanna-build
+</systemitem> which is generally useful to porters is available on the
+web at <ulink url="&url-buildd;"></ulink>. This data includes nightly
+updated statistics, queueing information and logs for build attempts.
</para>
<para>
We are quite proud of this system, since it has so many possible uses.
Some packages still have issues with building and/or working on some of the
architectures supported by Debian, and cannot be ported at all, or not within a
reasonable amount of time. An example is a package that is SVGA-specific (only
-i386), or uses other hardware-specific features not supported on all
-architectures.
+available for <literal>i386</literal> and <literal>amd64</literal>), or uses
+other hardware-specific features not supported on all architectures.
</para>
<para>
In order to prevent broken packages from being uploaded to the archive, and
</para>
<para>
Additionally, if you believe the list of supported architectures is pretty
-constant, you should change 'any' to a list of supported architectures in
-debian/control. This way, the build will fail also, and indicate this to a
-human reader without actually trying.
+constant, you should change <literal>any</literal> to a list of supported
+architectures in <filename>debian/control</filename>. This way, the build will
+fail also, and indicate this to a human reader without actually trying.
</para>
</listitem>
<listitem>
~ianmdlvl / developers-reference.git / blobdiff