Differences between revisions 31 and 32
Revision 31 as of 2009-11-11 19:41:21
Size: 10638
Editor: ?JanosGuljas
Comment:
Revision 32 as of 2009-11-11 19:57:05
Size: 10500
Comment: updates concerning backports, marked approx as working
Deletions are marked like this. Additions are marked like this.
Line 64: Line 64:
With 3.0 (quilt), backporting to etch is possible only if you don't remove the quilt related rules from debian/rules and if you don't use multiple upstream tarballs. With 3.0 (quilt), backporting to etch is possible if you don't use multiple upstream tarballs.
Line 69: Line 69:
 * remove debian/source/format  * remove debian/source/format (or put "1.0" in it)
Line 71: Line 71:
 * rebuild (on an etch system)  * rebuild (on an etch system), possibly with {{{dpkg-buildpackage -i.pc}}} to avoid including quilt's internal directory
Line 73: Line 73:
Keeping the quilt rules is not problematic, it will only lead to some supplementary patching/unpatching during the build ({{{dpkg-source -x}}} applies patches, {{{debian/rules clean}}} removes patches, {{{debian/rules build}}} re-applies patches). The changes coming from the quilt patches will be in the .diff.gz but it will work.
Line 146: Line 146:
   * '''Not tested yet'''.    * Works.

Summary

This pages summarizes information concerning the switch to the new source package formats "3.0 (quilt)" and "3.0 (native)". This switch is planned to happen in the squeeze development cycle.

Advantages of new formats

  • Supports bzip2 and lzma along with the usual gzip.
    • Note: lzma is not allowed on ftp-master.debian.org but xz might be in squeeze+1.
  • Supports multiple upstream tarballs.
  • Supports inclusion of binary files (no need anymore to uuencode a Debian specific PNG icon for example)
  • You don't have to repack the upstream tarball to strip the debian directory. (The debian directory is automatically replaced by the content of the  .debian.tar.{gz,bz2,lzma}  file at unpack time)

  • Debian-specific changes are no more stored in a single .diff.gz but in multiple patches in debian/patches/. It is compatible with quilt (hence its name) but does not require its usage as dpkg-source is able to do everything needed by itself. It applies patches at extraction time and update the patch series at build time.

  • NMU workflow is now really: unpack, hack, rebuild (for all 3.0 (quilt) packages).

Implementation

  • Lenny's dpkg has all the support for the new source formats. This is to avoid problems when working in Lenny with Squeeze source packages.
  • DAK (Debian Archive Kit) has been updated to cope with the new source package formats. See 457345 for history.

  • dpkg-source should be modified to build new source packages by default (see 553928 for details). But this can only be done when all packages are known to build fine with the new formats. This is tracked in the BTS with usertags: http://bugs.debian.org/cgi-bin/pkgreport.cgi?users=hertzog@debian.org;tag=3.0-quilt-by-default

FAQ

How to convert a source package?

You need to put "3.0 (quilt)" or "3.0 (native)" in debian/source/format to indicate the desired format to dpkg-source (see dpkg-source(1) for more information).

Native packages should not need any other change.

When you switch to "3.0 (quilt)", there are other changes that you might want to do:

  • If your .diff.gz modifies upstream files, you should really put those changes in separate quilt patches first, otherwise all those changes will be merged in a single quilt patch named debian/patches/debian-changes-<version>. Consider documenting those patches by following DEP-3.

  • If you use another patch system (like dpatch or dbs), consider switching to quilt (you can then simplify your debian/rules, see next point).
  • You can remove everything related to quilt in debian/rules (patch/unpatch logic, cleanup of quilt stamp file and its .pc directory) unless you care about backportability to etch (lenny supports 3.0 (quilt)).

Does a 3.0 (quilt) source package need to build-depend on quilt?

If you drop the quilt usage in debian/rules (patch/unpatch logic), then no.

How to use multiple upstream tarball in 3.0 (quilt) format?

Simply put a file  <source>_<version>.orig-<component>.tar.{gz,bz2,lzma}  near the traditional  .orig  tarball. The content of that tarball should also be already unpacked in the  component  subdir of the unpacked source package. The next  dpkg-source -b  will pick it up automatically.

Why should I convert my package to 3.0 (quilt) format?

