dpkg-parsechangelog

DPKG-SOURCE(1)              Debian GNU/Linux manual             DPKG-SOURCE(1)



NAME
       dpkg-source, dpkg-gencontrol, dpkg-shlibdeps, dpkg-genchanges,
       dpkg-buildpackage, dpkg-distaddfile, dpkg-parsechangelog - Debian
       source package tools

SYNOPSIS
       dpkg-source -x filename.dsc
       dpkg-source -b [options] directory [orig-directory|'']
       dpkg-gencontrol [options]
       dpkg-shlibdeps options
       dpkg-genchanges [options]
       dpkg-buildpackage [options]
       dpkg-distaddfile [options] filename section priority
       dpkg-parsechangelog [options]

DESCRIPTION
       dpkg-source packs and unpacks Debian source archives.

       dpkg-gencontrol reads information from an unpacked Debian source tree
       and generates a binary package control file on standard output; it also
       adds an entry for the binary package to debian/files.

       dpkg-shlibdeps calculates shared library dependencies for executables
       named in its arguments.  The dependencies are added to the substitution
       variables file debian/substvars as variable names
       shlibs:dependencyfield where dependencyfield is a dependency field
       name.  Any other variables starting shlibs: are removed from the file.
       dpkg-shlibdeps will read shared library dependency information from
       debian/shlibs.local, /etc/dpkg/shlibs.override, the shlibs control area
       file of the package containing the file which ldd reports as satisfying
       the library dependency, or /etc/dpkg/shlibs.default.  The first match
       will be used.  See the dpkg programmers' manual for details of the
       format of shared library dependency files.

       dpkg-genchanges reads information from an unpacked and built Debian
       source tree and from the files it has generated and generates a Debian
       upload control file (.changes file).

       dpkg-buildpackage is a control script which can be used to help
       automate the building of a package.

       dpkg-distaddfile adds an entry for a named file to debian/files.

       dpkg-parsechangelog reads and parses the changelog of an unpacked
       Debian source tree and outputs the information in it to standard output
       in a machine-readable form.

       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.

