2005-12-10

Differences between revisions 12 and 13
Revision 12 as of 2006-01-03 23:17:18
Size: 13366
Editor: pchb1f
Comment:
Revision 13 as of 2006-01-03 23:17:56
Size: 13365
Editor: pchb1f
Comment:
Deletions are marked like this. Additions are marked like this.
Line 161: Line 161:
||<LaserJock> do you have to have the stamps?|| ||LaserJock||do you have to have the stamps?||

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.

Firstly, I started off by setting up some commonly used variables. The DEB_BUILD_OPTIONS environment variable can control some aspects of building, often for things like not stripping a binary. Some small macros are defined to check that we are in the right directory & have uid 0. fakeroot is often used to fake the existence of uid 0 when building, since packages can & should be built as a user. DESTDIR is important, as it's an option passed to make to tell it where to relocate the installed files to when running make install. So it's used throughout, in the other directory variables.

We have listed 2 stamp rules, which are used to avoid repetition. make was originally meant for building plain source, so it needs some files to be created to avoid running targets again.

  • The configure-stamp: target is what contains the call to configure. In this case, we're not passing many configure options, but some packages do take quite a few, which can be put in here.

  • The build-stamp: target has configure-stamp after it, to indicate that it needs configure-stamp to run first, before building. It first checks that we're in the right directory, and runs make. The debian rules section is what is required by debian policy.

  • build: just depends on build-stamp, and does nothing more - if build-stamp was run it won't repeat it.

  • The clean: target gets rid of everything, and restores things to a (relatively) pristine state. if patches had been applied, they would be unapplied here. stamp files are removed, and make distclean is run to get rid of the build output.

  • binary-indep: is another fairly empty rule, which just depends on build. If this package was Architecture: all, we'd be doing a lot more in here.

ajmitch now has a few lines to give options to install, to avoid typing them over & over later on

The binary-arch: target is now where we do most of the actual packaging of the files which is why I've commented this one the most. Smile :)

If there are any questions up till now, please ask

We have a question: "How if the distclean rule from the source Makefile doesn't clean properly the source? Is there a way to restore it in the clean: rule?"

If distclean doesn't properly clean things, then often we resort to just using rm in the clean: rule. Upstream authors often don't have perfect makefiles that clean things. Smile :) If distclean fails (eg the makefile doesn't exist yet), then it will still continue.

LaserJock

do you have to have the stamps?

MOTU/School/2005-12-10 (last edited 2008-08-06 16:24:21 by localhost)