Provided by: dpkg-dev_1.14.20ubuntu6_all bug

NAME

       dpkg-source - Debian source package (.dsc) manipulation tool

SYNOPSIS

       dpkg-source [options] command

DESCRIPTION

       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.

COMMANDS

       -x filename.dsc [output-directory]
              Extract  a  source  package.  One  non-option  argument  must be
              supplied, the name of the Debian source control file (.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  source-version  under  the
              current working directory.

              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 .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.

              If the source package uses a non-standard format (currently this
              means all formats except "1.0"), its  name  will  be  stored  in
              debian/source/format  so that the following builds of the source
              package use the same format by default.

       -b 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.

              dpkg-source will build the source package with the first  format
              that  works  from this ordered list: the format indicated in the
              Format field of debian/control, the format(s) indicated with the
              --format   command-line   option(s),  the  format  indicated  in
              debian/source/format, "1.0", "3.0 (native)". See  below  for  an
              extensive description of various source package formats.

       -h, --help
              Show the usage message and exit.

       --version
              Show the version and exit.

GENERIC BUILD OPTIONS

       -ccontrolfile
              Specifies the main source control file to read information from.
              The default is debian/control.  If given with relative  pathname
              this  is  interpreted  starting  at  the source tree’s top level
              directory.

       -lchangelogfile
              Specifies the change log file  to  read  information  from.  The
              default  is  debian/changelog.   If given with relative pathname
              this is interpreted starting at  the  source  tree’s  top  level
              directory.

       -Fchangelogformat
              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.

       --format=value
              Try  first  the given format for building the source package. If
              used multiple  times,  they  are  tried  in  order.  It  doesn’t
              override any explicit Format field in debian/control but it does
              override any format given in debian/source/format.

       -Vname=value
              Deprecated.  Set   an   output   substitution   variable.    See
              deb-substvars(5) for a discussion of output substitution.

       -Tsubstvarsfile
              Deprecated.  Read  substitution  variables in substvarsfile; the
              default is to not read any file.

       -Dfield=value
              Override or add an output control file field.

       -Ufield
              Remove an output control file field.

       -Zcompression
              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: gzip, bzip2, and lzma.  gzip is the default.

       -zlevel
              Compression  level  to  use.  As  with  -Z it only affects newly
              created files. Supported values are: 1 to 9, best, and fast.   9
              is the default.

       -i[regexp]
              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.)  -i 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 -i 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.

       -I[file-pattern]
              If  this  option  is  specified,  the  pattern will be passed to
              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.

              -I 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.

       Note:  While  they have similar purposes, -i and -I have very different
       syntax and semantics. -i can only be specified once and  takes  a  perl
       compatible  regular  expression  which  is  matched  against  the  full
       relative path of each file. -I 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 --help command.

GENERIC EXTRACT OPTIONS

       --no-copy
              Do not copy original tarballs near the extracted source package.

       --no-check
              Do not check signatures and checksums before unpacking.

