The Debian packaging system is one of the most elegant methods of installing, upgrading, and removing software available. For all you fans of other packaging systems, before you send your flames, please note that I said "one of" and not simply "the most." Other packaging systems have their charms, but in this article I'm going to focus on the Debian packaging system. Specifically, I'm going to look at creating Debian packages so you can distribute your packages in Debian format -- or simply create packages for your own use.

I'll walk through the basic components of a package, what you need to create your own packages, and finally how to pull it all together to create a package.

Understanding Debian packages

In this section, we'll take a quick look at what Debian packages are. Debian packages are much like RPM (Red Hat Package Manager) packages, but they differ a little in the details. If you've already worked with creating RPMs, you'll probably find that it's not at all difficult to add Debian packaging to your repertoire.

What is a package, exactly?

To put it very simply, a package is a collection of files with instructions on what to do with them. A package usually contains a program or programs, but sometimes it has only documentation, window manager themes, or other files that are easier to distribute in an installable package.

The package contains instructions on where those files should reside in the filesystem, what libraries or other programs the contents of the package are dependent on (if any), setup instructions, and basic configuration scripts. Note that many packages cannot be used or should not be used with the default settings contained in their configuration files. With packages such as Apache, you'll still need to configure your installation after the package has been set up.

Packages usually contain precompiled software, but you can also package source code. Some admins may prefer to install from source, or your application may require customization prior to compilation, so if you're distributing software that is under a free or open source license, you may wish to create a source package as well as a "binary" package.

Note: Pre-compiled software packages are usually called "binaries," although this is something of a misnomer. Yes, executables are in binary format, but so are JPEGs, MP3s, and many other non-executable files. It would probably make more sense to call precompiled software "executable" packages.

All binary Debian packages consist of three basic things: a text file called debian-binary, a compressed tarball called control.tar.gz, and another compressed tarball called data.tar.gz.

The debian-binary text file contains the version number for the binary package, which should be 2.0. The control.tar.gz file contains the control file; the postinst file, which contains instructions on what to do after installing the package; and the prerm file, which contains removal instructions. control.tar.gz may also contain a file with information about configuration files for the package called conffiles and a file with the MD5 checksums for the package called md5sums.

The data.tar.gz contains the actual "payload" of the package. That is, it contains a filesystem with all the relevant files for your program that, when installed, will be placed in the appropriate spots in your system's filesystem.

If you want to see what a package looks like for yourself, download a few packages from the Debian site (see the link in the Resources later in this article) and run ar -x packagename.deb. Debian packages are simply archives of the files mentioned above.

Do I need to be a Debian Developer?

You don't need to be an official Debian Developer to create and distribute Debian-compatible packages. However, you do need to be a Debian Developer to actually upload packages and be a package maintainer for official Debian releases. If you're interested in becoming a Debian Developer, you can start by reading the "How You Can Help?" page on the Debian Web site (see Resources for a link).

There are a number of companies and projects that create and distribute Debian packages of their software. These are not "official" Debian packages, but they're still of great convenience to Debian users who wish to be able to install software using dpkg or APT (Advanced Packaging Tool).

What you need to get started

Obviously, you're going to need a current Debian system if you're going to create and test Debian packages. You'll also need to have something that you want to package. We'll start with the assumption that you already have those two things and go from there.

There are several packages that you'll need to have installed to build packages on a Debian system. Most of those packages will likely be installed by default, since you'll need dpkg, gcc, make, and so forth on most systems anyway. You will need the build-essential package and dpkg-dev package as well, which may or may not already be installed on your system.

Debian package naming conventions

If you've used Debian for any amount of time, you might have noticed that Debian package files all follow certain naming conventions. Every Debian binary package should have a filename that follows this format: packagename_version_arch.deb, where "packagename" is the name of the package, "version" is the package version with major, minor, and revision numbers, and "arch" is the architecture for the package.

The name of the package itself (not the filename, just the name of the package) can contain lowercase letters, numbers, and the "-" and "+" characters. (It might sound odd for a package to have a "+" in the package name, but it is used for several packages like "doc++" -- a documentation system for C/C++ code.) So, "mypackage-2++" is a perfectly valid package name, while "MY_Package" or "mypackage2.0" would not be.

