packaging 101@UDW

Ubuntu Developer
Week is going on right now and Daniel Holbach kicked it off with a
packaging 101, which i was attending at #ubuntu-classroom. I started to write
this entry as he conducts the session. Here is the rephrased version of the
live session, and if any important bits are omitted, please leave a comment to
poke me.

Dholbach started off with walking us through the bare-bone structure of a
source package (OT the .deb files/binary packages)>, the stuff that makes a
package build and what one will encounter in almost all packages. Some links he
gave:

Next, he asked folks to download a small sample package (devscripts
package), which contains the tools needed for packaging. Then, used (dget
http://daniel.holba.ch/motu/hello-debhelper_2.2-2.dsc
,command) to get the source package and saw a little about version's between
Debian and Ubuntu, how ubuntu names the repackaged package from debian and
pushes it upstream if any changes have been made and so on.

The orig.tar.gz is the original unmodified source code tarball that was
released on the homepage of the upstream developers (software authors) and
.diff.gz is the compressed patch we apply to make it build "our way" which
means Ubuntu need to add a bunch of instructional files to be able to apply ONE
build process to all kinds of source packages (no matter if they are python,
PHP, C, C++, etc), which applies to most of the packages that use the auto
tools (automake, autoconf, etc)

Running "dpkg-source -x hello-debhelper_2.2-2.dsc " command, extracts the
tarball and apply the patch while the .dsc file is used to check the md5sum and
so on (it contains a bit of meta-data about the source package).

CHANGELOG

Command : cd hello-debhelper-2.2 Debian/changelog has a very strict format
to adhere to but there's the dch tool in devscripts that makes the task easier
and each upload specifies: the name of the source package, the revision, the
part of Ubuntu (or Debian) it is uploaded too, the changelog entry text itself
and who made the particular upload, timestamp, etc... VERSION Looking at the
topmost entry the upload has the revision number 2.2-2 and was uploaded to
"unstable". The 2.2 (the part in front of the dash) means: this is the upstream
release that was packaged.

Example : the hello-debhelper_2.2.orig.tar.gz which basically said: these
are the unmodified changes that upstream released as 2.2 on their homepage. If
you change a tiny bit in the package, upload 2.2-2ubuntu1, which means :

- 2.2 was released upstream,

- 2 revisions have been made in Debian,

- 1 in Ubuntu,

Then if Ubuntu packager forward the changes to the Debian maintainer, it
will be incorporated in 2.2-3 to "sync" the package from Debian again.

Beware, "resetting the counter" in Ubuntu would mean "overwriting all Ubuntu
changes with the changes that have happened in Debian" which is risky as one
could drop other small bits that were important to Ubuntu users and might be a
regression. In some cases where Ubuntu is not able to sync straight-away
(different opinions of maintainers, upstream, etc) Ubuntu devels
merge the changes.

Some version strings like "2:1.0~rc2-0ubuntu13" , where the "2:" is called
"an epoch" and it allows you to use a lower version number again which the
common use-case for reverting to an older version of the package.

Example : you maintain the package frobnicator in Ubuntu and shipped the
safe but boring 2.0.0 version in hardy (say 2.0.0-0ubuntu1) but in intrepid you
decide to update to 2.1.87 because the set of features sounds cool. This would
change to 2.1.87-0ubuntu1 in intrepid but after getting lots and lots of bug
reports from users that your software is broken you decide to go back to 2.0.0
again. Then you ship 1:2.0.0-0ubuntu1 in intrepid release and everybody would
be happy again.

To summarize, the epoch should be used when upstream changes the versioning
scheme and the epoch is also another way of making sure the version number is
always increasing. Epochs are a nice feature, they just come with the problem
that if Ubuntu decide to introduce one and the respective Debian maintainer
decides to NOT use one, its a problem since new Debian revisions will always be
smaller than ubuntu and we cannot "sync" any more.

DistroDiff: if you take a source from SuSE it would not
work for Debian as the build process is different there.

DEBIAN/CONTROL

Looking at the two stanzas, where first one is about the Source package, the
following one(s) are about binary package(s). A source package needs a name, a
section and a maintainer and Standards-Version gives us the clue which version
of the Debian Policy (THE document to know about packaging rules) the package
complies with in testing other bit: Build-Depends

BUILD_DEPENDS

Build-Depends, the bare min reqd to build packages and he explained how to
extract the package, copy it into a minimal build environment (chroot
containing build-essential which gives make, etc) and then install the
build-depends.

He illustrated it with an Example : If dholbach uploaded a revision to the
build daemons (soyuz), upstream will extract the package (just like Ubuntu
did), copy it into a minimal build environment (chroot containing
build-essential which gives make, etc), then install the build-depends. Having
described the resulting binary packages (all files that are going to be
installed into the package go into one package) he pointed out those with which
have a package name and description (that turns up in synaptic, adept, etc) and
has Architechture and Depends

Command: apt-cache show hello-debhelper | grep ^Depends

will return a "Depends: libc6 (= 2.5-0ubuntu1)" which means the
hello-debhelper package that is in the archive needs libc6 to be installed. The
build process will figure out which shared libraries the binaries (stuff in
/usr/bin/ or /usr/lib/ etc) in our package are linked against and which package
they are in. Dependencies anyone ???

COPYLEFT

Running out of time he moved on to copyrights and mentioned that
debian/copyright is another critical part of the packaging process. Its
critical for different reasons as it has little to do with the actual build
process, but it makes sure each packager reflects all the copyright holders,
copyrights and upstream authors in the package.

At times, there is proprietary content that can't be shipped because of
licenses that forbid any changes. but one that must be paid close attention to
(when you create a package from scratch) the source tarball which should ship
the verbatim license texts all itself and you need to reiterate this.

DEBIAN-RULES

Command : #!/usr/bin/make -f

This was the last part of the puzzle : it's a Makefile. If one has worked
with makefiles, its easy to build targets called clean, install, build,
binary-indep, binary-arch and so on. On those targets the upstream build system
is "wrapped", ./configure is called, make is called, etc ...with different
prefixes and in 'special' places. The dh_* scripts are all part of debhelper
(remember, it's the package that is build-depended on), contains a huge set of
very handy helpers to make common tasks like "install this .desktop file and
register it in the right place" or "put this changelog in the right place and
pretty please compress it" very very easy.

To avoid getting a piece of the source package all wrong, he recommended to
start working on existing packages, fix small bugs first before moving on to
other things.

Links : https://wiki.ubuntu.com/MOTU/GettingStarted for all the
documentation and you can join #ubuntu-motu if you ever have any questions
about packaging. After a lot of hugging JorgeCastro started his talk on
"Upstream Bug Linkages" but that interesting topic belongs to another post.