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).
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, 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 ???
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.
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.