Experiences in the community

Just another WordPress.com weblog

The debian/watch file.

Hi all,
This would be a sort of longish blog post which attempts to share what the debian/watch file is and how it’s important in the debian ecosystem.

If you have looked at my 31st March 2015’s blog post you can see that I have mentioned the deb-src files in /etc/apt/sources.list as they make it easier to know how the binary came to you and what patches were applied to it and the whole process.

To understand the debian/watch file let’s download a source package and see what we find.


─[shirish@debian]
└─[$] mkdir leafpad

─[shirish@debian]
└─[$] cd leafpad

┌─[shirish@debian] - [~/leafpad]
└─[$]apt-get source leafpad

Reading package lists... Done
Building dependency tree
Reading state information... Done
NOTICE: 'leafpad' packaging is maintained in the 'Git' version control system at:
git://anonscm.debian.org/collab-maint/leafpad.git
Need to get 300 kB of source archives.
Get:1 http://httpredir.debian.org//debian/ jessie/main leafpad 0.8.18.1-4 (dsc) [1,932 B]
Get:2 http://httpredir.debian.org//debian/ jessie/main leafpad 0.8.18.1-4 (tar) [289 kB]
Get:3 http://httpredir.debian.org//debian/ jessie/main leafpad 0.8.18.1-4 (diff) [8,784 B]
Fetched 300 kB in 17s (16.7 kB/s)
dpkg-source: info: extracting leafpad in leafpad-0.8.18.1
dpkg-source: info: unpacking leafpad_0.8.18.1.orig.tar.gz
dpkg-source: info: unpacking leafpad_0.8.18.1-4.debian.tar.gz
dpkg-source: info: applying 20-format-spec.patch

The above is pretty simple. Made a directory where I wanted to download the source package and downloaded it. As can be seen there is just one single patch which Debian holds in it. I choose leafpad as it is one of the cheapest and tiniest binary I could find and do use that application daily.

So, with that let’s look how the source package files and directories look like :-

┌─[shirish@debian] - [~/leafpad]
└─[$] ll -h

total 304K
drwxr-xr-x 7 shirish shirish 4.0K May 15 03:56 leafpad-0.8.18.1
-rw-r--r-- 1 shirish shirish 8.6K Oct 13 2013 leafpad_0.8.18.1-4.debian.tar.gz
-rw-r--r-- 1 shirish shirish 1.9K Oct 13 2013 leafpad_0.8.18.1-4.dsc
-rw-r--r-- 1 shirish shirish 283K Sep 26 2011 leafpad_0.8.18.1.orig.tar.gz

┌─[shirish@debian] - [~/leafpad]
└─[$] cd leafpad-0.8.18.1
┌─[shirish@debian] - [~/leafpad/leafpad-0.8.18.1]
└─[$] [$] ll -h

total 720K
-rw-r--r-- 1 shirish shirish 75K Aug 30 2009 ABOUT-NLS
-rw-r--r-- 1 shirish shirish 65K Dec 23 2010 aclocal.m4
-rw-r--r-- 1 shirish shirish 37 Apr 28 2005 AUTHORS
-rw-r--r-- 1 shirish shirish 8.6K Dec 23 2010 ChangeLog
-rw-r--r-- 1 shirish shirish 3.7K Oct 30 2009 compile
-rw-r--r-- 1 shirish shirish 45K Jul 24 2009 config.guess
-rw-r--r-- 1 shirish shirish 2.3K Dec 23 2010 config.h.in
-rw-r--r-- 1 shirish shirish 34K Jul 24 2009 config.sub
-rwxr-xr-x 1 shirish shirish 230K Dec 23 2010 configure
-rw-r--r-- 1 shirish shirish 1.5K Dec 23 2010 configure.ac
-rw-r--r-- 1 shirish shirish 18K Oct 27 2009 COPYING
drwxr-xr-x 3 shirish shirish 4.0K Dec 23 2010 data
drwxr-xr-x 4 shirish shirish 4.0K Oct 12 2013 debian
-rw-r--r-- 1 shirish shirish 18K Oct 30 2009 depcomp
-rw-r--r-- 1 shirish shirish 9.3K Oct 30 2009 INSTALL
-rw-r--r-- 1 shirish shirish 14K Oct 30 2009 install-sh
-rw-r--r-- 1 shirish shirish 23K Oct 28 2009 intltool-extract.in
-rw-r--r-- 1 shirish shirish 39K Oct 28 2009 intltool-merge.in
-rw-r--r-- 1 shirish shirish 31K Oct 28 2009 intltool-update.in
-rw-r--r-- 1 shirish shirish 96 Oct 27 2009 Makefile.am
-rw-r--r-- 1 shirish shirish 22K Dec 23 2010 Makefile.in
-rw-r--r-- 1 shirish shirish 11K Oct 30 2009 missing
-rw-r--r-- 1 shirish shirish 3.5K Oct 30 2009 mkinstalldirs
-rw-r--r-- 1 shirish shirish 22 Apr 28 2005 NEWS
drwxr-xr-x 2 shirish shirish 4.0K Dec 23 2010 po
-rw-r--r-- 1 shirish shirish 2.2K Dec 18 2008 README
drwxr-xr-x 2 shirish shirish 4.0K May 15 03:56 src