Every package should also have a unique name that doesn't already exist in the Debian archive. Even though you technically do not need to adhere to this for your package to install, you should be sure that your package name does not conflict with an official Debian package. For example, if you wanted to distribute a specially patched version of Apache as an alternative to the official Debian version, you shouldn't use apache_X.X.X-i386.deb, because the Debian folks already have an apache package. Instead, you'd want to use something like acme-apache_X.X.X-i386.deb.

Creating a Debian package

Now that we've covered the basics, what packages are, and what you need, it's time to talk about the nuts and bolts of building packages.

Control files

You'll need to create a control file for your package. Don't worry; it's not very hard and all you need to create the file is your favorite text editor and a little information. The following is a sample control file. Note that I've included all the optional fields here for demonstration purposes -- your package is unlikely to need all of these fields.

Package: acme
Version: 1.0
Section: web 
Priority: optional
Architecture: all
Essential: no
Depends: libwww-perl, acme-base (>= 1.2)
Pre-Depends: perl 
Recommends: mozilla | netscape  
Suggests: docbook 
Installed-Size: 1024
Maintainer: Joe Brockmeier [jzb@dissociatedpress.net]
Conflicts: wile-e-coyote
Replaces: sam-sheepdog
Provides: acme
Description: The description can contain free-form text
             describing the function of the program, what
             kind of features it has, and so on.
.
More descriptive text.

Control file fields

The syntax for the control fields is very simple: the name of the field, followed by a colon, and then the body or value of the field. So, "Fieldname: value" is all you need. Some fields require a one-word value, while others allow a free-form description or set of values.

In this section we'll look at what each field in the control file means and what kind of information you need to provide. Most of these fields are optional, so your package will not have to include every field described here if they aren't relevant to your package. For example, a package will not require the "Source" field if source for the package is unavailable. If your package won't conflict with any other packages, then you need not include the "Conflicts" information, and so on.

The first field in any control file is the "Package" field. In this field you'll specify the name of the package. The next field, "Version" is the version number for the package. You may use whatever version numbering scheme the original author of the package uses, but it may not include a hyphen. Anything after a hyphen is considered the Debian revision number. For example, if a program's native version number is given as 1.01-1 for some reason, the version number would be considered "1.01" with a Debian revision number of "1" -- clearly, not the result you're looking for.

The "Maintainer" field should be your full name (or company name) and an e-mail address contained within angle brackets as shown above. The "Installed-Size" is pretty self-explanatory.

Dependencies

As you probably already know, one of the nicest things about Debian packages is the dependency resolution. When you use apt-get to retrieve packages, it automatically decides whether you have what you need on your system to use the requested package, and offers to resolve any conflicts you might have or retrieve any packages you're in need of. That feature depends on the package's dependencies being well thought out and properly set up in the package.

There are several optional fields that deal with dependencies. We'll cover each of them briefly here. Be sure you've sorted out exactly which packages your package may depend on before installation -- the dependency system is only as smart as the developers giving it information.

Dependencies make up five of the fields in a control file: Depends, Enhances, Pre-Depends, Recommends, and Suggests.

The Depends field should contain the name of any packages that your package absolutely needs to work. If there's a "nice to have" package related to yours, but not required for normal operation of your package, then you should use the "Recommends" or "Suggests" fields instead. You'll note in the example above that the "Recommends" field has two separate package separated by a pipe (|). This means that either package will satisfy the dependency; both are not required.

What's the difference between "Recommends" and "Suggests," anyway? Any packages that you should probably have, but are not absolutely required, belong in the "Recommends" field. According to the policy manual, "list packages that would be found together with this one in all but unusual installations." Packages that are likely to be useful but aren't in any way required should be listed in the "Suggests" field.

For example, the DocBook XML DTD package (docbook-xml) lists the DocBook SGML (docbook) package as a recommended package, and the DocBook documentation (docbook-doc) as a suggested package. In most circumstances, if you have the XML DTD, you'll probably have the SGML DTD too -- but not in every instance. It's usually (read: always) a good idea to install documentation about a package or related programs, like the DocBook docs, but it's not necessary for normal operation of your program.

The "Enhances" field is basically stating that your package may make another package more useful. So, the docbook-doc package might have an "Enhances" field with docbook-xml as one of the packages enhanced.

