Differences between revisions 1 and 42 (spanning 41 versions)
Revision 1 as of 2007-08-23 22:06:11
Size: 1126
Comment: Added Nelson's comments into a dedicated page on the debian/watch file
Revision 42 as of 2013-09-26 14:30:12
Size: 5936
Editor: eriberto
Comment:
Deletions are marked like this. Additions are marked like this.
Line 1: Line 1:
This page shall quickly gather Nelson's comments on the file 'watch' in the debian folder. It is used to download upstream's source or to check for the necessity of an update. The download itself will be performed with the uscan program of the devscripts package. #language en
= debian/watch =

The file named 'watch' in the debian directory is used to check for newer versions of upstream software is available and to download it if necessary. The download itself will be performed with the [[DebianMan:1/uscan|uscan]] program from the DebianPkg:devscripts package. It takes the path to the {{{debian}}} directory that uses the {{{watch}}} file as an argument or searches the directories underneath the current working directory.
Line 4: Line 7:
{{{
  version=3
  http://somesite.com/dir/filenamewithversion.tar.gz
}}}
Line 5: Line 12:
To allow the version to remain unspecified, it is expressed as a wildcard using regular expression in Perl format:
{{{
Line 6: Line 15:
  http://somesite.com/dir link_from_href-1.0.tar.gz   http://somesite.com/dir/filename_(.+).tar.gz
}}}
The uscan program will then execute a "dir" command and check all the files in that directory for the highest version number.
Line 8: Line 19:
"http://somesite.com/dir" is the site from where you are downloading
it and "link_from_href.1.0.tar.gz" is obtained from the HTML source
{{{uscan}}} also supports ftp protocol. Unfortunately, when working with http, HTML pages do not always contain directory listing with files. The complete (or relative) path of the .tar.gz file to be downloaded will appear as a hyperlink within the web page. We hence need two types of information, the path to the page announcing the file and a regular expression to grep for the right link:
{{{
  version=3
  http://somesite.com/path link_from_href-1.0.tar.gz
}}}
"{{{http://somesite.com/path}}}" is the site from where you are downloading
the source and "link_from_href.1.0.tar.gz" is obtained from the HTML source
Line 12: Line 28:
If http://somesite.com/dir HTML code has "<a If {{{http://somesite.com/path}}} HTML code has "<a
Line 14: Line 30:

  http://somesite.com/dir foo/program-(.*)\.tar\.gz
{{{
  http://somesite.com/dir foo/program-(.+)\.tar\.gz
}}}
Line 19: Line 35:
Generally you want a slightly more flexible regex for the tarball name so that if upstream switches tarball naming schemes or compression formats you are covered:

