Introduction

Welcome to the Ubuntu Packaging Guide! This guide is primarily addressed to those who would like to make and maintain Ubuntu packages. Although many of the concepts in this guide could be used to make binary packages for personal use, it is designed for those people wanting to distribute their packages to and for others. While it is written with the Ubuntu Linu distribution in mind, it should also be useful for any !ebian"based distribution. There are several reasons you might want to learn how to package for Ubuntu. First, building and fixing Ubuntu packages are great ways to contribute to the Ubuntucommunity. It is also useful for learning how Ubuntu and the applications you have installed work. Maybe you want to install a package that is not in the Ubunturepositories. opefully after you have completed this guide you will have the tools and knowledge you need to do all of these things. !here to "egin If you are completely new to #ebian$based packaging then please read this guide completely, paying special attention to the section called %rere&uisites, and the section "asic %ackaging. %eople who are experienced with #ebian$based packaging will find the section Ubuntu %ackaging most helpful. ere is a basic introduction to debian packages.

%rere&uisites
This guide assumes that the reader has a reasonable knowledge of building and installing software from source on 'inux distributions. The guide also uses the (ommand 'ine Interface )('I* throughout, so you should be comfortable using a terminal. +ou should be able to at least use the following,

make: G#$ %ake is a &ery important software building tool. 't is used to transform a comple compilation task into
a tri&ial one. 't is important that you know how to use it, because we will store most of the information about the packaging process in a %akefile. !ocumentation is a&ailable at the G#$website.

.-configure, This script is included in almost all 'inux source, especially for software written in
compiled languages such as ( and (... It is used to generate a Makefile )file used by make* that is properly configured for your system. /tandard #ebian packaging tools use it, so it is important that you know what the configure script does. Information on .-configure can be found in the make documentation.

0pt-#pkg, "eyond the basic use of installing programs, apt and dpkg have many features that
are useful for packaging.

apt$cache dump $ lists every package in the cache. This command is especially helpful
in combination with a grep pipe such as apt$cache dump 1 grep foo to search for packages whose names or dependencies include foo.

apt$cache policy $ lists the repositories )main-restricted-universe-multiverse* in which a

package exists.

apt$cache show $ displays information about a binary package. apt$cache showsrc $ displays information about a source package. apt$cache rdepends $ shows reverse dependencies for a package )which packages
re&uire the &ueried one.

 dpkg $/ $ lists the binary package to which a particular file belongs. dpkg $l $ lists currently installed packages. This is similar to apt$cache dump but for
installed packages.

dpkg $c $ lists the contents of a binary package. It is useful for ensuring that files are
installed to the right places.

dpkg $f $ shows the control file for a binary package. It is useful for ensuring that the
dependencies are correct.

grep$dctrl $ searches for speciali2ed information in packages. It is a specific use of

the grep package )but not installed by default*.

diff and patch, The diff program can be used to compare two files and to make patches. 0 typical
example might be diff $ru3 file.old file.new 4 file.diff. This command will create a diff )recursively if directories are used* that shows the changes, or delta, between the two files.

The patch program is used to apply a patch )usually created by diff or a similar
program* to a file or directory. To apply the patch created above, we can invoke patch $ p5 6 file.diff. The option $p tellspatch how much it should strip from the paths for the file names in the patch. The option $p5 means to strip nothing, or leave the path intact. 0ll of Ubuntu7s (ode, Translations, %ackages, "ugs, access control lists, team information, etc. live in 'aunchpad. /o for you to be able to contribute to bug discussions, upload packages, contribute code and translations, it7s important that you

(. set up your 'aunchpad profile ). set up your 8%8 key and register it with 'aunchpad *. set up your // key and register it with 'aunchpad
8etting /tarted

"inary and /ource %ackages

Most users of a #ebian$based distribution such as Ubuntu will never have to deal with the actual source code that is used to create all of the applications on their computers. Instead, the source code is compiled into binary packages from the source package that contains both the source code itself and the rules for making the binary package. %ackage maintainers upload the source packages with their changes to the build systems that then compile the binary packages for each architecture. 0 separate system distributes the generated binary .deb files and source changes to the repository mirrors.

%ackaging Tools
There are many tools written specifically for packaging on !ebian"based systems. %any of them are not essential to creating packages but are &ery helpful and often automate repetiti&e tasks. Their man and info pages are good sources of information. +owe&er, the following is a list of packages that are deemed necessary to begin packaging,

 build$essential is a metapackage that depends on libc9$dev, gcc, g.., make, and dpkg$dev.
:ne package that you might not be familiar with is dpkg$dev. It contains tools such as dpkg$ buildpackage and dpkg$source that are used to create, unpack, and build source and binary packages.

devscripts contains many scripts that make the packager7s maintenance work much easier.
/ome of the more commonly used aredebdiff, dch, debuild, and debsign.

ubuntu$dev$tools is also a collection of scripts )like devscripts*, but specific for Ubuntu. It
contains tools like update$maintainer, dgetlp, what$patch, pbuilder$dist, etc.

debhelper are scripts that perform common packaging tasks. dh;make can be used to create a template for your packaging. diff and patch are used to create and apply patches, respectively. They are used extensively
in packaging because it is easier, cleaner, and more efficient to represent small changes as patches rather than to have multiple copies of a file. 3ote, In Ubuntu <5.5= the diffbinary is provided by the diffutils package. The diff package is a dummy transitional package.

cdbs is the (ommon #ebian "uild /ystem. It provides )&uoting from the package description*
a >sane set of default rules upon which packages can build? any or all rules may be overridden as needed.>

&uilt manages a series of patches by keeping track of the changes each of them makes. They
are logically organi2ed as a stack, and you can apply, un$apply, refresh them easily by traveling into the stack )push-pop*. This package completely integrates into the (#"/, allowing maintainers using this new paradigm for their packaging scripts to benefit from the comfort of &uilt when editing their diff against upstream. The package also provides some basic support for those not using (#"/.

gnupg is a complete and free replacement for %8% used to digitally sign files )including
packages*.

fakeroot simulates running a command with root privileges. This is useful for creating binary
packages as a regular user.

lintian dissects #ebian packages and reports bugs and %olicy violations. It contains automated
checks for many aspects of #ebian %olicy as well as for common errors.

pbuilder constructs a chroot system and builds a package inside the chroot. It is an ideal
system to use to check that a package has correct build dependencies and to build clean packages to be tested and distributed. For convenience, here7s an apt$get command to install all of them, sudo apt$get install build$essential devscripts ubuntu$dev$tools debhelper dh$make diff patch cdbs &uilt gnupg @ fakeroot lintian pbuilder piuparts

The %ersonal "uilder, pbuilder

$sing pbuilder as a package builder allows you to build the package from within a chroot en&ironment. -ou can build binary packages without using pbuilder, but you must ha&e all the build dependencies installed on your system first. +owe&er,

pbuilder allows the packager to check the build dependencies because the package is built within a minimal Ubuntu installation, and the build dependencies are downloaded according to the debian/control file. %builder owto is a comprehensive guide to almost anything you could wish to do with pbuilder. 0 short overview, to create a pbuilder environment, run sudo pbuilder create $$distribution A)lsb;release $cs* @ $$othermirror >deb http,--archive.ubuntu.com-ubuntu A)lsb;release $cs* main restricted universe multiverse>

to build a package using pbuilder, run

sudo pbuilder build B.dsc to update a pbuilder environment, run sudo pbuilder update

use pbuilder$dist )of the ubuntu$dev$tools* to have several different pbuilder setups for
different Ubuntu releases.

"asic %ackaging Two of the problems that many no&ice packagers face are that there are multiple ways of packaging, and there is more than one tool to do the .ob. %ackage development often re&uires installing many packages )especially $dev packages containing headers and other common development files* that are not part of a normal desktop Ubuntu installation. If you want to avoid installing extra packages or would like to develop for a different Ubuntu release )the development one, for instance* from what you currently have, the use of a chroot environment is highly recommended. 0 guide to setting up a chroot can be found at #ebootstrap(hroot. !e will go through two examples with the common build systems. !e will use debhelper, the most common build system in #ebian. It helps the packager by automating repetitive tasks. Then we will briefly cover the (ommon #ebian "uild /ystem )(#"/*, a more streamlined build system that uses debhelper.

%ackaging from /cratch

Requirements: build-essential, automake, gnupg, lintian, fakeroot, pbuilder, debhelper, dpatch, and dh-make. 'n this e ample we will be using the G#$ hello program as our e ample. -ou can download the source tarball from ftp.gnu.org. /or the purposes of this e ample, we will be using the ~/hello/ directory. mkdir C-hello cd C-hello wget http,--ftp.gnu.org-gnu-hello-hello$D.=.tar.g2 If you are packaging your own software, or the software is not available as a tar.g2 file, you can create the re&uired .tar.g2 from an unpacked source directory with a command like the following,

mkdir hello$D.= tar c2f hello$D.=.tar.g2 hello$D.= For the purpose of this example, we will also compare our package )hello* to one that is already packaged in the Ubuntu repository )calledhello$debhelper*. For now, we will place it in the ubuntu directory so we can look at it later. This will unpack the source, mkdir ubuntu cd ubuntu apt$get source hello$debhelper cd .. Unlike most apt$get commands, you do not need to have root privileges to get the source package, because it is downloaded to the current directory. In fact, it is recommended that you only use apt$ get source as a regular user, because then you can edit files in the source package without needing root privileges. !hat the apt$get source command does is, <. #ownload the source package. 0 source package commonly contains, a .dsc file describing the package and giving mdEsums for the source package,

an .orig.tar.g2 file containing the source code from the author)s*, and a .diff.g2 file containing the packaging )in the debian- directory* and patches applied against the source code.

D. Untar the .orig.tar.g2 file into the current directory. F. 0pply the un2ipped .diff.g2 to the unpacked source directory. If you manually download the source package ).dsc, .orig.tar.g2, and .diff.g2 files*, you can unpack them in the same way apt$get source does by using dpkg$source as follows, dpkg$source $x B.dsc !e want to recreate the above from scratch. The first thing you will need to do is make a copy of the original )sometimes called >upstream>* tarball in the following format, 6packagename4;6version4.orig.tar.g2. This step does two things. First, it creates an additional copy of the source code. If you accidentally change or delete the working copy you can use the one you downloaded. /econd, it is considered poor packaging practice to change the original source tarball unless absolutely necessary. /ee the section called G(ommon MistakesH for reasons. cp hello$D.=.tar.g2 hello;D.=.orig.tar.g2 tar $x2vf hello;D.=.orig.tar.g2 Using an underscore )7;7* between the package name )hello* and the version )D.=* in the orig.tar.g2, as opposed to a hyphen )7$7*, is very important. The packaging tools look for a filename of this exact format, so if you get it wrong, the tools will incorrectly assume that there is no original source at all, and the package will be built as a #ebian native package. !e now have a hello$D.= directory containing the source files. 3ow we need to create the customary debian directory where all the packaging information is stored, allowing us to separate the packaging files from the application source files. !e will let dh$make do the work for us, )3ote, dh;make is the executable and dh$make is the package it7s found in.*

cd hello$D.= dh;make $e your.maintainerIaddress dh$make will then ask you a series of &uestions about your package, Type of package, single binary, multiple binary, library, kernel module or cdbsJ Ks-m-l-k-bL s Maintainer name , +our 3ame Mmail$0ddress , your.maintainerIaddress #ate , Thu, 9 0pr D559 <5,5N,<O $5N55 %ackage 3ame , hello Persion , D.= 'icense , blank Type of %ackage , /ingle it 6enter4 to confirm, Mnter :nly run dh;make once. If you run it again after you do it the first time, it will not work properly. If you want to change it or made a mistake, remove the source directory and untar the upstream tarball afresh. Then you can change to the source directory and try again. Qunning dh;make creates the basic files needed in debian- and many template files ).ex* that may be needed. The ello program is not very complicated, and as we have seen in the section called G%ackaging From /cratchH, packaging it does not re&uire much more than the basic files. Therefore, let us remove the .ex files, cd debian rm B.ex B.MR For hello, some additional files from the debian directory will also be unnecessary,

QM0#MM.#ebian, #ebian and Ubuntu end$user documentation file, sometimes simply

named QM0#MM. 3ot to be confused withQM0#MM.source, which )if present* is documentation for those interested in modifying the source package.

dirs, Used by dh;installdirs to create needed directories. docs, Used by dh;installdocs to install program documentation. info, Used by dh;installinfo to install the info file.
Seep in mind that for most packages, these files are re&uired. For more information on them, see the section called Gdh$make example filesH. 0t this point, you should have only changelog, compat, control, copyright, and rules files in the debian directory. changelog The changelog file is, as its name implies, a listing of the changes made in each &ersion. 't has a specific format that gi&es the package name, &ersion, distribution, changes, and who made the changes at a gi&en time. 'f you ha&e a GPG key, make sure to use the same name and email address in changelog as you ha&e in your key. The following is a template changelog, package )version* distribution? urgencyTurgency

