Whole document tree

Debian New Maintainers' Guide
Chapter 6 Final steps

6.1 Building the package

Enter the program's main directory and then issue this command:

       dpkg-buildpackage -rfakeroot

This will do everything for you, you'll just have to enter your PGP secret key, twice. After it's done, you will see four new files in the directory above (~/debian/):

• gentoo_0.9.12-1_i386.deb

  This is the completed binary package. You can use dpkg or dselect to install and remove this just like any other package.

• gentoo_0.9.12.orig.tar.gz

  This is the original source code gathered up so that if someone else wants to recreate your package from scratch they can. Or if they aren't using the Debian packaging system, but need to manually download the source and compile.

• gentoo_0.9.12-1.dsc

  This is a summary of the contents of the source code. The file is generated from the gentoo-0.9.12/debian/control file, and is used when unpacking the source with dpkg-source(1). This file is PGP signed, so that people can be sure that it's really yours.

• gentoo_0.9.12-1.diff.gz

  This compressed file contains each and every addition you made to the original source code, in the form known as "unified diff". It is made and used by dpkg-source(1).

• gentoo_0.9.12-1_i386.changes

  This file describes all the changes made in the current package revision, and it is used by the Debian FTP archive maintenance programs to install the binary and source packages in it. It is partly generated from the gentoo-0.9.12/debian/changelog file and the .dsc file.

  As you keep working on the package, behavior will change and new features will be added. People downloading your package can look at this file and quickly see what has changed. The long strings of numbers are MD5 checksums for the files mentioned. Person downloading your files can test them with md5sum(1) and if the numbers don't match, they'll know the file is corrupt or has been hacked. This file is PGP signed, so that people can be even more sure that it's really yours.

With a large package, you may not want to rebuild from scratch every time while you tune a detail in debian/rules. For testing purposes, you can make a .deb file without rebuilding the upstream sources like this:

       fakeroot debian/rules binary

Just make sure that your `install' rule does not have `install-stamp' child (that's the default nowadays), to make sure `dh_clean -k` is run each time. And once you are finished with cleanups, remember to rebuild following the right procedure, to be able to upload correctly.

6.2 Checking the package for errors

Run lintian(1) on your .changes file; this program will check for many common packaging errors. The command is:

       lintian -i gentoo_0.9.12-1_i386.changes

Of course, replace the filename with the name of the changes file generated for your package. If it appears that there are some errors (lines beginning with E:), read the explanation (the N: lines), correct mistakes, and rebuild as described in Building the package, Section 6.1. If there are lines that begin with W:, those are only warnings, so you can be pretty much sure that your package is okay (but it most probably needs some tuning).

Note that you can build the package with dpkg-buildpackage and run lintian all in one command with debuild(1).

Look inside the package using a file manager like mc(1), or unpack it in a temporary place using dpkg-deb(1). Be on the lookout for extra unneeded files both in the binary and source package, in case something went wrong and some cruft didn't get cleaned up. Tips: `zgrep ^+++ ../gentoo_0.9.12-1.diff.gz` will give you a list of your changes/additions to the source files, and `dpkg-deb -c gentoo_0.9.12-1_i386.deb` will list the files in the package.

Install the package to test it yourself, e.g. using the debi(1) command as root. Try to install and run it on machines other than your own and watch closely for any warnings or errors both on installation and running the program.

Later, when you build a new version, you should do the following to ensure basic upgradability of the package:

• upgrade from the previous version (and from the version in last Debian release),
• downgrade back again,
• install the package as a new package (i.e., with no previous version installed),
• uninstall it, reinstall it again, and then purge it.

6.3 Uploading the package

