From 24290de6079153d1befd552bec4900e8f52cfa80 Mon Sep 17 00:00:00 2001 From: he Date: Mon, 2 Jun 2008 09:34:15 +0000 Subject: [PATCH] Update and rewrite the porting guidelines in chapter 5, bringing the dev-ref up to the state of porting in the year 2008. Also fixes several wording issues, such as possible misunderstandments about the need to rebuild uploads. Closes: #483226 git-svn-id: svn://anonscm.debian.org/ddp/manuals/trunk/developers-reference@5201 313b444b-1b9f-4f58-a734-7bb04f332e8d --- debian/changelog | 4 ++ pkgs.dbk | 124 +++++++++++++++++++++++++---------------------- 2 files changed, 69 insertions(+), 59 deletions(-) diff --git a/debian/changelog b/debian/changelog index fb6a3b3..3069c55 100644 --- a/debian/changelog +++ b/debian/changelog @@ -22,6 +22,10 @@ developers-reference (3.4.0) UNRELEASED; urgency=low * Fix several typesetting errors and typos noticed by Sandro Tosi, thanks for the notes! Closes: #483223 * Update several bits about release management/testing transitions. + * Update and rewrite the porting guidelines in chapter 5, bringing + the dev-ref up to the state of porting in the year 2008. Also + fixes several wording issues, such as possible misunderstandments + about the need to rebuild uploads. Closes: #483226 -- Marc 'HE' Brockschmidt Sun, 01 Jun 2008 16:26:33 +0200 diff --git a/pkgs.dbk b/pkgs.dbk index 5494ef6..d78da35 100644 --- a/pkgs.dbk +++ b/pkgs.dbk @@ -1399,9 +1399,10 @@ you are not a porter, you should read most of this chapter. 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 -i386 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 i386 + architecture, it will be built for each of the other architectures, +amounting to &number-of-arches; more builds.
Being kind to porters @@ -1453,10 +1454,12 @@ Manual for instructions on setting build dependencies. -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. +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 only one architecture (such as i386 +or amd64) is usually incorrect. @@ -1471,7 +1474,7 @@ scratch with dpkg-buildpackage. 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 +files. They should be removed by the clean target of debian/rules. @@ -1487,7 +1490,9 @@ even if it's the same architecture. 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. @@ -1500,11 +1505,11 @@ standardize on different compilers. -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 -dpkg-buildpackage -B. +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 dpkg-buildpackage -B. @@ -1531,7 +1536,8 @@ The way to invoke dpkg-buildpackage is as -mporter-email. Of course, set porter-email 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 debian/rules. +using the binary-arch target in debian/rules +. If you are working on a Debian machine for your porting efforts and you need to @@ -1548,14 +1554,15 @@ which the package was built was not good enough (outdated or obsolete library, 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 -(katie refuses to install new packages if they don't have a +(dak refuses to install new packages if they don't have a version number greater than the currently available one). 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 $(Source-Version) +. Despite the required modification of the changelog, these are called @@ -1571,16 +1578,19 @@ source code). 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 +bnumber. 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''. 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. +2.9-3, your binary-only 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 +binary-only NMU should have a version number of 3.4+b2. + 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. + Similar to initial porter uploads, the correct way of invoking @@ -1614,11 +1624,11 @@ team first. 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 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 architectures in order to +comply with many licenses. Porters should try to avoid patches which simply kludge around bugs in the @@ -1667,34 +1677,30 @@ linkend="tools-porting"/> .
-
-<systemitem role="package">buildd</systemitem> +
+<systemitem role="package">wanna-build</systemitem> -The buildd system is used as a +The wanna-build system is used as a distributed, client-server build distribution system. It is usually used in -conjunction with build daemons, 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 buildd + program. Build daemons are ``slave'' hosts +which contact the central wanna-build +system to receive a list of packages that need to be built. -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. The actual automated builder is -packaged as sbuild, see its description -in . The complete buildd system also collects a number of as yet -unpackaged components which are currently very useful and in use continually, -such as andrea and wanna-build. +wanna-build 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, sbuild is available as a package, see its +description in . 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. -Some of the data produced by buildd -which is generally useful to porters is available on the web at . This data includes nightly updated -information from andrea (source dependencies) and -quinn-diff (packages needing -recompilation). +Most of the data produced by wanna-build + which is generally useful to porters is available on the +web at . This data includes nightly +updated statistics, queueing information and logs for build attempts. We are quite proud of this system, since it has so many possible uses. @@ -1717,8 +1723,8 @@ The buildds admins of each arch can be contacted at the mail address 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 i386 and amd64), or uses +other hardware-specific features not supported on all architectures. In order to prevent broken packages from being uploaded to the archive, and @@ -1736,9 +1742,9 @@ allow the package to build as soon as the required functionality is available. 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 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. -- 2.30.2