The "Pre-Depends" field is reserved for special cases. When a package is listed as a "Pre-Depends," it forces the system to make sure that the named packages are completely installed before attempting to install your package.

Finally, when working with version numbers, there are several symbols you'll need to understand. You'll note that one of the packages listed as a dependency has a version number given, acme-base (>= 1.2). This means, "this package requires the package acme-base version equal to or higher than 1.2."

The relations available are strictly earlier (<<), earlier or equal (<=), equal to only (=), equal to or later than (>=), and strictly later than (>>).

Specifying conflicts

The "Conflicts" and "Replaces" fields specify packages that are not dependencies, but rather packages that don't belong on the system at the same time as your package.

Packages that conflict with your package outright should be listed in the "Conflicts" fields. For example, if you're packaging a modified version of Apache, you won't want the normal version of Apache to be on the system as well as yours -- so "apache" would be listed as a conflict.

Finally, the control file should be located under a directory named DEBIAN, as should the scripts we discuss in the next section. This directory won't turn up in the final Deb archive.

Scripts

Your package will also need a few scripts to be run by the system when installing and removing the package. (Remember, no matter how wonderful your program is, someone may wish to uninstall it later on down the road.)

The postinst script should contain any necessary steps to be done after installing your program. The prerm script should contain instructions on what should be done to remove the program. Both of these scripts are required (see Resources for more on this).

The final step

After all the prep work that goes into making a Debian package, the actual package creation is somewhat anticlimactic.

You'll use the dpkg command with the -b or --build option (-b and --build are the same). The syntax for creating a package is dpkg -b directory packagename.deb where directory contains the filesystem tree with all the requisite files for your program. Note, you can build the package without specifying the name of the new package, but then it will simply place the package file under directory as ".deb" -- which might lead you to believe that the package wasn't created at all.

So, for example, if your program has a configuration file that belongs in etc/, the program itself, which will live in usr/bin/, and some documentation that lives under usr/share/doc/package/, you'll recreate that filesystem tree in a directory that will be used to create your package.

Beyond the basics

That's pretty much all there is to creating a Debian package. It might seem a bit complicated, but really it's just a number of simple steps. None are too complicated; you simply have to get them all right.

There are a few intricacies of creating packages that are beyond the scope of this article. For example, if you're packaging a mail user agent or mail transport agent, there are some specific considerations that apply. This article only covers the bare basics of creating a Debian package. Make sure you check the Debian Policy Manual (see Resources for a link) to make sure you're in full compliance with the guidelines for packages.

There are several categories of programs that require extra attention, including any Web servers, daemons, Perl programs or modules, X programs, and so forth. You'll find what you need to know in the Customized Programs section of the policy manual.

Resources

• Find official Debian packages on the Debian Web site.
  
  
• Read the How You Can Help page to find out about helping with the maintenance of Debian packages.
  
  
• Why Debian? As debianPlanet explains, Debian is more than a distro and more than an OS -- Debian is a community. Depending on your mood today and other variables, this might sound great, or it might sound like a lot of hooey. Better to suspend judgment until you can read about Debian for yourself.
  
  
• Read the Debian Free Software Guidelines for licensing requirements for official Debian packages.
  
  
• The Debian Policy Manual contains instructions on making Debian packages, as well as additional topics.
  
  
• The RPM-for-Unix HOWTO covers converting Debian packages to RPM.
  
  
• You can also make both RPM and deb packages from one source with tools like pkgwrite.
  
  
• Read this article series by Dan Poirier on packaging software with RPM: Part 1 (developerWorks, November 2001), Part 2 (developerWorks, December 2001), and Part 3 (developerWorks, February 2002).
  
  
• For a tarfile-based alternative to package management, read Manage packages using Stow (developerWorks, February 2003).
  
  
• If you are interested in learning more about Debian or if you're having trouble, there are a great many Debian mailing lists that can help you. We need hardly add that, as always, you should check the archives before posting any questions to the lists.
  
  
• Basics of the Debian Package Management System contains a sample Debian control file, among other useful samples and explanations.
  
  
• The Debian Policy Manual, Chapter 6 has more information on Package maintainer scripts.
  
  
• Don't forget to keep up with the Debian Weekly News.
  
  
• For information on building your next application using IBM tools and middleware, check out Speed-start your next Linux app.
  
  
• Find more resources for Linux developers in the developerWorks Linux zone.