From cf7bc52ee1a8e59551a9002b9dd7bf628d5c9c0b Mon Sep 17 00:00:00 2001 From: Raphael Hertzog Date: Sun, 16 Mar 2008 18:52:25 +0100 Subject: [PATCH] * man/dpkg-source.1: Updated manual page with all changes of the branch --- man/dpkg-source.1 | 236 +++++++++++++++++++++++++++++++++++++--------- 1 file changed, 194 insertions(+), 42 deletions(-) diff --git a/man/dpkg-source.1 b/man/dpkg-source.1 index d195556c..a91582d1 100644 --- a/man/dpkg-source.1 +++ b/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. -- 2.39.5