* man/dpkg-source.1: Updated manual page with all changes of the branch

man/dpkg-source.1

@@ -1,5 +1,5 @@
-.\" 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
 .
@@ -42,26 +42,20 @@ extractors' umask; if the parent directory is setgid then the
 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.
@@ -69,7 +63,7 @@ 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
@@ -90,12 +84,18 @@ Specifies the format of the changelog. By default the format is read
 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
@@ -105,13 +105,6 @@ Override or add an output control file field.
 .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,
@@ -174,17 +167,59 @@ documentation.
 
 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
@@ -276,17 +311,132 @@ All the
 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),
@@ -296,6 +446,8 @@ are not legal in package names or version numbers.
 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.