[ previous ] [ Contents ] [ 1 ] [ 2 ] [ 3 ] [ 4 ] [ 5 ] [ 6 ] [ 7 ] [ 8 ] [ 9 ] [ 10 ] [ 11 ] [ 12 ] [ A ] [ B ] [ C ] [ D ] [ E ] [ F ] [ G ] [ next ]

Ubuntu Policy Manual
Appendix C - Source packages (from old Packaging Manual)

The Debian binary packages in the distribution are generated from Debian sources, which are in a special format to assist the easy and automatic building of binaries.

C.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.

C.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, Section C.3.

C.1.2 dpkg-buildpackage - overall package-building control script

dpkg-buildpackage is a script which invokes dpkg-source, the debian/rules targets clean, build and binary, dpkg-genchanges and gpg (or pgp) to build a signed source and binary package upload.

It is usually invoked by hand from the top level of the built or unbuilt source directory. It may be invoked with no arguments; useful arguments include:

-uc, -us

Do not sign the .changes file or the source package .dsc file, respectively.


Invoke sign-command instead of finding gpg or pgp on the PATH. sign-command must behave just like gpg or pgp.


When root privilege is required, invoke the command root-command. root-command should invoke its first argument as a command, from the PATH if necessary, and pass its second and subsequent arguments to the command it calls. If no root-command is supplied then dpkg-buildpackage will take no special action to gain root privilege, so that for most packages it will have to be invoked as root to start with.

-b, -B

Two types of binary-only build and upload - see dpkg-source(1).

C.1.3 dpkg-gencontrol - generates binary package control files

This program is usually called from debian/rules (see The Debianised source tree, Section C.2) 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/ [101].

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/tmp-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.

C.1.4 dpkg-shlibdeps - calculates shared library dependencies

This program is usually called from debian/rules just before dpkg-gencontrol (see The Debianised source tree, Section C.2), in the top level of the source tree.

Its arguments are executables and shared libraries [102] for which shared library dependencies should be included in the binary package's control file.

If some of the found shared libraries should only warrant a Recommends or Suggests, or if some warrant a Pre-Depends, this can be achieved by using the -ddependency-field option before those executable(s). (Each -d option takes effect until the next -d.)

dpkg-shlibdeps does not directly cause the output control file to be modified. Instead by default it adds to the debian/substvars file variable settings like shlibs:Depends. These variable settings must be referenced in dependency fields in the appropriate per-binary-package sections of the source control file.

For example, a package that generates an essential part which requires dependencies, and optional parts that which only require a recommendation, would separate those two sets of dependencies into two different fields.[103] It can say in its debian/rules:

       dpkg-shlibdeps -dDepends program anotherprogram ... \
                      -dRecommends optionalpart anotheroptionalpart

and then in its main control file debian/control:

       Depends: ${shlibs:Depends}
       Recommends: ${shlibs:Recommends}

Sources which produce several binary packages with different shared library dependency requirements can use the -pvarnameprefix option to override the default shlibs: prefix (one invocation of dpkg-shlibdeps per setting of this option). They can thus produce several sets of dependency variables, each of the form varnameprefix:dependencyfield, which can be referred to in the appropriate parts of the binary package control files.

C.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.

C.1.6 dpkg-genchanges - generates a .changes upload control file

This program is usually called by package-independent automatic building scripts such as dpkg-buildpackage, but it may also be called by hand.

It is usually called in the top level of a built source tree, and when invoked with no arguments will print out a straightforward .changes file based on the information in the source package's changelog and control file and the binary and source packages which should have been built.

C.1.7 dpkg-parsechangelog - produces parsed representation of a changelog

This program is used internally by dpkg-source et al. It may also occasionally be useful in debian/rules and elsewhere. It parses a changelog, debian/changelog by default, and prints a control-file format representation of the information in it to standard output.

C.1.8 dpkg-architecture - information about the build and host system

This program can be used manually, but is also invoked by dpkg-buildpackage or debian/rules to set environment or make variables which specify the build and host architecture for the package building process.

C.2 The Debianised source tree

The source archive scheme described later is intended to allow a Debianised source tree with some associated control information to be reproduced and transported easily. The Debianised source tree is a version of the original program with certain files added for the benefit of the Debianisation process, and with any other changes required made to the rest of the source code and installation scripts.

The extra files created for Debian are in the subdirectory debian of the top level of the Debianised source tree. They are described below.

C.2.1 debian/rules - the main building script

See Main building script: debian/rules, Section 4.9.

C.2.2 debian/changelog

See Ubuntu changelog: debian/changelog, Section 4.4.

C.2.2.1 Defining alternative changelog formats

It is possible to use a different format to the standard one, by providing a parser for the format you wish to use.

In order to have dpkg-parsechangelog run your parser, you must include a line within the last 40 lines of your file matching the Perl regular expression: \schangelog-format:\s+([0-9a-z]+)\W The part in parentheses should be the name of the format. For example, you might say:

       @@@ changelog-format: joebloggs @@@

Changelog format names are non-empty strings of alphanumerics.

