Debian Packaging Manual - Chapter 14
Conversion procedure from old source packages

This is a brief summary of the procedure for converting a pre-2.0.0.0-format source package into the new format.

You are strongly advised to download and examine the hello package, and to read the section in the dpkg programmers' manual describing the source packaging tools. More detail about the exact functionality of these tools is available in dpkg-source(1).

• Download the original source code from wherever it can be found and do any rearrangement required to make it look like the original tree of the Debian source. Put it in package-upstream-version.orig/ or package_upstream-version.orig.tar.gz.
• Rename all files debian.* to debian/*. There may be some exceptions to this, but this is a good start.
• Edit the debian/changelog - create or rename it if necessary. Add a new revision to the top with the appropriate details, and a local variables entry to the bottom to set Emacs to the right mode:

         Local variables:
         mode: debian-changelog
         End:
  

• Edit/create debian/control:
  • Remove the Version field. If it is generated unusually (not equal to the source version) you must use the -v option to dpkg-gencontrol (see below). Section, Priority, Maintainer go above the first blank line, most of the rest below.
  • Reorder the fields and add a blank line at an appropriate point, separating the source package fields from the binary package fields.
  • Add the Source field.
  • Add the Standards-Version field. (Please check out the Debian Policy Manual for details about this field.)
  • Change the Architecture field for each package to any, all or whatever. If there isn't an Architecture field add one.
  • If any other use of sed or things used to happen to make the binary control files use dpkg-gencontrol's variable substitution features to achieve the same effect. Use debian/substvars if you need to put unusally-generated information (apart from details of .deb files) in the .changes file too.
• Edit the debian/rules:
  • Remove the source and diff and any changes and dist targets. These things now happen in a package-independent way and are not done by debian/rules.
  • Split the binary target into binary-arch and binary-indep; in many cases all of binary should go into binary-arch. Create the binary target and the unused of the two other binary-* targets if there is one - you can copy the ones from the hello package.
  • Change the binary target to use dpkg-gencontrol to make the package control file(s). Move it to after all the files have been installed but just before the last chown and chmod in the target.
  • Change occurrences of debian-tmp to debian/tmp.
  • Change occurrences of debian.{post,pre}{inst,rm} to debian/*.
  • Remove the version number setting at the top, if there is one.
  • Ensure that the package's Debian-specific and upstream changelogs are installed.
• Change the package to use dpkg-shlibdeps to determine its shared library dependencies and substitute them in. Shared library dependencies should no longer be hardwired in the source package.
• Check that the debian/README is really the copyright file, and if so rename it to debian/copyright and edit debian/rules to cope with this and to change the installation of the copyright file from /usr/doc/package/copyright to /usr/doc/copyright/package. If it isn't then find debian/copyright and decide what to do with the README.
• Check for various other anachronisms and problems:
  • Remove any Package_Revision, Package-Revision or Revision fields.
  • Rename Optional to Suggests, Recommended to Recommends.
  • Change /usr/doc/examples/package to /usr/doc/package/examples.
  • Make sure that manpages are installed compressed.
  • Check that the description has an extended description, is well-formatted and meaningful and helpful to people wanting to know whether to install a package.
• Look everything over.
• Do a test build using dpkg-buildpackage -us -uc -sa -rwhatever. Check the permissions and locations of files in the resulting package by examining the output of dpkg-deb --contents, and check that the source build happened OK. Test install the binary package(s) and test extract the source package(s).
• Sign the release: either rebuild everything with dpkg-buildpackage -sa, or PGP-sign the .dsc, rebuild the .changes using dpkg-genchanges -sa, and then PGP-sign the .changes.

The use of -sa on dpkg-buildpackage and dpkg-genchanges is important when doing the first build/uploading of a new-format source package. Unless this happens to be Debian revision 0 or 1 by default the original source tarfile will not be included in the uploaded files listed in the .changes file, and so it won't be installed on the FTP site. -sa requests that the original source be included regardless.