Home Man
Today's Posts

Linux & Unix Commands - Search Man Pages
Man Page or Keyword Search:
Select Section of Man Page:
Select Man Page Repository:

Linux 2.6 - man page for dpkg-source (linux section 1)

dpkg-source(1)				  dpkg utilities			   dpkg-source(1)

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

       dpkg-source [options] command

       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.

       -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 follow-
	      ing 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 found in this
	      ordered list: the format indicated with the --format command-line option, the  for-
	      mat  indicated  in debian/source/format, "1.0". The fallback to "1.0" is deprecated
	      and will be removed at some point in the future, you  should  always  document  the
	      desired  source  format in debian/source/format. See section SOURCE PACKAGE FORMATS
	      for an extensive description of the various source package formats.

       --print-format directory
	      Print the source format  that  would  be	used  to  build  the  source  package  if
	      dpkg-source  -b  directory  was  called  (in  the same conditions and with the same

       --before-build directory
	      This command should be called before any build of  the  package  (dpkg-buildpackage
	      calls it very early even before debian/rules clean). This command should be idempo-
	      tent and can be called multiple times. Not all source formats  implement	something
	      in  this	hook, and those that do usually prepare the source tree for the build for
	      example by ensuring that the Debian patches are applied.

       --after-build directory
	      This command should be called after any build  of  the  package  (dpkg-buildpackage
	      calls it last). This command should be idempotent and can be called multiple times.
	      Not all source formats implement something in this hook, and those that do  usually
	      use it to undo what --before-build has done.

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

	      Show the version and exit.

	      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.

	      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.

	      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  stan-
	      dard format.

	      Use  the	given format for building the source package. It does override any format
	      given in debian/source/format.

	      Set an output substitution variable.  See deb-substvars(5) for a discussion of out-
	      put substitution.

	      Read  substitution variables in substvarsfile; the default is to not read any file.
	      This option can be used multiple times to read substitution variables from multiple

	      Override or add an output control file field.

	      Remove an output control file field.

       -Zcompression, --compression=compression
	      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, lzma and xz.  gzip is the default. xz
	      is only supported since dpkg-dev 1.15.5.

       -zlevel, --compression-level=level
	      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], --diff-ignore[=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 can
	      be used to ignore uncommited changes on specific files. Using -i.* will ignore  all
	      of  them.)  -i by itself enables the option, with a default regexp 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.

	      The  perl  regular  expression specified will extend the default regular expression
	      associated to -i by concatenating "|regexp" to the default regexp.  This option  is
	      convenient  to  use  in  debian/source/options to exclude some auto-generated files
	      from the automatic patch generation.

       -I[file-pattern], --tar-ignore[=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 seman-
       tics. -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/man-
       ual/tar.html#wildcards for a full documentation.

       The  default  regexp and patterns for both options can be seen in the output of the --help

	      Do not copy original tarballs near the extracted source package.

	      Do not check signatures and checksums before unpacking.

	      Refuse to unpack the source package if it doesn't contain an OpenPGP signature that
	      can  be verified either with the user's trustedkeys.gpg keyring, one of the vendor-
	      specific	  keyrings,    or    one    of	  the	 official     Debian	 keyrings
	      (/usr/share/keyrings/debian-keyring.gpg	and  /usr/share/keyrings/debian-maintain-

       If you don't know what source format to use, you should probably pick either "3.0 (quilt)"
       or  "3.0  (native)".  See http://wiki.debian.org/Projects/DebSrc3.0 for information on the
       deployment of those formats within Debian.

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

	      The  process  fails  if the generated diff contains changes to files outside of the
	      debian sub-directory. This option is not allowed in debian/source/options  but  can
	      be used in debian/source/local-options.

       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 differ-
	      ent 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

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

	      Skips application of the debian diff on top of the upstream sources.

   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, lzma and xz) and a debian tarball (.debian.tar.ext). It can also con-
       tain additional original tarballs (.orig-component.tar.ext).  component can  only  contain
       alphanumeric characters and dashes ("-").


       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 cor-
       rectly 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 warn-
       ing 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  .pc/applied-patches  is  created  if	some patches have been applied during the


       All original tarballs found in the current directory are extracted in a	temporary  direc-
       tory by following the same logic as for the unpack, the debian directory is copied over in
       the temporary directory, and all patches except the automatic  patch  (debian-changes-ver-
       sion  or  debian-changes,  depending  on --single-debian-patch) are applied. The temporary
       directory is compared to the source package directory  and  the	diff  (if  non-empty)  is
       stored  in  the	automatic  patch.   If	the  automatic	patch  is  created/deleted,  it's
       added/removed from the series file and from the quilt metadata.

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

       Note: dpkg-source expects the source tree to have all patches listed in	the  series  file
       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 the patches by itself if it believes that
       they have not yet been applied. To detect this situation, it uses the following heuristic:
       it  finds the list of supposedly unapplied patches (they are listed in the series file but
       not in .pc/applied-patches), and if the first patch in that set	can  be  applied  without
       errors,	it  will apply them all.  The option --no-preparation can be used to disable this
       behaviour. This operation is usually done as part of the --prepare-build command.

       Build options

	      Allow dpkg-source to build the source package if the version of the quilt  metadata
	      is  the  one specified, even if dpkg-source doesn't know about it. Effectively this
	      says that the given version of the quilt metadata is compatible with the version	2
	      that dpkg-source currently supports. The version of the quilt metadata is stored in

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

	      Include timestamp in the automatically generated patch.

	      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.

	      Do not try to prepare the build tree by applying patches which are apparently unap-

	      Use  debian/patches/debian-changes instead of debian/patches/debian-changes-version
	      for the name of the automatic patch generated during build. This option is particu-
	      larly useful when the package is maintained in a VCS and a patch set can't reliably
	      be generated. Instead the current diff with upstream should be stored in	a  single
	      patch.  When  using this option, it is recommended to create a debian/source/patch-
	      header file explaining how the Debian changes can be best reviewed, for example  in
	      the VCS that is used.

	      Automatically  create  the  main	original  tarball as empty if it's missing and if
	      there are supplementary original tarballs. This option is meant to be used when the
	      source  package is just a bundle of multiple upstream software and where there's no
	      "main" software.

	      Unapply the patches in the --after-build hook. This is mainly useful when you build
	      your  package  directly  in a VCS that contains unpatched upstream source and where
	      you want to keep the tree unpatched even after a package build. This option is usu-
	      ally  put in debian/source/local-options (it's not allowed in debian/source/options
	      so that all generated source packages have the same behaviour by default).

	      The process fails if an automatic patch has been generated. This option can be used
	      to  ensure  that all changes were properly recorded in separate quilt patches prior
	      to the source package build. This option is not  allowed	in  debian/source/options
	      but can be used in debian/source/local-options.

       Extract options

	      Skips extraction of the debian tarball on top of the upstream sources.

	      Do not apply patches at the end of the extraction.

   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

	      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)
       This format is experimental.

       A  source  package  in this format consists of a single bundle of a git repository .git to
       hold the source of a package.  There may also be a .gitshallow file listing revisions  for
       a shallow git clone.


       The  bundle is cloned as a git repository to the target directory.  If there is a gitshal-
       low file, it is installed as `.git/shallow` inside the cloned git repository.

       Note that by default the new repository will have the same branch  checked  out	that  was
       checked	out  in  the original source. (Typically "master", but it could be anything.) Any
       other branches will be available, under as `remotes/origin/`


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

       git-bundle(1)  is  used	to  generate  a  bundle  of  the git repository.  By default, all
       branches and tags in the repository are included in the bundle.

       Build options

	      Allows specifying a git ref to include in the git bundle. Use disables the  default
	      behavior	of  including all branches and tags. May be specified multiple times. The
	      ref can be the name of a branch or tag to include. It may  also  be  any	parameter
	      that  can  be  passed  to  git-rev-list(1). For example, to include only the master
	      branch, use --git-ref=master. To include all tags and branches, except for the pri-
	      vate branch, use --git-ref=--all --git-ref=^private

	      Creates  a  shallow clone with a history truncated to the specified number of revi-

   Format: 3.0 (bzr)
       This format is experimental. It generates a single tarball containing the bzr repository.


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


       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 direc-
       tory. Before this temporary directory is packed in a tarball, various cleanup are done  to
       save space.

   no source format specified in debian/source/format
       The  file debian/source/format should always exist and indicate the desired source format.
       For backwards compatibility, format "1.0" is assumed when the file doesn't exist  but  you
       should  not rely on this: at some point in the future dpkg-source will be modified to fail
       when that file doesn't exist.

       The rationale is that format "1.0" is no longer the recommended format, you should usually
       pick  one of the newer formats ("3.0 (quilt)", "3.0 (native)") but dpkg-source will not do
       this automatically for you.  If you want to continue using the old format, you  should  be
       explicit about it and put "1.0" in debian/source/format.

   the diff modifies the following upstream files
       When  using source format "1.0" it is usually a bad idea to modify upstream files directly
       as the changes end up hidden and mostly undocumented in the  .diff.gz  file.  Instead  you
       should store your changes as patches in the debian directory and apply them at build-time.
       To avoid this complexity you can also use  the  format  "3.0  (quilt)"  that  offers  this

   cannot represent change to file
       Changes	to  upstream sources are usually stored with patch files, but not all changes can
       be represented with patches: they can only alter the content of plain text files.  If  you
       try  replacing  a  file	with something of a different type (for example replacing a plain
       file with a symlink or a directory), you will get this error message.

   newly created empty file file will not be represented in diff
       Empty files can't be created with patch files. Thus this change is  not	recorded  in  the
       source package and you are warned about it.

   executable mode perms of file will not be represented in diff
   special mode perms of file will not be represented in diff
       Patch  files  do  not  record  permissions  of files and thus modified permissions are not
       stored in the source package. This warning reminds you of that fact.

       This file contains on a single line the format that should be used  to  build  the  source
       package (possible formats are described above). No leading or trailing spaces are allowed.

       This  file  contains  a list of binary files (one per line) that should be included in the
       debian tarball. Leading and trailing spaces are stripped.  Lines  starting  with  "#"  are
       comments and are skipped. Empty lines are ignored.

       This  file  contains  a list of long options that should be automatically prepended to the
       set of command line options of  a  dpkg-source  -b  or  dpkg-source  --print-format  call.
       Options like --compression and --compression-level are well suited for this file.

       Each  option should be put on a separate line. Empty lines and lines starting with "#" are
       ignored. The leading "--" should be stripped and short options are not  allowed.  Optional
       spaces are allowed around the "=" symbol and optional quotes are allowed around the value.
       Here's an example of such a file:

	 # let dpkg-source create a debian.tar.bz2 with maximal compression
	 compression = "bzip2"
	 compression-level = 9
	 # use debian/patches/debian-changes as automatic patch

       Note: format options are not accepted in this file, you	should	use  debian/source/format

       Exactly	like  debian/source/options except that the file is not included in the generated
       source package. It can be useful to store a preference tied to the maintainer  or  to  the
       VCS repository where the source package is maintained.

       Free  form  text  that  is put on top of the automatic patch generated in formats "2.0" or
       "3.0 (quilt)".

       This file lists all patches that have to be applied (in the given order)  on  top  of  the
       upstream source package. Leading and trailing spaces are stripped. Lines starting with "#"
       are comments and are skipped. Empty lines are ignored. Remaining lines start with a  patch
       filename  (relative  to	the debian/patches/ directory) up to the first space character or
       the end of line. Optional quilt options can follow up to the end of line or the first  "#"
       preceded by one or more spaces (which marks the start of a comment up to the end of line).

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

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

       Copyright (C) 1995-1996 Ian Jackson
       Copyright (C) 2000 Wichert Akkerman
       Copyright (C) 2008-2010 Raphael Hertzog

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

Debian Project				    2011-03-04				   dpkg-source(1)

All times are GMT -4. The time now is 05:11 AM.

Unix & Linux Forums Content Copyrightę1993-2018. All Rights Reserved.
Show Password