If such a line exists then dpkg-parsechangelog will look for the parser as /usr/lib/dpkg/parsechangelog/format-name or /usr/local/lib/dpkg/parsechangelog/format-name; it is an error for it not to find it, or for it not to be an executable program. The default changelog format is dpkg, and a parser for it is provided with the dpkg package.

The parser will be invoked with the changelog open on standard input at the start of the file. It should read the file (it may seek if it wishes) to determine the information required and return the parsed information to standard output in the form of a series of control fields in the standard format. By default it should return information about only the most recent version in the changelog; it should accept a -vversion option to return changes information from all versions present strictly after version, and it should then be an error for version not to be present in the changelog.

The fields are:

If several versions are being returned (due to the use of -v), the urgency value should be of the highest urgency code listed at the start of any of the versions requested followed by the concatenated (space-separated) comments from all the versions requested; the maintainer, version, distribution and date should always be from the most recent version.

For the format of the Changes field see Changes, Section 5.6.18.

If the changelog format which is being parsed always or almost always leaves a blank line between individual change notes these blank lines should be stripped out, so as to make the resulting output compact.

If the changelog format does not contain date or package name information this information should be omitted from the output. The parser should not attempt to synthesize it or find it from other sources.

If the changelog does not have the expected format the parser should exit with a nonzero exit status, rather than trying to muddle through and possibly generating incorrect output.

A changelog parser may not interact with the user at all.

C.2.3 debian/substvars and variable substitutions

See Variable substitutions: debian/substvars, Section 4.10.

C.2.4 debian/files

See Generated files list: debian/files, Section 4.12.

C.2.5 debian/tmp

This is the canonical temporary location for the construction of binary packages by the binary target. The directory tmp serves as the root of the file system tree as it is being constructed (for example, by using the package's upstream makefiles install targets and redirecting the output there), and it also contains the DEBIAN subdirectory. See Creating package files - dpkg-deb, Section B.1.

If several binary packages are generated from the same source tree it is usual to use several debian/tmpsomething directories, for example tmp-a or tmp-doc.

Whatever tmp directories are created and used by binary must of course be removed by the clean target.

C.3 Source packages as archives

As it exists on the FTP site, a Debian source package consists of three related files. You must have the right versions of all three to be able to use them.

Debian source control file - .dsc

This file is a control file used by dpkg-source to extract a source package. See Debian source control files -- .dsc, Section 5.4.

Original source archive - package_upstream-version.orig.tar.gz

This is a compressed (with gzip -9) tar file containing the source code from the upstream authors of the program.

Debianisation diff - package_upstream_version-revision.diff.gz

This is a unified context diff (diff -u) giving the changes which are required to turn the original source into the Debian source. These changes may only include editing and creating plain files. The permissions of files, the targets of symbolic links and the characteristics of special files or pipes may not be changed and no files may be removed or renamed.

All the directories in the diff must exist, except the debian subdirectory of the top of the source tree, which will be created by dpkg-source if necessary when unpacking.

The dpkg-source program will automatically make the debian/rules file executable (see below).

If there is no original source code - for example, if the package is specially prepared for Debian or the Debian maintainer is the same as the upstream maintainer - the format is slightly different: then there is no diff, and the tarfile is named package_version.tar.gz, and preferably contains a directory named package-version.

C.4 Unpacking a Debian source package without dpkg-source

dpkg-source -x is the recommended way to unpack a Debian source package. However, if it is not available it is possible to unpack a Debian source archive as follows:

  • Untar the tarfile, which will create a .orig directory.

  • Rename the .orig directory to package-version.

  • Create the subdirectory debian at the top of the source tree.

  • Apply the diff using patch -p0.

  • Untar the tarfile again if you want a copy of the original source code alongside the Debianised version.

  • It is not possible to generate a valid Debian source archive without using dpkg-source. In particular, attempting to use diff directly to generate the .diff.gz file will not work.

    C.4.1 Restrictions on objects in source packages

    The source package may not contain any hard links [104] [105], device special files, sockets or setuid or setgid files. [106]

    The source packaging tools manage the changes between the original and Debianised source using diff and patch. Turning the original source tree as included in the .orig.tar.gz into the debianised source must not involve any changes which cannot be handled by these tools. Problematic changes which cause dpkg-source to halt with an error when building the source package are:

    Changes which cause dpkg-source to print a warning but continue anyway are:

    Changes which are not represented, but which are not detected by dpkg-source, are:

    The debian directory and debian/rules are handled specially by dpkg-source - before applying the changes it will create the debian directory, and afterwards it will make debian/rules world-executable.

    [ previous ] [ Contents ] [ 1 ] [ 2 ] [ 3 ] [ 4 ] [ 5 ] [ 6 ] [ 7 ] [ 8 ] [ 9 ] [ 10 ] [ 11 ] [ 12 ] [ A ] [ B ] [ C ] [ D ] [ E ] [ F ] [ G ] [ next ]

    Ubuntu Policy Manual

    version, 2009-06-19

    The Debian Policy Mailing List
    The Ubuntu Developers Mailing List