dpkg/man/dpkg-source.1

.\" Authors: Ian Jackson
.TH dpkg\-source 1 "2007-09-24" "Debian Project" "dpkg utilities"
.SH NAME
dpkg\-source \- Debian source package (.dsc) manipulation tool
.
.SH SYNOPSIS
.B dpkg\-source
.RI [ options ]
.I command
.
.SH DESCRIPTION
.B dpkg\-source
packs and unpacks Debian source archives.

None of these commands allow multiple options to be combined into one,
and they do not allow the value for an option to be specified in a
separate argument.
.
.SH COMMANDS
.TP
.BI "\-x " filename ".dsc " \fR[\fPoutput-directory\fR]\fP
Extract a source package. One non-option argument must be supplied,
the name of the Debian source control file
.RB ( .dsc ).
An optional second non-option argument may be supplied to specify the
directory to extract the source package to, this must not exist. If
no output directory is specified, the source package is extracted into
a directory named \fIsource\fR-\fIversion\fR under the current working
directory.

.B dpkg\-source
will read the names of the other file(s) making up the source package
from the control file; they are assumed to be in the same directory as
the
.BR .dsc .

The files in the extracted package will have their permissions and
ownerships set to those which would have been expected if the files
and directories had simply been created - directories and executable
files will be 0777 and plain files will be 0666, both modified by the
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.


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.
.TP
.BR \-\-version
Show the version and exit.
.
.SH OPTIONS
.TP
.BI \-c controlfile
Specifies the main source control file to read information from. The
default is
.BR debian/control .
If given with relative pathname this is interpreted starting at
the source tree's top level directory.
.TP
.BI \-l changelogfile
Specifies the change log file to read information from. The
default is
.BR debian/changelog .
If given with relative pathname this is interpreted starting at
the source tree's top level directory.
.TP
.BI \-F changelogformat
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 \-V name = value
Set an output substitution variable.
See \fBdeb\-substvars\fP(5) for a discussion of output substitution.
.TP
.BI \-T substvarsfile
Read substitution variables in
.IR substvarsfile ;
the default is to not read any file.
.TP
.BI \-D field = value
Override or add an output control file field.
.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,
it only affects new files. Supported values are:
.IR gzip ", " bzip2 ", and " lzma .
\fIgzip\fP is the default.
.TP
.BR \-z \fIlevel\fP
Compression level to use. As with \fB\-Z\fP it only affects newly created
files. Supported values are:
.IR 1 " to " 9 ", " best ", and " fast .
\fI9\fP is the default.
.TP
.BR \-i [\fIregexp\fP]
You may specify a perl regular expression to match files you want
filtered out of the list of files for the diff. (This list is
generated by a find command.) (If the source package is being built as a
version 3 source package using a VCS, this is instead used to
ignore uncommitted files.) \fB\-i\fP by itself enables the option,
with a default that will filter out control files and directories of the
most common revision control systems, backup and swap files and Libtool
build output directories. There can only be one active regexp, of multiple
\fB\-i\fP options only the last one will take effect.

This is very helpful in cutting out extraneous files that get included
in the diff, e.g. if you maintain your source in a revision control
system and want to use a checkout to build a source package without
including the additional files and directories that it will usually
contain (e.g. CVS/, .cvsignore, .svn/). The default regexp is already
very exhaustive, but if you need to replace it, please note that by
default it can match any part of a path, so if you want to match the
begin of a filename or only full filenames, you will need to provide
the necessary anchors (e.g. '(^|/)', '($|/)') yourself.
.TP
.BR \-I [\fIfile-pattern\fP]
If this option is specified, the pattern will be passed to
.BR tar (1)'s
\-\-exclude
option when it is called to generate a .orig.tar or .tar file. For
example, \-ICVS will make tar skip over CVS directories when generating
a .tar.gz file. The option may be repeated multiple times to list multiple
patterns to exclude.

\fB\-I\fP by itself adds default \-\-exclude options that will
filter out control files and directories of the most common revision
control systems, backup and swap files and Libtool build output
directories.
.PP
.B Note:
While they have similar purposes, \fB-i\fP and \fB-I\fP have very
different syntax and semantics. \fB-i\fP can only be specified once and
takes a perl compatible regular expression which is matched against
the full relative path of each file. \fB-I\fP can specified
multiple times and takes a filename pattern with shell wildcards.
The pattern is applied to the full relative path but also
to each part of the path individually. The exact semantic of tar's
\-\-exclude option is somewhat complicated, see
http://www.gnu.org/software/tar/manual/tar.html#wildcards for a full
documentation.

The default regexp and patterns for both options can be seen
in the output of the \fB\-\-help\fP command.
.TP
.B Build options (with -b):
.PP
.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
.IB package _ upstream-version .orig.tar. extension \fR.
It will leave this original source in place as a tarfile, or copy it
to the current directory if it isn't already there. The
tarball will be unpacked into 
.IB directory .orig
for the generation of the diff.
.TP
.B \-sp
Like
.B \-sk
but will remove the directory again afterwards.
.TP
.B \-su
Specifies that the original source is expected as a directory, by
default
.IB package - upstream-version .orig
and
.B dpkg\-source
will create a new original source archive from it.
.TP
.B \-sr
Like
.B \-su
but will remove that directory after it has been used.
.TP
.B \-ss
Specifies that the original source is available both as a directory
and as a tarfile. dpkg-source will use the directory to create the diff, but
the tarfile to create the
.BR .dsc .
This option must be used with care - if the directory and tarfile do
not match a bad source archive will be generated.
.TP
.B \-sn
Specifies to not look for any original source, and to not generate a diff.
The second argument, if supplied, must be the empty string. This is
used for Debian-specific packages which do not have a separate
upstream source and therefore have no debianisation diffs.
.TP
.BR \-sa " or " \-sA
Specifies to look for the original source archive as a tarfile or as a
directory - the second argument, if any, may be either, or the empty
string (this is equivalent to using
.BR \-sn ).
If a tarfile is found it will unpack it to create the diff and remove
it afterwards (this is equivalent to
.BR \-sp );
if a directory is found it will pack it to create the original source
and remove it afterwards (this is equivalent to
.BR \-sr );
if neither is found it will assume that the package has no
debianisation diffs, only a straightforward source archive (this is
equivalent to
.BR \-sn ).
If both are found then \fBdpkg\-source\fP will ignore the directory,
overwriting it, if
.B \-sA
was specified (this is equivalent to
.BR \-sP )
or raise an error if
.B \-sa
was specified.
.B \-sA
is the default.
.TP
.B Extract options (with \-x):
.PP
In all cases any existing original source tree will be removed.
.TP
.B \-sp
Used when extracting then the original source (if any) will be left
as a tarfile. If it is not already located in the current directory
or if an existing but different file is there it will be copied there.
(\fBThis is the default\fP).
.TP
.B \-su
Unpacks the original source tree.
.TP
.B \-sn
Ensures that the original source is neither copied to the current
directory nor unpacked. Any original source tree that was in the
current directory is still removed.
.PP
All the
.BI \-s X
options are mutually exclusive. If you specify more than one only the
last one will be used.
.
.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),
.BR dselect (1).
.
.SH AUTHORS
Copyright (C) 1995-1996 Ian Jackson
.br
Copyright (C) 2000 Wichert Akkerman
.sp
This is free software; see the GNU General Public Licence version 2 or later
for copying conditions. There is NO WARRANTY.