wiki:AnatomyOfAPackage

Version 8 (modified by jdreed, 11 years ago) (diff)

--

This page duplicates (and plagiarizes) the information at http://debathena.mit.edu/packaging/. However, this page is aimed more at working within the Athena repository.

Components

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. A brief reference is available at the end of this document. Note that while this can be auto-updated with CDBS from control.in, it is essential that it exists.
  • debian/control.in: CDBS packages will often have a file called debian/control.in 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.
  • 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. The information in the table above (along with the control file reference at the end of this document) should be sufficient to generate the files mentioned so far aside from debian/rules, so we will focus attention on that.

N.B. The control file can be generated from the control.in 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.

The rules file

The rules file is written in make. See CaffeinatedMake for a brief overview.

With CDBS, a simple package whose build system is based on autotools but where autoconf, automake, libtool, and aclocal should not be regenerated will probably look something like the following:

#!/usr/bin/make -f

include /usr/share/cdbs/1/rules/debhelper.mk
include /usr/share/cdbs/1/class/autotools.mk

For packages that use other build systems, there are rules files in /usr/share/cdbs/1/class/ for make, python-distutils, ant, and a few others. If you plan to use quilt patches, you’ll want to include /usr/share/cdbs/1/rules/patchsys-quilt.mk. CDBS is primarily controlled through the setting of make variables in the rules file or through the existence of special files in the debian directory. Many changes to flags passed to during the build process can be implemented by just setting a single variable. Many of these variables can also be set on a per-package basis using names like CFLAGS_package. To get a definitive answer, one should inspect the code of debhelper.mk or the class file that you are using.

Useful makefile variables

  • DEB_AUTO_UPDATE_DEBIAN_CONTROL: Set this to enabled auto-generation of debian/control from debian/control.in. This option is basically banned in Debian because it apparently causes problems with NMUs, but it can save work.
  • DEB_CONFIGURE_EXTRA_FLAGS (autotools.mk): Any extra flags you want to pass to configure.
  • DEB_MAKE_ENVVARS (makefile.mk): Any environment variables you want to set for make.
  • DEB_MAKE_INVOKE += … (makefile.mk): Pass extra flags to make (note the += here).
  • DEB_MAKE_{BUILD,CLEAN,…}_TARGET (makefile.mk): Control what make targets CDBS uses. Note that make install and make check unless you set their corresponding target variable.
  • DEB_MAKE_CLEAN_TARGET (makefile.mk): Often you want to set this to distclean.
  • CFLAGS,CPPFLAGS,LDFLAGS,… (makefile.mk): Control common compiler and linker flags.
  • DEB_CONFIGURE_EXTRA_FLAGS (autotools.mk): Any extra flags you want to pass to configure.
  • DEB_AUTO_UPDATE_AUTOAUTO = version (makefile.mk): Have autotools component AUTOAUTO-version run at build time.
  • DEB_DH_LINK_ARGS: Create symlinks in your installation (or use a .links file, see below)
  • DEB_DH_debhelper-tool_ARGS: Add flags to any of a number of debhelper tools.

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/package.docs: 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.