This is an automated email from the git hooks/post-receive script. osamu pushed a commit to branch multitar in repository devscripts.
commit 0753c2fe6628d1599d1d20917647fbc4c72969b6 Author: Osamu Aoki <[email protected]> Date: Tue Sep 8 15:41:13 2015 +0000 uscan: new improved manpage with POD * remove old uscan.1 * update Makefile * update devscripts-po4a.conf --- po4a/devscripts-po4a.conf | 4 +- scripts/Makefile | 2 +- scripts/uscan.1 | 596 -------------------- scripts/uscan.pl | 1313 +++++++++++++++++++++++++++++++++++++++++++-- 4 files changed, 1268 insertions(+), 647 deletions(-) diff --git a/po4a/devscripts-po4a.conf b/po4a/devscripts-po4a.conf index ff6c490..6d8c845 100644 --- a/po4a/devscripts-po4a.conf +++ b/po4a/devscripts-po4a.conf @@ -120,8 +120,8 @@ $lang:$lang/tagpending.$lang.pl add_$lang:?add_$lang/translator_pod.add [type:pod] ../scripts/transition-check.pl \ $lang:$lang/transition-check.$lang.pl add_$lang:?add_$lang/translator_pod.add -[type:man] ../scripts/uscan.1 \ - $lang:$lang/uscan.$lang.1 add_$lang:?add_$lang/translator_man.add +[type:pod] ../scripts/uscan.pl \ + $lang:$lang/uscan.$lang.pod add_$lang:?add_$lang/translator_pod.add [type:man] ../scripts/uupdate.1 \ $lang:$lang/uupdate.$lang.1 add_$lang:?add_$lang/translator_man.add [type:man] ../doc/what-patch.1 \ diff --git a/scripts/Makefile b/scripts/Makefile index 797c78f..872f9d2 100644 --- a/scripts/Makefile +++ b/scripts/Makefile @@ -22,7 +22,7 @@ COMPL_FILES := $(wildcard *.bash_completion) COMPLETION = $(patsubst %.bash_completion,devscripts.%,$(COMPL_FILES)) COMPL_DIR := $(shell pkg-config --variable=completionsdir bash-completion) -GEN_MAN1S += devscripts.1 mk-origtargz.1 +GEN_MAN1S += devscripts.1 mk-origtargz.1 uscan.1 all: $(SCRIPTS) $(GEN_MAN1S) $(CWRAPPERS) $(COMPLETION) diff --git a/scripts/uscan.1 b/scripts/uscan.1 deleted file mode 100644 index bd9d2a7..0000000 --- a/scripts/uscan.1 +++ /dev/null @@ -1,596 +0,0 @@ -.TH USCAN 1 "Debian Utilities" "DEBIAN" \" -*- nroff -*- -.SH NAME -uscan \- scan/watch upstream sources for new releases of software -.SH SYNOPSIS -\fBuscan\fR [\fIoptions\fR] [\fIpath-to-debian-source-packages\fR ...] -.SH DESCRIPTION -\fBuscan\fR scans the given directories (or the current directory if -none are specified) and all of their subdirectories for packages -containing a control file \fIdebian/watch\fR. Parameters are then -read from those control files and upstream ftp or http sites are -inspected for newly available updates (as compared with the upstream -version number retrieved from the \fIdebian/changelog\fR file in the -same directory). The newest updates are retrieved (as determined by -their version numbers) and if specified in the \fIwatch\fR file, a program -may then be executed on the newly downloaded source. -.PP -The traditional \fIdebian/watch\fR files can still be used, but the -current format offers both simpler and more flexible services. We do -not describe the old format here; for their documentation, see the -source code for \fRuscan\fR. - -.SH FORMAT of debian/watch files - -The following demonstrates the type of entries which can appear in a -\fIdebian/watch\fR file. Obviously, not all of these would appear in -one such file; usually, one would have one line for the current -package. - -.PP -.nf -# format version number, currently 3; this line is compulsory! -version=3 - -# Line continuations are performed with \fB\e\fR - -# This is the format for an FTP site: -# Full-site-with-pattern [Version [Action]] -ftp://ftp.tex.ac.uk/tex-archive/web/c_cpp/cweb/cweb-(.+)\e.tar\e.gz \e - debian uupdate - -# This is the format for an FTP site with regex special characters in -# the filename part -ftp://ftp.worldforge.org/pub/worldforge/libs/Atlas-C++/transitional/Atlas-C\e+\e+-(.+)\e.tar\e.gz - -# This is the format for an FTP site with directory pattern matching -ftp://ftp.nessus.org/pub/nessus/nessus-([\ed\e.]+)/src/nessus-core-([\ed\e.]+)\e.tar\e.gz - -# This can be used if you want to override the PASV setting -# for a specific site -# opts=pasv ftp://.../... - -# This is one format for an HTTP site, which is the same -# as the FTP format. \fBuscan\fR starts by downloading the homepage, -# obtained by removing the last component of the URL; in this case, -# \fIhttp://www.cpan.org/modules/by-module/Text/\fR -http://www.cpan.org/modules/by-module/Text/Text-CSV_XS-(.+)\e.tar\e.gz - -# This is a variant HTTP format which allows direct specification of -# the homepage: -# Homepage Pattern [Version [Action]] -http://www.dataway.ch/~lukasl/amph/amph.html \e - files/amphetamine-([\ed\e.]*).tar.bz2 - -# This one shows that recursive directory scanning works, in either of -# two forms, as long as the website can handle requests of the form -# \fIhttp://site/inter/mediate/dir/\fR -http://tmrc.mit.edu/mirror/twisted/Twisted/(\ed\e.\ed)/ \e - Twisted-([\ed\e.]*)\e.tar\e.bz2 -http://tmrc.mit.edu/mirror/twisted/Twisted/(\ed\e.\ed)/Twisted-([\ed\e.]*)\e.tar\e.bz2 - -# For maximum flexibility with upstream tarball formats, use this: -http://example.com/example-(\ed[\ed\.]*)\e.(?:zip|tgz|tbz2|txz|tar\e.(?:gz|bz2|xz)) - -# qa.debian.org runs a redirector which allows a simpler form of URL -# for SourceForge based projects. The format below will automatically -# be rewritten to use the redirector. -http://sf.net/audacity/audacity-src-(.+)\e.tar\e.gz - -# For GitHub projects you can use the tags or releases page. Since the archive -# URLs use only the version as the name, it is recommended to use a -# filenamemangle to adjust the name of the downloaded file: -opts="filenamemangle=s/(?:.*?\/)?v?(\ed[\ed.]*)\e.tar\e.gz/<project>-$1.tar.gz/" \e - https://github.com/<user>/<project>/tags (?:.*?/)?v?(\ed[\ed.]*)\e.tar\e.gz - -# For Google Code projects you should use the downloads page like this: -https://code.google.com/p/<project>/downloads/list?can=1 \e - .*/<project>-(\ed[\ed.]*)\e.tar\e.gz - -# This is the format for a site which has funny version numbers; -# the parenthesised groups will be joined with dots to make a -# sanitised version number -http://www.site.com/pub/foobar/foobar_v(\ed+)_(\ed+)\e.tar\e.gz - -# This is another way of handling site with funny version numbers, -# this time using mangling. (Note that multiple groups will be -# concatenated before mangling is performed, and that mangling will -# only be performed on the basename version number, not any path -# version numbers.) -opts="uversionmangle=s/^/0.0./" \e - ftp://ftp.ibiblio.org/pub/Linux/ALPHA/wine/development/Wine-(.+)\e.tar\e.gz - -# Similarly, the upstream part of the Debian version number can be -# mangled: -opts=dversionmangle=s/\e+dfsg\ed*$// \e - http://some.site.org/some/path/foobar-(.+)\e.tar\e.gz - -# The filename is found by taking the last component of the URL and -# removing everything after any '\fB?\fR'. If this would not make a usable -# filename, use filenamemangle. For example, -# <A href="http://foo.bar.org/download/?path=&download=foo-0.1.1.tar.gz";> -# could be handled as: -# opts=filenamemangle=s/.*=(.*)/$1/ \e -# http://foo.bar.org/download/\e?path=&download=foo-(.+)\e.tar\e.gz -# -# <A href="http://foo.bar.org/download/?path=&download_version=0.1.1";> -# could be handled as: -# opts=filenamemangle=s/.*=(.*)/foo-$1\e.tar\e.gz/ \e -# http://foo.bar.org/download/\e?path=&download_version=(.+) - -# The option downloadurlmangle can be used to mangle the URL of the file -# to download. This can only be used with http:// URLs. This may be -# necessary if the link given on the web page needs to be transformed in -# some way into one which will work automatically, for example: -# opts=downloadurlmangle=s/prdownload/download/ \e -# http://developer.berlios.de/project/showfiles.php?group_id=2051 \e -# http://prdownload.berlios.de/softdevice/vdr-softdevice-(.+).tgz - -.fi -.PP -Comment lines may be introduced with a `\fB#\fR' character. Continuation -lines may be indicated by terminating a line with a backslash -character. -.PP -The first (non-comment) line of the file must begin `version=3'. This -allows for future extensions without having to change the name of the -file. -.PP -There are two possibilities for the syntax of an HTTP \fIwatch\fR file line, -and only one for an FTP line. We begin with the common (and simpler) -format. We describe the optional opts=... first field below, and -ignore it in what follows. -.PP -The first field gives the full pattern of URLs being searched for. In -the case of an FTP site, the directory listing for the requested -directory will be requested and this will be scanned for files -matching the basename (everything after the trailing `\fB/\fR'). In the -case of an HTTP site, the URL obtained by stripping everything after -the trailing slash will be downloaded and searched for hrefs (links of -the form <a href=...>) to either the full URL pattern given, or to the -absolute part (everything without the http://host.name/ part), or to -the basename (just the part after the final `\fB/\fR'). Everything up to -the final slash is taken as a verbatim URL, as long as there are no -parentheses (`\fB(\fR' and '\fB)\fR') in this part of the URL: if it does, the -directory name will be matched in the same way as the final component -of the URL as described below. (Note that regex metacharacters such -as `\fB+\fR' are regarded literally unless they are in a path component -containing parentheses; see the Atlas-C++ example above. Also, the -parentheses must match within each path component.) -.PP -The pattern (after the final slash) is a Perl regexp (see -\fBperlre\fR(1) for details of these). You need to make the pattern -so tight that it matches only the upstream software you are interested -in and nothing else. Also, the pattern will be anchored at the -beginning and at the end, so it must match the full filename. (Note -that for HTTP URLs, the href may include the absolute path or full -site and path and still be accepted.) The pattern must contain at -least one Perl group as explained in the next paragraph. -.PP -Having got a list of `files' matching the pattern, their version -numbers are extracted by treating the part matching the Perl regexp -groups, demarcated by `\fB(...)\fR', joining them with `\fB.\fR' as a separator, -and using the result as the version number of the file. The version -number will then be mangled if required by the uversionmangle option -described below. Finally, the file versions are then compared to find -the one with the greatest version number, as determined by \fBdpkg -\-\-compare-versions\fR. Note that if you need Perl groups which are -not to be used in the version number, either use `\fB(?:...)\fR' or use the -uversionmangle option to clean up the mess! -.PP -The current (upstream) version can be specified as the second -parameter in the \fIwatch\fR file line. If this is \fIdebian\fR or absent, -then the current Debian version (as determined by -\fIdebian/changelog\fR) is used to determine the current upstream -version. The current upstream version may also be specified by the -command-line option \fB\-\-upstream-version\fR, which specifies the -upstream version number of the currently installed package (i.e., the -Debian version number without epoch and Debian revision). The -upstream version number will then be mangled using the dversionmangle -option if one is specified, as described below. If the newest version -available is newer than the current version, then it is downloaded -into the parent directory, unless the \fB\-\-report\fR or -\fB\-\-report-status\fR option has been used. Once the file has been -downloaded, then a symlink to the file is made from -\fI<package>_<version>.orig.tar.{gz|bz2|lzma|xz}\fR as described by the help -for the \fB\-\-symlink\fR option. -.PP -Finally, if a third parameter (an action) is given in the \fIwatch\fR file -line, this is taken as the name of a command, and the command -.nf - \fIcommand \fB\-\-upstream-version\fI version filename\fR -.fi -is executed, using either the original file or the symlink name. A -common such command would be \fBuupdate\fR(1). (Note that the calling -syntax was slightly different when using \fIwatch\fR file without a -`\fBversion=\fR...' line; there the command executed was `\fIcommand filename -version\fR'.) If the command is \fBuupdate\fR, then the -\fB\-\-no\-symlink\fR option is given to \fBuupdate\fR as a first -option, since any requested symlinking will already be done by -\fBuscan\fR. -.PP -The alternative version of the \fIwatch\fR file syntax for HTTP URLs is as -follows. The first field is a homepage which should be downloaded and -then searched for hrefs matching the pattern given in the second -field. (Again, this pattern will be anchored at the beginning and the -end, so it must match the whole href. If you want to match just the -basename of the href, you can use a pattern like -".*/name-(.+)\e.tar\e.gz" if you know that there is a full URL, or -better still: "(?:.*/)?name-(.+)\e.tar\e.gz" if there may or may not -be. Note the use of (?:...) to avoid making a backreference.) If any -of the hrefs in the homepage which match the (anchored) pattern are -relative URLs, they will be taken as being relative to the base URL of -the homepage (i.e., with everything after the trailing slash removed), -or relative to the base URL specified in the homepage itself with a -<base href="..."> tag. The third and fourth fields are the version -number and action fields as before. -.SH "PER-SITE OPTIONS" -A \fIwatch\fR file line may be prefixed with `\fBopts=\fIoptions\fR', where -\fIoptions\fR is a comma-separated list of options. The whole -\fIoptions\fR string may be enclosed in double quotes, which is -necessary if \fIoptions\fR contains any spaces. The recognised -options are as follows: -.TP -\fBactive\fR and \fBpassive\fR (or \fBpasv\fR) -If used on an FTP line, these override the choice of whether to use -PASV mode or not, and force the use of the specified mode for this -site. -.TP -\fBuversionmangle=\fIrules\fR -This is used to mangle the upstream version number as matched by the -ftp://... or http:// rules as follows. First, the \fIrules\fR string -is split into multiple rules at every `\fB;\fR'. Then the upstream version -number is mangled by applying \fIrule\fR to the version, in a similar -way to executing the Perl command: -.nf - $version =~ \fIrule\fR; -.fi -for each rule. Thus, suitable rules might be `\fBs/^/0./\fR' to prepend -`\fB0.\fR' to the version number and `\fBs/_/./g\fR' to change underscores into -periods. Note that the \fIrule\fR string may not contain commas; -this should not be a problem. - -\fIrule\fR may only use the '\fBs\fR', '\fBtr\fR' and '\fBy\fR' operations. When the '\fBs\fR' -operation is used, only the '\fBg\fR', '\fBi\fR' and '\fBx\fR' flags are available and -\fIrule\fR may not contain any expressions which have the potential to -execute code (i.e. the (?{}) and (??{}) constructs are not supported). - -If the '\fBs\fR' operation is used, the replacement can contain -backreferences to expressions within parenthesis in the matching regexp, -like `\fBs/-alpha(\ed*)/.a$1/\fR'. These backreferences must use the -`\fB$1\fR' syntax, as the `\fB\e1\fR' syntax is not supported. -.TP -\fBdversionmangle=\fIrules\fR -This is used to mangle the Debian version number of the currently -installed package in the same way as the \fBuversionmangle\fR option. -Thus, a suitable rule might be `\fBs/\e+dfsg\ed*$//\fR' to remove a -`\fB+dfsg1\fR' suffix from the Debian version number, or to handle `\fB.pre6\fR' -type version numbers. Again, the \fIrules\fR string may not contain -commas; this should not be a problem. -.TP -\fBversionmangle=\fIrules\fR -This is a syntactic shorthand for -\fBuversionmangle=\fIrules\fB,dversionmangle=\fIrules\fR, applying the -same rules to both the upstream and Debian version numbers. -.TP -\fBfilenamemangle=\fIrules\fR -This is used to mangle the filename with which the downloaded file -will be saved, and is parsed in the same way as the -\fBuversionmangle\fR option. Examples of its use are given in the -examples section above. -.TP -\fBdownloadurlmangle=\fIrules\fR -This is used to mangle the URL to be used for the download. The URL -is first computed based on the homepage downloaded and the pattern -matched, then the version number is determined from this URL. -Finally, any rules given by this option are applied before the actual -download attempt is made. An example of its use is given in the -examples section above. -.TP -\fBpgpsigurlmangle=\fIrules\fR -If present, the supplied rules will be applied to the downloaded URL -(after any downloadurlmangle rules, if present) to craft a new URL -that will be used to fetch the detached OpenPGP signature file for the -upstream tarball. Some common rules might be `\fBs/$/.asc/\fR' or -`\fBs/$/.pgp/\fR' or `\fBs/$/.gpg/\fR'. This signature must be made -by a key found in the keyring \fBdebian/upstream/signing-key.pgp\fR or -the armored keyring \fBdebian/upstream/signing-key.asc\fR. If it is not -valid, or not made by one of the listed keys, uscan will report an -error. -.TP -\fBrepacksuffix=\fIsuffix\fR -If the upstream sources are modified because \fIdebian/copyright\fR contains -the \fBFiles-Excluded\fR field, \fIsuffix\fR will be appended to the upstream -version of the repacked tar archive. Common suffixes might be \fB+dfsg1\fR to -indicate the removal of files that are not DFSG-compliant or \fB+ds1\fR for -other reasons such as removal of prebuilt files or large embedded code copies. -.SH "Directory name checking" -Similarly to several other scripts in the \fBdevscripts\fR package, -\fBuscan\fR explores the requested directory trees looking for -\fIdebian/changelog\fR and \fIdebian/watch\fR files. As a safeguard -against stray files causing potential problems, and in order to -promote efficiency, it will examine the name of the parent directory -once it finds the \fIdebian/changelog\fR file, and check that the -directory name corresponds to the package name. It will only attempt -to download newer versions of the package and then perform any -requested action if the directory name matches the package name. -Precisely how it does this is controlled by two configuration file -variables \fBDEVSCRIPTS_CHECK_DIRNAME_LEVEL\fR and -\fBDEVSCRIPTS_CHECK_DIRNAME_REGEX\fR, and their corresponding command-line -options \fB\-\-check-dirname-level\fR and -\fB\-\-check-dirname-regex\fR. -.PP -\fBDEVSCRIPTS_CHECK_DIRNAME_LEVEL\fR can take the following values: -.TP -.B 0 -Never check the directory name. -.TP -.B 1 -Only check the directory name if we have had to change directory in -our search for \fIdebian/changelog\fR, that is, the directory -containing \fIdebian/changelog\fR is not the directory from which -\fBuscan\fR was invoked. This is the default behaviour. -.TP -.B 2 -Always check the directory name. -.PP -The directory name is checked by testing whether the current directory -name (as determined by \fBpwd\fR(1)) matches the regex given by the -configuration file option \fBDEVSCRIPTS_CHECK_DIRNAME_REGEX\fR or by the -command line option \fB\-\-check-dirname-regex\fR \fIregex\fR. Here -\fIregex\fR is a Perl regex (see \fBperlre\fR(3perl)), which will be -anchored at the beginning and the end. If \fIregex\fR contains a '/', -then it must match the full directory path. If not, then it must -match the full directory name. If \fIregex\fR contains the string -\'PACKAGE', this will be replaced by the source package name, as -determined from the \fIchangelog\fR. The default value for the regex is: -\'PACKAGE(-.+)?', thus matching directory names such as PACKAGE and -PACKAGE-version. -.SH EXAMPLE -This script will perform a fully automatic upstream update. - -.nf -#!/bin/sh \-e -# called with '\-\-upstream-version' <version> <file> -uupdate "$@" -package=`dpkg\-parsechangelog | sed \-n 's/^Source: //p'` -cd ../$package-$2 -debuild -.fi - -Note that we don't call \fBdupload\fR or \fBdput\fR automatically, as -the maintainer should perform sanity checks on the software before -uploading it to Debian. -.SH OPTIONS -.TP -.B \-\-report\fP, \fB\-\-no\-download -Only report about available newer versions but do not download anything. -.TP -.B \-\-report\-status -Report on the status of all packages, even those which are up-to-date, -but do not download anything. -.TP -.B \-\-download -Report and download. (This is the default behaviour.) -.TP -.B \-\-destdir -Path of directory to which to download. If the specified path is not -absolute, it will be relative to one of the current directory or, if directory -scanning is enabled, the package's source directory. -.TP -.B \-\-force-download -Download upstream even if up to date (will not overwrite local files, however) -.TP -.B \-\-pasv -Force PASV mode for FTP connections. -.TP -.B \-\-no\-pasv -Do not use PASV mode for FTP connections. -.TP -\fB\-\-timeout\fR \fIN\fR -Set timeout to N seconds (default 20 seconds). -.TP -.B \-\-no\-symlink -Do not call \fBmk\-origtargz\fR. -.P -The following options are passed to \fBmk\-origtargz\fR: -.RS -.TP -.B \-\-symlink -Make \fIorig.tar.gz\fR (with the appropriate extension) symlinks to the -downloaded files. -(This is the default behaviour.) -.TP -.B \-\-copy -Instead of symlinking as described above, copy the downloaded files. -.TP -.B \-\-rename -Instead of symlinking as described above, rename the downloaded files. -.TP -.B \-\-repack -After having downloaded an lzma tar, xz tar, bzip tar or zip archive, -repack it to a gzip tar archive, if required. -The \fBunzip\fR package must be installed in order to repack .zip archives, the -\fBxz-utils\fR package must be installed to repack lzma or xz tar archives. -.TP -\fB\-\-compression\fR [ \fBgzip\fR | \fBbzip2\fR | \fBlzma\fR | \fBxz\fR ] -In the case where the upstream sources are repacked (either because -\fB\-\-repack\fR option is given or \fIdebian/copyright\fR contains the -field \fBFiles-Excluded\fR), it is possible to control the compression -method via the parameter (defaults to \fBgzip\fR). -.TP -.B \-\-copyright\-file \fIcopyright-file\fR -Exclude files mentioned in \fBFiles-Excluded\fR in the given copyright file. -This is useful when running uscan not within a source package directory. -.RE -.TP -.B \-\-dehs -Use an XML format for output, as required by the DEHS system. -.TP -.B \-\-no-dehs -Use the traditional uscan output format. (This is the default behaviour.) -.TP -\fB\-\-package\fR \fIpackage\fR -Specify the name of the package to check for rather than examining -\fIdebian/changelog\fR; this requires the \fB\-\-upstream-version\fR -(unless a version is specified in the \fIwatch\fR file) -and \fB\-\-watchfile\fR options as well. Furthermore, no directory -scanning will be done and nothing will be downloaded. This option is -probably most useful in conjunction with the DEHS system (and -\fB\-\-dehs\fR). -.TP -\fB\-\-upstream-version\fR \fIupstream-version\fR -Specify the current upstream version rather than examine the \fIwatch\fR file -or \fIchangelog\fR to determine it. This is ignored if a directory scan is -being performed and more than one \fIwatch\fR file is found. -.TP -\fB\-\-watchfile\fR \fIwatchfile\fR -Specify the \fIwatchfile\fR rather than perform a directory scan to -determine it. If this option is used without \fB\-\-package\fR, then -\fBuscan\fR must be called from within the Debian package source tree -(so that \fIdebian/changelog\fR can be found simply by stepping up -through the tree). -.TP -\fB\-\-download\-version\fR \fIversion\fR -Specify the version which the upstream release must match in order to be -considered, rather than using the release with the highest version. -.TP -\fB\-\-download\-current\-version\fR -Download the currently packaged version -.TP -.B \-\-verbose -Give verbose output. -.TP -.B \-\-no\-verbose -Don't give verbose output. (This is the default behaviour.) -.TP -.B \-\-no\-exclusion -Do not automatically exclude files mentioned in -\fIdebian/copyright\fR field \fBFiles-Excluded\fR -.TP -.B \-\-debug -Dump the downloaded web pages to stdout for debugging your watch file. -.TP -\fB\-\-check-dirname-level\fR \fIN\fR -See the above section \fBDirectory name checking\fR for an explanation of -this option. -.TP -\fB\-\-check-dirname-regex\fR \fIregex\fR -See the above section \fBDirectory name checking\fR for an explanation of -this option. -.TP -\fB\-\-user-agent\fR, \fB\-\-useragent\fR -Override the default user agent header. -.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 -.B \-\-help -Give brief usage information. -.TP -.B \-\-version -Display version information. -.SH "CONFIGURATION VARIABLES" -The two configuration files \fI/etc/devscripts.conf\fR and -\fI~/.devscripts\fR are sourced by a shell in that order to set -configuration variables. These may be overridden by command line -options. Environment variable settings are ignored for this purpose. -If the first command line option given is \fB\-\-noconf\fR, then these -files will not be read. The currently recognised variables are: -.TP -.B USCAN_DOWNLOAD -If this is set to \fIno\fR, then newer upstream files will not be -downloaded; this is equivalent to the \fB\-\-report\fR or -\fB\-\-no\-download\fR options. -.TP -.B USCAN_PASV -If this is set to \fIyes\fR or \fIno\fR, this will force FTP -connections to use PASV mode or not to, respectively. If this is set -to \fIdefault\fR, then \fBNet::FTP\fR(3) makes the choice (primarily based on -the \fBFTP_PASSIVE\fR environment variable). -.TP -.B USCAN_TIMEOUT -If set to a number \fIN\fR, then set the timeout to \fIN\fR seconds. -This is equivalent to the \fB\-\-timeout\fR option. -.TP -.B USCAN_SYMLINK -If this is set to \fIno\fR, then a pkg_version.orig.tar.{gz|bz2|lzma|xz} -symlink will not be made (equivalent to the \fB\-\-no\-symlink\fR -option). If it is set to \fIyes\fR or \fIsymlink\fR, then the -symlinks will be made. If it is set to \fIrename\fR, then the files -are renamed (equivalent to the \fB\-\-rename\fR option). -.TP -.B USCAN_DEHS_OUTPUT -If this is set to \fIyes\fR, then DEHS-style output will be used. -This is equivalent to the \fB\-\-dehs\fR option. -.TP -.B USCAN_VERBOSE -If this is set to \fIyes\fR, then verbose output will be given. This -is equivalent to the \fB\-\-verbose\fR option. -.TP -.B USCAN_USER_AGENT -If set, the specified user agent string will be used in place of the -default. This is equivalent to the \fB\-\-user-agent\fR option. -.TP -.B USCAN_DESTDIR -If set, the downloaded files will be placed in this directory. This is -equivalent to the \fB\-\-destdir\fR option. -.TP -.B USCAN_REPACK -If this is set to \fIyes\fR, then after having downloaded a bzip tar, -lzma tar, xz tar, or zip archive, \fBuscan\fR will repack it to a gzip tar. -This is equivalent to the \fB\-\-repack\fR option. -.TP -.B USCAN_EXCLUSION -If this is set to \fIno\fR, files mentioned in the field \fBFiles-Excluded\fR -of \fIdebian/copyright\fR will be ignored and no exclusion of files will be -tried. This is equivalent to the \fB\-\-no-exclusion\fR option. -.SH "EXIT STATUS" -The exit status gives some indication of whether a newer version was -found or not; one is advised to read the output to determine exactly -what happened and whether there were any warnings to be noted. -.TP -0 -Either \fB\-\-help\fR or \fB\-\-version\fR was used, or for some -\fIwatch\fR file which was examined, a newer upstream version was located. -.TP -1 -No newer upstream versions were located for any of the \fIwatch\fR files -examined. -.SH "HISTORY AND UPGRADING" -This section briefly describes the backwards-incompatible \fIwatch\fR file -features which have been added in each \fIwatch\fR file version, and the -first version of the \fBdevscripts\fR package which understood them. -.TP -.I Pre-version 2 -The \fIwatch\fR file syntax was significantly different in those days. Don't -use it. If you are upgrading from a pre-version 2 \fIwatch\fR file, you are -advised to read this manpage and to start from scratch. -.TP -.I Version 2 -devscripts version 2.6.90: The first incarnation of the current style -of \fIwatch\fR files. -.TP -.I Version 3 -devscripts version 2.8.12: Introduced the following: correct handling -of regex special characters in the path part, directory/path pattern -matching, version number in several parts, version number mangling. -Later versions have also introduced URL mangling. - -If you are upgrading from version 2, the key incompatibility is if you -have multiple groups in the pattern part; whereas only the first one -would be used in version 2, they will all be used in version 3. To -avoid this behaviour, change the non-version-number groups to be -(?:...) instead of a plain (...) group. -.SH "SEE ALSO" -.BR dpkg (1), -.BR mk\-origtargz (1), -.BR perlre (1), -.BR uupdate (1), -.BR devscripts.conf (5) -.SH AUTHOR -The original version of \fBuscan\fR was written by Christoph Lameter -<[email protected]>. Significant improvements, changes and bugfixes -were made by Julian Gilbey <[email protected]>. HTTP support was added -by Piotr Roszatycki <[email protected]>. The program was rewritten -in Perl by Julian Gilbey. diff --git a/scripts/uscan.pl b/scripts/uscan.pl index df30f72..55c5b0f 100755 --- a/scripts/uscan.pl +++ b/scripts/uscan.pl @@ -22,6 +22,1270 @@ # You should have received a copy of the GNU General Public License # along with this program. If not, see <https://www.gnu.org/licenses/>. +=pod + +=head1 NAME + +uscan - scan/watch upstream sources for new releases of software + +=head1 SYNOPSIS + +B<uscan> [I<options>] [I<path>] + +=head1 DESCRIPTION + +For the basic usage, B<uscan> is executed without any arguments from the root +of the Debianized source tree where you see the F<debian/> directory. Then +typically the following happens: + +=over + +=item * B<uscan> reads the first entry in F<debian/changelog> to determine the +source package name I<< <spkg> >> and the last upstream version. + +=item * B<uscan> process the watch lines F<debian/watch> from the top to the +bottom in 1 pass. + +=over + +=item * B<uscan> downloads a web page from the specified I<URL> in +F<debian/watch>. + +=item * B<uscan> extracts hrefs pointing to the upstream tarball(s) from the +web page using the specified I<matching-pattern> in F<debian/watch>. + +=item * B<uscan> downloads the upstream tarball with the highest version newer +than the last upstream version. + +=item * B<uscan> saves the downloaded tarball to the parent B<../> directory: +I<< ../<upkg>-<uversion>.tar.gz >> + +=item * B<uscan> invokes B<mk-origtargz> to create the source tarball: I<< +../<spkg>_<oversion>.orig.tar.gz >> + +=over + +=item * Here, I<< ../<spkg>_<oversion>.orig-<component>.tar.gz >> instead for +the secondary upstream tarball of the multiple upstream tarball (MUT) package. + +=back + +=item * Repeat until all lines in F<debian/watch> are processed. + +=back + +=item * B<uscan> invokes B<uupdate> to create the Debianized source tree: I<< +../<spkg>-<oversion>/* >> + +=back + +Please note the following. + +=over + +=item * For simplicity, the compression method used in examples is B<gzip> with +B<.gz> suffix. Other methods such as B<xz>, B<bzip2>, and B<lzma> may also be +used. + +=item * The new B<version=4> enables to handle the MUT package but it is a rare +case for the Debian packaging. For the single upstream tarball package, there +is only one watch line and no I<< ../<spkg>_<oversion>.orig-<component>.tar.gz +>> . + +=item * B<uscan> with the B<--report> option produces a human readable report +without downloading the upstream tarball. + +=item * B<uscan> with the B<--verbose> option produces a human readable report +of the B<uscan> execution. + +=item * B<uscan> with the B<--debug> option produces a human readable report of +the B<uscan> execution with the internal variable states. + +=item * B<uscan> with the B<--dehs> option produces the upstream package status +report without downloading the upstream tarball in an XML format for other +programs such as the Debian External Health System. + +=back + +=head1 FORMAT OF THE WATCH FILE + +The current version 4 format of F<debian/watch> can be summarized as follows: + +=over + +=item * Leading spaces and tabs are dropped. + +=item * Empty lines are dropped. + +=item * A line started by B<#> (hash) is a comment line and dropped. + +=item * Single B<\> (back slash) at the end of a line is dropped and the +next line is concatenated after removing leading spaces and tabs. The +concatenated line is parsed as a single line. (The existence and non-existence +of the space before the tailing single B<\> is significant.) + +=item * The first non-comment line is: + +=over + +=item B<version=4> + +=back + +This is required. + +=item * The following non-comment lines (watch lines) specify the rule for the +selection of the candidate upstream tarball URLs and are in one of the +following 3 formats: + +=over + +=item * B<opts="> I<...> B<"> B<http://>I<URL> I<matching-pattern> [I<version> [I<script>]] + +=item * B<http://>I<URL> I<matching-pattern> [I<version> [I<script>]] + +=item * B<opts="> I<...> B<"> + +=back + +Here, + +=over + +=item * B<opts="> I<...> B<"> specifies the behavior of B<uscan>. See L<WATCH +FILE OPTIONS>. + +=item * B<http://>I<URL> specifies the web page where the upstream publishes +the link to the latest upstream source archive. + +=over + +=item * B<https://>I<URL> instead may be used, too. + +=item * B<ftp://>I<URL> pointing to the archive directory instead may be used, +too. + +=item * Some parts of I<URL> may be in the regex match pattern surrounded +between B<(> and B<)> such as B</foo/bar-([\.\d]+)/>. (If multiple +directories match, the highest version one is picked.) Otherwise, the I<URL> +is taken as verbatim. + +=back + +=item * I<matching-pattern> specifies the full string matching pattern for +hrefs in the web page. See L<WATCH FILE EXAMPLES>. + +=over + +=item * All matching parts in B<(> and B<)> are concatenated with B<.> (period) +to form the upstream version. + +=item * If the hrefs do not contain directory, you can combine this with the +previous entry. I.e., B<http://>I<URL>B</>I<matching-pattern> . + +=back + +=item * I<version> limits the downloading upstream tarball. The newest +available version is chosen for the download. + +=over + +=item * B<debian> limits the downloading upstream tarball to be newer than the +version obtained from F<debian/changelog>. + +=item * I<version-number> such as B<12.5> limits the downloading upstream +tarball to be newer than the I<version-number>. + +=item * B<same> limits the downloading version of the secondary tarballs to be +exactly the same as the one for the first upstream tarball downloaded. (useful +only for MUT) + +=item * B<previous> limits the downloading version of the signature +file. (used with sigmode=previous) + +=item * B<ignore> does not limit the downloading version of the secondary +tarballs. (maybe useful for MUT) + +=back + +=item * I<script> is executed at the end of B<uscan> execution with appropriate +arguments provided by the B<uscan>. + +=over + +=item * The typical Debian package is the non-native package made from one +upstream tarball. Only a single line of the watch line in one of the first 2 +formats is usually used with its I<version> set to B<debian> and I<script> +set to B<uupdate>. + +=item * The native package should skip specifying I<script>. + +=item * The multiple upstream tarball package should specify B<uupdate> as +I<script> at the last watch line and should skip specifying I<script> at +the rest of the watch lines. + +=back + +=item * The last format of the watch line is useful to set the persistent +parameters. If this is used, this must be followed by the I<URL> defining +watch line(s). + +=item * [ and ] in the above format are there to mark the optional parts and +should not be typed. + +=back + +=back + +=head1 WATCH FILE OPTIONS + +B<uscan> reads the watch options specified in B<opts="> I<...> B<"> to +customize its behavior. Multiple options I<option1>, I<option2>, I<option3>, +... can be set as B<opts=">I<option1>B<,> I<option2>B<,> I<option3>B<,> I< ... +>B<"> . The double quotes are necessary if options contain any spaces. + +Unless otherwise noted as persistent, most options are valid only within the +watch line. + +The available watch options are: + +=over + +=item B<component=>I<component> + +Set the name of the secondary source tarball as I<< +<spkg>_<oversion>.orig-<component>.tar.gz >> for the MUT package + +=item B<compression=>I<method> + +Set the compression I<method> when it is repacked. (persistent) + +Available I<method> values are B<xz>, B<gzip> (alias B<gz>), B<bzip2> (alias +B<bz2>), and B<lzma>. + +Please note the repack of the upstream tarballs happen in several cases: + +=over + +=item * B<USCAN_REPACK> is set in the devscript configuration. See L<DEVSCRIPT +CONFIGURATION VARIABLES>. + +=item * B<--repack> is set in the commandline. See <COMMANDLINE OPTIONS>. + +=item * The upstream tarballs contain files listed under the B<Files-Excluded> +and B<Files-Excluded->I<component> stanza of F<debian/copyright>. See +mk-origtargz(1). + +=back + +=item B<repack> + +Force to repack the upstream tarball using the compression I<mathod>. + +=item B<repacksuffix=>I<suffix> + +Add I<suffix> to the version as suffix when the source tarball is repackaged. +(persistent) This rule should be used only for the single upstream package. + +=item B<sigmode=>I<mode> + +Set the pgp/gpg signature verification I<mode>. + +=over + +=item B<mangle> + +Use B<pgpsigurlmangle=>I<rules> to generate the candidate upstream signature file +URL string from the upstream tarball URL. (default) + +=item B<next> + +Verify this downloaded file by the next downloaded signature file. The next watch line must be B<previous>. Otherwise, no verification. + +=item B<previous> + +Verify the previous downloaded file by this signature file. The previous watch line must be B<next>. + +=item B<self> + +Verify the file by the self signature (not implemented yet) + +=item B<none> + +No signature available. (No warning.) + +=back + +=item B<user-agent=>I<user-agent-string> + +Set the user-agent string used to contact the HTTP(S) server as +I<user-agent-string>. (persistent) + +B<user-agent> option should be specified by itself in the watch line without +I<URL> and other options to allow using semicolons and commas in it. + +=item B<pasv>, B<passsive> + +Use PASV mode for the FTP connection. + +If the PASV mode is required due to the client side network environment, set +B<uscan> to use PASV mode via L<COMMANDLINE OPTIONS> or L<DEVSCRIPT +CONFIGURATION VARIABLES> instead. + +=item B<active>, B<nopasv> + +Don't use PASV mode for the FTP connection. + +=item B<dversionmangle=>I<rules> + +Normalize the last upstream version string found in +F<debian/changelog> + +=item B<pagemangle=>I<rules> + +Normalize the downloaded web page string + +=item B<uversionmangle=>I<rules> + +Normalize the candidate upstream version strings +extracted from hrefs in the source of the web page. + +=item B<versionmangle=>I<rules> + +Syntactic shorthand for B<uversionmangle=>I<rules>B<,dversionmangle=>I<rules> + +=item B<filenamemangle=>I<rules> + +Normalize the downloaded tarball filename string I<< <upkg>-<uversion>.tar.gz +>>. + +=item B<oversionmangle=>I<rules> + +Generate the version string I<< <oversion> >> of the source tarball I<< +<spkg>_<oversion>.orig.tar.gz >> from I<< <uversion> >>. + +=item B<downloadurlmangle=>I<rules> + +Normalize the candidate upstream tarball URL +string + +=item B<pgpsigurlmangle=>I<rules> + +Generate the candidate upstream signature file +URL string from the upstream tarball URL. + +=back + +Here, the mangling rules apply the I<rules> to the pertinent string. Multiple +rules can be specified in a mangling rule by making a concatenated string of +each mangling I<rule> separated by B<;> (semicolon). + +Each mangling I<rule> can not contain B<;> (semicolon) nor B<,> (comma). + +Each mangling I<rule> behaves as if a Perl command "I<$string> B<~=> +I<rule>" is executed. There are some notable details. + +=over + +=item * I<rule> may only use the B<s>, B<tr>, and B<y> operations. + +=over + +=item B<s/>I<regex>B</>I<replacement>B</>I<options> + +Regex pattern match and replace the target string. Only the B<g>, B<i> and +B<x> flags are available. Use the B<$1> syntax for the back reference (No +B<\1> syntax). Code execution is not allowed (i.e. No B<(?{})> nor B<(??{})> +constructs). + +=item B<y/>I<source>B</>I<dest>B</> or B<tr/>I<source>B</>I<dest>B</> + +Transliterate the characters in the target string. + +=back + +=back + +=head1 EXAMPLE OF EXECUTION + +B<uscan> reads the first entry in F<debian/changelog> to determine the source +package name and the last upstream version. + +For example, if the first entry of F<debian/changelog> may be: + +=over + +=item * I<< bar >> (B<3:2.03+dfsg1-4>) unstable; urgency=low + +=back + +then, the source package name is I<< bar >> and the last upstream version +is B<3:2.03+dfsg1-4>. + +The last upstream version is normalized to B<2.03+dfsg1> by removing the epoch +and the Debian revision. + +If the B<dversionmangle> rule exists, the last upstream version is further +normalized by applying this rule to it. For example, if the last upstream +version is B<2.03+dfsg1> indicating the source tarball is repackaged, the +suffix B<+dfsg1> is removed by the string substitution B<s/\+dfsg\d*$//> to +make the (dversionmangled) last upstream version B<2.03> and it is compared to +the candidate upstream tarball versions such as B<2.03>, B<2.04>, ... found in +the remote site. Thus, set this rule as: + +=over + +=item * B<opts="dversionmangle=s/\+dfsg\d*$//"> + +=back + +B<uscan> downloads a web page from B<http://>I<URL> specified in +F<debian/watch>. + +=over + +=item * If the directory name part of I<URL> has no parentheses, B<(> and B<)>, +it is taken as verbatim. + +=item * If the directory name part of I<URL> has parentheses, B<(> and B<)>, +then B<uscan> recursively searches all possible directories to find a page for +the newest version. + +=back + +For example, this B<http://>I<URL> may be specified as: + +=over + +=item * B<http://www.example.org/DL(.+)/> + +=back + +Please note the trailing B</> in the above. + +If the B<pagemangle> rule exists, the whole downloaded web page as a string is +normalized by applying this rule to it. This is very powerful tool and needs to +be used with caution. If other mangling rules can be used to address your +objective, do not use this rule. + +The downloaded web page is scanned for hrefs defined in the B<< <a href=" >> +I<...> B<< "> >> tag to locate the candidate upstream tarball URLs. These +candidate upstream tarball URLs are matched by the Perl regex pattern +I<matching-pattern> such as B<< DL-(?:[\d\.]+?)/foo-(.+)\.tar\.gz >> to +narrow down the candidates. This pattern match needs to be anchored at the +beginning and the end. For example, candidate URLs may be: + +=over + +=item * B<< DL-2.02/foo-2.02.tar.gz >> + +=item * B<< DL-2.03/foo-2.03.tar.gz >> + +=item * B<< DL-2.04/foo-2.04.tar.gz >> + +=back + +Here the matching string of B<(.+)> in I<matching-pattern> is considered as the +candidate upstream version. If there are multiple matching strings of +capturing patterns in I<matching-pattern>, they are all concatenated with B<.> +(period) to form the candidate upstream version. Make sure to use the +non-capturing regex such as B<(?:[\d\.]+?)> instead for the variable text +matching part unrelated to the version. + +Then, the candidate upstream versions are: + +=over + +=item * B<2.02> + +=item * B<2.03> + +=item * B<2.04> + +=back + +The downloaded tarball filename is basically set to the same as its filename in +the remote URL. + +If the B<uversionmangle> rule exists, the candidate upstream versions are +normalized by applying this rule to them. (This rule may be useful if the +upstream version scheme doesn't sort correctly to identify the newest +version.) + +The upstream tarball URL corresponding to the newest (uversionmangled) candidate +upstream version newer than the (dversionmangled) last upstream version is +selected to be the candidate upstream tarball URL. + +Here, the order of the version is decided by B<dpkg --compare-versions>. + +If the B<filenamemangle> rule exists, the downloaded tarball filename is +normalized by applying this rule to it. (This rule may not be as significant +for modern use cases. B<mk-origtargz> takes care the proper renaming of the +source tarballs into <spkg>_<oversion>.orig.tar.gz based on the source package +name in F<debian/changelog> without relying on the filename of the remote URL. +Now, B<uupdate> is invoked by B<uscan> with B<--find> option and is not +expected to rename the downloaded tarball anymore.) + +If the candidate upstream tarball URL is a relative URL, it is converted to a +absolute URL using the base URL of the web page. If the B<< <base href=" >> I< +... > B<< "> >> tag exists in the web page, the candidate upstream tarball URL +is converted to the absolute URL using the specified base URL in the base tag, +instead. + +If the B<downloadurlmangle> rule exists, the candidate upstream tarball URL is +normalized by applying this rule to it. (This is useful for some sites with the +obfuscated download URL.) + +B<uscan> downloads the candidate upstream tarball to the parent B<../> +directory. For example, the downloaded file may be: + +=over + +=item * F<../foo-2.04.tar.gz> + +=back + +Let's call this downloaded version B<2.04> in the above example generically as +I<< <uversion> >> in the following. + +If the B<pgpsignurlmangle> rule exists, the upstream signature file URL is +generated by applying this rule to the (downloadurlmangled) candidate upstream +tarball URL and the signature file is tried to be downloaded. + +If the B<pgpsignurlmangle> rule doesn't exist, B<uscan> tries to download the +matching upstream signature file assuming they are available from the same URL +with their filename being suffixed by the 4 common suffix B<asc>, B<gpg>, +B<pgp>, and B<sig>. + +If the signature file is downloaded, the downloaded upstream tarball is checked +for its authenticity against the downloaded signature file using the keyring +F<debian/upstream/signing-key.pgp> or the armored keyring +F<debian/upstream/signing-key.asc>. If its signature is not valid, or not made +by one of the listed keys, B<uscan> will report an error. + +If the B<oversionmangle> rule exists, the source tarball version I<oversion> is +generated from the downloaded upstream version I<uversion> by applying this +rule. This rule is useful to add suffix such as B<+dfsg1> to the version of all +the source packages of the MUT package for which the repacksuffix mechanism +doesn't work well. + +B<uscan> invokes B<mk-origtargz> to create the source tarball properly named +for the source package with B<.orig.> in its filename. + +=over + +=item case A: packaging of the upstream tarball as is + +B<mk-origtargz> creates a symlink I<< ../bar_<oversion>.orig.tar.gz >> +linked to the downloaded local upstream tarball. Here, I<< bar >> is the source +package name found in F<debian/changelog>. The generated symlink may be: + +=over + +=item * F<../bar_2.04.orig.tar.gz> -> F<foo-2.04.tar.gz> (as is) + +=back + +Usually, there is no need to set up B<opts="dversionmangle=> I<...> B<"> for +this case. + +=item case B: packaging of the upstream tarball after removing non-DFSG files + +B<mk-origtargz> checks the filename glob of the B<Files-Excluded> stanza in the +first section of F<debian/copyright>, removes matching files to create a +repacked upstream tarball. Normally, the repacked upstream tarball is renamed +with I<suffix> to I<< ../bar_<oversion><suffix>.orig.tar.gz >> using +the B<repacksuffix> option for the single upstream package. Here I<< <oversion> >> +is updated to be I<< <oversion><suffix> >>. + +The removal of files is required if files are not DFSG-compliant. For such +case, B<+dfsg1> is used as I<suffix>. + +So the combined options are set as +B<opts="dversionmangle=s/\+dfsg\d*$// ,repacksuffix=+dfsg1">, instead. + +For example, the repacked upstream tarball may be: + +=over + +=item * F<../bar_2.04+dfsg1.orig.tar.gz> (repackaged) + +=back + +=back + +B<uscan> normally invokes "B<uupdate> B<--find --upstream-version> +I<oversion> " for the version=4 watch file. + +Please note that B<--find> option is used here since B<mk-origtargz> has been +invoked to make B<*.orig.tar.gz> file already. B<uscan> picks I<< bar >> from +F<debian/changelog>. + +It creates the new upstream source tree under the +I<< ../bar-<oversion> >> directory and Debianize it leveraging the +last package contents. + +=head1 WATCH FILE EXAMPLES + +When writing the watch file, you should rely on the latest upstream source +announcement web page. You should not try to second guess the upstream archive +structure if possible. Here are the typical F<debian/watch> files. + +The existance and non-existance of a space before tailing B<\> (back slash) are +significant. + +=head2 HTTP site (basic) + +For the basic single upstream tarball case: + + version=4 + http://example.com/~user/release/foo.html \ + files/foo-([\d\.]*).tar.gz debian uupdate + +If source package name is B<foo> and downloaded version of the main upstream +tarball is B<2.0>, then B<foo_2.0.orig.tar.gz>. + +=head2 HTTP site (basic MUT) + +For the basic 2 upstream tarball case: + + version=4 + http://example.com/~user/release/foo.html \ + files/foo-([\d\.]*).tar.gz debian true + opts=component=baz \ + http://example.com/~user/release/foo.html \ + files/baz-([\d\.]*).tar.gz same uupdate + +If source package name is B<foo> and downloaded version of the main upstream +tarball is B<2.0>, then B<foo_2.0.orig.tar.gz> and B<foo_2.0.orig-baz.tar.gz> +are created. + +=head2 HTTP site (flexible) + +For the maximum flexibility of upstream tarball formats: + + version=4 + http://example.com/example-(\d[\d.]*)\.\ + (?:zip|tgz|tbz2|txz|tar\.(?:gz|bz2|xz)) debian uupdate + +=head2 HTTP site (recursive directory scanning) + +For recursive directory scanning: + + version=4 + http://tmrc.mit.edu/mirror/twisted/Twisted/(\d\.\d)/ \ + Twisted-([\d\.]*)\.tar\.xz debian uupdate + +or in one string style variant + + version=4 + http://tmrc.mit.edu/mirror/twisted/\ + Twisted/(\d\.\d)/Twisted-([\d\.]*)\.tar\.xz debian uupdate + +Here, the web site should be able to handle requests to: + + http://tmrc.mit.edu/mirror/twisted/Twisted/ + +=head2 HTTP site (alternative) + +For one string style: + + version=4 + http://www.cpan.org/modules/by-module/Text/Text-CSV_XS-(.+)\.tar\.gz \ + debian uupdate + +This is the same as + + version=4 + http://www.cpan.org/modules/by-module/Text Text-CSV_XS-(.+)\.tar\.gz \ + debian uupdate + +=head2 HTTP site (sf.net) + +For SourceForge based projects, qa.debian.org runs a redirector which allows a +simpler form of URL. The format below will automatically be rewritten to use +the redirector. + + version=4 + http://sf.net/audacity/audacity-src-(.+)\.tar\.gz uupdate + +=head2 HTTP site (github.com) + +For GitHub projects, you can use the tags or releases page. The archive URLs +use only the version as the filename. You can rename the downloaded upstream +tarball into standard I<project>B<->I<version>B<.tar.gz> using +B<filenamemangle>: + + version=4 + opts="filenamemangle=\ + s/(?:.*?)?v?(\d[\d.]*)\.tar\.gz/<project>-$1.tar.gz/" \ + https://github.com/<user>/<project>/tags \ + (?:.*?/)?v?(\d[\d.]*)\.tar\.gz debian uupdate + +=head2 HTTP site (code.google.com) + +Sites which used to be hosted on the Google Code service should have migrated +to elsewhere (github?). Please look for the newer upstream site. + +=head2 HTTP site (funny version) + +For a site which has funny version numbers, the parenthesized groups will be +joined with B<.> (period) to make a sanitized version number. + + version=4 + http://www.site.com/pub/foobar/foobar_v(\d+)_(\d+)\.tar\.gz \ + debian uupdate + +=head2 HTTP site (DFSG) + +The upstream part of the Debian version number can be mangled to indicate the +source package was repackaged to clean up non-DFSG files: + + version=4 + opts="dversionmangle=s/\+dfsg\d*$//,repacksuffix=+dfsg1" \ + http://some.site.org/some/path/foobar-(.+)\.tar\.gz debian uupdate + +See L<COPYRIGHT FILE EXAMPLES>. + +=head2 HTTP site (filenamemangle) + +The upstream tarball filename is found by taking the last component of the URL +and removing everything after any '?'. If that leaves nothing for filename, +B<uscan> generate filename using the source package name in +B<debian/changelog>, the new version, and suffix B<.download> . + +If this does not fit to you, use B<filenamemangle>. For example, F<< <A +href="http://foo.bar.org/dl/?path=&dl=foo-0.1.1.tar.gz";> >> could be handled +as: + + version=4 + opts=filenamemangle=s/.*=(.*)/$1/ \ + http://foo.bar.org/dl/\?path=&dl=foo-(.+)\.tar\.gz \ + debian uupdate + +F<< <A href="http://foo.bar.org/dl/?path=&dl_version=0.1.1";> >> +could be handled as: + + version=4 + opts=filenamemangle=s/.*=(.*)/foo-$1\.tar\.gz/ \ + http://foo.bar.org/dl/\?path=&dl_version=(.+) \ + debian uupdate + +=head2 HTTP site (downloadurlmangle) + +The option B<downloadurlmangle> can be used to mangle the URL of the file +to download. This can only be used with B<http://> URLs. This may be +necessary if the link given on the web page needs to be transformed in +some way into one which will work automatically, for example: + + version=4 + opts=downloadurlmangle=s/prdownload/download/ \ + http://developer.berlios.de/project/showfiles.php?group_id=2051 \ + http://prdownload.berlios.de/softdevice/vdr-softdevice-(.+).tgz \ + debian uupdate + +=head2 HTTP site (origversionmangle, MUT) + +The option B<origversionmangle> can be used to mangle the version of the source +tarball (B<.orig.tar.gz> and B<.orig-bar.tar.gz>). For example, B<+dfsg1> can +be added to the upstream version as: + + version=4 + opts=origversionmangle=s/(.*)/$1+dfsg1/ \ + http://example.com/~user/release/foo.html \ + files/foo-([\d\.]*).tar.gz debian + opts="component=bar" \ + http://example.com/~user/release/foo.html \ + files/bar-([\d\.]*).tar.gz same uupdate + +See L<COPYRIGHT FILE EXAMPLES>. + +=head2 HTTP site (pagemangle) + +The option B<pagemangle> can be used to mangle the downloaded web page before +applying other rules. The non-standard web page without proper B<< <a href=" +>> << ... >> B<< "> >> entries can be converted. For example, if F<foo.html> +uses B<< <a bogus=" >> I<< ... >> B<< "> >>, this can be converted to the +standard page format with: + + version=4 + opts=pagemangle="s/<a\s+bogus=/<a href=/g" \ + http://example.com/release/foo.html \ + files/foo-([\d\.]*).tar.gz debian uupdate + +Please note the use of B<g> here to replace all occurrences. + +If F<foo.html> uses B<< <Key> >> I<< ... >> B<< </Key> >>, this can be +converted to the standard page format with: + + version=4 + opts="pagemangle=s%<Key>([^<]*)</Key>%<Key><a href="$1">$1</a></Key>%g" \\ + http://localhost:$PORT/ \ + (?:.*)/$PKG-([\d\.]+).tar.gz debian uupdate + +=head2 FTP site (basic): + + version=4 + ftp://ftp.tex.ac.uk/tex-archive/web/c_cpp/cweb/cweb-(.+)\.tar\.gz \ + debian uupdate + +=head2 FTP site (regex special characters): + + version=4 + ftp://ftp.worldforge.org/pub/worldforge/libs/\ + Atlas-C++/transitional/Atlas-C\+\+-(.+)\.tar\.gz debian uupdate + +Please note that this URL is connected to be I< ... >B<libs/Atlas-C++/>I< ... > +. For B<++>, the first one in the directory path is verbatim while the one in +the filename is escaped by B<\>. + +=head2 FTP site (funny version) + +This is another way of handling site with funny version numbers, +this time using mangling. (Note that multiple groups will be +concatenated before mangling is performed, and that mangling will +only be performed on the basename version number, not any path +version numbers.) + + version=4 + opts="uversionmangle=s/^/0.0./" \ + ftp://ftp.ibiblio.org/pub/Linux/ALPHA/wine/\ + development/Wine-(.+)\.tar\.gz debian uupdate + + +=head1 COPYRIGHT FILE EXAMPLES + +Here is an example for the F<debian/copyright> file which initiates automatic repackaging of the upstream tarball into I<< <spkg>_<oversion>.orig.tar.gz >>: + + Format: http://www.debian.org/doc/packaging-manuals/copyright-format/1.0/ + Files-Excluded: exclude-this + exclude-dir + */exclude-dir + .* + */js/jquery.js + + ... + +Here is another example for the F<debian/copyright> file which initiates automatic repackaging of the multiple upstream tarballs into I<< <spkg>_<oversion>.orig.tar.gz >> and I<< <spkg>_<oversion>.orig-bar.tar.gz >>: + + Format: http://www.debian.org/doc/packaging-manuals/copyright-format/1.0/ + Files-Excluded: exclude-this + exclude-dir + */exclude-dir + .* + */js/jquery.js + Files-Excluded-bar: exclude-this + exclude-dir + */exclude-dir + .* + */js/jquery.js + + ... + +See mk-origtargz(1). + +=head1 COMMANDLINE OPTIONS + +For the basic usage, B<uscan> does not require to set these options. + +=over + +=item B<--report>, B<--no-download> + +Only report about available newer versions but do not download +anything. + +=item B<--report-status> + +Report on the status of all packages, even those which are up-to-date, +but do not download anything. + +=item B<--download> + +Report and download. (This is the default behavior.) + +=item B<--destdir> + +Path of directory to which to download. If the specified path is not absolute, +it will be relative to one of the current directory or, if directory scanning +is enabled, the package's +source directory. + +=item B<--force-download> + +Download upstream even if up-to-date (will not overwrite local files, however) + +=item B<--pasv> + +Force PASV mode for FTP connections. + +=item B<--no-pasv> + +Do not use PASV mode for FTP connections. + +=item B<--timeout> I<N> + +Set timeout to I<N> seconds (default 20 seconds). + +=item B<--no-symlink> + +Do not call B<mk-origtargz>. + +=item B<--dehs> + +Use an XML format for output, as required by the DEHS system. + +=item B<--no-dehs> + +Use the traditional uscan output format. (This is the default behavior.) + +=item B<--package> I<package> + +Specify the name of the package to check for rather than examining +F<debian/changelog>; this requires the B<--upstream-version> (unless a version +is specified in the F<watch> file) and B<--watchfile> options as well. +Furthermore, no directory scanning will be done and nothing will be downloaded. +This option is probably most useful in conjunction with the DEHS system (and +B<--dehs>). + +=item B<--upstream-version> I<upstream-version> + +Specify the current upstream version rather than examine F<debian/watch> or +F<debian/changelog> to determine it. This is ignored if a directory scan is being +performed and more than one F<debian/watch> file is found. + +=item B<--watchfile> I<watchfile> + +Specify the I<watchfile> rather than perform a directory scan to +determine it. If this option is used without B<--package>, then +B<uscan> must be called from within the Debian package source tree +(so that F<debian/changelog> can be found simply by stepping up +through the tree). + +=item B<--download-version> I<version> + +Specify the I<version> which the upstream release must match in order to be +considered, rather than using the release with the highest version. + +=item B<--download-current-version> + +Download the currently packaged version + +=item B<--verbose> + +Give verbose output. + +=item B<--no-verbose> + +Don't give verbose output. (This is the default behavior.) + +=item B<--no-exclusion> + +Do not automatically exclude files mentioned in F<debian/copyright> field B<Files-Excluded> + +=item B<--debug> + +Dump the downloaded web pages to stdout for debugging your F<watch> file. + +=item B<--check-dirname-level> I<N> + +See the below section L<Directory name checking> for an explanation of this option. + +=item B<--check-dirname-regex> I<regex> + +See the below section L<Directory name checking> for an explanation of this option. + +=item B<--user-agent>, B<--useragent> + +Override the default user agent header. + +=item B<--no-conf>, B<--noconf> + +Do not read any configuration files. This can only be used as the first option +given on the command-line. + +=item B<--help> + +Give brief usage information. + +=item B<--version> + +Display version information. + +=back + +B<uscan> also accepts following options and passes them to B<mk-origtargz>: + +=over + +=item B<--symlink> + +Make B<orig.tar.gz> (with the appropriate extension) symlink to the downloaded +files. (This is the default behavior.) + +=item B<--copy> + +Instead of symlinking as described above, copy the downloaded files. + +=item B<--rename> + +Instead of symlinking as described above, rename the downloaded files. + +=item B<--repack> + +After having downloaded an lzma tar, xz tar, bzip tar or zip archive, repack it +to a gzip tar archive, if required. The unzip package must be installed in +order to repack .zip archives, the xz-utils package must be installed to repack +lzma or xz tar archives. + +=item B<--compression> [ B<gzip> | B<bzip2> | B<lzma> | B<xz> ] + +In the case where the upstream sources are repacked (either because B<--repack> +option is given or F<debian/copyright> contains the field B<Files-Excluded>), it is +possible to control the compression method via the parameter (defaults to +B<gzip>). + +=item B<--copyright-file> I<copyright-file> + +Exclude files mentioned in B<Files-Excluded> in the given I<copyright-file>. +This is useful when running B<uscan> not within a source package directory. + +=back + +=head1 DEVSCRIPT CONFIGURATION VARIABLES + +For the basic usage, B<uscan> does not require to set these configuration +variables. + +The two configuration files F</etc/devscripts.conf> and F<~/.devscripts> are +sourced by a shell in that order to set configuration variables. These +may be overridden by command line options. Environment variable settings are +ignored for this purpose. If the first command line option given is +B<--noconf>, then these files will not be read. The currently recognized +variables are: + +=over + +=item B<USCAN_DOWNLOAD> + +If this is set to B<no>, then newer upstream files will not be downloaded; this +is equivalent to the B<--report> or B<--no-download> options. + +=item B<USCAN_PASV> + +If this is set to yes or no, this will force FTP connections to use PASV mode +or not to, respectively. If this is set to default, then B<Net::FTP(3)> makes +the choice (primarily based on the B<FTP_PASSIVE> environment variable). + +=item B<USCAN_TIMEOUT> + +If set to a number I<N>, then set the timeout to I<N> seconds. This is +equivalent to the B<--timeout> option. + +=item B<USCAN_SYMLINK> + +If this is set to no, then a I<pkg>_I<version>B<.orig.tar.{gz|bz2|lzma|xz}> +symlink will not be made (equivalent to the B<--no-symlink> option). If it is +set to B<yes> or B<symlink>, then the symlinks will be made. If it is set to +rename, then the files are renamed (equivalent to the B<--rename> option). + +=item B<USCAN_DEHS_OUTPUT> + +If this is set to B<yes>, then DEHS-style output will be used. This is +equivalent to the B<--dehs> option. + +=item B<USCAN_VERBOSE> + +If this is set to B<yes>, then verbose output will be given. This is +equivalent to the B<--verbose> option. + +=item B<USCAN_USER_AGENT> + +If set, the specified user agent string will be used in place of the default. +This is equivalent to the B<--user-agent> option. + +=item B<USCAN_DESTDIR> + +If set, the downloaded files will be placed in this directory. This is +equivalent to the B<--destdir> option. + +=item B<USCAN_REPACK> + +If this is set to yes, then after having downloaded a bzip tar, lzma tar, xz +tar, or zip archive, uscan will repack it to a gzip tar. This is equivalent to +the B<--repack> option. + +=item B<USCAN_EXCLUSION> + +If this is set to no, files mentioned in the field B<Files-Excluded> of +F<debian/copyright> will be ignored and no exclusion of files will be tried. +This is equivalent to the B<--no-exclusion> option. + +=back + +=head1 EXIT STATUS + +The exit status gives some indication of whether a newer version was found or +not; one is advised to read the output to determine exactly what happened and +whether there were any warnings to be noted. + +=over + +=item B<0> + +Either B<--help> or B<--version> was used, or for some F<watch> file which was +examined, a newer upstream version was located. + +=item B<1> + +No newer upstream versions were located for any of the F<watch> files examined. + +=back + +=head1 ADVANCED FEATURES + +B<uscan> has many other enhanced features which are skipped in the above +section for the simplicity. Let's check their highlights. + +B<uscan> actually scans not just the current directory but all its +subdirectories looking for F<debian/watch> to process them all. +See L<Directory name checking>. + +B<uscan> can be executed with I<path> as its argument to change the starting +directory of search from the current directory to I<path> . + +See L<COMMANDLINE OPTIONS> and L<DEVSCRIPT CONFIGURATION VARIABLES> for other +variations. + +=head2 Custom script + +The optional I<script> parameter F<debian/watch> means to execute I<script> +with options after processing this line. You can customize this by specifying +F<debian/myuupdate> as I<script> and create executable file F<debian/myuupdate> +with the following content. + + #!/bin/sh -e + # called with --upstream-version <version> + uupdate --find "$@" + package=`dpkg-parsechangelog | sed -n 's/^Source: //p'` + cd ../$package-$2 + debuild + +Then B<uscan> invokes "I<debian/myuupdate> B<--upstream-version> I<version>" to +perform a fully automatic upstream update of Debian binary packages. + +Note that we don't call B<dupload> or B<dput> automatically, as the maintainer +should perform sanity checks on the software before uploading it to Debian. + +=head2 Directory name checking + +Similarly to several other scripts in the B<devscripts> package, B<uscan> +explores the requested directory trees looking for F<debian/changelog> and +F<debian/watch> files. As a safeguard against stray files causing potential +problems, and in order to promote efficiency, it will examine the name of the +parent directory once it finds the F<debian/changelog> file, and check that the +directory name corresponds to the package name. It will only attempt to +download newer versions of the package and then perform any requested action if +the directory name matches the package name. Precisely how it does this is +controlled by two configuration file variables +B<DEVSCRIPTS_CHECK_DIRNAME_LEVEL> and B<DEVSCRIPTS_CHECK_DIRNAME_REGEX>, and +their corresponding command-line options B<--check-dirname-level> and +B<--check-dirname-regex>. + +B<DEVSCRIPTS_CHECK_DIRNAME_LEVEL> can take the following values: + +=over + +=item B<0> + +Never check the directory name. + +=item B<1> + +Only check the directory name if we have had to change directory in +our search for F<debian/changelog>, that is, the directory containing +F<debian/changelog> is not the directory from which B<uscan> was invoked. This +is the default behavior. + +=item B<2> + +Always check the directory name. + +=back + +The directory name is checked by testing whether the current directory name (as +determined by pwd(1)) matches the regex given by the configuration file +option B<DEVSCRIPTS_CHECK_DIRNAME_REGEX> or by the command line option +B<--check-dirname-regex> I<regex>. Here regex is a Perl regex (see +perlre(3perl)), which will be anchored at the beginning and the end. If regex +contains a B</>, then it must match the full directory path. If not, then +it must match the full directory name. If regex contains the string I<package>, +this will be replaced by the source package name, as determined from the +F<debian/changelog>. The default value for the regex is: I<package>B<(-.+)?>, thus matching +directory names such as I<package> and I<package>-I<version>. + +=head1 HISTORY AND UPGRADING + +This section briefly describes the backwards-incompatible F<watch> file features +which have been added in each F<watch> file version, and the first version of the +B<devscripts> package which understood them. + +=over + +=item Pre-version 2 + +The F<watch> file syntax was significantly different in those days. Don't use it. +If you are upgrading from a pre-version 2 F<watch> file, you are advised to read +this manpage and to start from scratch. + +=item Version 2 + +B<devscripts> version 2.6.90: The first incarnation of the current style of +F<watch> files. + +=item Version 3 + +B<devscripts> version 2.8.12: Introduced the following: correct handling of +regex special characters in the path part, directory/path pattern matching, +version number in several parts, version number mangling. Later versions +have also introduced URL mangling. + +If you are upgrading from version 2, the key incompatibility is if you have +multiple groups in the pattern part; whereas only the first one would be used +in version 2, they will all be used in version 3. To avoid this behavior, +change the non-version-number groups to be B<(?:> I< ...> B<)> instead of a +plain B<(> I< ... > B<)> group. + +B<uscan> invokes the custom I<script> as "I<script> B<--upstream-version> +I<version> B<../>I<spkg>B<_>I<version>B<.orig.tar.gz>". + +B<uscan> invokes the standard B<uupdate> as "B<uupdate> B<--no-symlink +--upstream-version> I<version> B<../>I<spkg>B<_>I<version>B<.orig.tar.gz>". + +=item Version 4 + +B<uscan> invokes the custom I<script> as "I<script> B<--upstream-version> +I<version>". + +B<uscan> invokes the standard B<uupdate> as "B<uupdate> B<--find> +B<--upstream-version> I<version>". + +=back + +=head1 SEE ALSO + +dpkg(1), mk-origtargz(1), perlre(1), uupdate(1), devscripts.conf(5) + +=head1 AUTHOR + +The original version of uscan was written by Christoph Lameter +<[email protected]>. Significant improvements, changes and bugfixes were +made by Julian Gilbey <[email protected]>. HTTP support was added by Piotr +Roszatycki <[email protected]>. The program was rewritten in Perl by Julian +Gilbey. + +=cut + use 5.010; # defined-or (//) use strict; use warnings; @@ -681,54 +1945,7 @@ exit ($found ? 0 : 1); # greatest version number (as determined by the (...) group), using the # Debian version number comparison algorithm described below. # -# watch_version=3: -# -# Correct handling of regex special characters in the path part: -# ftp://ftp.worldforge.org/pub/worldforge/libs/Atlas-C++/transitional/Atlas-C\+\+-(.+)\.tar\.gz -# -# Directory pattern matching: -# ftp://ftp.nessus.org/pub/nessus/nessus-([\d\.]+)/src/nessus-core-([\d\.]+)\.tar\.gz -# -# The pattern in each part may contain several (...) groups and -# the version number is determined by joining all groups together -# using "." as separator. For example: -# ftp://site/dir/path/pattern-(\d+)_(\d+)_(\d+)\.tar\.gz -# -# This is another way of handling site with funny version numbers, -# this time using mangling. (Note that multiple groups will be -# concatenated before mangling is performed, and that mangling will -# only be performed on the basename version number, not any path version -# numbers.) -# opts=uversionmangle=s/^/0.0./ \ -# ftp://ftp.ibiblio.org/pub/Linux/ALPHA/wine/development/Wine-(.+)\.tar\.gz -# -# Similarly, the upstream part of the Debian version number can be -# mangled: -# opts=dversionmangle=s/\.dfsg\.\d+$// \ -# http://some.site.org/some/path/foobar-(.+)\.tar\.gz -# -# The versionmangle=... option is a shorthand for saying uversionmangle=... -# and dversionmangle=... and applies to both upstream and Debian versions. -# -# The option filenamemangle can be used to mangle the name under which -# the downloaded file will be saved: -# href="http://foo.bar.org/download/?path=&download=foo-0.1.1.tar.gz"; -# could be handled as: -# opts=filenamemangle=s/.*=(.*)/$1/ \ -# http://foo.bar.org/download/\?path=&download=foo-(.+)\.tar\.gz -# and -# href="http://foo.bar.org/download/?path=&download_version=0.1.1"; -# as: -# opts=filenamemangle=s/.*=(.*)/foo-$1\.tar\.gz/ \ -# http://foo.bar.org/download/\?path=&download_version=(.+) -# -# The option downloadurlmangle can be used to mangle the URL of the file -# to download. This can only be used with http:// URLs. This may be -# necessary if the link given on the webpage needs to be transformed in -# some way into one which will work automatically, for example: -# opts=downloadurlmangle=s/prdownload/download/ \ -# http://developer.berlios.de/project/showfiles.php?group_id=2051 \ -# http://prdownload.berlios.de/softdevice/vdr-softdevice-(.+).tgz +# watch_version=3 and 4: See POD. sub process_watchline ($$$$$$) -- Alioth's /usr/local/bin/git-commit-notice on /srv/git.debian.org/git/collab-maint/devscripts.git _______________________________________________ devscripts-devel mailing list [email protected] http://lists.alioth.debian.org/cgi-bin/mailman/listinfo/devscripts-devel
