diff options
Diffstat (limited to '')
| -rw-r--r-- | scripts/uupdate.1 | 199 |
1 files changed, 199 insertions, 0 deletions
diff --git a/scripts/uupdate.1 b/scripts/uupdate.1 new file mode 100644 index 0000000..cf63a0d --- /dev/null +++ b/scripts/uupdate.1 @@ -0,0 +1,199 @@ +.TH UUPDATE 1 "Debian Utilities" "DEBIAN" \" -*- nroff -*- +.SH NAME +uupdate \- upgrade a source code package from an upstream revision +.SH SYNOPSIS +\fBuupdate\fR [\fIoptions\fR] \fInew_upstream_archive\fR [\fIversion\fR] +.br +\fBuupdate\fR [\fIoptions\fR] \fB\-\-find\fR|\fB\-f\fR +.br +\fBuupdate\fR [\fIoptions\fR] \fB\-\-patch\fR|\fB\-p\fR \fIpatch_file\fR +.SH DESCRIPTION +\fBuupdate\fR modifies an existing Debian source code archive to +reflect an upstream update supplied as a patch or from a wholly new +source code archive. The utility needs to be invoked from the top +directory of the old source code directory, and if a relative name is +given for the new archive or patch file, it will be looked for first +relative to the execution directory and then relative to the parent of +the source tree. (For example, if the changelog file is +\fI/usr/local/src/foo/foo-1.1/debian/changelog\fR, then the archive or +patch file will be looked for relative to \fI/usr/local/src/foo\fR.) +Note that the patch file or archive cannot be within the source tree +itself. The full details of what the code does are given below. +.PP +Currently supported source code file types are \fI.tar.gz\fR, +\fI.tar.bz2\fR, \fI.tar.Z\fR, \fI.tgz\fR, \fI.tar\fR, \fI.tar.lzma\fR, +\fI.tar.xz\fR, \fI.7z\fR and \fI.zip\fR +archives. Also supported are already unpacked source code archives; +simply give the path of the source code directory. Supported patch +file types are \fBgzip\fR-compressed, \fBbzip2\fR-compressed, +\fBlzma\fR-compressed, \fBxz\fR-compressed and +uncompressed patch files. The file types are identified by the file +names, so they must use the standard suffixes. +.PP +Usually \fBuupdate\fR will be able to deduce the version number from +the source archive name (as long as it only contains digits and +periods). If that fails, you need to specify the version number +explicitly (without the Debian release number which will always be +initially \*(lq1\*(rq, or \*(lq0ubuntu1\*(rq on Ubuntu-detected systems). This can be +done with an initial \fB\-\-upstream-version\fR or \fB\-v\fR option, or +in the case of an archive, with a version number after the filename. +(The reason for the latter is so that \fBuupdate\fR can be called +directly from \fBuscan\fR.) +.PP +Since \fBuupdate\fR uses \fBdebuild\fR to clean the current archive +before trying to apply a patch file, it accepts a \fB\-\-rootcmd\fR or +\fB\-r\fR option allowing the user to specify a gain-root command to be +used. The default is to use \fBfakeroot\fR. +.PP +If an archive is being built, the pristine upstream source should be +used to create the \fI.orig.tar.gz\fR file wherever possible. This +means that MD5 sums or other similar methods can be used to easily +compare the upstream source to Debian's copy of the upstream version. +This is the default behaviour, and can be switched off using the +\fB\-\-no\-pristine\fR option below. +.SH OPTIONS +This is a summary of what was explained above. +.TP +\fB\-\-no-conf\fR, \fB\-\-noconf\fR +Do not read any configuration files. This can only be used as the +first option given on the command-line. +.TP +\fB\-\-upstream\-version \fIversion\fR, \fB\-v \fIversion\fR +Specify the version number of the upstream package explicitly. +.TP +\fB\-\-force\-bad\-version, \fB\-b +Force a version number to be less than the current one (e.g., when backporting). +.TP +\fB\-\-rootcmd \fIgain-root-command\fR, \fB\-r \fIgain-root-command\fR +Specify the command to be used to become root to build the package and +is passed onto \fBdebuild\fR(1) if it is specified. +.TP +\fB\-\-pristine\fR, \fB\-u\fR +Treat the source as pristine upstream source and symlink to it from +\fI<package>_<version>.orig.tar.gz\fR whenever possible. This option +has no meaning for patches. This is the default behaviour. +.TP +\fB\-\-no\-pristine\fR +Do not attempt to make a \fI<package>_<version>.orig.tar.gz\fR symlink. +.TP +\fB\-\-symlink\fR, \fB\-s\fR +Simply create a symlink when moving a new upstream \fI.tar.gz\fR +archive to the new \fI<package>_<version>.orig.tar.gz\fR location. +This is the default behaviour. +.TP +\fB\-\-no\-symlink\fR +Copy the upstream \fI.tar.gz\fR to the new location instead of making +a symlink, if \fI<package>_<version>.orig.tar.gz\fR is missing. +Otherwise, do nothing. +.TP +.B \-\-find, \fB\-f\fR +Find all upstream tarballs in \fI../\fR which match +\fI<pkg>_<version>.orig.tar.{gz|bz2|lzma|xz}\fR or +\fI<pkg>_<version>.orig\-<component>.tar.{gz|bz2|lzma|xz}\fR ; +\fB\-\-upstream\-version\fR required; pristine source required; +not valid for \fB\-\-patch\fR; +This option uses \fBdpkg\-source\fR as the backend to enable support for the +multiple upstream tarballs and to resolve minor bugs reported previously. The +use of this option is highly recommended. +.TP +.B \-\-verbose +Give verbose output. +.TP +.BR \-\-help ", " \-h +Display a help message and exit successfully. +.TP +.B \-\-version +Display version and copyright information and exit successfully. +.SH "CONFIGURATION VARIABLES" +The two configuration files \fI/etc/devscripts.conf\fR and +\fI~/.devscripts\fR are sourced in that order to set configuration +variables. Command line options can be used to override configuration +file settings. Environment variable settings are ignored for this +purpose. The currently recognised variables are: +.TP +.B UUPDATE_PRISTINE +If this is set to \fIno\fR, then it is the same as the +\fB\-\-no\-pristine\fR command line parameter being used. +.TP +.B UUPDATE_SYMLINK_ORIG +If this is set to \fIno\fR, then it is the same as the +\fB\-\-no\-symlink\fR command line parameter being used. +.TP +.B UUPDATE_ROOTCMD +This is equivalent to the \fB\-\-rootcmd\fR option. +.SH "ACTIONS TAKEN ON AN ARCHIVE" +.TP +.B Figure out new version number +Unless an explicit version number is provided, the archive name is +analyzed for a sequence of digits separated by dots. If something +like that is found, it is taken to be the new upstream version +number. If not, processing is aborted. +.TP +.B Create the .orig.tar.gz archive +If the \fB\-\-pristine\fR or \fB\-u\fR option is specified and the +upstream archive is a \fI.tar.gz\fR or \fI.tgz\fR archive, then this +will be copied directly to \fI<package>_<version>.orig.tar.gz\fR. +.TP +.B Unpacking +The archive is unpacked and placed in a directory with the correct +name according to Debian policy: package-upstream_version.orig. +Processing is aborted if this directory already exists. +.TP +.B Patching +The \fI.diffs.gz\fR from the current version are applied to the +unpackaged archive. A non-zero exit status and warning message will +occur if the patches did not apply cleanly or if no patch file was +found. Also, the list of rejected patches will be shown. The +file \fIdebian/rules\fR is made executable and all of the \fI.orig\fR +files created by \fBpatch\fR are deleted. +.TP +.B Changelog update +A changelog entry with the new version number is generated with the +text \*(lqNew upstream release.\*(rq. + +When used on Ubuntu systems, \fBdpkg-vendor\fR detection is used to set +the Debian revision to \*(lq0ubuntu1\*(rq. You may change +\fIdebian/changelog\fR manually afterwards. +.SH "ACTIONS TAKEN ON A PATCH FILE" +.TP +.B Figure out new version number +Unless an explicit version number is provided, the patch file name is +analyzed for a sequence of digits separated by dots. If something +like that is found, it is taken to be the new upstream version +number. If not, processing is aborted. +.TP +.B Clean the current source tree +The command \fBdebuild clean\fR is executed within the current Debian +source archive to clean it. If a \fB\-r\fR option is given to +\fBuupdate\fR, it is passed on to \fBdebuild\fR. +.TP +.B Patching +The current source archive (\fI.orig.tar.gz\fR) is unpacked and the +patch applied to the original sources. If this is successful, then +the \fI.orig\fR directory is renamed to reflect the new version number +and the current Debian source directory is copied to a directory with +the new version number, otherwise processing is aborted. The patch is +then applied to the new copy of the Debian source directory. The file +\fIdebian/rules\fR is made executable and all of the \fI.orig\fR files +created by \fBpatch\fR are deleted. If there was a problem with the +patching, a warning is issued and the program will eventually exit +with non-zero exit status. +.TP +.B Changelog update +A changelog entry with the new version number is generated with the +text \*(lqNew upstream release.\*(rq. + +When used on Ubuntu systems, \fBdpkg-vendor\fR detection is used to set +the Debian revision to \*(lq0ubuntu1\*(rq. You may change +\fIdebian/changelog\fR manually afterwards. +.SH "SEE ALSO" +.BR debuild (1), +.BR fakeroot (1), +.BR patch (1), +.BR devscripts.conf (5) + +.B The Debian Policy Manual +.SH AUTHOR +The original version of \fBuupdate\fR was written by Christoph Lameter +<clameter@debian.org>. Several changes and improvements have been +made by Julian Gilbey <jdg@debian.org>. |