[ previous ] [ Contents ] [ 1 ] [ 2 ] [ 3 ] [ 4 ] [ 5 ] [ 6 ] [ 7 ] [ 8 ] [ 9 ] [ 10 ] [ 11 ] [ 12 ] [ A ] [ B ] [ C ] [ D ] [ E ] [ F ] [ G ] [ next ]
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.
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.
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.
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:
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 use the fakeroot command, which
is sufficient to build most packages without actually requiring root
privileges.
Two types of binary-only build and upload - see dpkg-source(1).
dpkg-gencontrol - generates binary package control files
This program is usually called from debian/rules (see The Debian package 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/ [121].
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.
dpkg-shlibdeps - calculates shared library dependencies
See dpkg-shlibdeps(1).
dpkg-distaddfile - adds a file to debian/filesSome 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.
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.
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.
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.
The source archive scheme described later is intended to allow a Debian package source tree with some associated control information to be reproduced and transported easily. The Debian package source tree is a version of the original program with certain files added for the benefit of the packaging 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 Debian package source tree. They are described below.
debian/rules - the main building script
See Main building script:
debian/rules, Section 4.9.
debian/substvars and variable substitutions
See Variable substitutions:
debian/substvars, Section 4.10.
debian/files
See Generated files list:
debian/files, Section 4.12.
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.
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.
This file is a control file used by dpkg-source to extract a
source package. See Debian source control
files -- .dsc, Section 5.4.
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.
package_upstream_version-revision.diff.gzThis 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.
dpkg-sourcedpkg-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 Debian 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.
The source package may not contain any hard links [122] [123], device special files, sockets or setuid or setgid files. [124]
The source packaging tools manage the changes between the original and Debian
source using diff and patch. Turning the original
source tree as included in the .orig.tar.gz into the Debian
package 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:
Adding or removing symbolic links, sockets or pipes.
Changing the targets of symbolic links.
Creating directories, other than debian.
Changes to the contents of binary files.
Changes which cause dpkg-source to print a warning but continue
anyway are:
Removing files, directories or symlinks. [125]
Changed text files which are missing the usual final newline (either in the original or the modified source tree).
Changes which are not represented, but which are not detected by
dpkg-source, are:
Changing the permissions of files (other than debian/rules) and
directories.
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 ]
Debian Policy Manual
version 3.9.4.0, 2012-09-19