2005-12-10

Revision 11 as of 2006-01-03 23:15:45

Clear message

12:00-14:00 EST (17:00-19:00 UTC) (IRC #ubuntu-motu-school)

About Andrew Mitchell:

Andrew is Debian Developer and MOTU since January 2005. Actually to become a Debian Developer (abbrev.: DD) you will start as “Padawan”, so you learn packaging from the ground. To speak of a “Master of the Universe” (abbrev.: MOTU) he is one of our heros in several transitions and merge runs. He knows what he is doing and is always very sensible to do no mistakes in his packages.BR BRHis opinions and views are appreciated all over the MOTUs.

\sh

HELLO

The Channel is now switched to "Moderated" Status...so nobody can write something, only the moderators and operators. I like to welcome all of you to our first lecture about Debian Packaging. Today, Mr. Andrew Mitchell will show you, how to create debian packages without the help of debhelper and cdbs. If you have any questions about it, please query siretart or \sh, we will collect the questions and will raise them towards Mr. Andrew Mitchell. OK..I'll give now the voice to Mr. Andrew Mitchell aka ajmitch.


ajmitch:

Thanks, \sh

Welcome, everyone, to our newly created MOTU school.

What I'll be giving today, is not a packaging howto as such but a walk through creating a debian package without the use of dh_make, debhelper, or cdbs. I have done this example package in those 3 ways to quickly demonstrate the differences, also. We might as well start with looking at an example package which I very quickly prepared yesterday.

On http://ajmitch.dyndns.win.co.nz/debuild/ubuntu/school/scratch/ there are 2 files to be fetched if you want to follow along on your own box. Otherwise, I have the core part on pastebin Smile :) Please fetch the upstream tarball from http://www.southern-storm.com.au/download/treecc-0.3.6.tar.gz rather than from my box Smile :) (Any questions, please ask via \sh or siretart.)

The 2 files to fetch from my system are treecc_0.3.6-0ubuntu1.diff.gz and treecc_0.3.6-0ubuntu1.dsc.

siretart copied the source package to http://tiber.tauware.de/~siretart/treecc/ - might be faster for European and American users.]BR thanks siretart

If you're wanting to unpack this source package, please install dpkg-dev if you haven't done so already.

If haven't fetched the files yet:BR

wget http://www.southern-storm.com.au/download/treecc-0.3.6.tar.gz \
http://ajmitch.dyndns.win.co.nz/debuild/ubuntu/school/scratch/treecc_0.3.6-0ubuntu1.d{sc,iff.gz}

Ok, if you've got those files in a directory now..

dpkg-source -x treecc_0.3.6-0ubuntu1.dsc

In order to unpack them. I'll quickly explain about this after I remember to tell you to rename a file Smile :)

mv treecc-0.3.6.tar.gz treecc_0.3.6.orig.tar.gz

before you try the dpkg-source step Smile :)

A debian (or ubuntu) source package is usually made up of upstream source & changes that we have made. Those changes include packaging metadata which say how the package should be built, scripts to run on installation, etc. We keep the upstream tarball as-is, and the debian changes are kept as a single compressed patch against the upstream source. (Please feel free to send myself or \sh, siretart a msg if you want to interrupt at some point.) The treecc_0.3.6-0ubuntu1.dsc file that was downloaded has the tarball & the diff.gz listed in it, along with the md5sums of them. dpkg-source uses this to apply the patch.

Now if we go into the treecc-0.3.6/ directory that was created, we see a fairly normal unpacked tarball, except that we now have a debian/ directory which contains the relevant packaging info. In the debian/ dir there are 4 main files I want to talk about now.

The changelog file has a list of the changes made, both fixes we've made to upstream source & packaging changes. As I have just done a single revision, I have 1 changelog entry which is not very informative Smile :) The line:

treecc (0.3.6-0ubuntu1) dapper; urgency=low

has some important info. It has the version number, as upstream-debianrevision. It has the distribution (dapper), and the urgency field, which is not used in ubuntu, as far as I'm aware. For ubuntu, we number new packages, or new upstream versions with a debian revision of -0ubuntuX, to avoid clashes with debian in the future. A fix to a package 1.2.3-4 would be 1.2.3-4ubuntu1, BTW. After this line, changes are listed, in the format shown and the changelog entry is closed off by the name, email & date.