The above is also easily understood. You see the different files and directories in the first step, as can be seen there is only one directory went to that directory and see what is in it.

The listing above shares what the contents of the sub-directory are.As can be seen, there are only four directories listed therein, data, debian, po and src. The directory we want to see is the debian directory.

┌─[shirish@debian] - [~/leafpad/leafpad-0.8.18.1/debian]
└─[$] ll -h

total 80K
-rw-r--r-- 1 shirish shirish 14K Oct 12 2013 changelog
-rw-r--r-- 1 shirish shirish 32 Oct 12 2013 clean
-rw-r--r-- 1 shirish shirish 2 Oct 12 2013 compat
-rw-r--r-- 1 shirish shirish 720 Oct 12 2013 control
-rw-r--r-- 1 shirish shirish 2.6K Oct 12 2013 copyright
-rw-r--r-- 1 shirish shirish 20 Oct 12 2013 docs
-rw-r--r-- 1 shirish shirish 2.7K Oct 12 2013 leafpad.1.pod
-rw-r--r-- 1 shirish shirish 7 Oct 12 2013 leafpad.docs
-rw-r--r-- 1 shirish shirish 11 Oct 12 2013 leafpad.manpages
-rw-r--r-- 1 shirish shirish 193 Oct 12 2013 menu
drwxr-xr-x 2 shirish shirish 4.0K Oct 12 2013 patches
-rw-r--r-- 1 shirish shirish 1.8K Oct 12 2013 pod2man.mk
-rw-r--r-- 1 shirish shirish 365 Oct 12 2013 postinst
-rw-r--r-- 1 shirish shirish 237 Oct 12 2013 prerm
-rwxr-xr-x 1 shirish shirish 1.1K Oct 12 2013 rules
drwxr-xr-x 2 shirish shirish 4.0K Oct 12 2013 source
-rw-r--r-- 1 shirish shirish 76 Oct 12 2013 watch

So, as can be seen there is a watch file. Let’s see what the contents of the watch file are.

┌─[shirish@debian] - [~/leafpad/leafpad-0.8.18.1/debian]
└─[$] cat watch

version=3
http://savannah.nongnu.org/download/leafpad/leafpad-(.*)\.tar\.gz

It’s not a big file at all, in fact it’s a single file with just 2 lines in it. The first line is saying something about the version of the watch file, the second line however tells us where new releases of leafpad are made, upstream and gives some idea as to in which form the source package is shared, in the above case they are .tar.gz with some sort of numbering between it and the package to keep track of.

Now let’s see what that watch file can tell us :-

┌─[shirish@debian] - [~/leafpad/leafpad-0.8.18.1]
└─[$] uscan --no-symlink --verbose --no-download

