-.\" Authors: Ian Jackson
-.TH dpkg\-source 1 "2007-09-24" "Debian Project" "dpkg utilities"
+.\" Authors: Ian Jackson, Raphael Hertzog
+.TH dpkg\-source 1 "2008-03-16" "Debian Project" "dpkg utilities"
.SH NAME
dpkg\-source \- Debian source package (.dsc) manipulation tool
.
extracted directories will be too, and all the files and directories
will inherit its group ownership.
.TP
-.RI "\fB\-b\fP " directory " [" orig-directory | orig-targz |\(aq\(aq]
-Build a source package. One or two non-option arguments should
-be supplied. The first is taken as the name of the directory
-containing the debianized source tree (i.e. with a debian sub-directory
-and maybe changes to the original files). If a second argument is supplied
-it should be the name of the original source directory or tarfile or
-the empty string if the package is a Debian-specific one and so has no
-Debianisation diffs. If no second argument is supplied then
-.B dpkg\-source
-will look for the original source tarfile
-.IB package _ upstream-version .orig.tar. extension
-(where \fIextension\fP is one of
-.BR gz ", " bz2 ", and " lzma )
-or the original source directory
-.IB directory .orig
-depending on the \fB\-sX\fP arguments.
+.RI "\fB\-b\fP " directory " [" format-specific-parameters ]
+Build a source package. The first non-option argument is taken as the
+name of the directory containing the debianized source tree (i.e. with a
+debian sub-directory and maybe changes to the original files).
+Depending on the source package format used to build the package,
+additional parameters might be accepted.
+\fBdpkg\-source\fP will build the source package with the first format
+that works from this ordered list:
+the format indicated in the \fIFormat\fP field of \fBdebian/control\fP,
+the format(s) indicated with the \fI\-\-format\fP command-line option(s),
+"1.0", "3.0 (native)". See below for an extensive description of
+various source package formats.
-If the source package is being built as a version 3 source package using
-a VCS, no upstream tarball or original source directory is needed.
.TP
.BR \-h ", " \-\-help
Show the usage message and exit.
.BR \-\-version
Show the version and exit.
.
-.SH OPTIONS
+.SH GENERIC BUILD OPTIONS
.TP
.BI \-c controlfile
Specifies the main source control file to read information from. The
from a special line near the bottom of the changelog or failing that
defaults to the debian standard format.
.TP
+.BI \-\-format= value
+Try first the given format for building the source package. If used
+multiple times, the last value is tried first and the first one is
+tried last just before trying the default formats. It doesn't override
+any explicit \fIFormat\fP field in \fBdebian/control\fP.
+.TP
.BI \-V name = value
-Set an output substitution variable.
+\fBDeprecated\fP. Set an output substitution variable.
See \fBdeb\-substvars\fP(5) for a discussion of output substitution.
.TP
.BI \-T substvarsfile
-Read substitution variables in
+\fBDeprecated\fP. Read substitution variables in
.IR substvarsfile ;
the default is to not read any file.
.TP
.BI \-U field
Remove an output control file field.
.TP
-.BI \-E
-This option turns certain warnings into errors.
-.TP
-.BI \-W
-This option negates a previously set
-.BR \-E "."
-.TP
.BR \-Z \fIcompression\fP
Specify the compression to use for created files (tarballs and diffs).
Note that this option will not cause existing tarballs to be recompressed,
The default regexp and patterns for both options can be seen
in the output of the \fB\-\-help\fP command.
+.SH GENERIC EXTRACT OPTIONS
.TP
-.B Build options (with -b):
+.BI \-\-no\-copy
+Do not copy original tarballs near the extracted source package.
+.TP
+.BI \-\-no\-check
+Do not check signatures and checksums before unpacking.
+
+.SH SOURCE PACKAGE FORMATS
+.SS Format: 1.0
+A source package in this format consists either of a \fB.orig.tar.gz\fP
+associated to a \fB.diff.gz\fP or a single \fB.tar.gz\fP (in that case
+the package is said to be \fInative\fP).
+
+.B Extracting
+
+Extracting a native package is a simple extraction of the single
+tarball in the target directory. Extracting a non-native package
+is done by first unpacking the \fB.orig.tar.gz\fP and then applying
+the patch contained in the \fB.diff.gz\fP file. The timestamp of
+all patched files is reset to the extraction time of the source
+package (this avoids timestamp skews leading to problems when
+autogenerated files are patched). The diff can create new files (the whole
+debian directory is created that way) but can't remove files (empty files
+will be left over).
+
+.B Building
+
+Building a native package is just creating a single tarball with
+the source directory. Building a non-native package involves
+extracting the original tarball in a separate ".orig" directory and
+regenerating the \fB.diff.gz\fP by comparing the source package
+\fIdirectory\fP with the .orig directory.
+
+.TP
+.B Build options (with \-b):
.PP
+If a second non-option argument is supplied it should be the name of the
+original source directory or tarfile or the empty string if the package is
+a Debian-specific one and so has no Debianisation diffs. If no second
+argument is supplied then
+.B dpkg\-source
+will look for the original source tarfile
+.IB package _ upstream-version .orig.tar.gz
+or the original source directory
+.IB directory .orig
+depending on the \fB\-sX\fP arguments.
+
.BR \-sa ", " \-sp ", " \-sk ", " \-su " and " \-sr
will not overwrite existing tarfiles or directories. If this is
desired then
.BR \-sA ", " \-sP ", " \-sK ", " \-sU " and " \-sR
should be used instead.
-.PP
-If the source package is being built as a version 3 source package using
-a VCS, these options do not make sense, and will be ignored.
.TP
.BR \-sk
Specifies to expect the original source as a tarfile, by default
options are mutually exclusive. If you specify more than one only the
last one will be used.
.
+.SS Format: 2.0
+Also known as wig&pen. A source package in this format contains at least
+an original tarball (\fB.orig.tar.\fP\fIext\fP where \fIext\fP can be
+\fBgz\fP, \fBbz2\fP and \fBlzma\fP) and a debian tarball
+(\fB.debian.tar.\fP\fIext\fP). It can also contain additional original
+tarballs (\fB.orig-\fP\fIcomponent\fP\fB.tar.\fP\fIext\fP).
+.PP
+.B Extracting
+.PP
+The main original tarball is extracted first, then all additional original
+tarballs are extracted in subdirectories named after the \fIcomponent\fP
+part of their filename (any pre-existing directory is replaced). The
+debian tarball is extracted in a \fBdebian\fP subdirectory (and replaces
+any pre-existing \fBdebian\fP directory).
+.PP
+All patches in \fBdebian/patches\fP matching the perl regular expression
+\fB[\\w\-]+\fP are then applied in alphabetical order. The timestamp of
+patched files are reset to the extraction time. The patches can't remove
+files.
+.PP
+.B Building
+.PP
+All original tarballs found in the current directory are extracted in a
+temporary directory by following the same logic than the unpack, the
+debian directory is copied over in the temporary directory, and all
+patches except \fBzz_debian-diff-auto\fP are applied.
+The temporary directory is compared to the source package directory
+and the diff (if non-empty) is stored in
+\fBdebian/patches/zz_debian-diff-auto\fP. The updated debian directory is
+then used to regenerate the debian tarball.
+
+The automatically generated diff doesn't include changes on VCS specific
+files as well as many temporary files (see default value associated to
+\fB-i\fP option in the \fB\-\-help\fP output).
+
+Note: it's very important to generate the source package with all
+patches applied, otherwise the generation of the automatic patch will lead to
+a patch that reverts the patches which were not applied.
+.PP
+.B Build options
+.TP
+.B \-\-include\-removal
+Do not ignore removed files and include them in the automatically
+generated patch.
+.TP
+.B \-\-include\-timestamp
+Include timestamp in the automatically generated patch.
+.SS Format: 3.0 (native)
+This format is an extension of the native package format as defined
+in the 1.0 format. It supports all compression methods and
+will ignore by default any VCS specific files and directories
+as well as many temporary files (see default value associated to
+\fB-I\fP option in the \fB\-\-help\fP output).
+.
+.SS Format: 3.0 (quilt)
+This is a variant of the 2.0 format. The differences concern the
+management of the patches. This format uses an explicit list of
+patches contained in \fBdebian/patches/debian.series\fP or
+\fBdebian/patches/series\fP. The patches can remove files.
+.PP
+.B Extracting
+.PP
+Unpacking of tarballs is done exactly like in the 2.0 format.
+.PP
+When it comes to patch application, the list of patches is taken from
+\fBdebian/patches/debian.series\fP or \fBdebian/patches/series\fP.
+If the former file is used and the latter one doesn't exist, then the
+latter is replaced with a symlink to the former. This is meant to simplify
+usage of quilt to manage the set of patches.
+.PP
+.B Building
+.PP
+It behaves like the 2.0 format except that the name of the automatically
+generated patch is \fBdebian-changes-\fP\fIversion\fP\fB.diff\fP and the
+\fBseries\fP file is obviously updated to add/remove the automatically
+generated patch as needed.
+
+The \fB.pc\fI directory used by quilt is ignored during generation of the
+automatic patch.
+.PP
+.B Build options
+.PP
+It supports all the options of the 2.0 format.
+.PP
+.B Extract options
+.TP
+.B \-\-without\-quilt
+Don't use quilt to apply patches but dpkg-source's own code. It won't be
+possible to use quilt directly on the unpacked directory but it will be
+free of quilt's temporary files as well.
+.
+.SS Format: 3.0 (custom)
+This format is particular. It doesn't represent a real source package
+format but can be used to create source packages with arbitrary files.
+.PP
+.B Build options
+.PP
+All non-option arguments are taken as files to integrate in the
+generated source package. They must exist and are preferrably
+in the current directory. At least one file must be given.
+.TP
+.BI \-\-target\-format= value
+\fBRequired\fP. Defines the real format of the generated source package.
+The generated .dsc file will contain this value in its \fIFormat\fP field
+and not "3.0 (custom)".
+.
+.SS Format: 3.0 (git) and 3.0 (bzr)
+Those formats are experimental. They generate a single tarball
+containing the corresponding VCS repository.
+.PP
+.B Extracting
+.PP
+The tarball is unpacked and then the VCS is used to checkout the current
+branch.
+.PP
+.B Building
+.PP
+Before going any further, some checks are done to ensure that we
+don't have any non-ignored uncommitted changes.
+.PP
+Then the VCS specific part of the source directory is copied over to a
+temporary directory. Before being packed in a tarball, various cleanup are
+done to save space.
.SH BUGS
The point at which field overriding occurs compared to certain
standard output field settings is rather confused.
-
-The binary package entries in the
-.B debian/files
-file will be passed through variable substitution twice. This should
-not matter, since
-.BR $ ", " { " and " }
-are not legal in package names or version numbers.
-.
.SH SEE ALSO
.BR dpkg\-deb (1),
.BR dpkg (1),
Copyright (C) 1995-1996 Ian Jackson
.br
Copyright (C) 2000 Wichert Akkerman
+.br
+Copyright (C) 2008 Rapha\[:e]l Hertzog
.sp
This is free software; see the GNU General Public Licence version 2 or later
for copying conditions. There is NO WARRANTY.
projects / dpkg / commitdiff