B change details more change details B even more change details $$ maintainer name 6email address4Ktwo spacesL date The format )especially of the date* is important. The date should be in QF(UDD format, which can be obtained by using the command date $Q. For convenience, the command dch may be used to edit changelog. It will update the date automatically. Minor bullet points are indicated by a dash >$>, while maVor points use an asterisk >B>. If you are packaging from scratch, dch $$create )dch is in the devscripts package* will create a standard debian-changelog for you. ere is a sample changelog file for hello, hello )D.=$5ubuntu<* Vaunty? urgencyTlow B 3ew upstream release with lots of bug fixes and feature improvements. $$ (aptain %ackager 6packagerIcoolness.com4 !ed, E Wan D55O DD,FU,=O $5N55 3otice that the version has a $5ubuntu< appended to it, this is the distro revision, used so that the packaging can be updated )to fix bugs for example* with new uploads within the same source release version. Ubuntu and #ebian have slightly different package versioning schemes to avoid conflicting packages with the same source version. If a #ebian package has been changed in Ubuntu, it has ubuntuR )where R is the Ubuntu revision number* appended to the end of the #ebian version. /o if the #ebian hello D.=$< package was changed by Ubuntu, the version string would be D.=$<ubuntu<. If a package for the application does not exist in #ebian, then the #ebian revision is 5 )e.g., D.=$5ubuntu<*. 3ow look at the changelog for the Ubuntu source package that we downloaded earlier, less ..-..-ubuntu-hello$debhelper$D.D-debian-changelog 3otice that in this case the distribution is unstable )a #ebian branch*, because the #ebian package has not been changed by Ubuntu. Qemember to set the distribution to your target distribution release. (onsult #ebian changelog %olicy for more information. control The control file contains the information that the package manager 0such as apt-get, synaptic, and adept1 uses, build" time dependencies, maintainer information, and much more. For the Ubuntu hello package, the control file looks something like, /ource, hello /ection, devel %riority, optional

Maintainer, Ubuntu #evelopers 6ubuntu$devel$discussIlists.ubuntu.com4 R/"($:riginal$Maintainer, (aptain %ackager 6packagerIcoolness.com4 /tandards$Persion, F.N.F "uild$#epends, debhelper )4T E* omepage, http,--www.gnu.org-software-hello%ackage, hello 0rchitecture, any #epends, AXshlibs,#ependsY #escription, The classic greeting, and a good example The 83U hello program produces a familiar, friendly greeting. It allows non$programmers to use a classic computer science tool which would otherwise be unavailable to them. /eriously, though, this is an example of how to do a #ebian package. It is the #ebian version of the 83U %roVect7s Zhello world7 program )which is itself an example for the 83U %roVect*. In Ubuntu we set the Maintainer field to a general address because anyone can change any package )this differs from #ebian where changing packages is usually restricted to an individual or a team*. Mdit control using the information above )making sure to provide your information for the R/"($ :riginal$Maintainer field*. The first paragraph gives information about the source package. 'et us go through each line,

/ource, This is the name of the source package. /ection, The apt repositories are split up into sections for ease of browsing and categori2ation
of software.

%riority, This sets the importance of the package to users. It should be one of the following, Qe&uired $ packages that are essential for the system to work properly. If they are
removed it is highly likely that your system will break in an unrecoverable way.

Important $ minimal set of packages for a usable system. Qemoving these packages
will not produce an unrecoverable breakage of your system, but they are generally considered important tools without which any 'inux installation would be incomplete. 3ote, This does not include things like Mmacs or even the R !indow /ystem.

/tandard $ /omewhat self explanatory. :ptional $ in essence this category is for non$re&uired packages, or the bulk of
packages. owever, these packages should not conflict with each other.

Mxtra $ packages that may conflict with packages in one of the above categories. 0lso
used for speciali2ed packages that would only be useful to people who already know the purpose of the package.

Maintainer, The name of the package maintainer and their email address. /tandards$Persion, The version of the #ebian %olicy to which the package adheres. 0n easy
way to find the current version is apt$cache show debian$policy 1 grep Persion .

 "uild$#epends, :ne of the most important fields and often the source of bugs, this line lists
the binary packages )with versions if necessary* that need to be installed in order to create the binary package)s* from the source package. %ackages that are essential are re&uired by build$essential and do not need to be included in the "uild$#epends line. The list of build$ essential packages can be found at-usr-share-doc-build$essential-list.

omepage, 0 UQ' where more information on the software can be found.

The second paragraph is for the binary package that will be built from the source. If multiple binary packages are built from the source package, there should be one section for each one. 0gain, let us go through each line,

%ackage, The name for the binary package. Many times for simple programs )such as hello*,
the source and binary packages7 names are identical.

0rchitecture, The architectures for which the binary package)s* will be built. Mxamples are, all $ The source is not architecture$dependent. %rograms that use %ython or other
interpreted languages would use this. The resulting binary package would end with ;all.deb.

any $ The source is architecture$dependent and should compile on all the supported
architectures. There will be a .deb file for each architecture );iFU9.deb for instance*

0 subset of architectures )iFU9, amd9=, ppc, etc.* can be listed to indicate that the
source is architecture$dependent and does not work for all architectures supported by Ubuntu.

#epends, The list of packages that the binary package depends on for functionality. For hello,
we see AXshlibs,#ependsY, which is a variable that is used by dpkg$shlibdeps to add the shared library packages needed by the binaries to #epends,. /ee the dpkg$ source)<* and dpkg$shlibdeps)<* man page for more information.

Qecommends, Used for packages that are highly recommended and usually are installed with
the package. /ome package managers, most notably aptitude, automatically install Qecommended packages.

