APT

The Advanced Packaging Tool and its various frontends form the package management core of Debian and Debian-derived distributions such as SprezzOS. There are two types of packages -- sources (.dsc) and binaries (.deb). A source package typically contains (usually platform-neutral) original source code and associated files from an upstream vendor. In addition to making available these source packages, the distribution builds zero or more (usually several) binary packages from each source package. Most users will make exclusive use of binary packages, but source packages are available to facilitate unlimited customization, optimization, and flexibility. It is quite possible to build all installed packages locally from source, though not usually desirable.

There are roughly 5,000 ways to do any given thing with APT. I do not mean to imply that this is a feature.

Default paths

• /var/lib/apt and /var/lib/dpkg -- the local APT database. It's best not to touch these by hand.
• /var/cache/apt/archives -- locally downloaded packages.
• /etc/apt/trusted.gpg.* -- the local key database
• /etc/apt/sources.* -- the local archives database
• /etc/apt/apt.conf.* -- the local configuration database
• /var/cache/apt/apt-file -- the local Contents database
• /var/log/apt/ and /var/log/aptitude* -- local APT and aptitude logs

Relevant man pages

• deb(5) -- The deb binary package format, since Debian 0.93. Older versions are documented in deb-old(5).
• deb-version(5) -- Version number semantics.

Working with the database

• apt-get(8) -- command line interactive package tool
• dpkg(1) -- command line local package database management
• aptitude(8) -- modern ncurses interactive package tool.
• dselect(1) -- horrible old ncurses interactive package tool. Avoid at all costs.
• apt-cache(8), dpkg-query(1) -- query the database

Special databases

• apt-key(8) -- manage the key database
• apt-file(8) -- query the Contents database (file contents of packages in archives)
• apt-mark(8) -- manage automatic-installs database

Creating packages

• deb-control(5) -- The control files required to generate binary packages from source.
  • A given source package maps to a single control file, in which it is described.
  • A given source package can yield one or more binary packages. Each will have an entry in the control file.
• dch(1), debchange(1) -- Tools for managing changelog files.

Working with debs

• dpkg-deb(1) -- Unpacks, packs, dumps information about local .deb files.

Working with dscs

• apt-src(1p) -- Downloads, builds, and upgrades locally-unpackaged .dsc files

Repositories

A repository toplevel contains at least two subdirectories, dists and pool.

dists

dists contains subdirectories corresponding to distributions, and optionally symlinks (to facilitate distribution aliases). Each subdirectory contains:

• Release -- Information about the distribution (including what components are available), and cryptographic hashes of all files in subdirectories of the distribution toplevel,
• Release.gpg -- A signature of Release
• InRelease -- A copy of Release with an inline signature
• subdirectories corresponding to each Component contained within Release. Within each is:
  • Contents files listing the files in each package, used by apt-file
  • Subdirectories corresponding to the various architectures contained in each distributionXcomponent, containing:
    • Packages -- A listing of control file data from the packages in this distributionXcomponentXarchitecture
    • Packages.gz -- A compressed version of same
    • Release -- Information about this distributionXcomponentXarchitecture

pools

pools contains subdirectories corresponding to components. Within each component's subdirectory are 52 subdirectories, a-z and liba-libz. Within each is a subdirectory for every source package prefixed by that subdirectory's name. Within each of these subdirectories are the various outputs of the package-building process:

• An original source file
• A gzipped diff
• A .dsc file
• Generated packages

Packaging

Best Practices

• Make sure dh_install is invoked with --fail-missing. This can be done by adding to rules:

DEB_DH_INSTALL_ARGS+=--fail-missing

Recipes

Autoreconf

• Run autoreconf at the configure step using debhelper:
  • Add a Build-Depends on dh-autoreconf
  • Replace %: with

%:
        dh $@ --with autoreconf

• Run ./autogen.sh rather than autoreconf, still using debhelper:
  • Repeat the steps taken above
  • Override dh_autoreconf, and pass the script as a parameter:

override_dh_autoreconf:
        dh_autoreconf ./autogen.sh

• Call ./autogen.sh at the configure step, but using CDBS:
  • Add a Build-Depends on dh-autoreconf
  • Add the following:

include /usr/share/cdbs/1/rules/autoreconf.mk
DEB_DH_AUTORECONF_ARGS += $(CURDIR)/autogen.sh

• Pass an extra argument to configure using CDBS:
  • Add the following to rules:

DEB_CONFIGURE_EXTRA_FLAGS += extraarg

Cmake

• Use cmake with CDBS:
  • Add the following to rules:

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

• Pass arguments to cmake from CDBS:
  • Augment and export DEB_CMAKE_CFLAGS, eg:

export DEB_CMAKE_CFLAGS+=-DGLIB_DISABLE_DEPRECATION_WARNINGS

Testing

• To disable the testing step in debhelper, override dh_auto_test with any empty target:

override_dh_auto_test:

Watchfiles

Watchfiles are used together with the uscan tool to check for new upstream releases.

• Launchpad:

  http://launchpad.net/package/+download .*/package-([\d\.]+)\.tar\..*

• SourceForge:

  http://sf.net/owner/package-([\d\.]+)\.tar\..*

• GitHub tag:

  https://github.com/owner/package/tags/ .*/v([\d\.]+)\.tar\..*