This page duplicates (and plagiarizes) the information at However, this page is aimed more at working within the Athena repository.


Within a package source, you'll find the debian/ directory, which must contain the following files:

  • debian/changelog: The Debian changelog for the package. The changelog is the authoritative source for the Debian version number of the package. It is typically installed to /usr/share/doc/package/changelog.Debian.gz. Although it is a plain text file, it should be edited using Debian-specific tools such as dch or the Emacs mode change-log-mode. See Changelog for more information, including how version numbers are calculated in the Debathena repository.
  • debian/compat: The debhelper compatability level of the package. See CompatLevels for the correct value.
  • debian/control: The Debian packaging system’s metadata for the package. See Control. Note that while this can be auto-updated with CDBS from, it is essential that it exists.
    • debian/ CDBS packages will often have a file called debian/ that looks exactly like debian/control except that it has @cdbs@ as a build dependency. This is replaced with various build dependencies that CDBS knows about (like debhelper and cdbs) at build time to generate debian/control. As of June 2013, this file should not be present in the Athena source tree.
  • debian/copyright: A human-readable description of the copyright status of the package. See Copyright for what to use in the Athena repository.
  • debian/rules: The executable makefile used to build the binary package. See Rules.
  • debian/source/format: If present, it contains the version of the source package (either 1.0 or 3.0). If absent, debuild will generally create a version 1.0 source package.

N.B. The control file can be generated from the file with the following invocation, from within the package's root directory:

`DEB_AUTO_UPDATE_DEBIAN_CONTROL=yes debian/rules debian/control`

While that looks complicated, all it does is set a variable to 'yes', and then run debian/rules (remember, it's executable) with the argument: debian/control.

Other special files in debian/

  • debian/package.install: Pairs, one per line, of files and directories to install them to. Understands “*” and copies directories recursively.
  • debian/package.links: Pairs, one per line, of a target and the name of the symlink to create.
  • debian/package.init: The package’s init script. Code to run update-rc.d and run the init script at package installation and removal is automatically added to maintainer scripts.
  • debian/package.cron.d: cron job to be automatically installed into /etc/cron.d.
  • debian/ List documentation files/directories to be automatically installed into /usr/share/doc/package.
  • debian/package.dirs: List directories to be automatically created.
  • debian/package.postinst, debian/package.preinst, debian/package.postrm, debian/package.prerm: The package's maintainer scripts. See MaintainerScripts for more information.

Creating a package

At this point, it is worth discussing "native" vs "non-native" packages. A "native" package is a package that only exists in Debian, for which Debian itself is the "upstream" maintainer. A "non-native" package is a package of software written outside the Debian project, but packaged for Debian. The primary difference is the version numbering scheme. A Debian native package will have a version number like "1.0". A non-native package will have the software's real version number, plus a hyphen and a number indicating the version of the _packaging_ itself. For example, foobar-3.2-5 indicates that it is version 3.2 of the foobar software, and this is the 5th version of the Debian packaging for version 3.2. (If version 3.3 was then released, the first version in Debian would be 3.3-1).

While you can create all the special files listed above from scratch, Debhelper provides a tool to make things easy for you. Assuming you have a piece of software in a directory whose name is of the format package-version (e.g. foobar-1.0), you can use the dh_make command:

dh_make -c gpl -s --createorig

That will create a single binary (-s) package with the GPL license (-c gpl), and will create a .orig tarball for you in the parent directory (--createorig). It will create all the required files for you in the debian directory, and then a variety of optional example files (with the .ex extension), which you can either customize or delete.

If the directory does not have that name, or has an unusual name, you can use the -p option to pass a name and a version (e.g. dh_make -p foobar_1.0 -c gpl -s --createorig).

Next: BuildingAPackage