From dfce3fac910526aa41d6a22ce826c2a725c1b431 Mon Sep 17 00:00:00 2001 From: Raphael Hertzog Date: Sun, 30 Mar 2008 19:03:29 +0200 Subject: [PATCH] * man/dpkg-source.1: Say clearly that the format 2.0 is replaced by 3.0 (quilt) --- man/ChangeLog | 6 ++++ man/dpkg-source.1 | 85 ++++++++++++++++++++--------------------------- 2 files changed, 42 insertions(+), 49 deletions(-) diff --git a/man/ChangeLog b/man/ChangeLog index 19ca866d..e7de6171 100644 --- a/man/ChangeLog +++ b/man/ChangeLog @@ -1,3 +1,9 @@ +2008-03-30 Raphael Hertzog + + * dpkg-source.1: Make it clear that Format: 2.0 is not really + meant to be widely used by moving all the explanations in the + section describing the format "3.0 (quilt)". + 2008-03-30 Guillem Jover * po/dpkg-man.pot: Regenerated. diff --git a/man/dpkg-source.1 b/man/dpkg-source.1 index d92aa3ee..c8cd8027 100644 --- a/man/dpkg-source.1 +++ b/man/dpkg-source.1 @@ -312,7 +312,27 @@ 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 +Also known as wig&pen. This format is not recommended for wide-spread +usage, the format "3.0 (quilt)" replaces it. Wig&pen was the first +specification of a new-generation source package format. + +The behaviour of this format is the same as the "3.0 (quilt)" format +except that it doesn't use an explicit list of patches. All files in +\fBdebian/patches/\fP matching the perl regular expression \fB[\\w\-]+\fP +must be valid patches: they are applied at extraction time. + +When building a new source package, any change to the upstream source +is stored in a patch named \fBzz_debian-diff-auto\fP. +. +.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) +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 @@ -324,28 +344,30 @@ 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 on top of the source directory after prior -removal of any pre-existing \fBdebian\fP directory). Note that the +removal of any pre-existing \fBdebian\fP directory. Note that the debian tarball must contain a \fBdebian\fP sub-directory but it can also contain binary files outside of that directory (see \fB\-\-include\-binaries\fP option). .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 remove -files. +All patches listed in \fBdebian/patches/debian.series\fP or +\fBdebian/patches/series\fP are then applied. +If the former file is used and the latter one doesn't exist (or is a +symlink), 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. The +patches can 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. +patches except \fBdebian-changes-\fP\fIversion\fP\fB.diff\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. Any change on a binary file -is not representable in a diff and will thus lead to a failure unless -the maintainer deliberately decided to include that modified binary -file in the debian tarball (by listing it in +\fBdebian/patches/debian-changes-\fP\fIversion\fP\fB.diff\fP. Any change +on a binary file is not representable in a diff and will thus lead to a +failure unless the maintainer deliberately decided to include that +modified binary file in the debian tarball (by listing it in \fBdebian/source/include-binaries\fP). The updated debian directory and the list of modified binaries is then @@ -353,7 +375,9 @@ 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). +\fB-i\fP option in the \fB\-\-help\fP output). In particular, the +\fB.pc\fP directory used by quilt is ignored during generation of the +automatic patch. Note: it's very important to generate the source package with all patches applied, otherwise the generation of the automatic patch will lead to @@ -372,43 +396,6 @@ Include timestamp in the automatically generated patch. Add all modified binaries in the debian tarball. Also add them to \fBdebian/source/include-binaries\fP: they will be added by default in subsequent builds and this option is thus no more needed. -. -.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. -.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\fP 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 -- 2.39.5