{{{
  http://somesite.com/dir foo/program-(.+)\.(?:zip|tgz|tbz|txz|(?:tar\.(?:gz|bz2|xz)))
}}}
Line 20: Line 42:
(man uscan will help you more then me on this). ([[DebianMan:1/uscan|man uscan]] will help you).
Line 23: Line 45:

  uscan --report-status
{{{
  uscan --no-download --verbose
}}}
Line 28: Line 50:
{{{
  uscan --no-download --verbose --debug
}}}
Line 29: Line 54:
  uscan --report-status --debug == Common mistakes ==

 * Not escaping dots, which match any character. The solution is {{{\.}}} instead of {{{.}}} in the regex.
 * A file extension regex that is not flexible enough. The solution is {{{\.(?:zip|tgz|tbz|txz|(?:tar\.(?:gz|bz2|xz)))}}}
 * Not anchoring the version group at the right place. The solution is to include something before {{{(\d\S*)}}} like {{{fooproj-(\d\S*)\.tar\.gz}}}
 * Not starting the version part of the regex with a digit. The solution is to use {{{\d}}} instead of {{{.}}}
 * Not being flexible enough in the path to the file. The solution is to use {{{http://example.com/someproject/ .*/program-(\d\S*)\.tar\.gz}}} instead of {{{http://example.com/someproject/ /path/to/program/downloads/program-(\d\S*)\.tar\.gz}}}
 * Not mangling upstream versions that are alphas, betas or release candidates to make them sort before the final release. The solution is to use uversionmangle like this {{{opts=uversionmangle=s/(\d)[_\.\-\+]?((RC|rc|pre|dev|beta|alpha)\d*)$/$1~$2/}}}
 * Not mangling Debian versions to remove dfsg. The solution is to use dversionmangle like this {{{opts=dversionmangle=s/\+(debian|dfsg|ds|deb)\d*$//}}}


== Common sites ==

Files hosted on various big project hosting sites can be specified with the URLs below. !SourceForge has a special "redirector" URL (see more details in 'man uscan'). This allows the upstream URLs to change without the need to adapt watch files of affected packages.

=== SourceForge ===

{{{
  # 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-(\d\S*)\.(?:zip|tgz|tbz|txz|(?:tar\.(?:gz|bz2|xz)))
}}}
See also: http://anonscm.debian.org/viewvc/qa/trunk/wml/watch/

=== GitHub ===

{{{
opts=filenamemangle=s/.+\/v?(\d\S*)\.tar\.gz/<project>-$1.tar.gz/ \
  https://github.com/<user>/<project>/tags .*/v?(\d\S*)\.tar\.gz
}}}

The 2nd regexp matches most often used tags like '0.1.2' or 'v0.1.2'. It may need to be adapted if upstream uses other version tags. You may also want to use {{{releases}}} instead of {{{tags}}}.

Alternatively, you can use the site http://githubredir.debian.net to get a proposal of the debian/watch file.

=== Google Code ===

{{{
http://code.google.com/p/<project>/downloads/list .*/<project>-(\d\S*)\.(?:zip|tgz|tbz|txz|(?:tar\.(?:gz|bz2|xz)))
}}}

=== Gitorious ===

Gitorious provides a list of tags in the tree visible at `http://gitorious.org/<project>/<repo>/trees/master`. The download link is `http://gitorious.org/<project>/<repo>/archive-tarball/<tag>` so a downloadurlmangle is required to get the download link and then a filenamemangle is required to make a sensible filename for the downloaded file, since uscan doesn't use the filename suggested by the server in the HTTP headers.

{{{
opts=downloadurlmangle=s/trees/archive-tarball/,filenamemangle=s/.*\/(.*)/<package>-$1.tar.gz/ \
  http://gitorious.org/<project>/<repo>/trees/(\d+\.\d+\.\d+)
}}}

As with other examples on this page, adapt the tag regexp to match the style of the tag the project is using.

=== Bitbucket ===

{{{
https://bitbucket.org/<user>/<project>/downloads .*/(\d\S*)\.tar\.gz
}}}

The 2nd regexp matches most often used tags like '0.1.2' or 'v0.1.2'. It may need to be adapted if upstream uses other version tags.


----
CategoryDebianDirectory

debian/watch

The file named 'watch' in the debian directory is used to check for newer versions of upstream software is available and to download it if necessary. The download itself will be performed with the uscan program from the devscripts package. It takes the path to the debian directory that uses the watch file as an argument or searches the directories underneath the current working directory.

Basically a watch file will have this format:

  version=3
  http://somesite.com/dir/filenamewithversion.tar.gz

To allow the version to remain unspecified, it is expressed as a wildcard using regular expression in Perl format:

  version=3
  http://somesite.com/dir/filename_(.+).tar.gz

The uscan program will then execute a "dir" command and check all the files in that directory for the highest version number.

uscan also supports ftp protocol. Unfortunately, when working with http, HTML pages do not always contain directory listing with files. The complete (or relative) path of the .tar.gz file to be downloaded will appear as a hyperlink within the web page. We hence need two types of information, the path to the page announcing the file and a regular expression to grep for the right link:

  version=3
  http://somesite.com/path link_from_href-1.0.tar.gz

"http://somesite.com/path" is the site from where you are downloading the source and "link_from_href.1.0.tar.gz" is obtained from the HTML source code (from the "<a href=" tags).

If http://somesite.com/path HTML code has "<a href=foo/program-1.0.tar.gz>" inside it, for example, you will use

  http://somesite.com/dir foo/program-(.+)\.tar\.gz

Watch files with errors are generally wrong on this second part.

Generally you want a slightly more flexible regex for the tarball name so that if upstream switches tarball naming schemes or compression formats you are covered:

  http://somesite.com/dir foo/program-(.+)\.(?:zip|tgz|tbz|txz|(?:tar\.(?:gz|bz2|xz)))

For FTP sites it changes a little, but it's basically the same thing (man uscan will help you).

But the nice part is to test it:

  uscan --no-download --verbose

If it's not working as expected, you can use debug to see what it's fetching and what it's (not) matching:

  uscan --no-download --verbose --debug

Common mistakes

  • Not escaping dots, which match any character. The solution is \. instead of . in the regex.

  • A file extension regex that is not flexible enough. The solution is \.(?:zip|tgz|tbz|txz|(?:tar\.(?:gz|bz2|xz)))

  • Not anchoring the version group at the right place. The solution is to include something before (\d\S*) like fooproj-(\d\S*)\.tar\.gz

  • Not starting the version part of the regex with a digit. The solution is to use \d instead of .

  • Not being flexible enough in the path to the file. The solution is to use http://example.com/someproject/ .*/program-(\d\S*)\.tar\.gz instead of http://example.com/someproject/ /path/to/program/downloads/program-(\d\S*)\.tar\.gz

  • Not mangling upstream versions that are alphas, betas or release candidates to make them sort before the final release. The solution is to use uversionmangle like this opts=uversionmangle=s/(\d)[_\.\-\+]?((RC|rc|pre|dev|beta|alpha)\d*)$/$1~$2/

  • Not mangling Debian versions to remove dfsg. The solution is to use dversionmangle like this opts=dversionmangle=s/\+(debian|dfsg|ds|deb)\d*$//

Common sites

Files hosted on various big project hosting sites can be specified with the URLs below. SourceForge has a special "redirector" URL (see more details in 'man uscan'). This allows the upstream URLs to change without the need to adapt watch files of affected packages.

SourceForge

  # 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-(\d\S*)\.(?:zip|tgz|tbz|txz|(?:tar\.(?:gz|bz2|xz)))

See also: http://anonscm.debian.org/viewvc/qa/trunk/wml/watch/

GitHub

opts=filenamemangle=s/.+\/v?(\d\S*)\.tar\.gz/<project>-$1.tar.gz/ \
  https://github.com/<user>/<project>/tags .*/v?(\d\S*)\.tar\.gz

The 2nd regexp matches most often used tags like '0.1.2' or 'v0.1.2'. It may need to be adapted if upstream uses other version tags. You may also want to use releases instead of tags.

Alternatively, you can use the site http://githubredir.debian.net to get a proposal of the debian/watch file.

Google Code

http://code.google.com/p/<project>/downloads/list .*/<project>-(\d\S*)\.(?:zip|tgz|tbz|txz|(?:tar\.(?:gz|bz2|xz)))

Gitorious

Gitorious provides a list of tags in the tree visible at http://gitorious.org/<project>/<repo>/trees/master. The download link is http://gitorious.org/<project>/<repo>/archive-tarball/<tag> so a downloadurlmangle is required to get the download link and then a filenamemangle is required to make a sensible filename for the downloaded file, since uscan doesn't use the filename suggested by the server in the HTTP headers.

opts=downloadurlmangle=s/trees/archive-tarball/,filenamemangle=s/.*\/(.*)/<package>-$1.tar.gz/ \
  http://gitorious.org/<project>/<repo>/trees/(\d+\.\d+\.\d+)

As with other examples on this page, adapt the tag regexp to match the style of the tag the project is using.

Bitbucket

https://bitbucket.org/<user>/<project>/downloads .*/(\d\S*)\.tar\.gz

The 2nd regexp matches most often used tags like '0.1.2' or 'v0.1.2'. It may need to be adapted if upstream uses other version tags.


CategoryDebianDirectory