SOURCE PACKAGE FORMATS

   Format: 1.0
       A  source  package  in  this  format  consists either of a .orig.tar.gz
       associated to a .diff.gz or a single .tar.gz (in that case the  package
       is said to be native).

       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 .orig.tar.gz and then applying the patch
       contained in the .diff.gz 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).

       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
       .diff.gz by comparing the  source  package  directory  with  the  .orig
       directory.

       Build options (with -b):

       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  dpkg-source  will  look  for  the
       original  source  tarfile  package_upstream-version.orig.tar.gz  or the
       original  source  directory  directory.orig  depending   on   the   -sX
       arguments.

       -sa,  -sp,  -sk,  -su  and  -sr will not overwrite existing tarfiles or
       directories. If this is desired then -sA, -sP, -sK, -sU and -sR  should
       be used instead.

       -sk    Specifies to expect the original source as a tarfile, by default
              package_upstream-version.orig.tar.extension.  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 directory.orig for the generation of the diff.

       -sp    Like -sk but will remove the directory again afterwards.

       -su    Specifies  that  the original source is expected as a directory,
              by default package-upstream-version.orig  and  dpkg-source  will
              create a new original source archive from it.

       -sr    Like  -su but will remove that directory after it has been used.

       -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  .dsc.   This
              option  must be used with care - if the directory and tarfile do
              not match a bad source archive will be generated.

       -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.

       -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  -sn).   If  a
              tarfile is found it will unpack it to create the diff and remove
              it afterwards (this is equivalent to -sp);  if  a  directory  is
              found  it  will pack it to create the original source and remove
              it afterwards (this is equivalent to -sr); if neither  is  found
              it will assume that the package has no debianisation diffs, only
              a straightforward source archive (this is  equivalent  to  -sn).
              If  both  are  found then dpkg-source will ignore the directory,
              overwriting it, if -sA was specified (this is equivalent to -sP)
              or raise an error if -sa was specified.  -sA is the default.

       Extract options (with -x):

       In all cases any existing original source tree will be removed.

       -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.  (This is the default).

       -su    Unpacks the original source tree.

       -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.

       All the -sX options are mutually exclusive. If you  specify  more  than
       one only the last one will be used.

   Format: 2.0
       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
       debian/patches/  matching  the  perl  regular expression [\w-]+ 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 zz_debian-diff-auto.

   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  -I  option  in  the
       --help output).

   Format: 3.0 (quilt)
       A  source  package in this format contains at least an original tarball
       (.orig.tar.ext where ext can be gz, bz2 and lzma) and a debian  tarball
       (.debian.tar.ext).  It  can  also  contain additional original tarballs
       (.orig-component.tar.ext).

       Extracting

       The main original tarball  is  extracted  first,  then  all  additional
       original  tarballs  are  extracted  in  subdirectories  named after the
       component  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  debian  directory.
       Note that the debian tarball must contain a debian sub-directory but it
       can  also  contain  binary  files  outside  of  that   directory   (see
       --include-binaries option).

       All     patches     listed     in    debian/patches/debian.series    or
       debian/patches/series 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.  Note  however that while
       dpkg-source parses correctly series files with  explicit  options  used
       for patch application (stored on each line after the patch filename and
       one or more spaces), it does ignore those  options  and  always  expect
       patches  that can be applied with the -p1 option of patch. It will thus
       emit a warning when it encounters such options, and the build is likely
       to fail.

       Similarly  to  quilt’s  default behaviour, the patches can remove files
       too.

       The file debian/patches/.dpkg-source-applied is created if some patches
       have been applied during the extraction.

       Building

       All original tarballs found in the current directory are extracted in a
       temporary directory by following the same logic as for the unpack,  the
       debian  directory  is  copied  over in the temporary directory, and all
       patches  except  debian-changes-version  are  applied.   The  temporary
       directory  is compared to the source package directory and the diff (if
       non-empty)  is  stored  in  debian/patches/debian-changes-version.  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
       debian/source/include-binaries). The build will also fail if  it  finds
       binary  files  in  the  debian  sub-directory  unless  they  have  been
       whitelisted through debian/source/include-binaries.

       The updated debian directory and the list of modified binaries 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  -i option in the --help output). In particular, the .pc
       directory used by quilt is ignored during generation of  the  automatic
       patch.

       Note:  dpkg-source  expects the source tree to have all patches applied
       when you generate the source package. This is not  the  case  when  the
       source  tree  has been obtained by unpacking a source package using the
       Format: 1.0 for instance. To mitigate  the  problem,  dpkg-source  will
       apply  patches  before  building  unless it finds debian/patches/.dpkg-
       source-applied. The presence of a .pc subdirectory is also  interpreted
       as  a  sign  that some patches have been applied and in this case quilt
       unapplied is called to verify that all patches are applied. The  option
       --no-preparation can be used to disable this behaviour.

       Build options

       --include-removal
              Do   not   ignore   removed   files  and  include  them  in  the
              automatically generated patch.

       --include-timestamp
              Include timestamp in the automatically generated patch.

       --include-binaries
              Add all modified binaries in the debian tarball. Also  add  them
              to debian/source/include-binaries: they will be added by default
              in subsequent builds and this option is thus no more needed.

       --no-preparation
              Do not try to prepare the build tree by applying  patches  which
              are apparently unapplied.

       Extract options

       --skip-patches
              Do not apply patches at the end of the extraction.

       --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.

   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.

       Build options

       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.

       --target-format=value
              Required. Defines  the  real  format  of  the  generated  source
              package.  The generated .dsc file will contain this value in its
              Format field and not "3.0 (custom)".

   Format: 3.0 (git) and 3.0 (bzr)
       Those  formats  are  experimental.  They  generate  a  single   tarball
       containing the corresponding VCS repository.

       Extracting

       The  tarball  is  unpacked  and  then  the  VCS is used to checkout the
       current branch.

       Building

       Before going any further, some checks are done to ensure that we  don’t
       have any non-ignored uncommitted changes.

       Then  the VCS specific part of the source directory is copied over to a
       temporary directory. Before this temporary directory  is  packed  in  a
       tarball, various cleanup are done to save space.

BUGS

       The point at which field overriding occurs compared to certain standard
       output field settings is rather confused.

SEE ALSO

       dpkg-deb(1), dpkg(1), dselect(1).

AUTHORS

       Copyright (C) 1995-1996 Ian Jackson
       Copyright (C) 2000 Wichert Akkerman
       Copyright (C) 2008 Raphaël Hertzog

       This is free software; see the GNU General Public Licence version 2  or
       later for copying conditions. There is NO WARRANTY.