/uggests, Used for packages that are similar or useful when this package is installed. (onflicts, Used for packages that will conflict with this package. "oth cannot be installed at
the same time. If one is being installed, the other will be removed.

#escription, "oth short and long descriptions are used by package managers. 3ote that there
is one space at the beginning of each line in the long description. More information on how to make a good description can be found at http,--www.debian.org-doc-developers$ reference-best$pkging$practices.html[bpp$debian$control copyright This file gi&es the copyright information. Generally, copyright information is found in the COPYING file in the program2s source directory. This file should include such information as the names of the author and the packager, the $3L from which the source came, a 4opyright line with the year and copyright holder, and the te t of the copyright itself. An e ample template would be, This package was debiani2ed by X+our 3ameY 6your email address4

X#ateY It was downloaded from, XUQ' of webpageY Upstream 0uthor)s*, X3ame)s* and email address)es* of author)s*Y (opyright, (opyright )(* X+ear)s*Y by X0uthor)s*Y XMmail address)es*Y 'icense, X0dd licence text here. For 83U licences add the licence header and a link to the appropriate file in -usr-share-common$licences.Y %ackaging, (opyright )(* X+ear)s*Y by X+our 3ameY 6your email address4 released under Xthe licence you choose for your packagingY 0s one can imagine, hello is released under the 8%' license. In this case it is easiest to Vust copy the copyright file from the Ubuntu package, cp ..-..-ubuntu-hello$debhelper$D.D-debian-copyright . 3otice that the Ubuntu package7s copyright includes a license statement for the manual. It is important that all the files in the source be covered by a license statement. More information, caveats and tips are available in the (opyright section. source-version The debian build system wants to know which format the package source is to be kept in. This is done by the file source/format 0a file namedformat in a directory named source in the debian56 direcory. This file contains nothing but a single line. 0 sane content for this line is, F.5 )native* If this file is missing debuild complains both about having to use the legacy source format <.5 and about any directory it can find subversion, cvs or ba2aar is keeping its data in. rules The last file we need to look at is rules. This does all the work for creating our package. 't is a %akefile with targets to compile and install the application, then create the !deb file from the installed files. 't also has a target to clean up all the build files so you end up with .ust a source package again. ere is a simplified version of the rules file created by dh;make, [\-usr-bin-make $f [ $B$ makefile $B$ [ Uncomment this to turn on verbose mode.

[export # ;PMQ":/MT< ], dh AI 'et us go through this file in some detail. !hat this does is pass every build target that debian-rules is called with as an argument to-usr-bin-dh, which itself will call all the necessary dh;B commands. dh runs a se&uence of debhelper commands. The supported se&uences correspond to the targets of a debian-rules file, >build>, >clean>, >install>, >binary$arch>, >binary$indep>, and >binary>. (ommands in the binary$indep se&uence are passed the >$i> option to ensure they only work on binary independent packages, and commands in the binary$arch se&uences are passed the >$a> option to ensure they only work on architecture dependent packages. Mach debhelper command will record when it7s successfully run in debian-package.debhelper.log. )!hich dh;clean deletes.* /o dh can tell which commands have already been run, for which packages, and skip running those commands again. Mach time dh is run, it examines the log, and finds the last logged command that is in the specified se&uence. It then continues with the next command in the se&uence. The $$until, $$before, $$after, and $$remaining options can override this behavior. If debian-rules contains a target with a name like >override;dh;command>, then when it gets to that command in the se&uence, dh will run that target from the rules file, rather than running the actual command. The override target can then run the command with additional options, or run entirely different commands instead. )3ote that to use this feature, you should "uild$#epend on debhelper N.5.E5 or above.* ave a look at -usr-share-doc-debhelper-examples- for more examples. "uilding the %ackage 'ocally )"inary :nly* There is a simple command to build the binary package, debuild debuild will first check that all the build$depends packages are installed, it will then use dpkg$ buildpackage to compile, install and build the.debs using the rules in debian-rules. If that succeeds it will attempt to digitally sign the packages with 8%8, if it gives an error that it can not find your key that means it has successfully compiled the .deb packages but you do not have a 8%8 key with the same name, comment, and e$mail as you used in debian-changelog. /ee 8nu%rivacy8uard owto for instructions on creating your key. +our finished binary package ).deb file* has now been built locally? you should be able to find it in the directory above your source )i.e. inC-hello-*. ave a look and install it using the following commands, cd .. lesspipe Bdeb sudo dpkg $$install Bdeb "uilding the %ackage )/ource and "inary*

Perhaps more common than building the binary package locally is to do it through pbuilder after building the source package. Let2s mo&e into the root of the e tracted source 0i.e. ~/hello/hello-"!#1 where we build the source package using debuild along with a special option, debuild $/ !hat the $/ flag does is tell debuild to build a source package using another script, dpkg$ buildpackage, together with fakeroot, which grants us fake root privileges while making the package. It will take the .orig.tar.g2 file and produce a .diff.g2 )the difference between the original tarball from the author and the directory we have created, debian- and its contents* and a .dsc file that has the description and mdEsums for the source package. The .dsc and B;source.changes )used for uploading the source package* files are signed using your 8%8 key. If you do not have a gpg key set up you will get an error from debuild. +ou can either set up a gpg key or use the $us $uc keys with debuild to turn off signing. owever, you will not be able to have your packages uploaded to Ubuntu without signing them. To make sure debuild finds the right gpg key you should set the #M"FU''30MM and #M"MM0I' environment variables )in your C-.bashrc for instance* to the name and email address you use for your gpg key and in the debian-changelog. /ome people have reported that they were unable to get debuild to find their gpg key properly, even after setting the above environment variables. To get around this you can give debuild the $k6keyid4 flag where6keyid4 is your gpg key I#. !ith the source package now built, we can now use its .dsc file to build the corresponding binary package in a clean pbuilder environement, sudo pbuilder build ..-B.dsc Using pbuilder to build the binary packages is very important. It ensures that the build dependencies are correct, because pbuilder provides only a minimal environment, so all the build$time dependencies are determined by the control file. !e can check the source package for common mistakes using lintian, cd .. lintian $Ivi B.dsc Qe&uirements for 3ew Ubuntu %ackages !hen a source package is uploaded to Ubuntu which does not yet exist in the archive, or builds a new binary package, it will be held in the 3M! &ueue and has to be reviewed by an Ubuntu archive team member.
%ackaging

Most importantly, see copyright and licensing information below.

The source and binary packages should have a sane name, neither should they clutter the namespace )such as >editor>* nor should they have an entirely nonsensical name )such as >new$stuff$manager>*. debian-control and debian-rules should build packages with the right 0rchitecture,, "uild$ #ependsK$IndepL,, and rules target )binary$arch vs. binary$indep*. Maintainer and init scripts should not excessively mess up the system. 0 more comprehensive list of package checks is available from the (ode Qeview page.

:ther

The #ebian 3M! QeVect F0^ lists some important special cases which mostly apply
to Ubuntu as well.

%rocess documentation, Ubuntu#evelopment-3ew%ackages

%ackaging with (#"/

4!78 is a set of %akefile includes that uses debhelper to make building and maintaining !ebian packages e&en easier. 't uses ad&anced features of %akefiles to abstract the build process, so rules files end up primarily as a series of include statements. 't has many ad&antages,

It produces a short, readable, and efficient debian-rules It automates debhelper use for you, so you do not have to worry about repetitive tasks
It helps you focus on more important packaging problems, because it helps without limiting customi2ation Its classes have been well tested, so you can avoid dirty hacks to solve common problems It is extendable

/witching to (#"/ is easy

owever if your package has an oddity about how it is built you may need to tackle some of the Makefile syntax to extend (#"/ and tell it what is needed. Using (#"/ for Ubuntu packages is very easy, if the software you are packaging can be configured and built using the 83U autoconf tools )the >configure$make$make install> idiom*. 0fter adding cdbs to the "uild$#epends in debian-control, a basic debian-rules file using (#"/ can fit in D lines. For a simple (-(.. application with no extra rules, such as hello, debian-rules can look like this, [\-usr-bin-make $f include -usr-share-cdbs-<-rules-debhelper.mk include -usr-share-cdbs-<-class-autotools.mk That is all you need to build the program\ (#"/ handles installing and cleaning. +ou can then use the .install and .info files to tune your package with the usual debhelper functions in the various sections for debian-rules. /ometimes the upstream author has hardwired non$standard defaults into the autoconf scripts. For example, a package may place man pages in -usr-share-man-. In this case, you can specify the correct path using the following, #M";(:3FI8UQM;M03#IQT-usr-share-man0nother situation fre&uently encountered with configure scripts is that you need to specify certain configuration options provided by the software author. This is handled by substituting the appropriate option for the right side of a #M";(:3FI8UQM;MRTQ0;F'08/ assign statement like the following, #M";(:3FI8UQM;MRTQ0;F'08/ T $$enable$graphics $$with$gslT-usr ere is the list of standard configure options that are always passed to configure,

$$prefixTA)#M";(:3FI8UQM;%QMFIR* $$includedirTA)#M";(:3FI8UQM;I3('U#M#IQ* $$mandirTA)#M";(:3FI8UQM;M03#IQ* $$infodirTA)#M";(:3FI8UQM;I3F:#IQ* $$sysconfdirTA)#M";(:3FI8UQM;/+/(:3F#IQ* $$localstatedirTA)#M";(:3FI8UQM;':(0'/T0TM#IQ* $$libexecdirTA)#M";(:3FI8UQM;'I"MRM(#IQ* 4!78 mostly works by including !mk %akefiles in debian/rules. The cdbs package pro&ides such files in /usr/share/cdbs/$/ that allow you to do 9uite a lot of packaging tasks. :ther packages, such as %uilt, add modules to 4!78 and can be used as 7uild"!epends. #ote that you can also use your own 4!78 rules and include them in the package. The most useful modules included with the cdbs package are,

rules-debhelper.mk, (alls debhelper in all re&uired sections rules-dpatch.mk, 0llows you to use dpatch to ease patching the source. Must be included
before any other rule.

rules-simple$patchsys.mk, %rovides a very easy way to patch the source rules-tarball.mk, 0llows you to build packages using the compressed tarball in the package class-autotools.mk, (alls autotools in all re&uired sections class-gnome.mk, "uilds 83:MM programs )re&uires the proper "uild$#epends
in debian-control*

class-kde.mk, "uilds S#M programs )re&uires the proper "uild$#epends in debian-control* class-xfce.mk, "uild Rfce= programs )re&uires the proper "uild$#epends in debian-control* class-python$distutils.mk, Facilitates packaging %ython programs
It may happen that you need to patch files belonging to the autoconf system, in which case you will probably need to run aclocal, automakeand autoconf after applying the patch. (#"/ has options to assist you in this situation. It will run patch first, then rebuild autotools, and finally run configure >et al.> ere is an example where versions <.<5 of autoconf and automake are chosen, include -usr-share-cdbs-<-rules-dpatch.mk include -usr-share-cdbs-<-rules-debhelper.mk 4!78 runs the debhelper scripts after the package has been compiled and installed. 8ometimes you may need to modify the beha&iour of certain debhelper scripts. A bunch of &ariables are a&ailable for this purpose, debhelper script dh&builddeb dh&compress dh&fi0perms dh&gencontrol dh&installcatalog dh&installdebconf cdbs variable '()&)*I+'&'()&,-G. '()&CO/P-(..&,-G. '()&1I2P(-/.&,-G. '()&G(NCON3-O+&,-G. '()&IN.3,++C,3,+OG.&,-G. '()&IN.3,++'()CON1&,-G.

dh&installchangelogs '()&IN.3,++C4,NG(+OG.&,-G.

dh&installdeb dh&installemacsen dh&installinit dh&installlogcheck dh&installlogrotate dh&installmime dh&installpam dh&installude6 dh&install dh&makeshlibs dh&md8sums dh&perl dh&shlibdeps dh&strip

'()&IN.3,++&'()&,-G. '()&IN.3,++(/,C.(N&,-G. '()&IN.3,++INI3&,-G. '()&IN.3,+++OGC4(C5&,-G. '()&IN.3,+++OG-O3,3(&,-G. '()&IN.3,++/I/(&,-G. '()&IN.3,++P,/&,-G. '()&IN.3,++*'(7&,-G. '()&IN.3,++&,-G. '()&/,5(.4+I).&,-G. '()&/'8.*/.&,-G. '()&P(-+&,-G. '()&.4+I)'(P.&,-G. '()&.3-IP&,-G.

/ee the manpages of the individual debhelper scripts to see what options are available. :ne thing that is commonly needed is to exclude files from the action of certain debhelper scripts. For example, you may arrange that a certain file maintains the permissions with which it was installed, and not become modified by the dh;fixperms script, #M";FIR%MQM/;MR('U#M T -usr-sbin-suid$program The complete list of cdbs2 e clude &ariables is, '()&CO/P-(..&(2C+*'( '()&1I2P(-/.&(2C+*'( '()&C+(,N&(2C+*'( '()&'4&,+9,Y.&(2C+*'( '()&.3-IP&(2C+*'( %ackaging %ython modules with (#"/ (#"/ is also very well suited for packaging %ython modules, when these make use of the distutils building system. The following is an example of a debian-rules file, which in fact could be used ad verbatim for a great number of not$too$complicated modules. 3otice that we tellcdbs not to compress %ython source files, #M";%+T :3;/+/TMMTpysupport include -usr-share-cdbs-<-rules-debhelper.mk include -usr-share-cdbs-<-class-python$distutils.mk [ #on7t compress .py files #M";(:M%QM//;MR('U#M ,T .py Important note on #M";0UT:;U%#0TM;#M"I03;(:3TQ:', #o not use #M";0UT:;U%#0TM;#M"I03;(:3TQ:',Tyes t

o automatically changedebian-control. It can cause serious problems, and #ebian considers it a reason to reVect a package from entering the archives. /ee http,--ftp$master.debian.org-QMWM(T$ F0^.html for more information. For more information on (#"/, see Marc #e&u_nes7 guide at https,--perso.duckcorp.org-duck-cdbs$ doc-cdbs$doc.xhtml. /ee also this tutorial. 0dvanced %ackaging

4reating %ore Than :ne 7inary Package

:ften you will want to split a source package into more than one binary package. For single binary packages files are installed to debian-6packagename4 and packaged from there. For multiple packages they are installed todebian-tmp and split up by using multiple 6packagename4.install files For example, suppose you want to build D packages pkg< and pkgD from one source package, then first in debian-control you need to fill in two %ackage sections for both pkg< and pkgD, then create debian-pkg<.install and debian-pkgD.install specifying the pattern of files needed by the packages respectively. B pkg<.install usr-bin-somefile usr-share-somedir-prefixB B pkgD.install usr-doc-foobar-B

%ackaging /hared 'ibraries This document explains what shared libraries are, focusing on exported symbols, and explains some of the details of how to package them. It is a work in progress, based on a M:TU-/chool session. To see the log of that session please see M:TU-/chool-'ibrary%ackaging

/hared 'ibraries
/hared libraries are obVect files containing compiled code that can be linked in to an executable. This is usually done for one of two reasons,

(. To provide a dynamically loaded plugin mechanism using dlopen.

D. To share code between multiple applications. This guide will mainly concern itself with the second application. The structure of an )M'F* shared library is an obVect file containing >symbols> split in to >sections>. Usually the details of the sections used are not important when packaging, merely the list of symbols, and as such we will focus on those.

/hared 'ibraries
/hared libraries are obVect files containing compiled code that can be linked in to an executable. This is usually done for one of two reasons,

(. To provide a dynamically loaded plugin mechanism using dlopen.

D. To share code between multiple applications. This guide will mainly concern itself with the second application. The structure of an )M'F* shared library is an obVect file containing >symbols> split in to >sections>. Usually the details of the sections used are not important when packaging, merely the list of symbols, and as such we will focus on those. 0 symbol is an item that is exported from the shared obVect. This means that it is accessible from an executable that loads the shared library. 0 symbol can be a variable, or a function, or something else like a struct. If it is a variable then the executable can read and write the value of the variable, and if it is a function then the executable can call the function. The important thing to note is that if an executable contains code to call a function do;foo that it expects to find in libfoo.so, and libfoo.sodoes not export a function with that name, then the program will not run. There are more complications that arise if the program and the library differ in what they think the definition of a symbol are, and so we must strive to make sure that this never happens.
!here a symbol comes from

/ymbols are created by the compiler from certain constructs in the source code. (onsider the following code, [include 6stdio.h4 static int static;global T =D? int extern;global? const int const;extern;global T =D? static void local;function)int n* X int local;var T F? static int static;local;var T DF? if )n 4 F* X local;var T n? static;local;var T D B n? Y if )local;var 4 =* X fprintf)stderr, >static;varT]d@n>, static;global*? Y else X fprintf)stderr, >static;local;varT]d@n>, static;local;var*? Y

Y void global;function)int n* X fprintf)stderr, >extern;globalT]d@n>, extern;global*? Y int main)int argc, char BBargv* X local;function)argc*? global;function)argc*? return 5? Y !hen this code is compiled the compiler will decide whether each of the variables, functions etc. used in the code should be exported as a symbol. If we compile this code we will be able to see what becomes a symbol. /ave the code to a file named example.c and then run the following command to compile it, A gcc $c example.c $o example.o This doesn7t create a shared library yet, Vust an obVect file, but we are able to see some of the symbol information. Use nm to see the symbol list, A nm example.o 55555555 Q const;extern;global 5555555= ( extern;global U fprintf 5555559b 55555555 555555OD 55555555 5555555= T global;function t local;function T main d static;global d static;local;var.<NU< U stderr

In the rightmost column you can see the name of each of the symbols. There is one created for most of the variables and functions used in the file. owever, local;var is not there, as this is a local variable to a function, and as such is allocated on the stack. The other interesting feature is the number that is included in the name of static;local;var. This is to avoid name clashes if you were to have a static variable named static;local;var in another function in the file. ) owever, as we will see, this symbol will not make it in to the shared obVect, so this point is not too important.* In the middle column of the output there are letters that correspond to the type of symbol. +ou can find the definitions in man nm. The ones listed above are

 Q $ The symbol is in the read only data section. ( $ (ommon symbol, i.e. uninitiali2ed data. U $ The symbol is defined somewhere other than this file. T $ The symbol is in the text section, i.e. it is code. t $ The symbol is in the text section. d $ The symbol is in the initiali2ed data section.
+ou may notice that the local symbols are given a lowercase letter, and the global symbols an uppercase letter. This means that only symbols with an uppercase letter will make it in to the shared obVect. The interesting symbols are the ones given the symbol U, which indicates that they refer to the symbol, but do not define it, which means that it must be defined elsewhere. In this case stderr and fprintf fall in to that category, as they are defined in libc. The symbols will be matched up by the linker later. (ommon Mistakes

dh;make Mxample Files

!hen you use dh;make to create the initial >debianisation>, example files for various tasks are created in the debian- directory. The templates have a .ex extension. If you want to use one, rename it to remove the extension. If you do not need it, remove it to keep the debian- directory clean.

0busing dh;installdirs .dirs Files

Many packages wrongly use dh;installdirs and .dirs files to create directories. OO] of those cases are not necessary, since dh;installand .install files will automatically take care of creating directories. +ou only need to use dh;installdirs if your package needs to ship empty nonstandard directories, e. g. -etc-mypackage-plugins.d-.

(hanging the :riginal Tarball

There are two types of source packages, nati&e and non"nati&e. 0 native package is one that is specific to Ubuntu-#ebian. It has the debian- directory containing the packaging information and any changes to the source included in the tarball )usually 6packagename4;6version4.tar.g2*. 3on$native packages are more common. 0 non$native package splits the source package into a 6packagename4;6version4.orig.tar.g2tarball that is identical )hopefully mdEsum identical* to the source tarball downloaded from the proVect7s homepage and a .diff.g2 file that contains all the differences )debian- directory and patches* from the original source tarball. The following deals primarily with non$native packages. There is a newer format for non$native packages, /ource format F.5 )&uilt*. These packages have a .debian.tar.g2 file instead of a .diff.g2, containing the debian- directory and patches against files outside debian-, using the &uilt patch system )described later*. This format is selected by writing >F.5 )&uilt*> into debian-source-format. F.5 )&uilt* packages can be compressed with g2, b2D, l2ma or x2.

ere is a list of potential problems that can occur if you change the original tarball,

(. Qeproducibility, If you take Vust the .diff.g2 and .dsc, you or someone else has no means to
reproduce the changes in the original tarball.

). Upgradeability, It is much easier to upgrade to a new upstream )from the author* version if
the .orig.tar.g2 is preserved and there is a clear separation between the upstream source and the changes made to produce the Ubuntu source package.

*. #ebian to Ubuntu /ynchroni2ation, (hanging original tarballs makes it hard to automatically

sync from #ebian to Ubuntu. 3ormally, only the .diff.g2 and .dsc files change within the same upstream version, since the .orig.tar.g2 file is shared by all the #ebian orUbuntu revisions. It is much more difficult to sync if the mdEsums of the .orig.tar.g2 files are not the same.

;. Usage of Qevision (ontrol for #ebian package, If you use svn )and svn$buildpackage* or
similar tools to handle your #ebian package, you usually don7t store the original tarball inside. If someone else does a checkout, he7ll need to get the original tarball separately. :ther revision control systems can be used to track only the packaging files )debian-, etc.* and not the whole source. owever, if the .orig.tar.g2 is not the same, then obviously problems can occur.

<. /ecurity tracking, (onsider a situation where someone wants to introduce a backdoor, rootkit
or other malicious item. If the original tarball is intact, it can be scanned easily through the .diff.g2 to see if the person who modified the package attempted something evil. If the tarball has changed, however, you also need to check the differences between the tarball and the original source.

=. The .diff.g2, The option to use the .diff.g2 to reflect changes to the original tarball already
exists, so it is easy to make changes without touching the original tarball. It is acceptable to change the original tarball if one or more of the following hold true, It contains non$free parts that cannot be redistributed. Qemove those parts, and note it in the packaging. :ften such packages use >.dfsg> )which stands for #ebian Free /oftware 8uidelines* in the package name and-or versioning to indicate that non$free parts have been removed. The authors only provide b2ipDed source. owever you should consider Vust using source format F.5 )&uilt* which supports b2ipD.

Wust bun2ipD the .tar.b2D and g2ip $O the resulting tar. The mdEsums of the .tar you provide and the original .tar must match\ Mventually provide a get$orig$source rule in debian-rules that does this conversion
automatically. #irectly imported from /P3 - "2r - 8it - g - etc. %rovide get$orig$source in debian-rules.

The following are not reasons to change the original tarball,

!rong directory layout Files need to be removed to keep the .diff.g2 small )e.g., files created by autotools*. Mverything that needs to be deleted should be removed in the clean rule. /ince the .diff.g2 is created with diff $u, you will not see removed files in the .diff.g2.

 Files need to be modified. Files that need to be modified should be changed in the .diff.g2,
that is its purpose\

!rong permissions on files. +ou can use debian-rules to do this.

/olutions A get-orig-source rule in debian/rules should obtain the source, mangle it if necessary, and pack it, lea&ing it in the current directory. 8ee!ebian Policy 3o$change repacking )i.e. for 2ip files*, with uscan, get$orig$source, [ Uscan will read debian-watch, grab the correct version, repack, and leave it in the [ current directory uscan $$noconf $$force$download $$rename $$repack $$download$current$version $$destdirT. Qepacking manually, [ 8rab the version from the changelog, up to the first $ #M";U%/TQM0M;PMQ/I:3TA)shell dpkg$parsechangelog 1 sed $rne 7s,`Persion, )K`$L.*.B,@<,p7* get$orig$source, [ Uscan can grab upstream source 2ip uscan $$noconf $$force$download $$download$current$version $$destdirT. [ Wust to be safe rm $rf somesoftware$A)#M";U%/TQM0M;PMQ/I:3* [ Unpack un2ip somesoftware$A)#M";U%/TQM0M;PMQ/I:3*.2ip rm somesoftware$A)#M";U%/TQM0M;PMQ/I:3*.2ip [ Qepacked source should have a top$level directory ending in .orig [ as a reminder to other developers mv somesoftware$A)#M";U%/TQM0M;PMQ/I:3* somesoftware$A )#M";U%/TQM0M;PMQ/I:3*.orig 8aI%T$$best tar $c2 $$owner root $$group root $$mode a.rR @ $f somesoftware;A)#M";U%/TQM0M;PMQ/I:3*.orig.tar.g2 @ somesoftware$A)#M";U%/TQM0M;PMQ/I:3*.orig rm $r somesoftware$A)#M";U%/TQM0M;PMQ/I:3*.orig Qemoving non$#F/8 files, [ 8rab the version before .dfsg #M";U%/TQM0M;PMQ/I:3TA)shell dpkg$parsechangelog 1 sed $rne 7s,`Persion, )K`.L .*.B,@<,p7* get$orig$source, uscan $$noconf $$force$download $$rename $$download$current$version $$destdirT. rm $rf somesoftware$A)#M";U%/TQM0M;PMQ/I:3* tar $xf somesoftware;A)#M";U%/TQM0M;PMQ/I:3*.orig.tar.g2 rm somesoftware;A)#M";U%/TQM0M;PMQ/I:3*.orig.tar.g2 rm somesoftware$A)#M";U%/TQM0M;PMQ/I:3*-unredistributable.file mv somesoftware$A)#M";U%/TQM0M;PMQ/I:3* somesoftware$A )#M";U%/TQM0M;PMQ/I:3*.orig

8aI%T$$best tar $c2 $$owner root $$group root $$mode a.rR @ $f somesoftware;A)#M";U%/TQM0M;PMQ/I:3*.dfsg.orig.tar.g2 @ somesoftware$A)#M";U%/TQM0M;PMQ/I:3*.orig rm $r somesoftware$A)#M";U%/TQM0M;PMQ/I:3*.orig Qecompressing tarballs )not necessary with source format F.5 )&uilt**, #M";U%/TQM0M;PMQ/I:3TA)shell dpkg$parsechangelog 1 sed $rne 7s,`Persion, )K`$L.*.B,@<,p7* get$orig$source, wget http,--somesite.org-stuff-somesoftware$A)#M";U%/TQM0M;PMQ/I:3*.tar.b2D $:$ @ 1 b2cat 1 g2ip $Ofn $c $ 4 somesoftware;A)#M";U%/TQM0M;PMQ/I:3*.orig.tar.g2 From a b2r branch, QMPTA)shell dpkg$parsechangelog 1 sed $rne 7s,`Persion, .BK.CLb2r)K5$OL.*.B,@<,p7* PMQTA)shell dpkg$parsechangelog 1 sed $rne 7s,`Persion, )K`$L.*.B,@<,p7* get$orig$source, b2r export $r A)QMP* $$rootTsomesoftware$A)PMQ*.orig @ somesoftware;A)PMQ*.orig.tar.g2 lp,somesoftware From an svn repo, QMPTA)shell dpkg$parsechangelog 1 sed $rne 7s,`Persion, .BK.CLsvn)K5$OL.*.B,@<,p7* PMQTA)shell dpkg$parsechangelog 1 sed $rne 7s,`Persion, )K`$L.*.B,@<,p7* get$orig$source, rm $rf somesoftware$A)PMQ*.orig svn $& export $r A)QMP* http,--somesite.org-stuff-somesoftware-trunk @ somesoftware$A)PMQ*.orig 8aI%T$$best tar $c2 $$owner root $$group root $$mode a.rR @ $f somesoftware;A)PMQ*.orig.tar.g2 @ somesoftware$A)PMQ*.orig rm $r somesoftware$A)PMQ*.orig From an hg repo, QMPTA)shell dpkg$parsechangelog 1 sed $rne 7s,`Persion, .BK.CLhg)K5$OL.*.B,@<,p7* PMQTA)shell dpkg$parsechangelog 1 sed $rne 7s,`Persion, )K`$L.*.B,@<,p7* get$orig$source, rm $rf somesoftware$A)PMQ*.orig hg clone http,--somesite.orgstuff-somesoftware somesoftware$A)PMQ*.orig cd somesoftware$A)PMQ*.orig bb hg up $r A)QMP* rm $r somesoftware$A)PMQ*.orig-.hg somesoftware$A)PMQ*.orig-.hgignore 8aI%T$$best tar $c2 $$owner root $$group root $$mode a.rR @ $f somesoftware;A)PMQ*.orig.tar.g2 @ somesoftware$A)PMQ*.orig rm $r somesoftware$A)PMQ*.orig Tips

 Always remember to reference get-orig-source: in debian/rules when you need to repack

the orig!tar!g;. > plain why you repacked it and how others can &erify your work.

It is always a good idea to contact upstream regarding issues with autoconf or directory
layout )or old Free /oftware Foundation addresses in a (:%+QI8 T file*, etc. so that you can avoid having to patch the .diff.g2 at a later date.

:lder packages )from #ebian %olicy F.F.U or earlier* keep the information on repacking
in debian-QM0#MM.#ebian$source. !hen updating an older package, it is acceptable to leave it here, but when upgrading or packaging new software debian-copyright is much preferred.

If a package already contains a debian- directory, do not repackage it. /ource format F.5
)&uilt* will remove an existing debian- directory. 0lternatively, ask the author)s* to delete debian- and provide a diff.g2 instead. This makes it easier to review their work, and it separates packaging from program source. (opyright Information When dealing with copyright information of packages, the following points are critical, since they determine whether we are allowed at all to redistribute the package. Packages must not be accepted if any of these points is not fulfilled, For all files it must be clear under which license they fall. /ource code files should usually have a short comment at the top which points out the license. Files shipped under the 8%' must be in the 7preferred form of modification7 format. This applies to some other free licenses like the M%', too )but e. g. not to "/#*. 3egative examples are Flash animations )B.swf*, most %ost/cript-%#F files, and automatically generated source code. The suspicious$source script in the ubuntu$dev$tools package helps to spot such files. to -usr-share-common$licenses- licenses included there*, and declare which licenses apply to which parts of the package. /ince there are now multiple versions of the 8%' and '8%', the copyright headers and files must be clear about which version)s* apply.

debian-copyright must list the primary copyright holders and all licenses )use pointers

(ommon errors,

/hipping %#Fs and other files without source like a 'aTeR or :pen:ffice document #ocumentation is actually under 8F#', but debian-copyright does not mention it. 0s of gutsy,
the 8F#' is in -usr-share-common$licenses-, so a pointer there is sufficient for debian-copyright.

debian-copyright only mentions a license, but no copyright The source files and-or debian-copyright are not clear about which files fall under which
license

/ource is shipped under >8%' D only>, while debian-copyright says >8%' D or later>

8%'ed packages link against :pen//' )directly or indirectly* #ifferent copyright holders and different licenses not mentioned in debian-copyright. %lease grep $ir copyright B your packages7 directories to make sure you got them all. In the case of large numbers of trivial copyright holders, not all need be mentioned )ask on IQ( if you are in doubt*, but all licenses must be listed.

The rule of thumb is, look at copyright definitions in the source code and accompanying (:%+I38-0UT :Q/ file, as well as all involved licenses. There is no such thing as a general rule of thumb to get it right because different licenses have different re&uirements for redistribution. !hile a public domain license may even state that you can do everything with the source code )which would mean that you need not put anything intodebian-copyright and are even free to include your own may$be$distributed$in$(#$form$only$on$rainy$/aturdays license*, other licenses may impose certain restrictions, such as having to include the copyright statement, credit the original authors or make clear if the source code is altered from its original form. /ometimes the involved licenses even conflict with each other )e.g. 8%' and :pen//' 'icense*, which means that the resulting binary package cannot be distributed. There are six interesting things that are kept in #ebian copyright, as follows, <. !ho created the package, and on which date s-he did that. This isn7t a legal re&uirement, but helps identify a person who may have a relation with upstream. ). The location from which the updated source can be downloaded, although a watch file and a get$orig$source target in debian-rules are recommended where possible. F. 0ny licensing for the packaging. Ideally, this should be the same as for the package, unless the packaging was copied from another package with a more restrictive license. =. The names of any upstream authors. This is mostly to give credit where it is due. E. Identification of the copyright holder)s*. These are the people ultimately responsible for the licensing of the work, although they may have granted the right to sublicense to other parties. =. #escription of the license under which the work is being distributed. This is typically the full text of the license, but may be a shorter form for some common licenses )e.g. 8%', '8%', "/#, 0rtistic 'icense etc.*. In such a case you can refer to the corresponding file in the-usr-share-common$licenses- directory. 3ote that items E and 9 are legal re&uirements. Mxample <, 8%' The GPL re9uires that its complete te t be distributed along with GPL"licensed software 0you can refer to /usr/share/common-licenses/GP+-"0or GPL"* in case it applies, it is discouraged to point to the GPL symlink itself1, which always e ists on !ebian5$buntu systems1, in addition to information about the author0s1 and a short disclaimer of warranty 0which you should include in debian/copyright1. /or e ample, 'icense, 8%'$D 6one line to give the program7s name and a brief idea of what it does.4 (opyright )(* 6year4 6name of author4 . This program is free software? you can redistribute it and-or modify it under the terms of the 83U 8eneral %ublic 'icense as published by the Free /oftware Foundation? either version D of the 'icense, or )at your option* any later version. . This program is distributed in the hope that it will be useful, but !IT :UT 03+ !0QQ03T+? without even the implied warranty of MMQ( 03T0"I'IT+ or FIT3M// F:Q 0 %0QTI(U'0Q %UQ%:/M. /ee the 83U 8eneral %ublic 'icense for more details. .

+ou should have received a copy of the 83U 8eneral %ublic 'icense along with this program? if not, write to the Free /oftware Foundation, Inc., E< Franklin /t, Fifth Floor, "oston, M0 5D<<5$<F5< U/0 R$(omment, :n #ebian 83U-'inux systems, the complete text of the 83U 8eneral %ublic 'icense can be found in the -usr-share-common$licenses-8%'$D file. %lease note that we use the new machine$readable copyright format here. 0lso, please note that upstream can choose to restrict a license to one specific version of the 8%', in which case you will need to modify the above text. Typically, such a restriction would be written in the source code files of a package, and you could simply copy it into debian-copyright. 0lways ensure you are using the correct version of the license, be it 8%' D or F, or '8%' D.5, D.< or F. Use licensecheck to verify that the licenses of all files are consistent. 0lso, make sure that full copies of the licenses have been included by upstream, as it is not uncommon for the texts of '8%' and F#' to be missing. Mxample D, 8%' with different 8%' derived files from a different author 't is not uncommon for copyright notices to be written incorrectly, so always grep the word ?copyright? to try and gather non" ob&ious information about a gi&en pro.ect2s authorship. Then, be sure document the information in debian/copyright, as this file must include a list of all contributing authors and the files they modified. The typical format is as follows, Files, src-foo.c, (opyright, c D55=$D55E by (racky (oder. 'icense, 8%'$D Files, src-bar.c, (opyright, "ased on foobar c D55< by 'icense, 8%'$D

arry

acker.

For more details, see the documentation for the proposed machine$readable copyright format. 8eneral 0dvice (ombining the 8%' with another license will always make the combined work either 8%' or, if the licenses conflict, undistributable. 0 list of combinable licenses is available at http,--www.gnu.org-licenses-license$list.html. Usually you will need to list the different relevant licenses in debian-copyright. 0 good way to do this is to list files with a different license together with the license in &uestion. !hether you actually need to list a given license depends on the stipulations of the licenses involved. !hat you don7t need to mention are licenses from libraries the package links against. They are accompanied by their own copyright file, and the package in &uestion can never be installed without the linked library. :f course, there are exceptions that impose different restrictions, such as the :pen//' 'icense, which re&uires a disclaimer to be present in debian-copyright if one of its works is used )as in linked against* in a proVect. /uch additional restrictions imply that the utili2ed library is incompatible with the 8%'. !hile most proVects don7t typically encounter legal issues, it7s very simple to introduce these via inaccurate copyright files. There is a rule of thumb, better safe than sorry, so be verbose and include any item in doubt in debian-copyright.

Qeference %ackages
Simple installation of files ubuntu-art<ork e0ample-content PHP gallery" roundcube Python Python central =okosher scribes pyenchant pyparallel debconf <6dial Maintainer scripts 0postinst, postrm, prerm, preinst1 Java packages %atch /ystems @uite often it turns out that the upstream source needs to be patched, either to ad.ust the program to work with $buntu or to fi bugs in the source before they are fi ed upstream. 7ut how should we represent these changesA We could simply make the changes in the unpacked source package, in which case the patch would be e pressed in the !diff!g; file. +owe&er, this is not ideal. 'f there is more than one patch you lose the ability to separate the patches as you .ust see one big diff that also contains the packaging files 0in debian/1. This can make it more difficult when you want to send the patches upstream. 't is also &ery con&enient to separate the author2s source from the changes made for $buntu. The best place to put this information is in the debian/ that is already used for the packaging files. /or the rest of this chapter we will be looking at the &arious ways to set up patches in this way. 8eneral Tips There will almost always be the need to apply patches before building a package. +ere are a few patching tips taken fromhttp,55wiki.debian.org5Games5Tools!iscuss. /ome tips on how to use patches efficiently )Thanks 'inas dvirblis*, %rovide descriptive file names for your patches, 7fix$loading$libfoo$on$architecture$bar.patch7 is a good name, 755<.patch7 is not? Make your patches stand$alone. Mach patch should apply cleanly without depending on any other patch being applied? 0void modifying the same file in multiple patches? Python support linda bittornado aptoncd rhythmbo0

python-imaging e0aile

If you absolutely need to create patches that depend on each other, specify that in the filenames, 755patchfoo$do$this.patch7, 75<patchfoo$do$that.patch7 or similar? #o not include multiple unrelated modifications into a single patch? %atch your packages at build time. There is no need to ship a patch plus an already patched source. This only increases the si2e of the diff. Make sure patch is applied before anything else happens with your package. Make configure rule depend on the patch rule? (lean first, unpatch afterwards. /ome files could have been modified during the build so unpatching may fail, unless you restore them. If simply makecleaning the sources does not restore their state, it may be a good idea to make backup copies, for example, in patch rule. using a patch system )cf. K!!!Lhttp,--lists.debian.org-ece-D55U-59-msg5555<.html*. The page QM0#MM.source owTo attempts to collect sample QM0#MM.source file for each packaging systems.

#ebian policy F.U.5 imposes that packages specify explicit how to apply their patches when

To find out which patch system is used, use what$patch from the ubuntu$dev$tools package
)also re&uires (#"/ to be installed*, danielIlovegood,C-Vokosher$5.OA what$patch cdbs danielIlovegood,C-Vokosher$5.OA or danielIlovegood,C-seahorse$D.DD.DA what$patch &uilt danielIlovegood,C-seahorse$D.DD.DA In an ideal world the perfect workflow to get a patch included would be,

(. get it accepted Upstream )if applicable* ). get it accepted in #ebian )if applicable, the easiest way to get it submitted is to
use submittodebian )from the ubuntu$dev$toolspackage** F. get it accepted in Ubuntu To not waste the time of #ebian or upstream maintainers figuring out if a specific problem you forward to them is QM0''+ their problem, it7s advisable to do a bit of research before and to point out in the bug report which kind of research you did beforehand. 0 good way to check if a problem was probably introduced in Ubuntu only is to check debian-changelog and see if there7s any Ubuntu revisions in there that describe a similar change. There7s also a number of changes where Ubuntu decided to deviate from #ebian and upstream for specific reasons. ere7s some more decision making help,

!hen to /end to #ebian

ere7s a few examples,

Missing icons, desktop files )0pplications menu entries*, man pages or documentation files Mrrors in default configuration files or init scripts Mrrors when installing, upgrading or removing a package can often be present in #ebian too %ackages failing to build correctly )FT"F/* can often be sent to #ebian as the same issue may affect their package. owever, you should first attempt to check that the #ebian package fails to build before sending it up.

0s a rule of thumb, any patches that only affect files in the debian directory should be sent to the #ebian bug tracking system )it7s rare for these files to ever need to go all the way upstream to the original developers*. Most bugs tagged with the >packaging> tag are also prime candidates to be sent up to #ebian. +ou can ask the #ebian #erivatives Front #esk for assistance if you have problems getting your patch integrated into #ebian )e.g. the package maintainer does not respond*. The Front #esk can be contacted via 6derivatives 0T debian.org4. More information is available at #ebian #erivativesFront#esk

!hen to /end Upstream

(rashes, lock$ups, hangs, failures to start Incorrect-unexpected outputs Memory leaks, excessive (%U usage %atches which do not touch the -debian directory should normally be sent to the original developers

Mssentially everything not listed in the #ebian section above should be forwarded to the original upstream authors. If the upstream is not available, for instance if the proVect is no longer active, it can still be maintained in #ebian, so all patches for such proVects should be forwarded there.

:ther (ases
owever, there are often reasons why you might want to skip one or two upstreams,

#on7t forward any patches to #ebian if the package does not exist in #ebian )(heck
using http,--packages.debian.org*

#on7t wait for Upstream or #ebian approval )but forward anyway*, if it fixes an important
)importance set at (ritical or igh* bug and we7re late in the Qelease/chedule.

In case you are working on /tableQeleaseUpdates or we7re late in the Qelease/chedule, you
might need to fix the bug in a different way than #ebian or Upstream. It7s important to use a minimally intrusive fix in those cases, even if this means a temporary deviation.

More release schedule specific decision making help.

3ot every patch can get easily included in Ubuntu. to get a certain change into Ubuntu. unchanged*, /yncQe&uest%rocess ere7s a list of what technically needs to happen

If the source package can be imported straight from #ebian )Ubuntu package If the change needs to be merged from #ebian, Ubuntu#evelopment-Merging 8etting a patch uploaded by a sponsor, /ponsorship%rocess

 If it7s sufficiently urgent to get the patch into Ubuntu directly, subscribe the ubuntu$
sponsors team to the bug report. !e have good guidelines that explain what makes a good patch. 0 good rule of thumb is, the better understood the problem is, the better documented the patch is and the more buy$in the patch has from the original software authors, the more likely it is to be included. The easiest way

0uthoring a patch
'f you want to author a patch that changes parts of the source code of the package, edit-patch takes away a lot of the comple ity. The easiest way to patch packages is using edit$patch )from the ubuntu$dev$tools package*. It basically is a wrapper around every other patch system you can imagine. Mxample, First get the source code for the package, danielIbert,CA '(;0''T( apt$get source Vokosher Qeading package lists... #one "uilding dependency tree Qeading state information... #one 3:TI(M, 7Vokosher7 packaging is maintained in the 7/vn7 version control system at, svn,--svn.debian.org-python$apps-packages-Vokosher-trunk3eed to get <DNEk" of source archives. 8et,< http,--archive.ubuntu.com-ubuntu- lucid-universe Vokosher 5.<<.E$<ubuntu< )dsc* K<==D"L 8et,D http,--archive.ubuntu.com-ubuntu- lucid-universe Vokosher 5.<<.E$<ubuntu< )tar* K<D99k"L 8et,F http,--archive.ubuntu.com-ubuntu- lucid-universe Vokosher 5.<<.E$<ubuntu< )diff* KNO5N"L Fetched <DNEk" in <<s )<<<k"-s* gpgv, /ignature made /un 0pr DE 5=,5E,=< D5<5 (M/T using #/0 key I# #(F(FF#5 gpgv, (an7t check signature, public key not found dpkg$source, warning, failed to verify signature on .-Vokosher;5.<<.E$<ubuntu<.dsc dpkg$source, info, extracting Vokosher in Vokosher$5.<<.E dpkg$source, info, unpacking Vokosher;5.<<.E.orig.tar.g2 dpkg$source, info, unpacking Vokosher;5.<<.E$<ubuntu<.debian.tar.g2 dpkg$source, info, applying update;mime;database.patch dpkg$source, info, applying desktop;file.patch dpkg$source, info, applying load;extensions;from;unpacked;eggs.patch dpkg$source, info, applying hard$code$omf$location.patch dpkg$source, info, applying cairo;fix.patch danielIbert,CA

3ext use edit$patch,

danielIbert,CA cd Vokosher$5.<<.E

danielIbert,C-Vokosher$5.<<.EA edit$patch <D$make$things$work$again 3ormali2ing patch name to <D$make$things$work$again.patch 0pplying patch update;mime;database.patch patching file setup.py 0pplying patch desktop;file.patch patching file bin-Vokosher.desktop 0pplying patch load;extensions;from;unpacked;eggs.patch patching file Wokosher-MxtensionManager.py 0pplying patch hard$code$omf$location.patch patching file help-Vokosher-Vokosher$(.omf 0pplying patch cairo;fix.patch patching file Wokosher-PU!idget.py 0pplying patch <5$make$things$work$again.patch patching file QM0#MM 3ow at patch <5$make$things$work$again.patch %atch <D$make$things$work$again.patch is now on top danielIbert,-tmp-&uilt$Do'RmwA ls 0UT :Q/ (:%+I38 (:%+I38$#:(/ Instruments Wokosher %S8$I3F: QM0#MM bin debian extensions help images locale setup.py danielIbert,-tmp-&uilt$Do'RmwA vi QM0#MM

0ftering making the necessary changes, you Vust hit (trl$# or type exit to leave the subshell.
danielIbert,-tmp-&uilt$Do'RmwA exit exit File .-QM0#MM added to patch <D$make$things$work$again.patch Qefreshed patch <D$make$things$work$again.patch Qemoving patch <D$make$things$work$again.patch Qestoring QM0#MM Qemoving patch <5$make$things$work$again.patch Qestoring QM0#MM Qemoving patch cairo;fix.patch Qestoring Wokosher-PU!idget.py Qemoving patch hard$code$omf$location.patch Qestoring help-Vokosher-Vokosher$(.omf Qemoving patch load;extensions;from;unpacked;eggs.patch Qestoring Wokosher-MxtensionManager.py

Qemoving patch desktop;file.patch Qestoring bin-Vokosher.desktop Qemoving patch update;mime;database.patch Qestoring setup.py 3o patches applied Qemember to add debian-patches-<D$make$things$work$again.patch debian-patches-series to a P(/ if you use one danielIbert,C-Vokosher$5.<<.EA

Then the dch dialogue will pop up to ask you to add a changelog entry for your patch.
#one.

0pplying a patch -ou might run into cases where you downloaded a patch and want to know if it2s ?ready for consumption? already or if it needs to be fed to a patch"system, etc. 'et7s consider the case below, danielImiya2aki,CA wget $& http,--launchpadlibrarian.net-=EFEO==5-555<$#on$t$limit$users$list$s$ width$re&uest.patch danielImiya2aki,CA lsdiff 555<$#on$t$limit$users$list$s$width$re&uest.patch a-interfaces-users.ui danielImiya2aki,CA 0s you can see the patch Vust changes one file and it7s not in any kind of debian- directory. This means that the patch should be applied to the source of the package as part of whatever patch system is or is not used. The easiest way to do this is to use edit$patch )version 5.<55 and above* from the ubuntu$dev$ tools package. danielImiya2aki,C-gnome$system$tools$D.F5.5A edit$patch C-555<$#on$t$limit$users$list$s$width$ re&uest.patch 3ormali2ing patch path to 555<$#on$t$limit$users$list$s$width$re&uest.patch 3ormali2ing patch name to 555<$#on$t$limit$users$list$s$width$re&uest.patch (opying and applying new patch. +ou can now edit the patch or exit the subshell to save. ... 0pplying patch 555<$#on$t$limit$users$list$s$width$re&uest.patch patching file interfaces-users.ui 3ow at patch 555<$#on$t$limit$users$list$s$width$re&uest.patch danielImiya2aki,-tmp-&uilt$= bhTgA 3ow you need do type exit or hit (trl$d and edit$patch will fire up a editor, where you can describe the effects of the patch in a changelog entry.

If the lsdiff output mentions a debian-changelog change, you can easily Vust apply the patch by running hackerImachine,C-source$tree$<.5A patch $p< 6 C-complete.patch +ou might need to modify the argument to $p. %atching !ithout a %atch /ystem As we mentioned abo&e, you can patch the original source by simply applying changes to the unpacked source directory. A real"life e ample of this is cron. 'f you grab cron2s source package and look at the !diff!g;, you will see that se&eral of the original source2s files were changed, apt$get source cron 2grep ... cronB.diff.g2 "ut again, this is not really the best way to represent patches. 0 better way is to create individual patch files, put them in debian-patches- and then apply those patches )using patch* in debian-rules. This is what is done for udev. If you are using Intrepid or earlier, download the source with, apt$get source udev udev was altered in Waunty in a way that makes it no longer suitable for this example, so if you7re using Waunty or later, you can get the Intrepid version of udev with, dget $x $u https,--edge.launchpad.net-ubuntu-intrepid-.source-udev-<D=$U-.files-udev;<D=$U.dsc :nce you7ve gotten the udev source into your folder of choice using one of the above two methods, you can proceed with the following, 2grep ... udevB.diff.g2 ls udevB-debian-patchesless udevB-debian-rules The rules file contains the following prescriptions for applying and unapplying patches, [ 0pply patches to the package patch, patch$stamp patch$stamp, dh;testdir IpatchesTdebian-patches-B.patch? for patch in AApatches? do @ test $f AApatch 11 continue? @ echo >0pplying AApatch>? @ patch $stu3 $p< 6 AApatch 11 exit <? @ done touch AI [ Qemove patches from the package unpatch, dh;testdir Iif test $f patch$stamp? then @

patchesTdebian-patches-B.patch? @ for patch in AApatches? do @ reversepatchesT>AApatch AAreversepatches>? @ done? @ for patch in AAreversepatches? do @ test $f AApatch 11 continue? @ echo >Qeversing AApatch>? @ patch $suQf $p< 6 AApatch 11 exit <? @ done? @ rm $f patch$stamp? @ fi That is all well and good, but how do we create new patches for udev using this schemeJ The general approach is as follows, <. (opy the clean source tree to a temporary directory. ). 0pply all patches up to the one you want to edit, or if you want to create a new patch, apply all existing ones )this is necessary since in general patches depend on previous patches*. If you want, you can use debian-rules for this? Vust remove the patches that come afterthe one you want to edit and call debian-rules patch. The actual name for the patch target varies, and may appear as any of the following )or something else*, patch, setup, apply$ patches, unpack and patch$stamp. +ou have to check in debian-rules to see what it is called.

*. (opy the whole source tree again, cp $a -tmp-old -tmp-new. ;. 8o to -tmp-new and make your modifications. <. 8o back to the original source tree and generate the patch with diff $
3urp -tmp-old -tmp-new 4 mypatchname.patch. Mxample <. Let us make a new patch for ude6 called >?&penguins!patch which replaces Linux with Penguin in the ude6 -(,'/( file, cd udevBcp $a . -tmp-old pushd -tmp-old debian-rules patch cp $a . -tmp-new? cd ..-new sed $i 7s-'inux-%enguin-g7 QM0#MM cd .. diff $3urp old new 4 O5;penguins.patch popd mv -tmp-O5;penguins.patch debian-patches rm $rf -tmp-old -tmp-new Mxample D. Note: This example may not work in later versions of udev where 10-selinux-include-udev-h.patch does not exist.

!hat happens if we want to edit an existing patchJ !e can use a procedure similar to the one in Mxample <, but we must apply the patch to be edited first, cp $a . -tmp-old pushd -tmp-old cp $a . -tmp-new cd ..-new? patch $p< 6 debian-patches-<5$selinux$include$udev$h.patch sed $i 7< s-A-BBBBB M'': !:Q'# BBBB-7 udev;selinux.c cd .. diff $3urp old new 4 <5$selinux$include$udev$h.patch popd mv -tmp-<5$selinux$include$udev$h.patch debian-patches rm $rf -tmp-old -tmp-new /o this way of patching the source, while technically fine, can become very complicated and unmanageable. To make patching easier and more straightforward, patch systems were developed. !e will take a look at couple of the most popular ones.

(#"/ with /imple %atchsys )Mxample %ackage, pmount*

The 4!78 build"helper system 0see Packaging with 4!781 has a &ery simple patch system built in. -ou .ust need to add an include for simple-patchsys!mk in debian/rules. An e ample is the package pmount, whose entire rules file consists of the following, include -usr-share-cdbs-<-rules-debhelper.mk include -usr-share-cdbs-<-class-autotools.mk include -usr-share-cdbs-<-rules-simple$patchsys.mk common$post$build$arch,, [ 8enerate a %:T file cd po? intltool$update $p $$verbose The module simple$patchsys.mk has that name for a reason, it comes with absolutely no bells or whistles whatsoever. 3evertheless, it has won popularity because it7s sufficiently complex for most tasks, and because long ago Martin %itt wrote the script cdbs$edit$patch, which has made people7s lives a lot easier. This script is provided with the cdbs package by default? the way it works, you simply supply the name of a patch to the script, and depending on whether or not that name is already present, cdbs$edit$patch will either create a new patch or edit the existing one with that name. )That is to say, the commands to create and edit patches using cdbs$edit$patch are identical.* Mxecution of the script opens a new shell, where you make your changes to the patch? once you7ve finished, (trl.# closes the embedded shell and saves your changes todebian-patches-. Mxample with pmount, cd -wherever-you-unpacked-the-source-pmount$5.O.<< cdbs$edit$patch 5F$simple$readme.patch echo 7This should document pmount7 4 QM0#MM 6%ress (trl.# to end your editing session4

/ince the Ubuntu Mdgy version of cdbs, cdbs$edit$patch also works for packages using tarball.mk, and it can edit patches which produce reVections.

dpatch
A popular patch system is dpatch. 't has a dpatch-edit-patch script like cdbs has but stores the patches a little differently. 't uses a file named debian/patches/??list to find the name and order of patches to apply. This means you can order your patches in whiche&er way you want and can disable a patch without remo&ing it altogether. +owe&er, it also means you need to update ??list if you add a patch. 'f dpatch-edit-patch is called with two arguments it will edit5create the patch named by the first argument relati&e to the patch named by the second argument. 'n other words, dpatch$edit$patch new.dpatch old.dpatch will apply patches up to old.dpatch and then create new.dpatch. 3ote that dpatch patches usually have a .dpatch suffix. This is becausedpatch stores the patches in a slightly different format than a normal patch that adds a special header. &uilt )Mxample %ackage, xterm* %uilt is the other non"dumb standard patch system. Like dpatch, it has a list of patches to apply in debian/patches/series. This link should be helpful, ^uilt for #ebian maintainers elpful step$by$step walkthrough with explanations of ^uilt, ^uilt, 0 %atch Management /ystem, to /urvive !ith Many %atches T:#:, the below should be updated, at the moment the link above is much nicer owever, &uilt is non$trivial to set up and has a lot of advanced commands which make it very flexible, but not all that easy to use. !e will only look at a small example here. First, set yourself up to use &uilt, cd -wherever-you-unpacked-the-sourcemkdir debian-patches export ^UI'T;%0T( M/Tdebian-patches touch debian-patches-series 3ote that once ^UI'T;%0T( M/ is set, you cannot use cd to move around the source tree and expect &uilt to operate sanely. +ou need to stay in the top$level source directory for any &uilt operations. For convenience )especially if you only use ^uilt for packaging*, you can add ^UI'T;%0T( M/Tdebian-patches to C-.&uiltrc 3ow, let7s edit the already existing patch O5<;xterm;manpage.diff, &uilt push O5<;xterm;manpage.diff sed $i 7s-(opyright-(opyleft-7 xterm.man &uilt refresh O5<;xterm;manpage.diff &uilt pop $a Unlike the other patch systems, &uilt works with patched inline sources, but it keeps track of modifications. ow

Finally, let7s add a new patch to the top of the stack, &uilt push $a &uilt new muhaha.diff &uilt add QM0#MM [ you have to do that for all files you modify sed $i 7< s-`-MU 0 0-7 QM0#MM &uilt refresh &uilt pop $a For a full introduction to &uilt, this pdf is &uite useful. %atching :ther %eople7s %ackages The most important thing to keep in mind when patching packages maintained by other people is to keep the patch system )or lack thereof* that the maintainer has set up. This will ensure consistency and make the package maintainer more likely to accept your patch. It is also a good idea to separate patches logically rather than creating one giant patch. If the upstream authors apply one of your changes but not another it is much easier to Vust drop a patch than edit a monolithic patch to update it.

S#M
While 7asic Packaging is a guide for packaging in general, this section deals with the B!>"specific points. If you haven7t already done so, all the software listed in the #ebian 3ew Maintainer7s 8uide and #ebian #eveloper7s Qeference must be installed to package software for S#M. 0lso recommended,

The kdesdk package, which provides many useful applications and scripts docbookDx, which it is useful for converting #oc"ook format into man pages. )#ebian policy
re&uires that every single application have a man page\* Mssential %ackaging "its B!> * applications typically use the G#$ autoconf5automake build system. There is a 4!78 include file designed for B!>, include -usr-share-cdbs-<-class-kde.mk +ou will need to build$dep on kdelibs=$dev and, if the package builds kcontrol modules, kdebase$dev. If you patch any Makefile.am or configure.in files, you will need to re$run auto$tools, which can be done using the following line, make $f debian-rules buildprep 3ote that this step is necessary if upstream has not packaged a configure file.

S#M = applications use a new build system, (Make. The way we build S#M = packages is still changing so there is no file included in (#"/ yet. +ou can get a suitable kde.mk by downloading the source for kde=libs and copying debian-cdbs. include debian-cdbs-kde.mk +ou will need to build$depend on kdelibsE$dev and sometimes also libphonon$dev and kdepimlibsE$ dev. If there is already a S#M F application with the same name in the archives, rename the package 6appname4$kde=. S#M Manpages The template for a B!> manpage can be found here. This file is a standard file for a basic S#M application. (ustomi2e it for your application and check that every important command line option is described in detail. If you don7t want to edit the file by hand, install the manedit package and type manedit Kmanpage name or fileL 0dd a build$depend on docbookDx in debian-control. 0fter that Vust add this line to the debian-rules file )assuming the name of the binary package is myapp*, build-myapp,, docbookDx$man debian-myapp.<.docbook cleanbuilddir-myapp,, rm $f myapp.< #M";I3/T0'';M03%08M/;myapp T myapp.< :f course, you have to replace myapp.<.docbook with your manual source file. +ou also have to add a docbookDx build dependency to thedebian-control file. If you have more than one manpage to install )e.g. if your .deb installs a program and its daemon* simply separate their names with a space, #M";I3/T0'';M03%08M/;myapp T myapp.< myappdaemon.U 0s an alternative you can use the kdemangen.pl script to generate a man page based on the command line help of the program.

/upplementary Files

.desktop Files
'n order to ensure that the menus are properly populated, and that software is easily installable from the Add53emo&e... software, each package should contain a !desktop file. As a matter of policy, !desktop files should only be present for G$' interfaces, software intended to be used from the command line should not pro&ide such an interface.

.desktop files may be included in packages in two ways, either as part of the upstream distribution, or as part of the distribution packaging. Including the .desktop file in the upstream distribution is vastly preferred, as this allows for appropriate translation of the .desktop file. If it cannot be included upstream, the .desktop file should be stored in the debian- directory. (riteria for the inclusion of .desktop files, <. The package must provide a binary with a 8UI interface D. The binary must be typically executed with constant arguments F. Users would expect to launch the program from the menu %ackages typically not needing a .desktop file are, !indow Managers, programs that do not have sensible defaults, programs that only act on files )rather than having a standard interface*, programs that have no 8UI, programs that start up invisible. /ome packaging notes,

In debian-control, if cdbs is not used, build$depend on debhelper )4T =.D.D<*. ensure that .desktop files are installed or moved to -usr-share-applications-6binary4.desktop ensure that icon files are installed or moved to -usr-share-pixmaps/ome ideas about icons, %rovide a FDxFD$pixel R%M icon for use by the #ebian menus :ptionally provide a =Ux=U$pixel %38 icon for use by freedesktop.org menus )the #ebian icon will be used if this is unavailable* If neither format is available, many formats can be converted as follows,

8et a base icon )clip of package graphic, .ico file, from scratch, etc.*
(rop or resi2e to FDxFD pixels If convert generated multiple images, select one )and name correctly*

Qun convert editedicon.ico 6package4.xpm )re&uires imagemagick*

0bout .desktop files generally,

(heck the specifications 0void absolute pathnames in .desktop files #o not include a file$type extension in IconT Mnsure that (ategoriesT includes at least one Qegistered (ategory
0dd any other applicable 0dditional (ategories

(heck with desktop$file$validate to ensure everything is correct

The !orkflow,

Find a package without a .desktop file Perify there is no .desktop file in the latest development version If no .desktop file is needed, add the package to the list below If a .desktop is needed, (heck to see if there is a .desktop in the upstream or #ebian bug tracker

 (reate the necessary .desktop file-icon if necessary :pen a wishlist bug in the package reporting the missing .desktop file 0ttach the .desktop file and icon to the bug )optionally a patch for both*
'ink the bug to the #ebian "T/ )create a "T/ bug if re&uired*

Tag the bug with >desktop$file>

/imple creation techni&ues, In 83:MM, use 3autilus7 >(reate 'auncher> to create a template file /cripted, /ome of this can be automated. %lease check the results of the automation prior to submission. Most importantly, please ensure that any useful additional categories are included.

/hell snippets that might prove useful, Using an absolute path for an icon, grep $M >`IconT@-usr@-> -usr-share-applications-B.desktop 1 cut $d, $f< 1 xargs dlocate Using an absolute path for a binary, grep $M >`MxecT@-usr@-> -usr-share-applications-B.desktop 1 cut $d, $f< 1 xargs dlocate

.desktop file fails validation,

for i in -usr-share-applications? do desktop$file$validate Ai 44 -dev-null 11 echo Ai? done 1 xargs dlocate 0 minimal desktop file for a program to appear in the application menu looks like this, K#esktop MntryL TypeT0pplication 3ameTfoo 3ameKxxLTfoo 8eneric3ameT"ar description MxecTkfoo IconTkfoo TerminalTfalse (ategoriesT^t?S#M?Utility? +ou should ensure that the icon pointed to by IconT exists in the hicolor namespace and not in the crystalsvg or oxygen themes, this is so it can be found by 83:MM and other desktops. /ome notes about S#M .desktop files, B!> also uses !desktop files to describe many resources such as libraries to be loaded or kcontrol modules. .desktop files for applications should be in -usr-share-applications-kde for S#M F or -usr-share-applications-kde= for S#M =. /ometimes packages install the .desktop file in the old directory )-usr-share-applnk*. +ou may want to copy the furnished .desktop file to the new location )-usr-share-applications-kde*. 0dd these lines to debian-rules,

install-myapp,, [other stuff dh;install desktop;file usr-share-applications-kde

Man %ages

Using %:#
P:! is a &ery simple but also elegant format for writing manual pages. 't is much easier to learn than writing it directly in groff or using other alternati&es like !oc7ook.

"asic template
"elow is a sample manpage template in %:# format. (ustomi2e it for your application and check that every important command line option is described in detail. +ou can also see a real example. Thead< 30MM (ommand $ /hort one$line description. Thead< /+3:%/I/ command Koptions...L Thead< #M/(QI%TI:3 (ommand is a foo that does bar. Thead< :%TI:3/ Tover U Titem "6$$keyTI6value44 Uses the given value as key. Titem "6$$moo4 /hows an easter egg )don7t explain this in real man pages ?**. Titem "6$$stupid$example4 #oesn7t do anything. Titem "6$$version4 #isplays information about the currently installed version and exists. Thead< "U8/

This command has absolutely no bugs, as I have written it. 0lso, as it has no bugs, there is no need for a bug tracker. Thead< 0UT :Q/ "6command4 was written by Woe acker 6Voe.hackerIexample.com4 and Wohn #ough 6guy<D9UIexample.net4. This manual page was written by (ool %ackager 6myselfIexample.com4. "oth are released under the 83U 8eneral %ublic 'icense, version F or later. Tcut

/ome formatting options

"6...text...4 $ >...text...> will be shown in bold. I6...text...4 $ >...text...> will be shown in italics. Usually, the command name is always written in bold )except in the 30MM and /+3:%/I/ sections*, and variables that the user should replace in italics )as in $$keyTI6value4*.

3ecessary packaging changes $ 0dd a build dependency on perl in debian-control.

$ 0fter that Vust add this line to the debian-rules file )assuming the name of the binary package is myapp and that it is using cdbs*, build-myapp,, podDman $$sectionT< $$releaseTA)PMQ/I:3* $$center >> debian-myapp.pod 4 myapp.< cleanbuilddir-myapp,, rm $f myapp.< #M";I3/T0'';M03%08M/;myapp T myapp.< :f course you have to replace myapp.pod with the name of your manpage source file, and the section number with that one corresponding to what you are documenting )see man man for a list of all sections*. If you have more than one manpage to install )e.g. if your .deb installs a program and its daemon* simply separate their names with a space, #M";I3/T0'';M03%08M/;myapp T myapp.< myappdaemon.U

Qecipes 3ote, %ackaging8uide-Qecipes may offer some recipes not included below.

Updating an Ubuntu %ackage

'n this recipe, we will update the package brasero from &ersion ?!8!"-?ubuntu$ to &ersion ?!@!$-?ubuntu$. This will ser&e as an introduction to the common practice of updating a package to a new upstream &ersion. Ingredients

(. To sign the package once it2s finished, you2ll need a GPG key. 8ee the GnuPri&acyGuard+owto for a guide. ). The debian packaging tools use some environment variables to put your name and e$mail
address in the changelog and to find your 8%8 key I#. To set these up, edit C-.bashrc and add your name and mail address )the ones you used for the 8%8 key*, example, export #M"FU''30MMT7#aniel olbach7 export #M"MM0I'T7daniel.holbachIubuntu.com7 to make these changes take affect, start a new terminal or type source C-.bashrc in the terminal.

*. pbuilder is a very handy command used to test$build packages. /ee the %builder owto for a
guide to setting it up for the active development release. =. Install some necessary tools, sudo apt$get install devscripts build$essential wget cdbs fakeroot liburi$perl debhelper pbuilder dpatch &uilt gnome$pkg$tools Method

(. Get the source for the old brasero package. $sually you would run apt-get source brasero, but since this
is .ust an e ample, do instead, dget $xu http,--people.ubuntu.com-Cdholbach-motu-brasero;5.E.D$5ubuntu<.dsc

). 8et the new source. Usually you would look up where the old version was downloaded from
)check debian-copyright* or usedebian-watch. "ut again, since this is a prepared example, wget http,--people.ubuntu.com-Cdholbach-motu-brasero$5.9.<.tar.g2 F. Unpack and rename the new source tarball, tar xf2 brasero$5.9.<.tar.g2 mv brasero$5.9.<.tar.g2 brasero;5.9.<.orig.tar.g2 3ote, If you use the 6package name4;6version4.orig.tar.g2 scheme, a .diff.g2 file containing all of your changes to the upstream tarball will be generated automatically during one of the next steps. =. (opy the packaging from the old source tree into the new one, cp $r brasero$5.E.D-debian brasero$5.9.<-

<. 0dd a debian-changelog entry,

cd brasero$5.9.<

dch $i ere you enter something like >3ew upstream version> and make sure the version number is 5.9.<$5ubuntu<. 9. "uild the source package, debuild $/ $sa

C. "uild the binary with pbuilder,

cd .. sudo pbuilder build brasero;5.9.<$5ubuntu<.dsc The results will be stored in -var-cache-pbuilder-result-. U. 0nd you are done\ 3ote, This package may not build in pbuilder on Intrepid and later releases of Ubuntu. It appears that the oled brasero package uses an older version of 8((. +ou should not have this problem building other packages. For "onus %oints...

(. 4heck the file configure!in for changes which need to be reflected in the packaging,
diff $u brasero$5.XE.D,9.<Y-configure.in In some cases, this file may be called configure.ac. Most software programmed in ( or (.. includes this file? it generates checks during the configure run of the build. 'ooking closely at the diff, you will notice that most changes are reformatting and the only one that might be relevant is $'I""UQ3;QM^UIQM#T5.D.F .'I""UQ3;QM^UIQM#T5.F.= /ince a look at debian-control reveals that libburn goes unused here, we are done.

). Qead the 3M!/ file,

less brasero$5.9.<-3M!/ This file, if included by upstream, contains valuable information about the package update. !hile maintaining a package, it is important not to neglect the 3M!/ file. F. (ompare the contents of the old package and the new package, wget http,--people.ubuntu.com-Cdholbach-motu-brasero;5.E.D$5ubuntu<;iFU9.deb debdiff brasero;5.E.D$5ubuntu<;iFU9.deb -var-cache-pbuilder-result-brasero;5.9.<$ 5ubuntu<B.deb The output will show you that some icons have been replaced and some translations added. Mverything looks good here\ Wust remember that, in order to download the old package, you would normally have to run a command such as the following,

aptitude download brasero

;. (heck debian-watch or create if it doesn7t exist <. 3ow, get to work fixing some upgrade bugs\
(reating a #ebdiff

Use Ubuntu Merge %roposals

To make use of $buntu merge proposals, follow these easy steps,

set up the tools get the source work on the package seek sponsorship
In short, <. 8et set up, A sudo apt$get install b2r b2r$builddeb A b2r whoami >Wames !estby 6Vames.westbyIubuntu.com4> A b2r launchpad$login Vames$w D. 8et the source, A b2r branch lp,ubuntu-seccure seccure or for a particular release, A b2r branch lp,ubuntu-hardy$proposed-seccure hardy$proposed F. (reate branch for specific bug fix, A b2r branch seccure seccure.fix$<DF=E =. Make changes. <. Make sure you mention the bug you worked on in debian-changelog )ie, )'%, [=O=N5=** 9. Qun A debcommit N. %ush change to 'aunchpad, A b2r push lp,CVames$w-ubuntu-karmic-seccure-seccure$fix$<DF=E U. :pen branch in browser, A b2r lp$open O. (lick on >%ropose for merging into another branch>.

(onsult the Qelease /chedule Which work can be integrated into $buntu relies hea&ily on where in the release cycle we are. 7efore reading on, consult the current release schedule and find out.

The beginning of the release cycle is usually the best time to get intrusive changes applied. 0fter FeatureFree2e, you will need to get a free2e exception.

If you want to get a change into a stable release, you need a /QU exception. More decision making help.
Traditional %rocess 'n this recipe, we will fi a simple bug and create a corresponding debdiff, which could be sent to others or attached to bug reports to apply a bug fi . This recipe will not do all of the work that edit$patch does to make a tidy patch for submission, with correct patch name and changelog file. Most developers should use edit$patch when submitting debdiff patches, this procedure is for more advanced users who will be manually changing the patch names and changelog. Ingredients (. The debian packaging tools use some en&ironment &ariables to put your name and e"mail address in the changelog and to find your GPG key '!. To set these up, edit ~/!bashrc and add your name and mail address 0the ones you used for the GPG key1, e ample, export #M"FU''30MMT7#aniel olbach7 export #M"MM0I'T7daniel.holbachIubuntu.com7 to make these changes take effect, start a new terminal or type source C-.bashrc in the terminal.

). pbuilder is a very handy command used to test$build packages. /ee the %builder owto for a
guide to setting it up for the active development release. F. Install some necessary tools, sudo apt$get install devscripts build$essential wget fakeroot cdbs patchutils debhelper

;. To sign the package once it7s finished, you7ll need a 8%8 key. /ee
the 8nu%rivacy8uard owto for a guide. 3ote that this is only important if you plan to upload the result to a access$restricted archive directly , most of the time it is not important when creating a debdiff. Method (. Let2s pretend we got a bug report saying that colour in the description of 0icc should be color and we want to fi it. (This is just a bad joke and a bad example. /irst &erify if that2s true, A apt$cache show xicc %ackage, xicc %riority, optional /ection, universe-x<< Installed$/i2e, ND Maintainer, Qoss "urton 6rossIdebian.org4

0rchitecture, amd9= Persion, 5.D$D #epends, libc9 )4T D.F.=$<*, libglibD.5$5 )4T D.U.5*, libice9, libsm9, libx<<$9 Filename, pool-universe-x-xicc-xicc;5.D$D;amd9=.deb /i2e, UDD= M#Esum, aD99d95cdND<efO<fcb<dFd=Necd9a=5 / 0<, bUdaD<bUdfbaNedOcNac9faEcOcFeN5b=FUdN<D= / 0DE9, 9FEcDUNa<c=FdfF<9N5aD5<O=eNN=E9<=NOdN5dOU<bfD=c<=FcFN<<NOObdUFOa #escription, set the I(( colour profile for an R display This utility lets you set an I(( colour profile for an R display, so that applications can use it to display colour calibrated images. 0pplications have to specifically look for this atom but several applications such as 8imp and Mye :f 8nome already do. "ugs, mailto,ubuntu$usersIlists.ubuntu.com :rigin, Ubuntu D. Time to act on it... get the source of the package, dget $xu http,--people.ubuntu.com-Cdholbach-motu-xicc;5.D$D.dsc )!e would typically do this with >apt$get source xicc> or >pull$lp$source xicc> )which is included in ubuntu$dev$tools* ? dget is used in this example to grab this specific file*

*. Mdit debian-control and fix colour,

cd xicc$5.D sed $i 7s-colour-color-g7 debian-control :f course patching is not always that easy and you might have to patch bigger parts of the package. %lease refer to our %atch guidelines.

;. 0dhere to #ebianMaintainerField, Mdit debian-control and replace

Maintainer, Qoss "urton 6rossIdebian.org4 with Maintainer, Ubuntu #evelopers 6ubuntu$devel$discussIlists.ubuntu.com4 R/"($:riginal$Maintainer, Qoss "urton 6rossIdebian.org4 +ou can use the update$maintainer tool )in the ubuntu$dev$tools package* for that.

<. Update debian-changelog,

dch $i and describe the changes you did. 9. 8enerate a new source package, debuild $/ or if you7re creating an unsigned package,

debuild $/ $us $uc N. 'ook at the debdiff, cd .. debdiff xicc;5.D$D.dsc xicc;5.D$Dubuntu<.dsc 1 less U. To create a patch file that you can send to others, run debdiff xicc;5.D$D.dsc xicc;5.D$Dubuntu<.dsc 4 xicc;5.D.Dubuntu<.debdiff

D. 0nd we7re done. +ou can now attach the debdiff to a bug report or send it to the relevant
person. /ponsorship%rocess explains how to get a package uploaded to Ubuntu. (reating and Using a debian-watch File This recipe demonstrates how it can be useful to include a debian/<atch file in your package and how to upload a new upstream &ersion for a package. 'n this case, we will be updating package medit from &ersion ?!A!8-$ to &ersion ?!>!#?ubuntu$ using tools uscan and uupdate. Ingredients

(. To sign the package once it is ready, you will need a GPG key. 8ee GnuPri&acyGuard+owto for a guide. ). #ebian packaging tools use some environment variables to put your name and e$mail address
in the changelog and to find your 8%8 key I#. To set these up, edit C-.bashrc and add your name and mail address )the ones you used for the 8%8 key*, example, export #M"FU''30MMT70rthur 'oiret7 export #M"MM0I'T7arthur.loiretIgmail.com7 to make these changes take effect, start a new terminal or type source C-.bashrc in the terminal.

*. pbuilder is a very handy command used to test$build packages. /ee the %builder owto for a
guide on how to set it up for the current development release. =. Install some necessary tools, sudo apt$get install devscripts build$essential wget fakeroot Method

(. >nter the following to download the source for the medit package,
dget $xu http,--people.ubuntu.com-Cdholbach-motu-medit;5.U.E$<.dsc

). 3ow, instead of looking for new upstream versions manually, we are going to add
a debian-watch file to the package. This will allow us to check automatically for new upstream versions using the tool uscan. The first line of the watch file must be the format version )F, at the time of this writing*, while the following lines contain any UQ's to parse. For example, versionTF

http,--sf.net-mooedit-medit$)@d.B*@.tar@.b2D 0s you can see from the above, the syntax for /ourceForge proVects ishttp,--sf.net-6proVect;name4-6tarball;name;with;regex4. This means that if the proVect were in a tar.g2 file, you would have to change the b2D to g2 in the UQ'. /ee the uscan man page for more information.

*. 3ext, we run uscan from the source directory to ensure that the debian-watch file is working,
uscan $$verbose $$ /canning for watchfiles in . $$ Found watchfile in .-debian $$ In debian-watch, processing watchfile line, http,--sf.net-mooedit-medit$)@d.B*.tar.b2D $$ Found the following matching hrefs, medit$5.9.OU.tar.b2D medit$5.9.OO.tar.b2D medit$5.N.5.tar.b2D medit$5.N.<.tar.b2D medit$5.N.O.tar.b2D medit$5.N.OE.tar.b2D medit$5.N.O9.tar.b2D medit$5.N.ON.tar.b2D medit$5.U.5.tar.b2D medit$5.U.<.tar.b2D medit$5.U.<5.tar.b2D medit$5.U.<<.tar.b2D medit$5.U.D.tar.b2D medit$5.U.F$bD5595DDF.tar.b2D medit$5.U.F.tar.b2D medit$5.U.=.tar.b2D medit$5.U.E.tar.b2D medit$5.U.9.tar.b2D medit$5.U.N.tar.b2D medit$5.U.U.tar.b2D medit$5.U.O.tar.b2D medit$5.O.5.tar.b2D medit$5.O.<.tar.b2D medit$5.O.D.tar.b2D medit$5.O.F.tar.b2D medit$5.O.=.tar.b2D 3ewest version on remote site is 5.O.=, local version is 5.U.E T4 3ewer version available from http,--&a.debian.org-watch-sf.php-mooedit-medit$5.O.=.tar.b2D $$ #ownloading updated package medit$5.O.=.tar.b2D $$ /uccessfully downloaded updated package medit$5.O.=.tar.b2D and symlinked medit;5.O.=.orig.tar.b2D to it $$ /can finished

0nd now we have the new upstream version\

;. 3ote the tarball7s file extension using the ls command,

ls .. medit$5.U.E- medit;5.U.E$<.diff.g2 medit;5.U.E$<.dsc medit;5.U.E.orig.tar.g2 medit;5.O.=.orig.tar.b2D medit$5.O.=.tar.b2D Though you were probably expecting to find a .orig.tar.g2 file extension, you can see that the tarball is actually calledmedit;5.O.=.orig.tar.b2D. +ou do not have to worry about the particular archive type, as uupdate supports the .tar.g2, .tar.b2D,.tar.a, .tg2, .tar and .2ip formats. owever, if you are still concerned and wish to have a .orig.tar.g2 file instead, be sure to read(hanging:rigTarball before making any changes to the original tarball.

<. 3ow, run uupdate on the new original tarball,

uupdate ..-medit;5.O.=.orig.tar.b2D 3ew Qelease will be Z5.O.=$5ubuntu<Z. $$ Untarring the new sourcecode archive ..-medit;5.O.=.orig.tar.b2D U out of << hunks F0I'M# $$ saving reVects to file config.sub.reV = out of 9 hunks F0I'M# $$ saving reVects to file config.guess.reV uupdate, the diffs from version 5.U.E$< did not apply cleanly\ QeVected diffs are in .-config.sub.reV .-config.guess.reV Qemember, +our current directory is the :'# sourcearchive\ #o a >cd ..-medit$5.O.=> to see the new package )#id you see the warnings aboveJ* )#o not worry about the failure on config.sub as it is typical.* +ou have to update the changelog file and be sure that it builds correctly. The easiest and the cleanest way to do this is to run dch $e, which should produce the following results, medit )5.O.=$5ubuntu<* intrepid? urgencyTlow B 3ew upstream release B 0dd debian watch $$ +our 3ame 6your.nameIurl.com4 Tue, 5= 3ov D55U D5,FD,DD $5E55 +our package is almost ready now\ 9. Finally, let us test the new upstream release, debuild $/ $sa sudo pbuilder build ..-medit;5.O.=$5ubuntu<.dsc 3ote, The above method is exactly the same for an Ubuntu package, except that the version field in the changelog file needs to be updated to reflect the package7s revision number.

3otes /teps F and E )of the howto* can be combined by using additional parameters in the UQ' line of the watch file versionTF http,--sf.net-medit-mooedit$).B*.tar.b2D debian uupdate +ou may want to continue at M:TU-(ontributing[head$ bD5EcN=eDNfe<EeNOe<5cOeNf<=dFcdfbFEOdU<d to create an interdiff for sponsorship.

0ppendix
0dditional Qesources
Debian Resources

#ebian 3ew Maintainers 8uide $ 8ood resource for learning to package. #ebian %olicy $ The essential %olicy manual for #ebian and #ebian$based distros. #ebian #eveloper7s Qeference $ /pecific information for #ebian #evelopers but has some
items of interest for packagers.

'ibrary %ackaging 8uide $ 8uide for packaging libraries. #ebian !omen %ackaging Tutorial $ 0nother good introduction to #ebian packaging. #ebian Mentors F0^ debian$mentors mailing list $ new maintainers can ask &uestions and find a #ebian sponsor
here

8enerating multiple binaries from a single source #ebian 3ew %ython %olicy #ebian ('I %olicy #ebian %ackaging andbook packaging from upstream /P3 repository #ebian Type of /ections
!iki Qesources

M:TU-8etting/tarted %ackaging8uide Ubuntu#evelopment %builder owto #ebootstrap(hroot Ubuntu#evelopment-3ew%ackages

:ther Qesources

I"M %ackaging Tutorial #uckcorp (#"/ #ocumentation Ubuntu (#"/ #ocumentation. Managing packages with /ubversion and pbuilder (reating .desktop files )(ategories* #ebian 'ibrary %ackaging 8uide Make Manual )debian-rules is a Makefile*
Mxample files

Readme.Debian is used to document changes that you ha&e made to the original upstream source that other people
might need to know or information specific to !ebian or Ubuntu.

conffiles.ex, If the package installs a configuration file, when the package is

upgraded dpkg can prompt a user whether to keep his or her version if modified or install the new version. /uch configuration files should be listed in conffiles )one per line*. #o not list configuration files that are only modified by the package or have to be set up by the user to work.

cron.d.ex, If your package re&uires regularly scheduled tasks to operate properly, you can use
this file to configure it. If you use this file, rename it to cron.d.

dirs specifies the directories that are needed but the normal installation procedure
)make installapplication* somehow doesn7t create.

docs specifies the filenames of documentation files that dh;installdocs will install into the
temporary directory.

emacsen$B.ex specifies Mmacs files that will be bytecompiled at install time. They are installed
into the temporary directory bydh;installemacsen.

init.d.ex, If your package is a daemon that needs to be run at system startup rename this file
to init.d and adVust it to your needs.

manpage.<.ex and manpage.sgml.ex are templates for man pages if the package does not
already have one.

menu.ex is used to add your package to the #ebian menu. Ubuntu uses
the freedesktop.org standard .desktop files but remember that packages in Universe-Multiverse are widely used in other )desktop$less* environments. "eside, we strongly want to give$back to #ebian )where menu files are re&uired by policy*, therefore you are encouraged to include them in your Ubuntu package too.

watch.ex, The package maintainer can use the uscan program and a watch file to check for a
new upstream source tarball. )%ackaging8uide-Qecipes-#ebian!atch*

ex.package.doc$base is used to register your package7s documentation )other

than man and info pages* with doc$base.

 postinst.ex, preinst.ex, postrm.ex, and prerm.ex, These maintainer scripts are run
by dpkg when the package is installed, upgraded, or removed. For more details refer to the #ebian 3ew Maintainer7s 8uide. 'ist of #ebhelper Tools

dh&builddeb " build debian packages dh;clean $ clean up package build directories dh;clideps $ calculates ('I ).3MT* dependencies dh;compress $ compress files and fix symlinks in package build directories dh;desktop $ Qegister .desktop files dh;fixperms $ fix permissions of files in package build directories dh;gconf $ generate 8(onf schema registration scripts dh;gencontrol $ generate and install control file dh;install $ install files into package build directories dh;installcatalogs $ install and register /8M' (atalogs dh;installchangelogs $ install changelogs into package build directories dh;installcligac $ register assemblies to be late installed into a 80( dh;installcron $ install cron scripts into etc-cron.B dh;installdeb $ install files into the #M"I03 directory dh;installdebconf $ install files used by debconf in package build directories dh;installdefoma $ install a defoma related scripts dh;installdirs $ create subdirectories in package build directories dh;installdocs $ install documentation into package build directories dh;installemacsen $ register an emacs add on package dh;installexamples $ install example files into package build directories dh;installinfo $ install and register info files dh;installinit $ install init scripts into package build directories dh;installlogcheck $ install logcheck rulefiles into etc-logcheck dh;installlogrotate $ install logrotate config files dh;installman $ install man pages into package build directories dh;installmanpages $ old$style man page installer dh;installmenu $ install debian menu files into package build directories dh;installmime $ install mime files into package build directories

 dh;installmodules $ register modules with modutils dh;installpam $ install pam support files dh;installppp $ install ppp ip$up and ip$down files dh;installtex $ register Type < fonts, languages, or formats with TeR dh;installudev $ install udev rules files dh;installwm $ register a window manager dh;installxfonts $ register R fonts dh;installxmlcatalogs $ install and register RM' catalog files dh;link $ create symlinks in package build directories dh;listpackages $ list binary packages debhelper will act on dh;make $ #ebiani2e a regular source archive dh;makeclilibs $ automatically create clilibs file dh;makeshlibs $ automatically create shlibs file dh;mdEsums $ generate #M"I03-mdEsums file dh;movefiles $ move files out of debian-tmp into subpackages dh;perl $ calculates perl dependencies dh;pycentral $ use the python$central framework to handle %ython modules and extensions dh;pysupport $ use the python$support framework to handle %ython modules dh;python $ calculates python dependencies and adds postinst and prerm python scripts dh;scrollkeeper $ generate /crollSeeper registration scripts dh;shlibdeps $ calculate shared library dependencies dh;strip $ strip executables, shared libraries, and some static libraries dh;suidregister $ obsolete suid registration program dh;testdir $ test directory before building debian package dh;testroot $ ensure that a package is built as root dh;testversion $ ensure that the correct version of debhelper is installed dh;undocumented $ obsolete undocumented.N symlink program dh;usrlocal $ migrate usr-local directories to maintainer scripts