-- Scanning for watchfiles in .
-- Found watchfile in ./debian
-- In debian/watch, processing watchfile line:
http://savannah.nongnu.org/download/leafpad/leafpad-(.*)\.tar\.gz
-- Found the following matching hrefs:
leafpad-0.7.6.tar.gz (0.7.6)
leafpad-0.7.6.tar.gz (0.7.6)
leafpad-0.7.7.tar.gz (0.7.7)
leafpad-0.7.7.tar.gz (0.7.7)
leafpad-0.7.8.tar.gz (0.7.8)
leafpad-0.7.8.tar.gz (0.7.8)
leafpad-0.7.9.tar.gz (0.7.9)
leafpad-0.7.9.tar.gz (0.7.9)
leafpad-0.8.0.tar.gz (0.8.0)
leafpad-0.8.0.tar.gz (0.8.0)
leafpad-0.8.1.tar.gz (0.8.1)
leafpad-0.8.1.tar.gz (0.8.1)
leafpad-0.8.2.tar.gz (0.8.2)
leafpad-0.8.2.tar.gz (0.8.2)
leafpad-0.8.3.tar.gz (0.8.3)
leafpad-0.8.3.tar.gz (0.8.3)
leafpad-0.8.4.tar.gz (0.8.4)
leafpad-0.8.4.tar.gz (0.8.4)
leafpad-0.8.5.tar.gz (0.8.5)
leafpad-0.8.5.tar.gz (0.8.5)
leafpad-0.8.6.tar.gz (0.8.6)
leafpad-0.8.6.tar.gz (0.8.6)
leafpad-0.8.7.tar.gz (0.8.7)
leafpad-0.8.7.tar.gz (0.8.7)
leafpad-0.8.8.tar.gz (0.8.8)
leafpad-0.8.8.tar.gz (0.8.8)
leafpad-0.8.9.tar.gz (0.8.9)
leafpad-0.8.9.tar.gz (0.8.9)
leafpad-0.8.10.tar.gz (0.8.10)
leafpad-0.8.10.tar.gz (0.8.10)
leafpad-0.8.11.tar.gz (0.8.11)
leafpad-0.8.11.tar.gz (0.8.11)
leafpad-0.8.12.tar.gz (0.8.12)
leafpad-0.8.12.tar.gz (0.8.12)
leafpad-0.8.13.tar.gz (0.8.13)
leafpad-0.8.13.tar.gz (0.8.13)
leafpad-0.8.14.tar.gz (0.8.14)
leafpad-0.8.14.tar.gz (0.8.14)
leafpad-0.8.15.tar.gz (0.8.15)
leafpad-0.8.15.tar.gz (0.8.15)
leafpad-0.8.16.tar.gz (0.8.16)
leafpad-0.8.16.tar.gz (0.8.16)
leafpad-0.8.17.tar.gz (0.8.17)
leafpad-0.8.17.tar.gz (0.8.17)
leafpad-0.8.18.1.tar.gz (0.8.18.1)
leafpad-0.8.18.1.tar.gz (0.8.18.1)
leafpad-0.8.18.tar.gz (0.8.18)
leafpad-0.8.18.tar.gz (0.8.18)
D000001: cmpversions a='1:0.8.18.1-0' b='1:0.8.18.1-0' r=0
Newest version on remote site is 0.8.18.1, local version is 0.8.18.1
=> Package is up to date
-- Scan finished

Let’s see what we accomplished here. As the manpage of uscan tells us the utility is used to scan upstream sources for new releases of software. uscan is part of devscripts package. While the manpage of uscan is exhaustive/extensive I would share only those options which I have used here :-

--no-symlink - Do not call mk-origtargz.
--verbose - Give verbose output.
--report, --no-download - Only report about available newer versions but do not download anything

As we are not packaging anything but simply looking to see if a new version of my favourite package has arrived the above options were chosen. As can be seen by using verbose output it lists all the versions which are available there and even compares them to see if there is a newer one. The --no-download switch prevents it from downloading anything hence saving bandwidth.

Now, why this is important is because otherwise the Debian maintainer/Debian Developer have to trawl upstream every few days to see if a new version has come. That would take some of the precious time away which could be spent on doing something more fruitful. What is not known to people is that probably a significant point in time maybe used by the Debian Maintainer/Debian Developer to see if the package is fit to be released or not. There may be issues with the source package or some sub-feature may be lost or something. It really depends on the DM/DD as to how much a DM/DD care for that package.

In short though, the tool helps people in saving time and having knowledge. It will fail only if upstream changes the home. The only con I see is there doesn’t seem to be a way if suddenly there are no new releases or upstream changes its place. The only hint would be that most probably the output would be mangled up in some way. In either case, it does tell how important the debian/watch in the grander scheme of things.

To find more, look at debian/watch on Debian wiki and the uscan manpage. Both have same/similar content but would also make it easier the concept and relationships easier as well.

Single Post Navigation

Leave a Reply

Fill in your details below or click an icon to log in:

WordPress.com Logo

You are commenting using your WordPress.com account. Log Out / Change )

Twitter picture

You are commenting using your Twitter account. Log Out / Change )

Facebook photo

You are commenting using your Facebook account. Log Out / Change )

Google+ photo

You are commenting using your Google+ account. Log Out / Change )

Connecting to %s

%d bloggers like this: