You are on page 1of 18

IntroDebianPackaging - Debian Wiki


Translation(s): English - Español - Italiano - Català - Română

1. Introduction to Debian Packaging 2. Requirements 3. Three central concepts 4. The packaging workflow 5. Conclusions 6. Questions and Answers 7. See also

Introduction to Debian Packaging
Debian Women IRC Training Session held by Lars Wirzenius on the 18th November 2010, with a couple of small, clearly marked additions by Sebastian Tennant (following my crash course in Debian packaging by Daniel Baumann at DebCamp 2011, Banja Luka)

This is an introductory tutorial for making Debian packages: it doesn't get very deep into the more intricate bits of Debian packaging, but it will show how to make Debian packages for software that is simple to package. For this purpose, it will be used only the dh command from debhelper 7.

In this tutorial it is assumed that: you understand installation of binary packages; you understand general command line use, and editing of text files using an editor of your choice ( DebianPkg: emacs, DebianPkg: vim, DebianPkg: gedit, DebianPkg: kate, etc.);

1 de 18

23-08-2011 11:41

When you have the upstream tarball.IntroDebianPackaging . in its simplest form. A patch file.dsc ending).gz ending. The packaging workflow The packaging workflow is usually like this: 1. 2. The tarball is exactly what Debian takes and builds a package out of. This has a . unpack the upstream tarball 2 de 18 23-08-2011 11:41 . with any changes made to upstream source. This sounds a bit more complicated than is necessary. It's also easier to keep track of what has been necessary to change for Debian. which lists the other two files. source package and binary package.diff. The upstream developer will make a release of his software and the concrete result of that is the "upstream source archive file" or tarball.tgz file upstream makes (tarball is a bit of computer jargon). 3. Most people package software that someone else has written: this someone else is called the upstream developer. at first sight: it would be simpler to just have everything in one file. it turns out that it saves a lot of disk space and bandwidth to keep the upstream tarball separate from any Debian specific changes. The upstream tarball. rename the upstream tarball to follow a specific naming pattern 2. A tarball is the . A description file (with .gz or Technical requirements: DebianPkg: build-essential DebianPkg: devscripts DebianPkg: debhelper version 7 Three central concepts The three central concepts are upstream tarball. plus all the files created for the Debian package. of three files: 1. from this you can then build the Debian binary package which is what actually get installed.Debian Wiki http://wiki. renamed to follow a systematic pattern.tar. the next step is to make the Debian source package. The source package consists. However.

followed by . and make any other necessary changes 4. then you should use that. not an underscore. upload the source and binary packages to Debian For this tutorial Lars has used this tarball. digits. and can contain letters.tar. upstream has wisely picked a suitable name. Otherwise. # mv hithere-1. "hithere". and dashes.orig. in between) so ideally the upstream tarball will unpack into a directory called "hithere-1.0. Step 1: rename the tarball The Debian packaging tools assume the upstream tarball has a very specific name. the sources should go into a directory named after the source package name and upstream version (with a hyphen.gz Step 2: unpack the tarball In general. The name consists of the source package name.0. We should end up with a file called hithere_1.gz hithere_1. so there's no need to worry about it. add the Debian packaging files (in a subdirectory called debian).debian.gz. 3 de 18 23-08-2011 11:41 .tar.tar. Some other characters are also allowed.tar. The source package name should be all in lower case. build binary package 6.orig. This is important.IntroDebianPackaging .Debian Wiki http://wiki. because the packaging tools are picky. If the upstream developer uses a name that looks like a good Debian source package name. not a dash (-). an underscore.orig. build the source package 5.0. In this case. Note that there is an underscore (_). the upstream version number. change the upstream name as little as possible to make it fit for Debian.0". This is again because the packaging tools are picky. in the 3.

# tar xf hithere_1. we still need to make a changelog entry. This is the log of changes to the Debian package.Debian Wiki http://wiki. they read the version of the package. Let's look at them in order. though it can be helpful to users to summarize those changes. upstream has again been wise and made the tarball unpack into the right subdirectory. debian/changelog has a very particular format.IntroDebianPackaging . urgency=low * Initial release. Most importantly. (Closes: #XXXXXX) 4 de 18 23-08-2011 11:41 . The easiest way to create it is to use the dch tool. # dch --create -v 1. It does not need to list everything that has changed in upstream code.gz Step 3: add Debian packaging files All of these files go into the debian/ subdirectory inside the source tree.0.orig.debian. However.0 # mkdir debian There are a bunch of files we need to provide. # cd hithere-1.0-1 --package hithere This will result in a file like this: hithere (1. Since we are now making the first version. too. because the packaging tools read certain information from the changelog. there is nothing to log.0-1) UNRELEASED.tar. debian/changelog First file is debian/ In this case.

and gives some information about them. Then 1. then the next version of the package will be called 1. We don't need to go into what that means.Lars Wirzenius <liw@liw. and when. The final line in the changelog tells who made this version of the package.0-1 is the version. The 1.) bit. The dch tool tries to guess the name and e-mail address. This is a magic number. The (Closes: #XXXXXX) bit is for closing bugs when the package is uploaded. The -1 part is the Debian version: the first version of the Debian package of upstream version 1. If the Debian package has a bug.0 part is the upstream version. 1.0-3. debian/compat This file should contain the number 7. debian/compat specifies the "compatibility level" for the debhelper -. UNRELEASED means the package is not yet ready to be uploaded. right now.0. such as their names..debian.. It's a good idea to keep the UNRELEASED there so you don't upload by mistake.Debian Wiki http://wiki. See the dch(1) manual page for details. UNRELEASED is called the upload target. who the package 5 de 18 23-08-2011 11:41 .IntroDebianPackaging . It tells the upload tool where the binary package should be uploaded. debian/control The control file describes the source and binary package. but you can configure it with the right details.0-2. but the upstream version remains the> Thu. and so on. and it gets fixed. We can just remove the (Closes. 18 Nov 2010 17:25:32 +0000 A couple of notes: The hithere part MUST be the same as the source package name. Just keep it there. This is the usual way in which bugs are closed in Debian: when the package that fixes the bug is uploaded. the bug tracker notices this and marks the bug as closed. It doesn't matter right now. Do not put any other number in there. Or not. Ignore urgency=low for now.

in debian/control. or if it's not intended to be used on a standard desktop installation. A package should be 'extra' rather than 'optional' if it conflicts with another 'optional' package. ${misc:Depends} Description: greet user hithere greets the user. There are several required fields.e. but you can just treat them as magic. 'standard'. In general a package is 'optional' unless it's 'essential' for a standard functioning system.IntroDebianPackaging . 'important'. Source: hithere Maintainer: Lars Wirzenius <liw@liw. 6 de 18 23-08-2011 11:41 .9. for now.. So. 'optional' or 'extra').3. there are two paragraphs. booting or networking functionality. "Priority:" gives the priority of the package (one of 'required'.Debian Wiki http://wiki.0 Build-Depends: debhelper (>= 7. The first one describes the source package: "Source:" field gives the source package> Section: misc Priority: optional Standards-Version: 3. "Maintainer:" gives the name and e-mail address of the person responsible for the package.debian. and so on. Notable example of 'extra' packages are debugging packages. or the maintainer is. i.8) Package: hithere Architecture: any Depends: ${shlibs:Depends}. (Added by Sebastian Tennant). Below an example of what it might look like.

the code has been written portably.debian. The name might be different from the source package name.IntroDebianPackaging . the ${shlibs:Depends} magic bit needs to be in there. the binary package will still need to be built for each architecture separately. error-prone work. They might or might not be needed to actually use the package. Shell scripts work the same everywhere and not need to be compiled. For example. Actually. armel for ARM processors. To make this work. The "Architecture:" field can contain names of particular architectures. "Build-Depends:" lists the packages that need to be installed to build the package. "Architecture:" tells which computer architectures the binary package is expected to work on: i386 for 32-bit Intel CPUs. without having to be built separately for each.Debian Wiki http://wiki. and so on. so it does not make too many assumptions about the hardware. amd64 for 64-bit. The second paragraph describes the binary package built from this source. Debian works on about a dozen computer architectures in total. "any" (which we see in the example) means that the package can be built for any architecture. so this architecture support is crucial. "all" means that the same binary package will work on all architectures. there can be many binary packages built from the same source. Listing such dependencies manually is tedious. but usually it contains one of two special values. "Depends:" field lists the packages that must be installed for the program in the binary package to work. In other words. a package consisting only of shell scripts would be "all". "Package:" is the binary package name. The shlibs 7 de 18 23-08-2011 11:41 . The {misc:Depends} bit. The other magic stuff is there for debhelper.

the misc magic is for some stuff debhelper does. For Debian. and TAB is what the make command wants debian/rules can actually be quite a complicated file.} magic bits only work in Depends "Description:" is the package description. the dh command in debhelper version 7 has made it possible to keep it this simple in many cases. However. it is not important from a technical point of view. copyright-related information about a package. not by spaces.Debian Wiki http://wiki. and it should contain the version number "1. However. For now. It is meant to be helpful to users. For other dependencies. this file is used to keep track of the legal.IntroDebianPackaging . We can get back to debian/copyright later. The file is a makefile.. debian/copyright It is quite an important file. debian/source/format The final file we need is debian/source/ magic is for shared library dependencies. debian/rules It should look like this: #!/usr/bin/make -f %: dh $@ Note: The last line should be indented by one TAB character.0".debian. 8 de 18 23-08-2011 11:41 . you need to add them manually to Depends or Build-Depends and the ${. if there's interest. we'll concentrate on the technical aspects. but for now we will be happy enough with an empty file.

You do your best creating debian/* files.debian.IntroDebianPackaging .0/debian/hithe The upstream Makefile is trying to install the compiled program into the wrong location.0' dh_auto_install: make -j1 install DESTDIR=/home/liw/debian-packaging-tutorial/ make: *** [binary] Error 29 dpkg-buildpackage: error: fakeroot debian/rules binary gave error exit status debuild: fatal error at line 1325: dpkg-buildpackage -rfakeroot -D -us -uc failed Something went wrong. This is what usually happens. but this is the one we'll use. you'll get output similar to this: make[1]: Entering directory `/home/liw/debian-packaging-tutorial/x/hithere-1. Steps 4&5: build the package Now we can build the package. The command to do that is debuild -us -uc There are many commands we could use for this. There's a couple of things going on here: first is a bit about how Debian 9 de 18 23-08-2011 11:41 . So. If you run the command. and even though it happens to be the same as the upstream version.Debian Wiki http://wiki. but there's always something that you don't get This is the version number for the format of the source package. that is just a co-incidence.0 install hithere /home/liw/debian-packaging-tutorial/x/hithere-1. the thing that went wrong is this bit: install hithere /home/liw/debian-packaging-tutorial/x/hithere-1.0/debian/hithe install: cannot create regular file `/home/liw/debian-packaging-tutorial/x/hit make[1]: *** [install] Error 1 make[1]: Leaving directory `/home/liw/debian-packaging-tutorial/x/hithere-1.

So the . For now. #!/usr/bin/make -f %: dh $@ override_dh_auto_install: $(MAKE) DESTDIR=$$(pwd)/debian/hithere prefix=/usr install It's again a bit of magic. as usual. I'll summarize by saying that there's a command debhelper runs that takes care of installing the upstream packaging works. The right way to fix this is to change debian/rules so that it tells the Makefile where to install things.IntroDebianPackaging . We need to override this stage. and to understand it you'll need to know how Makefiles work. 10 de 18 23-08-2011 11:41 . and this stage is called dh_auto_install. When program has been built. and then we put that into the binary package. and we do that with a rule in debian/rules called override_dh_auto_install.. except that it should not be installing it under usr/local. We create a subset of the whole filesystem under debian/hithere. and the various stages of a debhelper run../debian/hithere /usr/local/bin bit is fine. but directly under usr.debian. The final line in the new debian/rules is a bit of 1970s technology to invoke the upstream Makefile from debian/rules with the right arguments. but somewhere under the debian/ subdirectory. We need to do something to make it install into the right location (debian/hithere/usr/bin). it does not get installed into /usr or /usr/local.Debian Wiki http://wiki. and is "installed".

but none of them look like they'll be a problem for trying the package.0/debian/hithe We are now trying to install into the right place.0 (current is 3. but in this case the upstream developer was too lazy to do so. but it does not exist. but there's still some small problems. we need to tell the packaging tools to create the directory first.9. this is the failing command: install hithere /home/liw/debian-packaging-tutorial/x/hithere-1. So let's ignore them for now. Now the build succeeds. It reports several for this new package: Now running lintian. W: hithere source: out-of-date-standards-version Let's try to build things again. which checks the package that has been built for some common errors.Debian Wiki http://wiki. Create a file called debian/hithere. These should eventually be fixed. debuild runs the lintian tool..1) W: hithere: copyright-without-copyright-notice W: hithere: new-package-should-close-itp-bug W: hithere: wrong-bug-number-in-closes l3:#XXXXXX Finished running lintian. To fix this. We will need it later. Ideally. debhelper) provide a way to do that. and make it look like this: usr/bin usr/share/man/man1 The second line creates the directory for the manual page. the upstream Makefile would create the directory itself. 11 de 18 23-08-2011 11:41 .debian.9..IntroDebianPackaging .dirs. It still fails! This time. The packaging tools (specifically.

Debian Wiki http://wiki.diff. Virtual machines are a good place to do development..0 hithere_1./ hithere_1.. 12 de 18 23-08-2011 11:41 . Setting up hithere (1..orig./hithere_1.dsc hithere_1.changes hithere_1..0-1_amd64. 154793 files and directories currently installed.deb hithere_1.gz The following command will install the package that you've just built. # sudo dpkg -i . Processing triggers for man-db . # ls .deb) .IntroDebianPackaging . (Reading database .0. it is best to do package development on a computer that is well backed up. Do NOT run it on a computer unless you don't mind breaking it..0-1_amd64./hithere_1..) Unpacking hithere (from .deb [sudo] password for liw: Selecting previously deselected package hithere.deb And here's the output: liw@havelock$ sudo dpkg -i ..0-1_amd64.. In Look in the parent directory to find the package that was built. liw@havelock$ How do we test the package? We can run the command.0-1_amd64..0-1_amd64.tar.debian. and that you don't mind re-installing if everything goes really badly wrong..0-1_amd64..0-1.0-1) . hithere-1.gz hithere_1.

The best tool for that I know of is DebianPkg: reprepro. and debian/copyright is empty.) And. though.. lintian had things to say. you may want to look at the tool called DebianPkg: piuparts. etc.IntroDebianPackaging .org/devel/ web page. 13 de 18 23-08-2011 11:41 . so your package is easy to install. I've never had to do this. but it isn't yet of the high quality that is expected of a Debian package. it's not perfect. We have a package that works. For more testing of your package. Questions and Answers QUESTION: Can I generate a multi-arch package? ANSWER: I don't think Debian supports multi-arch packages.Debian Wiki http://wiki. you'll want to learn about the DebianPkg: quilt tool. (I wrote it originally so it is perfect and never has any bugs.e. finally. i. and just avoid compiling them from source. but I'll cover "Architecture: all" packages later QUESTION: Please clarify about packaging those packages that are already in binary form.debian. you treat the tarball with the bloBs as the source package.debian. Remember. Other things you might want to read are listed on the http://www. if you start making changes to the upstream source. Conclusions Once you've built your own # hithere It works! But. you'll eventually want to learn how to set up your apt repository. nvidia blob or likewise ANSWER: For binary blob packages. yet.. er.

in which case that's too much detail for this session to get it right in all cases. or the "non-maintainer upload" format. It used to be necessary.deb packages in /var/cache/apt/archives are binary packages. but "1.0-1. QUESTION: I can see "official" DEB packages in /var/cache/apt/archives without changelog and compat files. many many years ago.0-1).1" would be an example QUESTION: When is "dpkg-source -x" run? Is it done manually? ANSWER: "dpkg-source -x" is the command to unpack a Debian source package after it has already been built (usually by someone else). the compat file is only in the source package QUESTION: Liw said the the compat file should contain the magic number 7. if necessary. not QUESTION: is there anything like ppa in ubuntu? ANSWER: Debian does not run a PPA service like Ubuntu. it is not usually run when creating the package 14 de 18 23-08-2011 11:41 .0 folder? ANSWER: I think that these days.Debian Wiki http://wiki. you don't need to repack it. Why? ANSWER: the . but all the tools to make apt repositories yourself are there. it's just a lot to configure oneself QUESTION: do we need to repack the original tarball if it doesn't contains a properly named foo-1. I assume this just means as single char files as produced by 'echo 7 >debian/compat' ? ANSWER: yes. a single character 7 is enough to have in debian/compat QUESTION: I've heard of non-maintainer specific format for debian revision numbers ANSWER: I think you mean either the "native package" format (in which the version number would be just 1.IntroDebianPackaging . but now the "dpkg-source -x" command will name the directory the right way.0. the changelog is included in them (under a different name).

Debian Wiki http://wiki. if the PHP script is only used to run a test. but it does not get run while the package is built. then PHP would go into Depends only. and I don't think there is an easy way to do it. Both are usually necessary QUESTION: can I build package for armel from my i386. after being installed. sorry. in what case I have to use only Depends instead of Build-Depends? ANSWER: Build-Depends are needed only during package build. the Maintainer field.IntroDebianPackaging . and it is perfectly ok (from a packaging tool point of view) to have dependencies only in one and not the other. while it is being compiled. and its test suite is being run. As an example. QUESTION: how can one determine the needed packages to be used by Build-Depends? ANSWER: I usually do that by a) trial and error and b) reading the source of the program. but I am not familiar with them. and can i do it easy? ANSWER: that would be cross-compilation. should I write my name in the Uploader field. there are tools for it. QUESTION: what's the difference between Depends and Build Depends. Depends is needed only when the package is actually being used.debian. none ? 15 de 18 23-08-2011 11:41 . it would only be in Build-Depends and not in Depends QUESTION: may I have a Build-Depends that does not have a corresponding Depends? I'm thinking to statical linked libraries ANSWER: Build-Depends and Depends are pretty much entirely separate. Some things might be both build and runtime dependencies. not Build-Depends. and in that case you need to put them into both Build-Depends and Depends. or in both QUESTION: If I want to do a NMU. if a package contains a PHP script. and does not get inclued in the binary package.

but the first line of the changelog should be "Non-maintainer upload" QUESTION: When I build a package with "Architecture: all" field. so a package with a .org/IntroDebianPackaging?action=print ANSWER: (by dapal) none./waf and other tools to build ? ANSWER: I like dapal's answer: <dapal> lilith: using dh7. . what to do with . or cmake or scons or . then there's no point in building it on amd64 QUESTION: that example debian/rules contains only #!make -f .build.. ANSWER: the "Architecture:" field tells whoever is building the package whether there is any point in building the package on a particular computer architecture so if it says i386 only. does heuristics handle those source packages that need . just do something like: override_dh_auto_configure <TAB>dh_auto_configure -. anything else part? ANSWER: dh has a lot of heuristic.changes) still have the build architecture in the name. no need to worry about it QUESTION: Is there another package for source package or its the same of binary package? I will generate and mantain two packages (binary and source)? ANSWER: you edit the source package and then run a command (which I will get to in a bit) to build the binary package out of the source package QUESTION: It's not clear to me if "Architecture" options will make effect over source package (building process) or binary package (install and run).IntroDebianPackaging ./configure script. will usually build without any additions QUESTION: heuristics is good./configure . that is the right behavior. or one of the other common ways of building packages.--yourparams 16 de 18 23-08-2011 11:41 . some of the resulting file (b. Is a right behaviour? ANSWER: yep.debian. if you want to pass something to ./configure. but what if we need to pass --withsomething-special to configure or cmake arguments.Debian Wiki http://wiki.

0 directory.0 or outside? should there be an outer dir called hithere (without number) ANSWER: I always run the packaging commands in the hithere-1. it is pretty easy to use. That's not a really good workflow. once you've read the docs QUESTION: where can we find docs for override stuff of debhelper 7? ANSWER: dh runs a specific sequence of commands to build a package.2. sorry 17 de 18 23-08-2011 11:41 . each command is called dh_something. QUESTION: from where do you usually run your commands? inside the dir hithere-1. and possibly how to use version management with debian packaging. you then have to read the manual page for that command to see if you can configure it (via a file such as debian/hithere. it is just neater. and i usually have a directory above that called hithere but the parent directory is not necessary.12 (so no additional things needed).Debian Wiki http://wiki.IntroDebianPackaging .3-4") and try to build. but bascially: unpack the upstream source to a new directory.4. Can I add it to debian/rules? How? ANSWER: (by gregoa) debhelper supports qmake since 7. but for that you will need to learn quilt. copy the debian/* directory from the old package. I am not sure what is the best workflow for that. or if you need to override it.dirs). so files from different projects don't get mixed up QUESTION: I have a upstream that needs a qmake (uses Qt) before make. update debian/changelog ("dch -v 1. and fix anything that is broken. and each such command can be overridden by having a debian/rules entry called dh has a nice extension/override mechanism that allows you to override particular parts. Add the --no-act option to the dh command in debian/rules to see what commands it runs. and that's too big a topic for this session.debian. before that you needed a override_dh_auto_configure :\n\tqmake QUESTION: what is a good workflow to update a package to a new upstream version? ANSWER: ah.

is there something like a rule what an official package is allowed to do or not? Can such a package get an official package? ANSWER: http://www.debian. like activating network routing in kernel and so is the best written set of rules we have for what an official Debian package is allowed to do. unless that other package provides a documented interface for it See also http://www.IntroDebianPackaging . Debian packages are not allowed to change other package's http://liw.debian. For this it also makes some system critical changes.Debian Wiki http://wiki. or is required to do.debian.. The only thing my package does is actually configure the other packages in a certain way that it fits certain peoples IntroDebianPackaging (editada pela última vez em 2011-07-23 21:21:17 por GuillaumeDelacour) 18 de 18 23-08-2011 11:41 .org/devel/ QUESTION: I have a made debian-package that depends on several other packages.debian..