Pick the reasons that matter to you:

  • by keeping patches separate and properly documented (with DEP-3):

    • the Debian changes are more likely to be reviewed (for example thanks to http://patch-tracking.debian.org)

    • any upstream contributor is more likely to find and merge the patches (if you haven't forwarded it properly)
    • other distributions can reuse our patches
  • even if you don't have any upstream patch right now, next time that someone must NMU your package, they can cleanly add a patch (with a proper DEP-3 header) without having to modify the build system
  • same applies for derivative distributions that have to modify your packages... you're more likely to be able to find something valuable to merge if their changes are kept as separate patches instead of merged within the .diff.gz
  • debian/rules can be simplified by getting rid of the patching/unpatching code (or the uuencoding/uudecoding code if you ship a supplementary binary file like an icon)
  • the upstream tarball is bzip2-compressed and you don't want to have to convert it
  • the upstream author releases the software in multiple tarballs
  • you don't have to add -i -I every time that you manually build the package from the VCS repository (the VCS-specific files are ignored by default)
  • in the long run it's best to standardize on a single patch system (new contributors need to learn a single system, more people can help you, etc.) and quilt appears to be that patch system.

Will my packages be backportable to etch?

With 3.0 (quilt), backporting to etch is possible if you don't use multiple upstream tarballs.

If this is the case, you can trivially backport by doing the following:

  • unpack the source package with a recent dpkg-source (lenny or newer)
  • convert any .orig.tar.bz2 into .orig.tar.gz
  • remove debian/source/format (or put "1.0" in it)
  • do any other usual backporting (tweaking build-dependencies, etc.)
  • rebuild (on an etch system), possibly with dpkg-buildpackage -i.pc to avoid including quilt's internal directory

The changes coming from the quilt patches will be in the .diff.gz but it will work.

I get lintian errors and warnings with new source formats

  • patch-system-but-no-source-readme is wrong (see )

  • unsupported-source-format 3.0 (quilt/native) is wrong (see 552707)

You should ignore them until lintian is fixed.

What shall I do with the debian/patches/.dpkg-source-applied file?

This file serves as a hint that the patches have been applied at extraction time. It will not be included in the generated debian.tar.gz. Thus it should also not be included in any VCS... tools importing source package in VCS should probably learn to use --skip-patches when importing 3.0 (quilt) source packages (they can also use --skip-debianization to extract only the upstream part of the source package).

I converted my package but it fails to unpack on all buildds

You certainly have quilt patches that only applies with fuzz (i.e. they only apply if patch ignores context lines). quilt applies those without failing but dpkg-source doesn't. Since quilt isn't installed on buildd, they are using the internal dpkg-source implementation and fail. You can reproduce the failure with dpkg-source --without-quilt -x <dsc-file>. The solution is to refresh the patches, for example with those commands :

quilt pop -a
while quilt push; do quilt refresh -p ab; done

Why aren't -p0 patch supported in 3.0 (quilt) format?

See sub-thread starting here.

How many packages have already been converted?

http://upsilon.cc/~zack/stuff/dpkg-v3/

Validation of all tools with new source formats

For all applications, please be sure to test the 3 important cases:

  • 3.0 (native)
  • 3.0 (quilt)
  • 3.0 (quilt) with multiple upstream tarballs

It's also interesting to test with various compressions methods (gz, bz2, lzma).

Some sample source packages are available here. You can add it to /etc/apt/sources.list with deb-src http://people.debian.org/~hertzog/packages/ debsrc3.0/. They have the following characteristics:

  • sample1: 3.0 (quilt) with orig.tar.gz / debian.tar.gz and additional tarballs with all compressions schemes
  • sample2: 3.0 (quilt) with orig.tar.bz2 / debian.tar.bz2
  • sample3: 3.0 (quilt) with orig.tar.lzma / debian.tar.lzma
  • sample4: 3.0 (native) with tar.gz
  • sample5: 3.0 (native) with tar.bz2
  • sample6: 3.0 (native) with tar.lzma

Current test results:

Please try using new source packages with all your usual tools (in particular if you maintain them) and file bugs if you encounter problems and usertag them appropriately (user hertzog@debian.org / tag 3.0-quilt-by-default). Also update the list above with any relevant information (including pointers to bugs).


CategorySpec