COMMON OPTIONS
       Many of these programs share options; these are described here,
       together with the programs that accept them.

       -h     Display the particular program's version and usage message,
              including a synopsis of the options it understands.  This option
              is understood by all the source package tools.

       -vversion
              In dpkg-buildpackage, dpkg-genchanges and dpkg-parsechangelog
              this causes changelog information from all versions strictly
              later than version (which must appear in the changelog file) to
              be used.

              In dpkg-gencontrol it sets the version number of the binary
              package which will be generated.

       -Cchangesdescription
              Read the description of the changes from the file
              changesdescription rather than using the information from the
              source tree's changelog file.  This is understood by dpkg-
              buildpackage and dpkg-genchanges.

       -mmaintaineraddress
              Use maintaineraddress as the name and email address of the
              maintainer for this upload, rather than using the information
              from the source tree's changelog.  This is understood by dpkg-
              buildpackage and dpkg-genchanges.

       -si, -sa, -sd
              These options control whether the original source archive is
              included in the upload generated by dpkg-buildpackage and dpkg-
              genchanges if any source is being generated (ie, -b or -B
              haven't been used).

              By default, or if -si is specified, the original source will be
              included if the version number ends in -0 or -1, ie if the
              Debian revision part of the version number is 0 or 1.

              -sa forces the inclusion of the original source; -sd forces its
              exclusion and includes only the diff.

       -Vname=value
              Set an output substitution variable.  This option is understood
              by dpkg-source, dpkg-gencontrol and dpkg-genchanges.  See below
              for a discussion of output substitution.

       -Tsubstvarsfile
              Read (or, for dpkg-shlibdeps, write) substitution variables in
              substvarsfile; the default is debian/substvars.  This option is
              understood by dpkg-source, dpkg-gencontrol, dpkg-shlibdeps and
              dpkg-genchanges.

       -Dfield=value
              Override or add an output control file field.  This option is
              understood by dpkg-source, dpkg-gencontrol and dpkg-genchanges.

       -Ufield
              Remove an output control file field.  This option is understood
              by dpkg-source, dpkg-gencontrol and dpkg-genchanges.

       -b|-B  For dpkg-genchanges and dpkg-buildpackage this specifies that a
              binary-only build is taking place.  -b indicates that no source
              files are to be built and/or distributed, and -B that no
              architecture-independent binary package files are to be
              distributed either.  The distinction between -b and -B is only
              used by dpkg-buildpackage; dpkg-genchanges just produces a
              .changes file for whatever files were produced by the binary-*
              target(s) of the package being built.

              -b tells dpkg-source to build a source package (rather than to
              extract one) - see below.

       -ccontrolfile
              Specifies the main source control file to read information from.
              The default is debian/control.  This option is understood by
              dpkg-source, dpkg-gencontrol and dpkg-genchanges.

       -lchangelogfile
              Specifies the change log file to read information from.  The
              default is debian/changelog.  This option is understood by dpkg-
              source, dpkg-gencontrol and dpkg-genchanges.

       -ffileslistfile
              Read or write the list of files to be uploaded here, rather than
              using debian/files.  This option is understood by dpkg-
              gencontrol, dpkg-genchanges and dpkg-distaddfile.

       -Fchangelogformat
              Specifies the format of the changelog.  By default the format is
              read from a special line near the bottom of the changelog (see
              the programmers' manual) or failing that defaults to debian, the
              standard format described in the dpkg programmers' manual.  This
              option is understood by dpkg-source, dpkg-gencontrol and dpkg-
              genchanges.

DPKG-SOURCE OPTIONS
       When the common options -c and -l are given with relative pathnames
       these are interpreted starting at the source tree's top level
       directory.

       -x     Extract a source package.  One non-option argument should be
              supplied, the name of the Debian source control file (.dsc).  No
              options are useful with dpkg-source -x.  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.

       -b     Build: pack up a source tree.  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 dpkg-source will look for
              the original source tarfile package_upstream-version.orig.tar.gz
              or the original source directory directory.orig or the empty
              string (no original source, and so no diff) depending on the
              arguments.

       -sa,-sp,-su,-sk,-sA,-sP,-sU,-sK,-ss with -b
              If -sk or -sp is specified dpkg-source expects the original
              source as a tarfile, by default package_upstream-
              version.orig.tar.gz.  It will leave this original source in
              place as a tarfile, or copy it to the current directory if it
              isn't already there If -sp is used rather than -sk it will
              remove it again afterwards.

              If -su or -sr is specified 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.  If
              -sr is used dpkg-source will remove that directory after it has
              been used.

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

              If -sn is specified dpkg-source will not look for any original
              source, and will 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.

              If -sa or -sA is specified dpkg-source will 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.

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

       -sp,-su,-sn with -x
              In all cases any existing original source tree will be removed.

              If -sp is 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.

DPKG-GENCONTROL OPTIONS
       dpkg-gencontrol does not take any non-option arguments.

       -ppackage
              Generate information for the binary package package.  If the
              source control file lists several binary packages then this
              option may be omitted; otherwise it is essential to select which
              binary package's information to generate.

       -is, -ip, -isp
              Include the Section and Priority fields for this package from
              the main source control file in the binary package control file
              being generated.  Usually this information is not included here,
              but only in the .changes file.  -isp includes both fields, -is
              only the Section and -ip only the Priority.

       -Ppackagebuilddir
              Tells dpkg-source that the package is being built in
              packagebuilddir instead of debian/tmp.  This value is used to
              find the default value of the Installed-Size substitution
              variable and control file field (using du), and for the default
              location of the output file.

       -O     Causes the control file to be printed to standard output, rather
              than to debian/tmp/DEBIAN/control (or
              packagebuilddir/DEBIAN/control if -P was used).

DPKG-SHLIBDEPS OPTIONS
       dpkg-shlibdeps interprets non-option arguments as executable names,
       just as if they'd been supplied as -eexecutable.

       -eexecutable
              Include dependencies appropriate for the shared libraries
              required by executable.

       -ddependencyfield
              Add dependencies to be added to the control file dependency
              field dependencyfield.  (The dependencies for this field are
              placed in the variable shlibs:dependencyfield.)

              The -ddependencyfield option takes effect for all executables
              after the option, until the next -ddependencyfield.  The default
              dependencyfield is Depends.

              If the same dependency entry (or set of alternatives) appears in
              more than one of the recognised dependency field names Pre-
              Depends, Depends, Recommends or Suggests then dpkg-shlibdeps
              will automatically remove the dependency from all fields except
              the one representing the most important dependencies.

       -pvarnameprefix
              Causes substitution variables to start with varnameprefix:
              instead of shlib:.  Likewise, any existing substitution
              variables starting with varnameprefix: (rather than shlib:) are
              removed from the the substitution variables file.

       -Llocalshlibsfile
              Causes dpkg-shlibs to read overriding shared library dependency
              information from localshlibsfile instead of debian/shlibs.local.

       -O     Causes the substitution variable settings to be printed to
              standard output, rather than being added to the substitution
              variables file (debian/substvars by default).

DPKG-GENCHANGES OPTIONS
       dpkg-gencontrol does not take any non-option arguments.

       -uuploadfilesdir
              Look for the files to be uploaded in uploadfilesdir rather than
              ..  (dpkg-genchanges needs to find these files so that it can
              include their sizes and checksums in the .changes file).

       -q     Usually dpkg-genchanges will produce informative messages on
              standard error, for example about how many of the package's
              source files are being uploaded.  -q suppresses these messages.

DPKG-BUILDPACKAGE OPTIONS
       dpkg-buildpackage does not take any non-option arguments.

       -rgain-root-command
              When dpkg-buildpackage needs to execute part of the build
              process as root, it prefixes the command it executes with gain-
              root-command if one has been specified.  gain-root-command
              should be the name of a program on the PATH and will get as
              arguments the name of the real command to run and the arguments
              it should take.  gain-root-command should not contain spaces or
              any other shell metacharacters.  gain-root-command might
              typically be sudo, super or really.  su is not suitable, since
              it requires a -c option to run a command and even then it can
              only invoke the user's shell with -c instead of passing
              arguments individually to the command to be run.

       -ppgp-command
              When dpkg-buildpackage needs to execute PGP to sign a source
              control (.dsc) file or a .changes file it will run pgp-command
              (searching the PATH if necessary) instead of pgp.  pgp-command
              will get all the arguments that pgp would have done.  pgp-
              command should not contain spaces or any other shell
              metacharacters.

       -tc    Clean the source tree (using gain-root-command debian/rules
              clean) after the package has been built.

       -us, -uc
              Do not PGP-sign the source package or the changelog,
              respectively.

DPKG-DISTADDFILE ARGUMENTS
       dpkg-distaddfile does not take any non-common options.  It takes three
       non-option arguments, the filename and the section and priority for the
       .changes file.

       The filename should be specified relative to the directory where dpkg-
       genchanges will expect to find the files, usually .., rather than being
       a pathname relative to the current directory when dpkg-distaddfile is
       run.

DPKG-PARSECHANGELOG ARGUMENTS
       dpkg-parsechangelog does not take any non-common options or non-option
       arguments.

VARIABLE SUBSTITUTION
       Before dpkg-source, dpkg-gencontrol and dpkg-genchanges write their
       control information (to the source control file .dsc for dpkg-source
       and to standard output for dpkg-gencontrol and dpkg-genchanges) they
       perform some variable substitutions on the output file.

       A variable substitution has the form ${variable-name}.  Variable names
       consist of alphanumerics, hyphens and colons and start with an
       alphanumeric.  Variable substitutions are performed repeatedly until
       none are left; the full text of the field after the substitution is
       rescanned to look for more substitutions.

       After all the substitutions have been done each occurence of the string
       ${} (which is not a legal substitution) is replaced with a $ sign.

       Variables can be set using the -V common option.  They can be also
       specified in the file debian/substvars (or whatever other file is
       specified using the -T option).  This file consists of lines of the
       form name=value.  Trailing whitespace on each line, blank lines, and
       lines starting with a # symbol (comments) are ignored.

       Additionally, the following standard variables are available:

       Arch   The current build architecture (from dpkg --print-architecture).

       Source-Version
              The source package version (from the changelog file).

       Installed-Size
              The total size of the package's installed files.  This value is
              copied into the corresponding control file field; setting it
              will modify the value of that field.  If this variable isn't set
              dpkg-gencontrol will use du -k debian/tmp to find the default
              value.

       Extra-Size
              Additional disk space used when the package is installed.  If
              this variable is set its value is added to that of the
              Installed-Size variable (whether set explicitly or using the
              default value) before it is copied into the Installed-Size
              control file field.

       F:fieldname
              The value of the output field fieldname (which must be given in
              the canonical capitalisation).  Setting these variables has no
              effect other than on places where they are expanded explicitly.

       Format The .changes file format version generated by this version of
              the source packaging scripts.  If you set this variable the
              contents of the Format field in the .changes file will change
              too.

       Newline, Space, Tab
              These variables each hold the corresponding character.

       shlibs:dependencyfield
              Variable settings with names of this form are generated by dpkg-
              shlibdeps - see above.

       If a variable is referred to but not defined it generates a warning and
       an empty value is assumed.

FILES
       debian/control
              The main source control information file, giving version-
              independent information about the source package and the binary
              packages it can produce.

       debian/changelog
              The changelog file, used to obtain version-dependent information
              about the source package, such as the urgency and distribution
              of an upload, the changes made since a particular release, and
              the source version number itself.

       debian/files
              The list of generated files which are part of the upload being
              prepared.  dpkg-gencontrol adds the presumed filenames of binary
              packages whose control files it generates here; dpkg-distaddfile
              can be used to add additional files.  dpkg-genchanges reads the
              data here when producing a .changes file.

       debian/substvars
              List of substitution variables and values.

       debian/shlibs.local
              Package-local overriding shared library dependency information.

       /etc/dpkg/shlibs.override
              Per-system overriding shared library dependency information.

       /etc/dpkg/shlibs.default
              Per-system default shared library dependency information.

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

       The binary package entries in the debian/files file will be passed
       through variable substitution twice.  This should not matter, since $,
       { and } are not legal in package names or version numbers.

       It should be possible to specify spaces and shell metacharacters in and
       initial arguments for gain-root-command and pgp-command.

SEE ALSO
       dpkg programmers' manual,
       Debian policy manual,
       dpkg-deb(1), dpkg(8), dselect(8).

AUTHOR
       The utilities and this manpage were written by Ian Jackson.  They are
       Copyright (C)1995-1996 by him and released under the GNU General Public
       Licence; there is NO WARRANTY.  See /usr/doc/copyright/dpkg and
       /usr/doc/copyright/GPL for details.



Debian Project                    7th August                    DPKG-SOURCE(1)