3.1. Tools for processing source packages

Various tools are provided for manipulating source packages; they pack and unpack sources and help build of binary packages and help manage the distribution of new versions.

They are introduced and typical uses described here; see dpkg-source(1) for full documentation about their arguments and operation.

For examples of how to construct a Debian source package, and how to use those utilities that are used by Debian source packages, please see the hello example package.

3.1.1. dpkg-source - packs and unpacks Debian source packages

This program is frequently used by hand, and is also called from package-independent automated building scripts such as dpkg-buildpackage.

To unpack a package it is typically invoked with

dpkg-source -x .../path/to/filename.dsc

with the filename.tar.gz and filename.diff.gz (if applicable) in the same directory. It unpacks into package-version, and if applicable package-version.orig, in the current directory.

To create a packed source archive it is typically invoked:

dpkg-source -b package-version

This will create the .dsc, .tar.gz and .diff.gz (if appropriate) in the current directory. dpkg-source does not clean the source tree first - this must be done separately if it is required.

See also Source packages as archives.

3.1.2. dpkg-buildpackage - overall package-building control script

See dpkg-buildpackage(1).

3.1.3. dpkg-gencontrol - generates binary package control files

This program is usually called from debian/rules (see section_title) in the top level of the source tree.

This is usually done just before the files and directories in the temporary directory tree where the package is being built have their permissions and ownerships set and the package is constructed using dpkg-deb/. 1

dpkg-gencontrol must be called after all the files which are to go into the package have been placed in the temporary build directory, so that its calculation of the installed size of a package is correct.

It is also necessary for dpkg-gencontrol to be run after dpkg-shlibdeps so that the variable substitutions created by dpkg-shlibdeps in debian/substvars are available.

For a package which generates only one binary package, and which builds it in debian/tmp relative to the top of the source package, it is usually sufficient to call dpkg-gencontrol.

Sources which build several binaries will typically need something like:

dpkg-gencontrol -Pdebian/pkg -ppackage

The -P tells dpkg-gencontrol that the package is being built in a non-default directory, and the -p tells it which package’s control file should be generated.

dpkg-gencontrol also adds information to the list of files in debian/files, for the benefit of (for example) a future invocation of dpkg-genchanges.

3.1.4. dpkg-shlibdeps - calculates shared library dependencies

See dpkg-shlibdeps(1).

3.1.5. dpkg-distaddfile - adds a file to debian/files

Some packages’ uploads need to include files other than the source and binary package files.

dpkg-distaddfile adds a file to the debian/files file so that it will be included in the .changes file when dpkg-genchanges is run.

It is usually invoked from the binary target of debian/rules:

dpkg-distaddfile filename section priority

The filename is relative to the directory where dpkg-genchanges will expect to find it - this is usually the directory above the top level of the source tree. The debian/rules target should put the file there just before or just after calling dpkg-distaddfile.

The section and priority are passed unchanged into the resulting .changes file.

3.1.6. dpkg-genchanges - generates a .changes upload control file

See dpkg-genchanges(1).

3.1.7. dpkg-parsechangelog - produces parsed representation of a changelog

See dpkg-parsechangelog(1).

3.1.8. dpkg-architecture - information about the build and host system

See dpkg-architecture(1).