path: root/man/dpkg-source.1

.\" Authors: Ian Jackson
.TH dpkg\-source 1 "2007-07-18" "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 [" options "] " directory " [" orig-directory | orig-targz |'']
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 unpacked source tree. 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.gz
or the original source directory
.IB directory .orig
depending on the \fB\-sX\fP arguments.
.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
.BR debian/substvars .
.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 \-W
This option turns certain errors into warnings.
.TP
.BI \-E
This option negates a previously set
.BR \-W "."
.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.) \fB\-i\fR 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.

This is very helpful in cutting out extraneous files that get included
in the .diff.gz, (eg: "debian/BUGS_TODO/*" or "debian/RCS/*,v"). For
instance, if you maintain a package that you track via remote CVS,
where you don't have access permissions for committing the debian
control files and making tags for \fIcvs\-buildpackage(1)\fR, it is
necessary to perform an extra checkout/update into a directory you
keep pristine, to generate the .orig.tar.gz from. That directory will
have CVS/Entries files in it that will contain timestamps that differ
from the ones in your working directory, thus causing them to be
unnecessarily included in every .diff.gz, unless you use the \fB\-i\fR
switch.
.TP
.BI \-I filename
If this option is specified, the filename will be passed to tar's \-\-exclude
option when it is called to generate a .orig.tar.gz or .tar.gz 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
filenames to exclude.
.PP
All the
.BI \-s X
options are mutually exclusive. If you specify more than one only the
last one will be used.
.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.
.TP
.BR \-sk
Specifies to expect the original source as a tarfile, by default
.IB package _ upstream-version .orig.tar.gz\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.
.TP
.B \-sp
Like
.B \-sk
but will remove that tarball 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. If 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.
.
.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.