Now, onto debian/control. Quoting from the debian policy manual..

  • The debian/control file contains the most vital (and version-independent) information about the source package and about the binary packages it creates.

    The first paragraph of the control file contains information about the source package in general. The subsequent sets each describe a binary package that the source tree builds.

In this case, we build 1 binary package, so there's only 2 paragraphs of info (source+binary). dh_make would kindly fill this out for you from a template. (BTW we accept questions at any time Wink ;) )

Debian policy is a very good reference for what we need, but it is not intended as a HOWTO.

\sh

and we are answering them directly...

http://www.us.debian.org/doc/debian-policy/ch-controlfields.html#s-sourcecontrolfiles has the relevant info about what fields are required.

A question about finding what to put in the Build-Depends field - much of that is done by reading what the package needs in its README, configure output, etc.

SWAT

what does the ${shlibs:Depends} stand for?

ajmitch will work through the fields & explain them :)

I'll go through the source package fields first.. & I'll do a bit of quoting from the policy document to explain. Smile :)

  • Source: This field identifies the source package name. Probably one of the easiest for us to fill in.

  • Section: This is the debian section that the package comes under. There's a list in debian policy, or we'd look at a similar package to see what section it is in.

  • Priority: is used to sort the archive into varying priorities, such as required, standard, optional. It's mainly used in debian & in main, as most of universe would be optional or extra.

  • Maintainer: This is the name & email address of the person who created or looks after the package. We generally don't change this in ubuntu if we're making fixes to a debian package but a new package, we set our name & email here.

  • Build-Depends: came up earlier - it's a list of packages that are required to build this from source. the exception is build-essential, which is assumed to be installed when building any package. For this package, I read the README file & checked what configure needed in order to build properly.

  • Standards-Version: This is the version of debian policy that the package conforms to - there's a list of changes, but it's expected that we follow the latest. the latest is 3.6.2.1, but the .1 is for editorial changes, so it can be left off in this file.

Now... onto the binary sections Smile :)

ajmitch will have to try & speed this along

Feedback is welcome to tell us if this is going too slow, too fast, etc.

retrix

how do you find out what the latest standards version is?

aha

dpkg -l debian-policy

gives you the version of the installed policy package debian-policy is also available online, from http://www.debian.org/doc/debian-policy/

ok, onwards..

  • Package: this gives the name of the *binary* package that gets created.

  • The Architecture: field indicates what arches the packages should build on. It's common to specify all, for a package that is architecture-independent, eg python code or any, for a package that compiles on any architecture.

  • The Depends: field gives info about what binary packages this one will depend on when installing - what it needs to run, rather than what it needs to compile.BRBR${shlibs:Depends} gets replaced when the package is built to give info about what libraries it needs.

  • The Description: field is 2 parts - a short, 1 line description which doesn't need to be a full sentence and a paragraph or so of text about what it is.

A question about "architecture: any" vs. "architecture: all"

Packages that are "arch: all" get built once, and work on all architectures - they are usually data files, python code, shell scripts, etc. "arch: any" gets compiled for any arch - you could list i386 amd64 powerpc instead to limit it to these archs.

ajmitch would like to move onto the big debian/rules if there are no objections, since this is taking a little longer than I expected :)

siretart hasn't received any question yet, feel free to ask anything which you think that might be noteworthy

debian/rules is the main file that controls how everything gets built - it is a makefile, with specific required make targets. As an example, I have the same package done 3 ways (debhelper, cdbs, without helper programs) to compare. Smile :)

170 lines for this debian/rulesBR61 lines with debhelperBRand 12 with cdbs

You can probably tell that this way is more verbose & more complex Smile :)

Again, from debian policy..

  • This file must be an executable makefile, and contains the package-specific recipes for compiling the package and building binary package(s) from the source.

    It must start with the line "#!/usr/bin/make -f</tt>", so that it can be invoked by saying its name rather than invoking make explicitly.

    Since an interactive debian/rules script makes it impossible to auto-compile that package and also makes it hard for other people to reproduce the same binary package, all required targets MUST be non-interactive. At a minimum, required targets are the ones called by dpkg-buildpackage, namely, clean, binary, binary-arch, binary-indep, and build. It also follows that any target that these targets depend on must also be non-interactive.

Basically, it says that we need these few makefile targets, and they can't ask the builder anything since everything uploaded in ubuntu gets built on a build daemon, unattended.

We might as well look at the debian/rules now.