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.
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.
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.
Listing 1. A sample control file
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 <[email protected]> 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.
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.