Now that you have tested your new package thoroughly, you'll need to upload these files to master.debian.org, using dupload(1). First you have to set up dupload's config file, ~/.dupload.conf . Put something like this in it:

       package config;
       $default_host = "master";
       
       $cfg{"master"}{"method"} = "scpb";
       $cfg{"master"}{"login"} = "joy";
       $cfg{"master"}{"visibleuser"} = "jrodin";
       $cfg{"master"}{"visiblename"} = "jagor.srce.hr";
       $cfg{"master"}{"fullname"} = "Josip Rodin";
       
       $cfg{"non-us"}{"method"} = "scpb";
       $cfg{"non-us"}{"login"} = "joy";
       $cfg{"non-us"}{"visibleuser"} = "jrodin";
       $cfg{"non-us"}{"visiblename"} = "jagor.srce.hr";
       $cfg{"non-us"}{"fullname"} = "Josip Rodin";
       
       1;

Of course, change my personal settings to yours, and read the dupload.conf(5) manual page to understand what each of these options means.

Then connect to your Internet provider, and issue this command:

       dupload --to master gentoo_0.9.12-1_i386.changes

Dupload checks that the files' md5 checksums match those from the .changes file, so it will warn you to rebuild it as described in Building the package, Section 6.1 so it can properly upload.

Dupload will ask for your password on master.debian.org, upload the packages, and give a short announcement about your upload on debian-devel-changes@lists.debian.org if necessary.

If you live in Europe, you can use some other upload queues instead of master. For details look in dupload(1), dupload.conf(5) and the Developer's Reference.

6.4 Updating the package

Let's say that a bug report was filed against your package, #54321, and it describes a problem that you can solve. To create a new Debian revision of the package, you need to:

• Correct the problem in the package source, of course.
• Add a new revision in the Debian changelog file, with `dch -i`, and include a short description of the bug and the solution, followed by this: "Closes: #54321". That way, the bug report will be automagically closed by the archive maintenance software the moment your package gets accepted in the Debian archive.
• Repeat what you did in Building the package, Section 6.1, Checking the package for errors, Section 6.2, and Uploading the package, Section 6.3. The difference is that this time, original source archive won't be included, as it hasn't been changed and it already exists in the Debian archive.

Now let's consider a different, a wee bit more complicated situation - a new upstream version was released, and of course you want it packaged. You need to do the following:

• Download the new sources and put the tarball (e.g. named `gentoo-0.9.13.tar.gz') in the directory above the old source tree (e.g. ~/debian/).
• Enter the old source directory, and run:

         uupdate -u gentoo-0.9.13.tar.gz
  

  Of course, replace this filename with the name of your program's source archive. uupdate(1) will properly rename that tarball, try to apply all the changes from your previous .diff.gz file, and update the new debian/changelog file.

• Change directory to `../gentoo-0.9.13', the new package source tree, and repeat what you did in Building the package, Section 6.1, Checking the package for errors, Section 6.2, and Uploading the package, Section 6.3.

Note that if you set up `debian/watch' file as described in watch.ex, Section 5.6, you can run uscan(1) to automagically look for revised sources, download them, and run uupdate.

6.5 Where to ask for help

Before you decide to ask your question in some public place, please just RTFM. That includes documentation in /usr/share/doc/dpkg, /usr/share/doc/debian, /usr/share/doc/package/* files and the man/info pages for all the programs mentioned in this article. When you receive a bug report (yes, actual bug reports!), you will know that it is time that you dig in the Debian Bug Tracking System and read the documentation there, to be able to deal with the reports efficiently.

By joining the Debian Mentors' mailing list at debian-mentors@lists.debian.org you can team up with experienced Debian developers who will help you with questions you might have. You can subscribe to it by sending e-mail to debian-mentors-request@lists.debian.org with the word `subscribe' in the message subject.

If you still have questions, ask on the Debian Developers' mailing list at debian-devel@lists.debian.org. You can subscribe to it by sending e-mail to debian-devel-request@lists.debian.org with the word `subscribe' in the message subject. If you are already a Debian developer, you should be subscribed to it anyway.

Even if it all worked well, it's time to start praying. Why? Because in just a few hours (or days) users from all around the world will start to use your package, and if you made some critical error you'll get mailbombed by numerous angry Debian users... Just kidding. :-)

Relax and be ready for bug reports, because there is a lot more work to be done before it will be fully in line with Debian policies (once again, read the real documentation for details). Good luck!