%trans; %common; %version; ]> Josip Rodin joy-mg@debian.org original contents Osamu Aoki osamu@debian.org updated contents &othercredit; version &docversion; &docisodate; 1998-2002 Josip Rodin 2005-2011 Osamu Aoki 2010 Craig Small 2010 Raphaël Hertzog This document may be used under the terms the GNU General Public License version 2 or higher. This document was made using with these two documents as examples: Making a Debian Package (AKA the Debmake Manual), copyright © 1997 Jaldhar Vyas. The New-Maintainer's Debian Packaging Howto, copyright © 1997 Will Lowe. This document tries to describe the building of a Debian package to ordinary Debian users and prospective developers. It uses fairly non-technical language, and it's well covered with working examples. There is an old Latin saying: Longum iter est per praecepta, breve et efficax per exempla (It's a long way by the rules, but short and efficient with examples). This document has been updated for the Debian &base-release; release. The document assumes you are using a &base-release; or newer system. If you need to follow this text in an older system (including an older Ubuntu system etc.), you must install backported dpkg and debhelper packages, at least. One of the things that makes Debian such a top-notch distribution is its package system. While there is a vast quantity of software already in the Debian format, sometimes you need to install software that isn't. You may be wondering how you can make your own packages; and perhaps you think it is a very difficult task. Well, if you are a real novice on Linux, it is hard, but if you were a rookie, you wouldn't be reading this document now :-) You do need to know a little about Unix programming but you certainly don't need to be a wizard. You can learn about the basic handling of a Debian system from the Debian Reference. It contains some pointers to learn about Unix programming, too. One thing is certain, though: to properly create and maintain Debian packages takes many hours. Make no mistake, for our system to work the maintainers need to be both technically competent and diligent. If you need some help on packaging, please read . Newer versions of this document should always be available online at and in the maint-guide package. The translations may be available in packages such as maint-guide-es. Please note that this documentation may be slightly outdated. Since this is a tutorial, I choose to explain each detailed step for some important topics. Some of them may look irrelevant to you. Please be patient. I have also intentionally skipped some corner cases and provided only pointers to keep this document simple.

Here are some observations of Debian's social dynamics, presented in the hope that it will prepare you for interactions with Debian. We all are volunteers. You cannot impose on others what to do. You should be motivated to do things by yourself. Friendly cooperation is the driving force. Your contribution should not overstrain others. Your contribution is valuable only when others appreciate it. Debian is not your school where you get automatic attention of teachers. You should be able to learn many things by yourself. Attention from other volunteers is a very scarce resource. Debian is constantly improving. You are expected to make high quality packages. You should adapt yourself to change. There are several types of people interacting around Debian with different roles. upstream author: the person who made the original program. upstream maintainer: the person who currently maintains the program. maintainer: the person making the Debian package of the program. sponsor: a person who helps maintainers to upload packages to the official Debian package archive (after checking their contents). mentor: a person who helps novice maintainers with packaging etc. Debian Developer (DD): a member of the Debian project with full upload rights to the official Debian package archive. Debian Maintainer (DM): a person with limited upload rights to the official Debian package archive. Please note that you cannot become an official Debian Developer (DD) overnight, because it takes more than technical skill. Please do not be discouraged by this. If it is useful to others, you can still upload your package either as a maintainer through a sponsor or as a Debian Maintainer. Please note that you do not need to create any new package to become an official Debian Developer. Contributing to the existing packages can provide a path to becoming an official Debian Developer too. There are many packages waiting for good maintainers (see ). Since we focus only on technical aspects of packaging in this document, please refer to the following to learn how Debian functions and how you can get involved. Debian: 17 years of Free Software, "do-ocracy", and democracy (Introductory slides) How can you help Debian? (official) The Debian GNU/Linux FAQ, Chapter 13 - "Contributing to the Debian Project" (semi-official) Debian Wiki, HelpDebian (supplemental) Debian New Maintainer site (official) Debian Mentors FAQ (supplemental)

Before you start anything, you should make sure that you have properly installed some additional packages needed for development. Note that the list doesn't contain any packages marked essential or required - we expect that you have those installed already. The following packages come with the standard Debian installation, so you probably have them already (along with any additional packages they depend on). Still, you should check it with aptitude show package or with dpkg -s package. The most important package to install on your development system is the build-essential package. Once you try to install that, it will pull in other packages required to have a basic build environment. For some types of packages, that is all you will require; however, there is another set of packages that while not essential for all package builds are useful to have installed or may be required by your package: autoconf, automake, and autotools-dev - many newer programs use configure scripts and Makefile files preprocessed with the help of programs like these (see info autoconf, info automake). autotools-dev keeps up-to-date versions of certain auto files and has documentation about the best way to use those files. debhelper and dh-make - dh-make is necessary to create the skeleton of our example package, and it will use some of the debhelper tools for creating packages. They are not essential for this purpose, but are highly recommended for new maintainers. It makes the whole process very much easier to start, and to control afterwards. (See dh_make 1 , debhelper 1 .) There are also some more specialized but similar packages such as dh-make-perl, dh-make-php, etc. devscripts - this package contains some useful scripts that can be helpful for maintainers, but they are also not necessary for building packages. Packages recommended and suggested by this package are worth looking into. (See .) fakeroot - this utility lets you emulate being root which is necessary for some parts of the build process. (See fakeroot 1 .) file - this handy program can determine what type a file is. (See file 1 .) gfortran - the GNU Fortran 95 compiler, necessary if your program is written in Fortran. (See gfortran 1 .) git - this package provides a popular version control system designed to handle very large projects with speed and efficiency; it is used for many high profile open source projects, most notably the Linux kernel. (See git 1 , git Manual.) gnupg - a tool that enables you to digitally sign packages. This is especially important if you want to distribute it to other people, and you will certainly be doing that when your work gets included in the Debian distribution. (See gpg 1 .) gpc - the GNU Pascal compiler, necessary if your program is written in Pascal. Worthy of note here is fp-compiler, the Free Pascal Compiler, which is also good at this task. (See gpc 1 , ppc386 1 .) lintian - this is the Debian package checker, which can let you know of any common mistakes after you build the package, and explains the errors found. (See lintian 1 , Lintian User's Manual.) patch - this very useful utility will take a file containing a difference listing (produced by the diff program) and apply it to the original file, producing a patched version. (See patch 1 .) patchutils - this package contains some utilities to work with patches such as the lsdiff, interdiff and filterdiff commands. pbuilder - this package contains programs which are used for creating and maintaining chroot environment. Building Debian package in this chroot environment verifies the proper build dependency and avoid FTBFS (Fails To Build From Source) bugs. (see pbuilder 8 and pdebuild 1 ) perl - Perl is one of the most used interpreted scripting languages on today's Unix-like systems, often referred to as Unix's Swiss Army Chainsaw. (See perl 1 .) python - Python is another of the most used interpreted scripting languages on the Debian system, combining remarkable power with very clear syntax. (See python 1 .) quilt - this package helps you to manage large numbers of patches by keeping track of the changes each patch makes. Patches can be applied, un-applied, refreshed, and more. (See quilt 1, quilt.pdf.) xutils-dev - some programs, usually those made for X11, also use these programs to generate Makefile files from sets of macro functions. (See imake 1 , xmkmf 1 .) The short descriptions that are given above only serve to introduce you to what each package does. Before continuing please read the documentation of each relevant program including ones installed through the package dependency such as make, at least, for the standard usage. It may seem like heavy going now, but later on you'll be very glad you read it. If you have specific questions later, I would suggest re-reading the documents mentioned above.

The following is the very important documentation which you should read along with this document: debian-policy - the Debian Policy Manual includes explanations of the structure and contents of the Debian archive, several OS design issues, the Filesystem Hierarchy Standard (FHS, which says where each file and directory should be), etc. For you, the most important thing is that it describes requirements that each package must satisfy to be included in the distribution. (See the local copies of policy.pdf and fhs-2.3.pdf.) developers-reference - the Debian Developer's Reference describes all matters not specifically about the technical details of packaging, like the structure of the archive, how to rename, orphan, or adopt packages, how to do NMUs, how to manage bugs, best packaging practices, when and where to upload etc. (See the local copy of developers-reference.pdf.) The following is the important documentation which you should read along with this document: Autotools Tutorial provides a very good tutorial for the GNU Build System known as the GNU Autotools whose most important components are Autoconf, Automake, Libtool, and gettext. gnu-standards - this package contains two pieces of documentation from the GNU project: GNU Coding Standards, and Information for Maintainers of GNU Software. Although Debian does not require these to be followed, these are still helpful as guidelines and common sense. (See the local copies of standards.pdf and maintain.pdf.) If this document contradicts any of the documents mentioned above, they are correct. Please file a bug report on the maint-guide package using reportbug.

Before you decide to ask your question in some public place, please read the fine documentation. files in /usr/share/doc/package for all pertinent packages contents of man command for all pertinent commands contents of info command for all pertinent commands contents of debian-mentors@lists.debian.org mailing list archive contents of debian-devel@lists.debian.org mailing list archive You can use web search engines more effectively by including search strings such as site:lists.debian.org to limit the domain. Making a small test package is a good way to learn details of packaging. Inspecting existing well maintained packages is the best way to learn how other people make packages. If you still have questions about packaging that you couldn't find answers to in the available documentation and web resources, you can ask them interactively. debian-mentors@lists.debian.org mailing list. (This mailing list is for the novice.) debian-devel@lists.debian.org mailing list. (This mailing list is for the expert.) IRC such as #debian-mentors. The more experienced Debian developers will gladly help you, if you ask properly after making your required efforts. When you receive a bug report (yes, actual bug reports!), you will know that it is time for you to dig into the Debian Bug Tracking System and read the documentation there, to be able to deal with the reports efficiently. I highly recommend reading the Debian Developer's Reference, 5.8. "Handling bugs". Even if it all worked well, it's time to start praying. Why? Because in just a few hours (or days) users from all around the world will start to use your package, and if you made some critical error you'll get mailbombed by numerous angry Debian users... Just kidding. :-) Relax and be ready for bug reports, because there is a lot more work to be done before your package will be fully in line with Debian policies and its best practice guidelines (once again, read the real documentation for details). Good luck!

Let's start by creating a package of your own (or, even better, adopting an existing one).

If you are making a Debian package with an upstream program, typical workflow of the Debian package building involves generating several specifically named files for each step as the following. We obtain an upstream program file usually in a compressed tar format. package-version.tar.gz We create a non-native Debian source package in the 3.0 (quilt) format, which refers to the set of input files for the Debian package building, by adding Debian package modifications to the upstream program under the debian directory. package_version.orig.tar.gz package_version-revision.debian.tar.gz For the older non-native Debian source package in the 1.0 format, package_version-revision.diff.gz is used instead. package_version-revision.dsc We build Debian binary packages, which are ordinary installable package files in .deb format (or .udeb format, used by the Debian Installer), from the Debian source package. package_version-revision_arch.deb Please note that the character separating package and version was changed from - (hyphen) to _ (underscore). Here, package part of the file name is substituted by the package name, version part of it is substituted by the upstream version, revision part of it is substituted by the Debian revision, arch part of it is substituted by the package architecture. The package name, upstream version, and Debian revision must be adjusted to comply with the Debian Policy Manual: 5.6.1 Source, 5.6.7 Package, and 5.6.12 Version. The package architecture follows the Debian Policy Manual: 5.6.8 Architecture and is automatically assigned by the package build process. If you are making a Debian specific package without an upstream program instead, typical workflow of the Debian package building is simpler. We create a native Debian source package in the 3.0 (quilt) format using a compressed tar format in which required files under the debian directory are also included. package_version.tar.gz package_version.dsc We build Debian binary packages from the native Debian source package. package_version_arch.deb In the following, each step of this is explained with detailed examples.

You have probably chosen the package you want to create. The first thing you need to do is check if the package is in the distribution archive already by using the following. the aptitude command the Debian packages web page the Debian Package Tracking System web page If the package already exists, well, install it! :-) If it happens to be orphaned (that is, if its maintainer is set to Debian QA Group), you may be able to pick it up if it's still available. You may also adopt a package whose maintainer has filed a Request for Adoption (RFA). See Debian Developer's Reference 5.9.5. "Adopting a package". There are several package ownership status resources. Work-Needing and Prospective Packages Debian Bug report logs: Bugs in pseudo-package wnpp in unstable Debian Packages that Need Lovin' Browse wnpp bugs based on debtags As a side note, it's important to point out that Debian already has packages for most kinds of programs, and the number of packages already in the Debian archive is much larger than that of contributors with upload rights. Thus, contributions to packages already in the archive are far more appreciated (and more likely to receive sponsorship) by other developers Having said that, there will of course always be new programs that are worth packaging. . You can contribute in various ways. taking over orphaned, yet actively used, packages joining packaging teams triaging bugs of very popular packages preparing QA or NMU uploads If you are able to adopt the package, get the sources (with something like apt-get source packagename) and examine them. This document unfortunately doesn't include comprehensive information about adopting packages. Thankfully you shouldn't have a hard time figuring out how the package works since someone has already done the initial setup for you. Keep reading, though; a lot of the advice below will still be applicable for your case. If the package is new, and you decide you'd like to see it in Debian, proceed as follows: First, you must know that the program works, and have tried it for some time to confirm its usefulness. You must check that no one else is already working on the package on the Work-Needing and Prospective Packages site. If no one else is working on it, file an ITP (Intent To Package) bug report to the wnpp pseudo-package using reportbug. If someone's already on it, contact them if you feel you need to. If not - find another interesting program that nobody is maintaining. The software must have a license. For the main section, Debian Policy requires it to be fully compliant with the Debian Free Software Guidelines (DFSG) and not to require a package outside of main for compilation or execution. This is the desired case. For the contrib section, it must comply with the DFSG but it may require a package outside of main for compilation or execution. For the non-free section, it may be non-compliant with the DFSG but it must be distributable. If you are unsure about where it should go, post the license text on debian-legal@lists.debian.org and ask for advice. The program should not introduce security and maintenance concerns to the Debian system. The program should be well documented and its code needs to be understandable (i.e. not obfuscated). You should contact the program's author(s) to check if they agree with packaging it and are amicable to Debian. It is important to be able to consult with the author(s) in case of any problems with the program, so don't try to package unmaintained software. The program certainly should not run setuid root, or even better, it shouldn't need to be setuid or setgid to anything. The program should not be a daemon, or go in an */sbin directory, or open a port as root. Of course, the last one is just a safety measures, and intended to save you from enraging users if you do something wrong in some setuid daemon... When you gain more experience in packaging, you'll be able to package such software. As a new maintainer, you are encouraged to get some experience in packaging with easier packages and discouraged from creating complicated packages. Simple packages single binary package, arch = all (collection of data such as wallpaper graphics) single binary package, arch = all (executables written in the POSIX shell language) single binary package, arch = all (executables written in interpreter languages) Intermediate complexity packages single binary package, arch = any (executables written in compiler languages such as C and C++) multiple binary packages, arch = any + all (packages for executables + documentation) upstream source in a format other than tar.gz or tar.bz2 upstream source containing undistributable contents High complexity packages interpreter module package used by other packages generic library package used by other packages multiple binary packages containing a library package source package with multiple upstream sources kernel module packages kernel patch packages any package with non-trivial maintainer scripts Packaging high complexity packages is not too hard, but it requires a bit more knowledge. You should seek specific guidances for every complexity. For example, some interpreter languages have their policy. Perl policy Python policy Java policy

So the first thing to do is to find and download the original source code. Presumably you already have the source file that you picked up at the author's homepage. Sources for free Unix programs usually come in tar+gzip format with the extension .tar.gz, tar+bzip2 format with the extension .tar.bz2, or tar+xz format with the extension .tar.xz. These usually contain a directory called package-version with all the sources inside. If the latest version of the source is available through a VCS such as Git, Subversion, or CVS, you need to get it with git clone, svn co, or cvs co and repack it into tar+gzip format yourself by using the --exclude-vcs option. If your program's source comes as some other sort of archive (for instance, the filename ends in .Z or .zip You can identify the archive format using the file command when the file extension is not enough. ), you should also unpack it with the appropriate tools and repack it. As an example, I'll use a program called gentoo, a GTK+ file manager. This program is already packaged. The current version uses Autotools as its build structure and is substantially different from the following examples, which were based on version 0.9.12. Create a subdirectory under your home directory named debian or deb or anything you find appropriate (e.g. just ~/gentoo would do fine in this case). Place the downloaded archive in it, and extract it (with tar xzf gentoo-0.9.12.tar.gz). Make sure there are no warning messages, even irrelevant ones, because other people's unpacking tools may or may not ignore these anomalies, so they may have problems unpacking them. Your shell command line may look something like this: $ mkdir ~/gentoo ; cd ~/gentoo $ wget http://www.example.org/gentoo-0.9.12.tar.gz $ tar xvzf gentoo-0.9.12.tar.gz $ ls -F gentoo-0.9.12/ gentoo-0.9.12.tar.gz Now you have another subdirectory, called gentoo-0.9.12. Change to that directory and thoroughly read the provided documentation. Usually there are files named README*, INSTALL*, *.lsm or *.html. You must find instructions on how to compile and install the program (most probably they'll assume you want to install to the /usr/local/bin directory; you won't be doing that, but more on that later in ). You should start packaging with a completely clean (pristine) source directory, or simply with freshly unpacked sources.

Simple programs come with a Makefile and can be compiled just by invoking make. Many modern programs come with a script configure which when executed creates a Makefile customized for your system. Some of them support make check, which runs included self-tests. Installation to the destination directories is usually done with make install. Now try to compile and run your program, to make sure it works properly and doesn't break something else while it's installing or running. Also, you can usually run make clean (or better make distclean) to clean up the build directory. Sometimes there's even a make uninstall which can be used to remove all the installed files.

A lot of free software programs are written in the C and C++ languages. Many of these use Autotools or CMake to make them portable across different platforms. These build tools need to be used to generate the Makefile and other required source files first. Then, such programs are built using the usual make; make install. Autotools is the GNU build system comprising Autoconf, Automake, Libtool, and gettext. You can recognize such sources by the configure.ac, Makefile.am, and Makefile.in files. Autotools is too big to deal in this small tutorial. This section is meant to provide keywords and references only. Please make sure to read the Autotools Tutorial and , if you need to use it. The first step of the Autotools workflow is usually that upstream runs autoreconf -i -f in the source directory and distributes the generated files along with the source. configure.ac-----+-> autoreconf -+-> configure Makefile.am -----+ | +-> Makefile.in src/Makefile.am -+ | +-> src/Makefile.in | +-> config.h.in automake aclocal aclocal.m4 autoheader Editing configure.ac and Makefile.am files requires some knowledge of autoconf and automake. See info autoconf and info automake. The second step of the Autotools workflow is usually that the user obtains this distributed source and runs ./configure && make in the source directory to compile the program into a binary executable. Makefile.in -----+ +-> Makefile -----+-> make -> binary src/Makefile.in -+-> ./configure -+-> src/Makefile -+ config.h.in -----+ +-> config.h -----+ | config.status -+ config.guess --+ You can change many things in the Makefile; for instance you can change the default location for file installation using the option ./configure --prefix=/usr. Although it is not required, updating the configure and other files with autoreconf -i -f may improve the compatibility of the source. You can automate this by using dh-autoreconf package. See . CMake is an alternative build system. You can recognize such sources by the CMakeLists.txt file.

If the upstream source comes as gentoo-0.9.12.tar.gz, you can consider package name to be gentoo and upstream version to be 0.9.12. These are used in the debian/changelog file described later in , too. Although this simple approach works most of the times, you may need to adjust package name and upstream version by renaming the upstream source to follow the Debian Policy and the existing convention. You must choose the package name to consist only of lower case letters (a-z), digits (0-9), plus (+) and minus (-) signs, and periods (.). It must be at least two characters long, must start with an alphanumeric character, and must not be the same as existing ones. It is good idea to keep its length within 30 characters. The package name field length of aptitude is 30. For more than 90% of packages, the package name is less than 24 characters. If upstream source uses generic words such as test-suite as its name, it is good idea to rename it not to contaminate name space for the package name and to identify its contents explicitly. If you follow the Debian Developer's Reference 5.1. "New packages", the ITP process will usually catch this kind of issues. You should choose the upstream version to consist only of alphanumerics (0-9A-Za-z), plus (+), tildes (~), and periods (.). It must start with a digit (0-9). This stricter rule should help you avoid confusing file names. It is good idea to keep its length within 8 characters if possible. The version field length of aptitude is 10. The Debian revision with preceding hyphen usually consumes 2. For more than 80% of packages, the upstream version is less than 8 charactes and the Debian revision is less than 2 characters. For more than 90% of packages, the upstream version is less than 10 charactes and the Debian revision is less than 3 characters. If the upstream software does not use normal version system like 2.30.32 but uses some kind of date such as 09Oct23, a random codename string or a VCS hash value as a part of version, make sure to remove them from the upstream version. Such information can be recorded in the debian/changelog file. If you need to invent a version string, use the YYYYMMDD format such as 20110429 as upstream version. This ensures that dpkg properly sees later versions as upgrades. Version strings Version strings may be version, revision, or version-revision. See for how the Debian revision revision is incremented. can be compared with dpkg 1 as the following. $ dpkg --compare-versions ver1 op ver2 The version comparison rule can be summarized as the following. The strings are compared from the head to the tail. Alphabets are larger than numbers. Numbers are compared as the integer. Alphabets are compared in the ASCII code order. There are some special rules for periods (.), plus (+) and tildes (~) as the followings. 0.0 < 0.5 < 0.10 < 0.99 < 1 < 1.0~rc1 < 1.0 < 1.0+b1 < 1.0+nmu1 < 1.1 < 2.0 One of the tricky case happens when the upstream releases gentoo-0.9.12-ReleaseCandidate-99.tar.gz as the pre-release of gentoo-0.9.12.tar.gz. You need to make sure that the upgrade works properly by renaming the upstream source to gentoo-0.9.12~rc99.tar.gz.

Set up the shell environment variables $DEBEMAIL and $DEBFULLNAME so that various Debian maintenance tools recognize your email address and name to use for packages. The following text assumes you are using Bash as your login shell. If you use some other login shell such as Z shell, use their corresponding configuration files instead of ~/.bashrc. $ cat >>~/.bashrc <<EOF DEBEMAIL=your.email.address@example.org DEBFULLNAME=Firstname Lastname export DEBEMAIL DEBFULLNAME EOF $ . ~/.bashrc

Normal Debian packages are non-native Debian packages made from upstream programs. If you wish to create a non-native Debian package of an upstream source gentoo-0.9.12.tar.gz, you can create an initial non-native Debian package for it by issuing the dh_make command as follows. $ cd ~/gentoo $ wget http://example.org/gentoo-0.9.12.tar.gz $ tar -xvzf gentoo-0.9.12.tar.gz $ cd gentoo-0.9.12 $ dh_make -f ../gentoo-0.9.12.tar.gz Of course, replace the filename with the name of your original source archive. If the upstream source provides the debian directory and its contents, run the dh_make command with the extra option --addmissing. The new source 3.0 (quilt) format is robust enough not to break even for these packages. You may need to update the contents provided by the upstream for your Debian package. See dh_make 1 for details. You should see some output asking you what sort of package you want to create. Gentoo is a single binary package - it creates only one binary package, i.e, one .deb file - so we will select the first option (with the s key), check the information on the screen, and confirm by pressing ENTER. There are several choices here: s for Single binary package, i for arch-Independent package, m for Multiple binary packages, l for Library package, k for Kernel module package, n for kernel patch package, and b for cdbs package. This document focuses on the use of the dh command (from the package debhelper) to create a single binary package, but also touches on how to use it for arch-independent or multiple binary packages. The package cdbs offers an alternative packaging script infrastructure to the dh command and is outside the scope of this document. This execution of dh_make creates a copy of the upstream tarball as gentoo_0.9.12.orig.tar.gz in the parent directory to accommodate the creation of the non-native Debian source package with the name debian.tar.gz later. $ cd ~/gentoo ; ls -F gentoo-0.9.12/ gentoo-0.9.12.tar.gz gentoo_0.9.12.orig.tar.gz Please note two key features of this filename gentoo_0.9.12.orig.tar.gz: Package name and version are separated by the character _ (underscore). The string .orig is inserted before the .tar.gz. You should also notice that many template files are created in the source under the debian directory. These will be explained in and . You should also understand that packaging cannot be a fully automated process. You will need to modify the upstream source for Debian (see ). After this, you need to use the proper methods for building Debian packages (), testing them (), and uploading them (). All the steps will be explained. If you accidentally erased some template files while working on them, you can recover them by running dh_make with the --addmissing option again in a Debian package source tree. Updating an existing package may get complicated since it may be using older techniques. While learning the basics, please stick to creating a fresh package; further explanations are given in . Please note that the source file does not need to contain any build system discussed in and . It could be just a collection of graphics data etc. Installation of files may be enabled by debhelper configuration files such as debian/install (see ) only.

Debian native packages are simpler to manage if they contain source files you manage only for Debian, possibly only for local uses. If you have source files in ~/mypackage-1.0, you can create an initial native Debian package for it by issuing the dh_make command as follows. $ cd ~/mypackage-1.0 $ dh_make --native Then the debian directory and its contents are created just like . This does not create a tarball since this is a native Debian package. But that is the only difference. The rest of the packaging activities are practically the same.

Please note that there isn't space here to go into all the details of fixing upstream sources, but here are some basic steps and problems people often run across.

The program quilt offers a basic method for recording modifications to the upstream source for Debian packaging. It's useful to have a slightly customized default, so let's create an alias dquilt for Debian packaging by adding the following line to ~/.bashrc. alias dquilt="quilt --quiltrc=~/.quiltrc-dpkg" Then let's create ~/.quiltrc-dpkg as follows. d=. ; while [ ! -d $d/debian -a `readlink -e $d` != / ]; do d=$d/..; done if [ -d $d/debian ] && [ -z $QUILT_PATCHES ]; then # if in Debian packaging tree with unset $QUILT_PATCHES QUILT_PATCHES="debian/patches" QUILT_PATCH_OPTS="--reject-format=unified" QUILT_DIFF_ARGS="-p ab --no-timestamps --no-index --color=auto" QUILT_REFRESH_ARGS="-p ab --no-timestamps --no-index" QUILT_COLORS="diff_hdr=1;32:diff_add=1;34:diff_rem=1;31:diff_hunk=1;33:diff_ctx=35:diff_cctx=33" if ! [ -d $d/debian/patches ]; then mkdir $d/debian/patches; fi fi See quilt 1 and quilt.pdf on how to use quilt.

Let's assume you find an error in the upstream Makefile as follows where install: gentoo should have been install: gentoo-target. install: gentoo install ./gentoo $(BIN) install icons/* $(ICONS) install gentoorc-example $(HOME)/.gentoorc Let's fix this and record it with the dquilt command as fix-gentoo-target.patch. The debian/patches directory should exist now if you ran dh_make as described before. This example operation creates it just in case you are updating an existing package. $ mkdir debian/patches $ dquilt new fix-gentoo-target.patch $ dquilt add Makefile You change the Makefile file as follows. install: gentoo-target install ./gentoo $(BIN) install icons/* $(ICONS) install gentoorc-example $(HOME)/.gentoorc Ask dquilt to generate the patch to create debian/patches/fix-gentoo-target.patch and add its description following DEP-3: Patch Tagging Guidelines. $ dquilt refresh $ dquilt header -e ... describe patch

Most third-party software installs itself in the /usr/local directory hierarchy. On Debian this is reserved for private use by the system administrator, so packages must not use directories such as /usr/local/bin but should instead use system directories such as /usr/bin, obeying the Filesystem Hierarchy Standard (FHS). Normally, make 1 is used to automate building the program, and executing make install installs programs directly to the desired destination (following the install target in the Makefile). In order for Debian to provide pre-built installable packages, it modifies the build system to install programs into a file tree image created under a temporary directory instead of the actual destination. These two differences between normal program installation on one hand and the Debian packaging system on the other can be transparently addressed by the debhelper package through the dh_auto_configure and dh_auto_install commands if the following conditions are met. The Makefile must follow GNU conventions and support the $(DESTDIR) variable. See GNU Coding Standards: 7.2.4 DESTDIR: Support for Staged Installs. The source must follow the Filesystem Hierarchy Standard (FHS). Programs that use GNU autoconf follow the GNU conventions automatically, so they can be trivial to package. On the basis of this and other heuristics, it is estimated that the debhelper package will work for about 90% of packages without making any intrusive changes to their build system. So packaging is not as complicated as it may seem. If you need to make changes in the Makefile, you should be careful to support the $(DESTDIR) variable. Although it is unset by default, the $(DESTDIR) variable is prepended to each file path used for the program installation. The packaging script will set $(DESTDIR) to the temporary directory. For packages of the single binary type, the temporary directory used by the dh_auto_install command will be set to debian/package. For packages of the multiple binary type, the dh_auto_install command uses debian/tmp as the temporary directory while the dh_install command with the help of debian/package-1.install and debian/package-2.install files will split the contents of debian/tmp into debian/package-1 and debian/package-2 temporary directories, to create package-1_*.deb and package-2_*.deb binary packages. Everything that is contained in the temporary directory will be installed on users' systems when they install your package; the only difference is that dpkg will be installing the files to paths relative to the root directory rather than your working directory. Bear in mind that even though your program installs in debian/package, it still needs to behave correctly when installed from the .deb package under the root directory. So you must not allow the build system to hardcode strings like /home/me/deb/package-version/usr/share/package into files in the package. Here's the relevant part of gentoo's Makefile This is just an example to show what a Makefile should look like. If the Makefile is created by the ./configure command, the correct way to fix this kind of Makefile is to execute ./configure from the dh_auto_configure command with default options including --prefix=/usr. : # Where to put binary executables on 'make install'? BIN = /usr/local/bin # Where to put icons on 'make install'? ICONS = /usr/local/share/gentoo We see that the files are set to install under /usr/local. As explained above, that directory hierarchy is reserved for local use on Debian, so change those paths to: # Where to put binary executables on 'make install'? BIN = $(DESTDIR)/usr/bin # Where to put icons on 'make install'? ICONS = $(DESTDIR)/usr/share/gentoo The exact locations that should be used for binaries, icons, documentation, etc. are specified in the Filesystem Hierarchy Standard (FHS). You should browse through it and read the sections relevant to your package. So, we should install binary executables in /usr/bin instead of /usr/local/bin, the manual page in /usr/share/man/man1 instead of /usr/local/man/man1, and so on. Notice how there's no manual page mentioned in gentoo's Makefile, but since Debian Policy requires that every program has one, we'll make one later and install it in /usr/share/man/man1. Some programs don't use Makefile variables to define paths such as these. This means you might have to edit some real C sources in order to fix them to use the right locations. But where to search, and exactly what for? You can find this out by issuing: $ grep -nr --include='*.[c|h]' -e 'usr/local/lib' . grep will run recursively through the source tree and tell you the filename and the line number for all matches. Edit those files and in those lines replace usr/local/lib with usr/lib. This can be done automatically as follows: $ sed -i -e 's#usr/local/lib#usr/lib#g' \ $(find . -type f -name '*.[c|h]') If you want to confirm each substitution instead, this can be done interactively as follows: $ vim '+argdo %s#usr/local/lib#usr/lib#gce|update' +q \ $(find . -type f -name '*.[c|h]') Next you should find the install target (searching for the line that starts with install: will usually work) and rename all references to directories other than ones defined at the top of the Makefile. Originally, gentoo's install target said: install: gentoo-target install ./gentoo $(BIN) install icons/* $(ICONS) install gentoorc-example $(HOME)/.gentoorc Let's fix this upstream bug and record it with the dquilt command as debian/patches/install.patch. $ dquilt new install.patch $ dquilt add Makefile In your editor, change this for the Debian package as follows: install: gentoo-target install -d $(BIN) $(ICONS) $(DESTDIR)/etc install ./gentoo $(BIN) install -m644 icons/* $(ICONS) install -m644 gentoorc-example $(DESTDIR)/etc/gentoorc You'll have noticed that there's now an install -d command before the other commands in the rule. The original Makefile didn't have it because usually /usr/local/bin and other directories already exist on the system where you are running make install. However, since we will be installing into a newly created private directory tree, we will have to create each and every one of those directories. We can also add in other things at the end of the rule, like the installation of additional documentation that the upstream authors sometimes omit: install -d $(DESTDIR)/usr/share/doc/gentoo/html cp -a docs/* $(DESTDIR)/usr/share/doc/gentoo/html Check carefully, and if everything is okay, ask dquilt to generate the patch to create debian/patches/install.patch and add its description. $ dquilt refresh $ dquilt header -e ... describe patch Now you have a series of patches. Upstream bug fix: debian/patches/fix-gentoo-target.patch Debian specific packaging modification: debian/patches/install.patch Whenever you make changes that are not specifically related to Debian package such as debian/patches/fix-gentoo-target.patch, be sure to send them to the upstream maintainer so they can be included in the next revision of the program and be useful to everyone else. Also remember to avoid making your fixes specific to Debian or Linux - or even Unix! Make them portable. This will make your fixes much easier to apply. Note that you don't have to send the debian/* files upstream.

There is one other common problem: libraries are often different from platform to platform. For example, a Makefile can contain a reference to a library which doesn't exist on the Debian system. In that case, we need to change it to a library which does exist in Debian, and serves the same purpose. Let's assume a line in your program's Makefile (or Makefile.in) as the following. LIBS = -lfoo -lbar If your program doesn't compile since the foo library doesn't exist and its equivalent is provided by the foo2 library on the Debian system, you can fix this build problem as debian/patches/foo2.patch by changing foo into foo2.If there are API changes from the foo library to the foo2 library, required changes to the source code need to be made to match the new API. $ dquilt new foo2.patch $ dquilt add Makefile $ sed -i -e 's/-lfoo/-lfoo2/g' Makefile $ dquilt refresh $ dquilt header -e ... describe patch

There is a new subdirectory under the program's source directory, it's called debian. There are a number of files in this directory that we should edit in order to customize the behavior of the package. The most important of them are control, changelog, copyright and rules, which are required for all packages. In this chapter, files in the debian directory are referred without preceding debian/ for simplicity whenever they are obvious.

This file contains various values which dpkg, dselect, apt-get, apt-cache, aptitude, and other package management tools will use to manage the package. It is defined by the Debian Policy Manual, 5 "Control files and their fields". Here is the control file dh_make created for us: 1 Source: gentoo 2 Section: unknown 3 Priority: extra 4 Maintainer: Josip Rodin <joy-mg@debian.org> 5 Build-Depends: debhelper (>= 7.0.50~) 6 Standards-Version: 3.8.4 7 Homepage: <insert the upstream URL, if relevant> 8 9 Package: gentoo 10 Architecture: any 11 Depends: ${shlibs:Depends}, ${misc:Depends} 12 Description: <insert up to 60 chars description> 13 <insert long description, indented with spaces> (I've added the line numbers.) Lines 1-7 are the control information for the source package. Lines 9-13 are the control information for the binary package. Line 1 is the name of the source package. Line 2 is the section of the distribution the source package goes into. As you may have noticed, Debian archive is divided in sections: main (the free software), non-free (the not really free software) and contrib (free software that depends on non-free software). Under those, there are logical subsections that describe in short what packages are in. So we have admin for administrator-only programs, base for the basic tools, devel for programmer tools, doc for documentation, libs for libraries, mail for e-mail readers and daemons, net for network apps and daemons, x11 for X11 programs that don't fit anywhere else, and many more. See Debian Policy Manual, 2.4 "Sections" and List of sections in sid. Let's change it then to x11. (A main/ prefix is implied so we can omit it.) Line 3 describes how important it is that the user installs this package. See Debian Policy Manual, 2.5 "Priorities". The optional priority will usually work for new packages that do not conflict with others with required, important or standard priorities. The extra priority will usually work for new packages that conflict with others with non-extra priorities. Section and priority are used by the frontends like aptitude when they sort packages and select defaults. Once you upload the package to Debian, the value of these two fields can be overridden by the archive maintainers, in which case you will be notified by email. As this is a normal priority package and doesn't conflict with anything else, we will change the priority to optional. Line 4 is the name and email address of the maintainer. Make sure that this field includes a valid To header for an email, because after you upload it, the bug tracking system will use it to deliver bug emails to you. Avoid using commas, ampersands and parenthesis. The 5th line includes the list of packages required to build your package as the Build-Depends field. You can also have the Build-Depends-Indep field as an additional line, here. See Debian Policy Manual, 7.7 "Relationships between source and binary packages - Build-Depends, Build-Depends-Indep, Build-Conflicts, Build-Conflicts-Indep". Some packages like gcc and make which are required by the build-essential package are implied. If you need to have other tools to build your package, you should add them to these fields. Multiple entries are separated with commas; read on for the explanation of binary package dependencies to find out more about the syntax of these lines. For all packages packaged with the dh command in the debian/rules file, you must have debhelper (>=7.0.50~) in the Build-Depends field to satisfy the Debian Policy requirement for the clean target. For source packages which have some binary packages with Architecture: any, they are rebuild by the autobuilder. Since this autobuilder procedure runs debian/rules build in it while installing only packages listed in the Build-Depends field (see ), the Build-Depends field needs to list practically all the required packages and the Build-Depends-indep is rarely used. For source packages which have binary packages only with Architecture: all, the Build-Depends-Indep field may list all the required packages unless they are already listed in the Build-Depends field to satisfy the Debian Policy requirement for the clean target. If you are not sure which one should be used, use the Build-Depends field to be on the safe side. This somewhat strange situation is a feature well documented in the Debian Policy Manual, Footnotes 48. This is not due to the use of the dh command in the debian/rules file but due to how the dpkg-buildpackage works. The same situation applies to the auto build system for Ubuntu. To find out what packages your package needs to be built run the command: $ dpkg-depcheck -d ./configure To manually find exact build dependency for /usr/bin/foo, you execute $ objdump -p /usr/bin/foo | grep NEEDED and for each library listed, e.g., libfoo.so.6, execute $ dpkg -S libfoo.so.6 Then you just take -dev version of every package as Build-Depends entry. If you use ldd for this purpose, it will report indirect lib dependencies as well, resulting in the problem of excessive build dependencies. gentoo also happens to require xlibs-dev, libgtk1.2-dev and libglib1.2-dev to build, so we'll add them here next to debhelper. Line 6 is the version of the Debian Policy Manual standards this package follows, the one you read while making your package. On line 7 you can put the URL of the homepage for the upstream program. Line 9 is the name of the binary package. This is usually the same as the name of the source package, but it doesn't necessarily have to be that way. Line 10 describes the CPU architecture the binary package can be compiled for. We'll leave this as any because dpkg-gencontrol 1 will fill in the appropriate value for any machine this package gets compiled on. If your package is architecture independent (for example, a shell or Perl script, or a document), change this to all, and read later in about using the binary-indep rule instead of binary-arch for building the package. Line 11 shows one of the most powerful features of the Debian packaging system. Packages can relate to each other in various ways. Apart from Depends, other relationship fields are Recommends, Suggests, Pre-Depends, Breaks, Conflicts, Provides, and Replaces. The package management tools usually behave the same way when dealing with these relations; if not, it will be explained. (see dpkg 8 , dselect 8 , apt 8 , aptitude 1 etc.) Here is a simplified description of package relationships. See Debian Policy Manual, 7 "Declaring relationships between packages". Depends The package will not be installed unless the packages it depends on are installed. Use this if your program absolutely will not run (or will cause severe breakage) unless a particular package is present. Recommends Use this for packages that are not strictly necessary but are typically used with your program. When a user installs your program, all frontends will likely prompt them to install the recommended packages. aptitude and apt-get install recommended packages along with your package (but the user can disable this default behaviour). dpkg will ignore this field. Suggests Use this for packages which will work nicely with your program but are not at all necessary. When a user installs your program, all frontends will likely prompt them to install the suggested packages. aptitude can be configured to install suggested packages along with your package but this is not its default. dpkg and apt-get will ignore this field. Pre-Depends This is stronger than Depends. The package will not be installed unless the packages it pre-depends on are installed and correctly configured. Use this very sparingly and only after discussing it on the debian-devel@lists.debian.org mailing list. Read: don't use it at all. :-) Conflicts The package will not be installed until all the packages it conflicts with have been removed. Use this if your program absolutely will not run or will cause severe problems if a particular package is present. Breaks The package will be installed while all the listed packages will be broken. Normally a Breaks entry has an earlier than version clause. The resolution is generally to upgrade the listed packages by the higher-level package management tools. Provides For some types of packages where there are multiple alternatives virtual names have been defined. You can get the full list in the virtual-package-names-list.txt.gz file. Use this if your program provides a function of an existing virtual package. Replaces Use this when your program replaces files from another package, or completely replaces another package (used in conjunction with Conflicts). Files from the named packages will be overwritten with the files from your package. All these fields have uniform syntax. They are a list of package names separated by commas. These package names may also be lists of alternative package names, separated by vertical bar symbols | (pipe symbols). The fields may restrict their applicability to particular versions of each named package. These versions are listed in parentheses after each individual package name, and they should contain a relation from the list below followed by the version number. The relations allowed are: <<, <=, =, >= and >> for strictly lower, lower or equal, exactly equal, greater or equal and strictly greater, respectively. For example, Depends: foo (>= 1.2), libbar1 (= 1.3.4) Conflicts: baz Recommends: libbaz4 (>> 4.0.7) Suggests: quux Replaces: quux (<< 5), quux-foo (<= 7.6) The last feature you need to know about is ${shlibs:Depends}, ${perl:Depends}, ${misc:Depends}, etc. dh_shlibdeps 1 calculates shared library dependencies for binary packages. It generates a list of ELF executables and shared libraries it has found for each binary package. Such list is used for substituting ${shlibs:Depends}. dh_perl 1 calculates Perl dependencies. It generates a list of a dependency on perl or perlapi for each binary package. Such list is used for substituting ${perl:Depends}. Some debhelper commands may make the generated package need to depend on some other packages. All such commands generate a list of required packages for each binary package. Such list is used for substituting ${misc:Depends}. dh_gencontrol 1 generates DEBIAN/control for each binary package while substituting ${shlibs:Depends}, ${perl:Depends}, ${misc:Depends}, etc. Having said all that, we can leave the Depends field exactly as it is now, and insert another line after it saying Suggests: file, because gentoo can use some features provided by that file package. Line 9 is the Homepage URL. Let's assume this to be at . Line 12 is the short description. Most people screens are 80 columns wide so this shouldn't be longer than about 60 characters. I'll change it to fully GUI-configurable, two-pane X file manager. Line 13 is where the long description goes. This should be a paragraph which gives more details about the package. Column 1 of each line should be empty. There must be no blank lines, but you can put a single . (dot) in a column to simulate that. Also, there must be no more than one blank line after the long description. These descriptions are in English. Translations of these descriptions are provided by The Debian Description Translation Project - DDTP. Let's insert Vcs-* fields to document the Version Control System (VCS) location between line 6 and 7. See Debian Developer's Reference, 6.2.5. "Version Control System location". Let's assume that the gentoo package has its VCS located in Debian Alioth Git Service at git://git.debian.org/git/collab-maint/gentoo.git. Finally, here is the updated control file: 1 Source: gentoo 2 Section: x11 3 Priority: optional 4 Maintainer: Josip Rodin <joy-mg@debian.org> 5 Build-Depends: debhelper (>= 7.0.5), xlibs-dev, libgtk1.2-dev, libglib1.2-dev 6 Standards-Version: 3.8.4 7 Vcs-Git: git://git.debian.org/git/collab-maint/gentoo.git 8 Vcs-browser: http://git.debian.org/?p=collab-maint/gentoo.git 9 Homepage: &gentoo; 10 11 Package: gentoo 12 Architecture: any 13 Depends: ${shlibs:Depends}, ${misc:Depends} 14 Suggests: file 15 Description: fully GUI-configurable, two-pane X file manager 16 gentoo is a two-pane file manager for the X Window System. gentoo lets the 17 user do (almost) all of the configuration and customizing from within the 18 program itself. If you still prefer to hand-edit configuration files, 19 they're fairly easy to work with since they are written in an XML format. 20 . 21 gentoo features a fairly complex and powerful file identification system, 22 coupled to a object-oriented style system, which together give you a lot 23 of control over how files of different types are displayed and acted upon. 24 Additionally, over a hundred pixmap images are available for use in file 25 type descriptions. 26 . 29 gentoo was written from scratch in ANSI C, and it utilises the GTK+ toolkit 30 for its interface. (I've added the line numbers.)

This file contains the information about package upstream resources, copyright and license information. Debian Policy Manual, 12.5 "Copyright information" dictates its content and DEP-5: Machine-parseable debian/copyright provides guidelines for its format. dh_make can give you a template copyright file. Let's use the --copyright gpl2 option here to get a template file for the gentoo package released under GPL-2. You must fill in missing information such as the place you got the package from, the actual copyright notice and their license to complete this file. For the common free software licenses such as GNU GPL-1, GNU GPL-2, GNU GPL-3, LGPL-2, LGPL-2.1, LGPL-3, GNU FDL-1.2, GNU FDL-1.3, Apache-2.0 or the Artistic license, you can just refer to the appropriate file in /usr/share/common-licenses/ directory that exists on every Debian system. Otherwise, you must include the complete license. In short, here's how gentoo's copyright file should look like: 1 Format-Specification: http://svn.debian.org/wsvn/dep/web/deps/dep5.mdwn?op=file&rev=135 2 Name: gentoo 3 Maintainer: Josip Rodin <joy-mg@debian.org> 4 Source: http://sourceforge.net/projects/gentoo/files/ 5 6 Copyright: 1998-2010 Emil Brink <emil@obsession.se> 7 License: GPL-2+ 8 9 Files: icons/* 10 Copyright: 1998 Johan Hanson <johan@tiq.com> 11 License: GPL-2+ 12 13 Files: debian/* 14 Copyright: 1998-2010 Josip Rodin <joy-mg@debian.org> 15 License: GPL-2+ 16 17 License: GPL-2+ 18 This program is free software; you can redistribute it and/or modify 19 it under the terms of the GNU General Public License as published by 20 the Free Software Foundation; either version 2 of the License, or 21 (at your option) any later version. 22 . 23 This program is distributed in the hope that it will be useful, 24 but WITHOUT ANY WARRANTY; without even the implied warranty of 25 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the 26 GNU General Public License for more details. 27 . 28 You should have received a copy of the GNU General Public License along 29 with this program; if not, write to the Free Software Foundation, Inc., 30 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA. 31 . 32 On Debian systems, the full text of the GNU General Public 33 License version 2 can be found in the file 34 `/usr/share/common-licenses/GPL-2'. (I've added the line numbers.) Please follow the HOWTO provided by ftpmasters and sent to debian-devel-announce: .

This is a required file, which has a special format described in the Debian Policy Manual, 4.4 "debian/changelog". This format is used by dpkg and other programs to obtain the version number, revision, distribution and urgency of your package. For you, it is also important, since it is good to have documented all changes you have done. It will help people downloading your package to see whether there are issues with the package that they should know about. It will be saved as /usr/share/doc/gentoo/changelog.Debian.gz in the binary package. dh_make created a default one, and this is how it looks like: 1 gentoo (0.9.12-1) unstable; urgency=low 2 3 * Initial release (Closes: #nnnn) <nnnn is the bug number of your ITP> 4 5 -- Josip Rodin <joy-mg@debian.org> Mon, 22 Mar 2010 00:37:31 +0100 6 (I've added the line numbers.) Line 1 is the package name, version, distribution, and urgency. The name must match the source package name, distribution should be either unstable (or even experimental) Some people use invalid distribution values such as UNRELEASED to prevent a package to be accidentally uploaded when updating a package in a shared VCS. , and urgency shouldn't be changed to anything higher than low. :-) Lines 3-5 are a log entry, where you document changes made in this package revision (not the upstream changes - there is special file for that purpose, created by the upstream authors, which you will later install as /usr/share/doc/gentoo/changelog.gz). Let's assume your ITP (Intent To Package) bug report number was 12345. New lines must be inserted just before the uppermost line that begins with * (asterisk). You can do it with dch 1 , or manually with a text editor. You will end up with something like this: 1 gentoo (0.9.12-1) unstable; urgency=low 2 3 * Initial Release. Closes: #12345 4 * This is my first Debian package. 5 * Adjusted the Makefile to fix $(DESTDIR) problems. 6 7 -- Josip Rodin <joy-mg@debian.org> Mon, 22 Mar 2010 00:37:31 +0100 8 (I've added the line numbers.) You can read more about updating the changelog file later in .

Now we need to take a look at the exact rules which dpkg-buildpackage 1 will use to actually create the package. This file is actually another Makefile, but different from the one(s) in the upstream source. Unlike other files in debian, this one is marked as executable.

Every rules file, as any other Makefile, consists of several targets and their rules specifying how to handle the source. Debian Policy Manual, 4.9 "Main building script: debian/rules" explains its details. The simplified explanation of targets are the following. clean target: to clean all compiled, generated, and useless files in the build-tree. (required) build target: to build the source into compiled programs and formatted documents in the build-tree. (required) install target: to install files into a file tree for each binary package under the debian directory. If defined, binary* targets effectively depend on this target. (optional) binary target: to create all binary packages (effectively combination of binary-arch and binary-indep targets). (required) This target is used by dpkg-buildpackage as in . binary-arch target: to create arch-dependent (Architecture: any) binary packages in the parent directory. (required) This target is used by dpkg-buildpackage -B as in . binary-indep target: to create arch-independent (Architecture: all) binary packages in the parent directory. (required) This target is used by dpkg-buildpackage -A. get-orig-source target: to obtain the most recent version of the original source package from upstream archive site. (optional) Rules that you want to execute are invoked as command line arguments (for example, ./debian/rules build or fakeroot make -f debian/rules binary). After the target name, you can name the dependency, program or file that the rule depends on. After that, there can be any number of commands, indented with TAB. A new rule begins with the target declaration in the first column. Empty lines and lines beginning with # (hash) are treated as comments and ignored. You are probably confused now, but it will all be clear upon examination of the rules file that dh_make gives us as a default. You should also read info make for more information.

Newer dh_make generates a very simple but powerful default rules file using the dh command: 1 #!/usr/bin/make -f 2 # -*- makefile -*- 3 # Sample debian/rules that uses debhelper. 4 # This file was originally written by Joey Hess and Craig Small. 5 # As a special exception, when this file is copied by dh-make into a 6 # dh-make output file, you may use that output file without restriction. 7 # This special exception was added by Craig Small in version 0.37 of dh-make. 8 9 # Uncomment this to turn on verbose mode. 10 #export DH_VERBOSE=1 11 12 %: 13 dh $@ (I've added the line numbers. In the actual rules file, the leading white spaces are TAB codes.) You are probably familiar with lines like line 1 from shell and Perl scripts. It tells the operating system that this file is to be processed with /usr/bin/make. Line 11 can be uncommented to set DH_VERBOSE variable to 1. Then, the dh command will output which dh_* commands are executed by the dh command. You can also add export DH_OPTIONS=-v line here. Then each dh_* command will output which commands are executed by each dh_* command. This helps you to understand what exactly is going on behind this simple rules file and to debug its problems. This new dh is a core part of the debhelper tools and does not hide anything from you. Lines 12 and 13 are where all the work is done. The percent sign means any targets which then call a single program, dh with the target name. This uses the new debhelper V7 features. Its design concepts are explained in Not Your Grandpa's Debhelper presented at Debconf9 by the debhelper upstream. Under lenny, dh_make created a much more complicated rules file with many dh_* scripts listed for each required explicit targets and frozen them to the state when it was initially packaged. This new dh command is simpler and frees us from this constrain. You still have full power to customize this with override_dh_* targets. See . It is based only on the debhelper package and does not obfuscate the package building process like the cdbs package. The dh command is a wrapper script which runs appropriate sequences of dh_* programs depending on its argument. You can verify actual sequences of dh_* programs invoked for a given target as dh --no-act target or debian/rules -- '--no-act target' without really running them. debian/rules clean runs dh clean; which in turn runs the following: dh_testdir dh_auto_clean dh_clean debian/rules build runs dh build; which in turn runs the following: dh_testdir dh_auto_configure dh_auto_build dh_auto_test fakeroot debian/rules binary runs fakeroot dh binary; which in turn runs the following This assumes that the python-support package is installed on the system. : dh_testroot dh_prep dh_installdirs dh_auto_install dh_install dh_installdocs dh_installchangelogs dh_installexamples dh_installman dh_installcatalogs dh_installcron dh_installdebconf dh_installemacsen dh_installifupdown dh_installinfo dh_pysupport dh_installinit dh_installmenu dh_installmime dh_installmodules dh_installlogcheck dh_installlogrotate dh_installpam dh_installppp dh_installudev dh_installwm dh_installxfonts dh_bugfiles dh_lintian dh_gconf dh_icons dh_perl dh_usrlocal dh_link dh_compress dh_fixperms dh_strip dh_makeshlibs dh_shlibdeps dh_installdeb dh_gencontrol dh_md5sums dh_builddeb fakeroot debian/rules binary-arch runs fakeroot dh binary-arch; which in turn runs the same sequence as fakeroot dh binary but with the -a option appended for each command. fakeroot debian/rules binary-indep runs fakeroot dh binary-indep; which in turn runs almost the same sequence as fakeroot dh binary but excluding dh_strip, dh_makeshlibs, and dh_shlibdeps with the -i option appended for each remaining command. The function of dh_* commands are almost self-evident from their names. For complete information on what do all these dh_* scripts exactly do, and what their other options are, please read their respective manual pages and the debhelper documentation. There are few notable ones worth making (over)simplified explanation here assuming typical build environment based on Makefile. These commands support other build environments such as setup.py which can be listed by executing dh_auto_build --list in a package source directory. dh_auto_clean usually executes the following if Makefile exists with the distclean target. It actually looks for the first available target of distclean, realclean or clean in Makefile and execute it. make distclean dh_auto_configure usually executes the following if ./configure exists (arguments abbreviated for readability). ./configure --prefix=/usr --sysconfdir=/etc --localstatedir=/var ... dh_auto_build usually executes the following to execute the first target of Makefile if it exists. make dh_auto_test usually executes the following if Makefile exists with the test target. It actually looks for the first available target of test or check in Makefile and execute it. make test dh_auto_install usually executes the following if Makefile exists with the install target (line folded for readability). make install \ DESTDIR=/path/to/package_version-revision/debian/package Targets which require the fakeroot command contain dh_testroot. If you are not pretending to be root using this command, it exits with an error. The important part to know about the rules file created by dh_make, is that it is just a suggestion. It will work for most packages but for more complicated ones, don't be afraid to customize it to fit your needs. Only things that you must not change are the names of the rules, because all the tools use these names, as mandated by the Debian Policy. Although install is not required target, it is supported. fakeroot dh install behaves like fakeroot dh binary but stops after dh_fixperms.

There are many ways to customize the rules file created with the new dh command. The dh $@ command can be customized as follows. If a package installs the /usr/share/perl5/Debian/Debhelper/Sequence/custom_name.pm file, you should activate its customization function by dh --with custom-name $@. Add support of the dh_pysupport command. (The best choice for Python.) Use of the dh_pysupport command is preferred over use of the dh_pycentral command. Do not use the dh_python command. Install the python-support package in Build-Depends. Use dh $@ as usual. (This is enabled by default) This handles Python modules using the python-support framework. Add support of the dh_pycentral command. Install the python-central package in Build-Depends. Use dh --with python-central $@ instead. This also deactivates the dh_pysupport command. This handles Python modules using the python-central framework. Add support of the dh_installtex command. Install the tex-common package in Build-Depends. Use dh --with tex $@ instead. This registers Type 1 fonts, hyphenation patterns, or formats with TeX. Add support of the dh_quilt_patch and dh_quilt_unpatch commands. Install the quilt package in Build-Depends. Use dh --with quilt $@ instead. This applies and un-applies patches to the upstream source from files in the debian/patches directory for the 1.0 source package. This is not needed if you use the new 3.0 (quilt) source package. Add support of the dh_dkms command. Install the dkms package in Build-Depends. Use dh --with dkms $@ instead. This correctly handles DKMS usage by the kernel module package. Add support of the dh_autotools-dev_updateconfig and dh_autotools-dev_restoreconfig commands. Install the autotools-dev package in Build-Depends. Use dh --with autotools-dev $@ instead. This updates and restores config.sub and config.guess. Add support of the dh_autoreconf and dh_autoreconf_clean commands. Install the dh-autoreconf package in Build-Depends. Use dh --with autoreconf $@ instead. This updates the GNU Build System files and restores them after the build. Add support to the bash completion feature. Install the bash-completion package in Build-Depends. Use dh --with bash-completion $@ instead. This installs bash completions using configuration file at debian/package.bash-completion. Many dh_* commands invoked by the new dh command can be customized by the corresponding configuration files in the debian directory. See and the manpage of each command for the customization of such features. Some dh_* commands invoked by the new dh command may require you to run it with some arguments or to run additional commands with them or to skip them. For such cases, you create an override_dh_foo target with its rule in the rules file only for the dh_foo command you want to change. It basically say run me instead. Under lenny, if you wanted to change the behavior of a dh_* script you found the relevant line in the rules file and adjusted it. Please note that the dh_auto_* commands tend to do more than what has been discussed as (over)simplified explanation to take care all the corner cases. Use of simplified equivalent command instead of these in override_dh_* targets except the override_dh_auto_clean target is a bad idea since it may kill such debhelper's smart features. If you want to store the system configuration data in the /etc/gentoo directory instead of the usual /etc directory for the recent gentoo package using Autotools, you can override the default --sysconfig=/etc argument given by the dh_auto_configure command to the ./configure command by the following. override_dh_auto_configure: dh_auto_configure -- --sysconfig=/etc/gentoo The arguments given after -- are appended to the default arguments of the auto-executed program to override them. Using the dh_auto_configure command is better than the ./configure command here since it will only override the --sysconfig argument and keeps well intended other arguments to the ./configure command. If Makefile of a source for gentoo requires you to specify build as its target to build it dh_auto_build without any arguments will execute the first target in the Makefile file. , you create an override_dh_auto_build target to enable it. override_dh_auto_build: dh_auto_build -- build This ensures to run $(MAKE) with all the default arguments given by the dh_auto_build command and build argument. If Makefile of a source for gentoo requires you to specify the packageclean target to clean it for Debian package instead of the distclean or clean targets in the Makefile file, you create an override_dh_auto_clean target to enable it. override_dh_auto_clean: $(MAKE) packageclean If Makefile of a source for gentoo contains test target which you do not want to run for the Debian package building process, you can use empty override_dh_auto_test target to skip it. override_dh_auto_test: If gentoo has an unusual upstream changelog file called FIXES, dh_installchangelogs will not install that file by default. The dh_installchangelogs command requires FIXES as its argument to install it. The debian/changelog and debian/NEWS files are always automatically installed. The upstream changelog is searched by converting filenames to the lower case and matching them with the changelog, changes, changelog.txt, and changes.txt. override_dh_installchangelogs: dh_installchangelogs FIXES When you use the new dh command, use of explicit targets such as the ones listed in except get-orig-source target may make it difficult to understand their exact effects. Please limit explicit targets to override_dh_* targets and completely independent ones, if possible.

To control most of what debhelper does while building the package, you put optional configuration files under the debian directory. This chapter will provide an overview of what each of these does and its format. Please read the Debian Policy Manual and Debian Developer's Reference for guidelines for packaging. The dh_make command will create some template configuration files under the debian directory. Most of them come with filenames suffixed by .ex. Some of them come with filenames prefixed by the binary package name such as package. Take a look at all of them. In this chapter, files in the debian directory are referred to without the preceding debian/ for simplicity whenever they are obvious. Some template configuration files for debhelper may not be created by the dh_make command. In such cases, you need to create them with an editor. If you wish or need to activate any of these, please do the following: rename template files by removing the .ex or .EX suffix if they have one; rename the configuration files to use the actual binary package name in place of package; modify template file contents to suit your needs; remove template files which you do not need; modify the control file (see ), if necessary; modify the rules file (see ), if necessary. Any debhelper configuration files without a package prefix, such as install, apply to the first binary package. When there are many binary packages, their configurations can be specified by prefixing their name to their configuration filenames such as package-1.install, package-2.install, etc.

Any extra details or discrepancies between the original package and your Debian version should be documented here. dh_make created a default one; this is what it looks like: gentoo for Debian ----------------- <possible notes regarding this package - if none, delete this file> -- Josip Rodin <joy-mg@debian.org>, Wed, 11 Nov 1998 21:02:14 +0100 If you have nothing to be documented, remove this file. See dh_installdocs 1 .

The compat file defines the debhelper compatibility level. Currently, you should set it to the debhelper v7 as follows: $ echo 7 > debian/compat

One of the most annoying things about software is when you spend a great deal of time and effort customizing a program, only to have an upgrade stomp all over your changes. Debian solves this problem by marking such configuration files as conffiles. See dpkg 1 and Debian Policy Manual "D.2.5 Conffiles". When you upgrade a package, you'll be asked whether you want to keep your old configuration files or not. dh_installdeb 1 automatically flags any files under the /etc directory as conffiles, so if your program only has conffiles there you do not need to specify them in this file. For most package types, the only place conffiles should ever be is under /etc, and so this file doesn't need to exist. If your program uses configuration files but also rewrites them on its own, it's best not to make them conffiles because dpkg will then prompt users to verify the changes all the time. If the program you're packaging requires every user to modify the configuration files in the /etc directory, there are two popular ways to arrange for them to not be conffiles, keeping dpkg quiet. Create a symlink under the /etc directory pointing to a file under the /var directory generated by the maintainer scripts. Create a file generated by the maintainer scripts under the /etc directory. For information on maintainer scripts, see .

If your package requires regularly scheduled tasks to operate properly, you can use these files to set that up. You can set up regular tasks that either happen hourly, daily, weekly, or monthly, or alternatively happen at any other time that you wish. The filenames are: package.cron.hourly - Installed as /etc/cron.hourly/package; run once an hour. package.cron.daily - Installed as /etc/cron.daily/package; run once a day. package.cron.weekly - Installed as /etc/cron.weekly/package; run once a week. package.cron.monthly - Installed as /etc/cron.monthly/package: run once a month. package.cron.d - Installed as /etc/cron.d/package: for any other time. Most of these files are shell scripts, with the exception of package.cron.d which follows the format of crontab 5 . No explicit cron.* file is needed to set up log rotation; for that, see dh_installlogrotate 1 and logrotate8.

This file specifies any directories which we need but which are not created by the normal installation procedure (make install DESTDIR=... invoked by dh_auto_install). This generally means there is a problem with the Makefile. Files listed in an install file don't need their directories created first. See . It is best to try to run the installation first and only use this if you run into trouble. There is no preceding slash on the directory names listed in the dirs file.

If your package has documentation other than manual and info pages, you should use the doc-base file to register it, so the user can find it with e.g. dhelp 1 , dwww 1 , or doccentral 1 . This usually includes HTML, PS and PDF files, shipped in /usr/share/doc/packagename/. This is what gentoo's doc-base file gentoo.doc-base looks like: Document: gentoo Title: Gentoo Manual Author: Emil Brink Abstract: This manual describes what Gentoo is, and how it can be used. Section: File Management Format: HTML Index: /usr/share/doc/gentoo/html/index.html Files: /usr/share/doc/gentoo/html/*.html For information on the file format, see install-docs 8 and the doc-base manual, in Debian doc-base Manual. For more details on installing additional documentation, look in .

This file specifies the file names of documentation files we can have dh_installdocs 1 install into the temporary directory for us. By default, it will include all existing files in the top-level source directory that are called BUGS, README*, TODO etc. For gentoo, some other files are also included: BUGS CONFIG-CHANGES CREDITS NEWS README README.gtkrc TODO

If your package supplies Emacs files that can be bytecompiled at package installation time, you can use these files to set it up. They are installed into the temporary directory by dh_installemacsen 1 . If you don't need these, remove them.

The dh_installexamples 1 command installs files and directories listed in this file as example files.

If your package is a daemon that needs to be run at system start-up, you've obviously disregarded my initial recommendation, haven't you? :-) The package.init file is installed as the /etc/init.d/package script which starts and stops the daemon. Its fairly generic skeleton template is provided by the dh_make command as init.d.ex. You'll likely have to rename and edit it, a lot, while making sure to provide Linux Standard Base (LSB) compliant headers. It gets installed into the temporary directory by dh_installinit 1 . The package.default file will be installed as /etc/default/package. This file sets defaults that are sourced by the init script. This package.default file is most often used to disable running a daemon, or to set some default flags or timeouts. If your init script has certain configurable features, you can set them in the package.default file, instead of in the init script itself. If your upstream program provides a file for the init script, you can either use it or not. If you don't use their init script then create a new one in package.init. However if the upstream init script looks fine and installs in the right place you still need to set up the rc* symlinks. To do this you will need to override dh_installinit in the rules file with the following lines: override_dh_installinit: dh_installinit --onlyscripts If you don't need this, remove the files.

If there are files that need to be installed into your package but your standard make install won't do it, put the filenames and destinations into this install file. They are installed by dh_install 1 . This replaces the deprecated dh_movefiles 1 command which is configured by the files file. You should first check there is not a more specific tool to use. For example, documents should be in the docs file and not in this one. This install file has one line per file installed, with the name of the file (relative to the top build directory) then a space then the installation directory (relative to the install directory). One example of where this is used is if a binary src/bar is left uninstalled; the install file might look like: src/bar usr/bin This means when this package is installed, there will be a binary executable /usr/bin/bar. Alternatively, this install can have the name of the file only without the installation directory when the relative directory path does not change. This format is usually used for a large package that splits the output of its build into multiple binary packages using package-1.install, package-2.install, etc. The dh_install command will fall back to looking in debian/tmp for files, if it doesn't find them in the current directory (or wherever you've told it to look using --sourcedir).

If your package has info pages, you should install them using dh_installinfo 1 by listing them in a package.info file.

If lintian reports an erroneous diagnostic for a case where Debian policy allows exceptions to some rule, you can use package.lintian-overrides or source/lintian-overrides to quieten it. Please read Lintian User's Manual and refrain from abusing this. package.lintian-overrides is for the binary package named package and is installed into usr/share/lintian/overrides/package by the dh_lintian command. source/lintian-overrides is for the source package. This is not installed.

Your program(s) should have a manual page. If they don't, you should create them. The dh_make command creates some template files for manual pages. These need to be copied and edited for each command missing its manual page. Please make sure to remove unused templates.

Manual pages are normally written in nroff 1 . The manpage.1.ex template is written in nroff, too. See the man 7 manual page for a brief description of how to edit such a file. The final manual page file name should give the name of the program it is documenting, so we will rename it from manpage to gentoo. The file name also includes .1 as the first suffix, which means it's a manual page for a user command. Be sure to verify that this section is indeed the correct one. Here's a short list of manual page sections: Section Description Notes 1 User command Executable commands or scripts 2 System calls Functions provided by the kernel 3 Library calls Functions within system libraries 4 Special files Usually found in /dev 5 File formats E.g. /etc/passwd's format 6 Games Games or other frivolous programs 7 Macro packages Such as man macros 8 System administration Programs typically only run by root 9 Kernel routines Non-standard calls and internals So gentoo's man page should be called gentoo.1. If there was no gentoo.1 man page in the original source, you should create it by renaming the manpage.1.ex template to gentoo.1 and editing it using information from the example and from the upstream docs. You can use the help2man command to generate a man page out of the --help and --version output of each program, too. Note that help2man's placeholder man page will claim that more detailed documentation is available in the info system. If the command is missing an info page, you should manually edit the man page created by the help2man command.

If on the other hand you prefer writing SGML instead of nroff, you can use the manpage.sgml.ex template. If you do this, you have to: rename the file to something like gentoo.sgml. install the docbook-to-man package add docbook-to-man to the Build-Depends line in the control file add an override_dh_auto_build target to your rules file: override_dh_auto_build: docbook-to-man debian/gentoo.sgml > debian/gentoo.1 dh_auto_build

If you prefer XML over SGML, you can use the manpage.xml.ex template. If you do this, you have to: rename the source file to something like gentoo.1.xml install the docbook-xsl package and an XSLT processor like xsltproc (recommended) add the docbook-xsl, docbook-xml, and xsltproc packages to the Build-Depends line in the control file add an override_dh_auto_build target to your rules file: override_dh_auto_build: xsltproc --nonet \ --param make.year.ranges 1 \ --param make.single.year.ranges 1 \ --param man.charmap.use.subset 0 \ -o debian/ \ http://docbook.sourceforge.net/release/xsl/current/manpages/docbook.xsl\ debian/gentoo.1.xml dh_auto_build

If your package has manual pages, you should install them using dh_installman 1 by listing them in a package.manpages file. To install docs/gentoo.1 as a manpage for the gentoo package, create a gentoo.manpages file as follows. docs/gentoo.1

X Window System users usually have a window manager with a menu that can be customized to launch programs. If they have installed the Debian menu package, a set of menus for every program on the system will be created for them. Here's the default menu.ex file that dh_make created. ?package(gentoo):needs=X11|text|vc|wm \ section=Applications/see-menu-manual\ title=gentoo command=/usr/bin/gentoo The first field after the colon character is needs, and it specifies what kind of interface the program needs. Change this to one of the listed alternatives, e.g. text or X11. The next is the section that the menu and submenu entry should appear in. The current list of sections is in The Debian Menu sub-policy 2.1 "Preferred menu structure". There was a major reorganization of menu structure for squeeze. The title field is the name of the program. You can start this one in uppercase if you like. Just keep it short. Finally, the command field is the command that runs the program. Let's change the file name to menu and change the menu entry to this: ?package(gentoo): needs=X11 \ section=Applications/Tools \ title=Gentoo command=gentoo You can also add other fields like longtitle, icon, hints etc. See dh_installmenu 1 , menufile 5 , update-menus 1 , and The Debian Menu sub-policy for more information.

The dh_installchangelogs 1 command installs this.

These postinst, preinst, postrm, and prerm files Despite this use of the bash shorthand expression {pre,post}{inst,rm} to indicate these filenames, you should use pure POSIX syntax for these maintainer scripts for compatibility with dash as the system shell. are called maintainer scripts. They are scripts which are put in the control area of the package and run by dpkg when your package is installed, upgraded, or removed. As a novice maintainer, you should avoid any manual editing of maintainer scripts because they are problematic. For more information refer to the Debian Policy Manual, 6 "Package maintainer scripts and installation procedure", and take a look at the example files provided by dh_make. If you did not listen to me and have created custom maintainer scripts for a package, you should make sure to test them not only for install and upgrade but also for remove and purge. Upgrades to the new version should be silent and non-intrusive (existing users should not notice the upgrade except by discovering that old bugs have been fixed and perhaps that there are new features). When the upgrade is necessarily intrusive (eg., config files scattered through various home directories with totally different structure), you may consider as the last resort switching the package to a safe fallback state (e.g., disabling a service) and providing the proper documentation required by policy (README.Debian and NEWS.Debian). Don't bother the user with debconf notes invoked from these maintainer scripts for upgrades. The ucf package provides a conffile-like handling infrastructure to preserve user changes for files that may not be labeled as conffiles such as those managed by the maintainer scripts. This should minimize issues associated with them. These maintainer scripts are among the Debian enhancements that explain why people choose Debian. You must be very careful not to turn them into a source of annoyance.

The dh_installdocs 1 command installs this.

The watch file format is documented in the uscan 1 manpage. The watch file configures the uscan program (in the devscripts package) to watch the site where you originally got the source from. This is also used by the Debian External Health Status (DEHS) service. Here are its contents: # watch control file for uscan version=3 &sf-net;/gentoo/gentoo-(.+)\.tar\.gz debian uupdate Normally with a watch file, the URL at &sf-net;/gentoo is downloaded and searched for links of the form <a href=...>. The basename (just the part after the final /) of each linked URL is compared against the Perl regular expression pattern (see perlre 1 ) gentoo-(.+)\.tar\.gz. Out of the files that match, the one with the greatest version number is downloaded and the uupdate program is run to create an updated source tree. Although this is true for other sites, the SourceForge download service at is an exception. When the watch file has an URL matching the Perl regexp ^http://sf\.net/, the uscan program replaces it with &qa-do;watch/sf.php/ and then applies this rule. The URL redirector service at is designed to offer a stable redirect service to the desired file for any watch pattern of the form &sf-net;/project/tar-name-(.+)\.tar\.gz. This solves issues related to periodically changing SourceForge URLs.

In the debian/source/format file, there should be a single line indicating the desired format for the source package (check dpkg-source 1 for an exhaustive list). After squeeze, it should say either: 3.0 (native) for Debian native packages or 3.0 (quilt) for everything else. The newer 3.0 (quilt) source format records modifications in a quilt patch series within debian/patches. Those changes are then automatically applied during extraction of the source package. See DebSrc3.0 for a summary on the switch to the new 3.0 (quilt) and 3.0 (native) source formats. The Debian modifications are simply stored in a debian.tar.gz archive containing all files under the debian directory. This new format supports inclusion of binary files such as PNG icons by the package maintainer without requiring tricks. Actually, this new format also supports multiple upstream tarballs and more compression methods. These are beyond the scope of this document. When dpkg-source extracts a source package in 3.0 (quilt) source format, it automatically applies all patches listed in debian/patches/series. You can avoid applying patches at the end of the extraction with the --skip-patches option.

When you want to manage Debian packaging activities under a VCS, you typically create one branch (e.g. upstream) tracking the upstream source and another branch (e.g. typically master for Git) tracking the Debian package. For the latter, you usually want to have unpatched upstream source with your debian/* files for the Debian packaging to ease merging of the new upstream source. After you build a package, the source is normally left patched. You need to unpatch it manually by running dquilt pop -a before committing to the master branch. You can automate this by adding the optional debian/source/local-options file containing unapply-patches. This file is not included in the generated source package and changes the local build behavior only. This file may contain abort-on-upstream-changes, too (see dpkg-source 1 ). unapply-patches abort-on-upstream-changes

The autogenerated files in the source tree can be quite annoying for packaging since they generate meaningless large patch files. There are custom modules such as dh_autoreconf to ease this problem as described in . You can provide a Perl regular expression to the --extend-diff-ignore option argument of dpkg-source1 to ignore changes made to the autogenerated files while creating the source package. As a general solution to address this problem of the autogenerated files, you can store such a dpkg-source option argument in the source/options file of the source package. The following will skip creating patch files for config.sub, config.guess, and Makefile. extend-diff-ignore = "(^|/)(config\.sub|config\.guess|Makefile)$"

The old 1.0 source format created a single large diff.gz file containing package maintenance files in debian and patch files for the source. Such a package is a bit cumbersome to inspect and understand for each source tree modification later. This is not so nice. The newer 3.0 (quilt) source format stores patches in debian/patches/* files using the quilt command. These patches and other package data which are all contained under the debian directory are packaged as the debian.tar.gz file. Since the dpkg-source command can handle quilt formatted patch data in the 3.0 (quilt) source without the quilt package, it does not need a Build-Depends on quilt. Several methods of patch set maintenance have been proposed and are in use for Debian packages. The quilt system is the preferred maintenance system in use. Others include dpatch, dbs, and cdbs. Many of these keep such patches as debian/patches/* files. The quilt command is explained in quilt 1 . It records modifications to the source as a stack of -p1 patch files in the debian/patches directory and the source tree is untouched outside of the debian directory. The order of these patches is recorded in the debian/patches/series file. You can apply (=push), un-apply (=pop), and refresh patches easily. If you are asking a sponsor to upload your package, this kind of clear separation and documentation of your changes is very important to expedite the package review by your sponsor. For , we created three patches in debian/patches. Since Debian patches are located in debian/patches, please make sure to set up the dquilt command properly as described in . When anyone (including yourself) provides a patch foo.patch to the source later, modifying a 3.0 (quilt) source package is quite simple: $ dpkg-source -x gentoo_0.9.12.dsc $ cd gentoo-0.9.12 $ dquilt import ../foo.patch $ dquilt push $ dquilt refresh $ dquilt header -e ... describe patch The patches stored in the newer 3.0 (quilt) source format must be fuzz free. You can ensure this with dquilt pop -a; while dquilt push; do dquilt refresh; done.

We should now be ready to build the package.

In order to perform a complete (re)build of a package properly, you need to make sure you have installed the build-essential package, packages listed in the Build-Depends field (see ), and packages listed in the Build-Depends-indep field (see ). Then you issue the following command in the source directory: $ dpkg-buildpackage This will do everything to make full binary and source packages for you. It will: clean the source tree (debian/rules clean) build the source package (dpkg-source -b) build the program (debian/rules build) build binary packages (fakeroot debian/rules binary) sign the source .dsc file, using gpg create and sign the upload .changes file, using dpkg-genchanges and gpg The only input that will be required of you is your GPG secret pass phrase, twice. This GPG key must be signed by a Debian developer to get connected to the web of trust and must be registered to the Debian keyring. This enables your uploaded packages to be accepted to the Debian archives. See Creating a new GPG key and Debian Wiki on Keysigning. After all this is done for the non-native Debian package, you will see the following files in the directory above (~/gentoo): gentoo_0.9.12.orig.tar.gz This is the original upstream source code tarball, merely renamed to the above so that it adheres to the Debian standard. Note that this was created initially by the dh_make -f ../gentoo-0.9.12.tar.gz. gentoo_0.9.12-1.dsc This is a summary of the contents of the source code. The file is generated from your control file, and is used when unpacking the source with dpkg-source 1 . This file is GPG signed, so that people can be sure that it's really yours. gentoo_0.9.12-1.debian.tar.gz This compressed tarball contains your debian directory contents. Each and every addition you made to the original source code is stored as a quilt patch in debian/patches. If someone else wants to re-create your package from scratch, they can easily do so using the above three files. The extraction procedure is trivial: just copy the three files somewhere else and run dpkg-source -x gentoo_0.9.12-1.dsc. You can avoid applying quilt patches in the 3.0 (quilt) source format at the end of the extraction with the --skip-patches option. Alternatively, you can run dquilt pop -a after normal operation. gentoo_0.9.12-1_i386.deb This is your completed binary package. You can use dpkg to install and remove this just like any other package. gentoo_0.9.12-1_i386.changes This file describes all the changes made in the current package revision; it is used by the Debian FTP archive maintenance programs to install the binary and source packages. It is partly generated from the changelog file and the .dsc file. This file is GPG signed, so that people can be sure that it's really yours. As you keep working on the package, its behavior will change and new features will be added. People downloading your package can look at this file and quickly see what has changed. Debian archive maintenance programs will also post the contents of this file to the debian-devel-announce@lists.debian.org mailing list. The long strings of numbers in the .dsc and .changes files are SHA1/SHA256 checksums for the files mentioned. Anyone downloading your files can test them with sha1sum 1 or sha256sum 1 and if the numbers don't match, they'll know the file is corrupt or has been tampered with. Here, if you are building Debian packages only for your local use, you can skip promptings for the GPG signitures on the .dsc file and the .changes file as: $ dpkg-buildpackage -us -uc

Debian supports many ports with the autobuilder network running buildd daemons on computers of many different architectures. Although you do not need to do this yourself, you should be aware of what will happen to your packages. Let's look into roughly how they rebuild your packages for multiple architectures. The actual autobuilder system involves much more complicated schemes than the one documented here. Such details are beyond the scope of this document. For Architecture: any packages, the autobuilder system performs a rebuild. It ensures the installation of the build-essential package, and packages listed in the Build-Depends field (see ). Then it issues the following command in the source directory: $ dpkg-buildpackage -B This will do everything to make architecture dependent binary packages on another architecture. It will: clean the source tree (debian/rules clean) build the program (debian/rules build) build architecture dependent binary packages (fakeroot debian/rules binary-arch) sign the source .dsc file, using gpg create and sign the upload .changes file, using dpkg-genchanges and gpg This is why you see your package for other architectures. Although packages listed in the Build-Depends-Indep field are required to be installed for our normal packaging work (see ), they are not required to be installed for the autobuilder system since it builds only architecture dependent binary packages. Unlike under the pbuilder package, the chroot environment under the sbuild package used by the autobuilder system does not enforce the use of a minimal system and may have many leftover packages installed. This distinction between normal packaging and autobuilding procedures is what dictates whether you should record such required packages in the Build-Depends or Build-Depends-Indep fields of the debian/control file (see ).

You can automate the dpkg-buildpackage command's package build process further with the debuild command. See debuild 1 . Customization of the debuild command can be done through /etc/devscripts.conf or ~/.devscripts. I would suggest at least the following items: DEBSIGN_KEYID=Your_GPG_keyID DEBUILD_LINTIAN_OPTS=-i -I --show-overrides With these, packages are signed by your specified GPG key ID (good for sponsoring packages) and checked in detail by the lintian command. Cleaning the source and rebuilding the package from your user account is as simple as: $ debuild Here, if you are building Debian packages only for your local use, you can skip promptings for the GPG signitures on the .dsc file and the .changes file as: $ debuild -us -uc You can clean the source tree as simply as: $ debuild clean

For a clean room (chroot) build environment to verify the build dependencies, the pbuilder package is very useful. Since the pbuilder package is still evolving, you should check the actual configuration situation by consulting the latest official documentation. This ensures a clean build from the source under the sid auto-builder for different architectures and avoids a severity serious FTBFS (Fails To Build From Source) bug which is always in the RC (release critical) category. See for more on Debian package auto-building. . Let's customize the pbuilder package as follows: setting the /var/cache/pbuilder/result directory writable by for your user account. creating a directory, e.g. /var/cache/pbuilder/hooks, writable by the user, to place hook scripts in. configuring ~/.pbuilderrc or /etc/pbuilderrc to include the followsing. AUTO_DEBSIGN=${AUTO_DEBSIGN:-yes} HOOKDIR=/var/cache/pbuilder/hooks This will allow you to sign generated packages with your secret GPG key in the ~/.gnupg/ directory. First let's initialize the local pbuilder chroot system as follows. $ sudo pbuilder create If you already have a completed source package, issue the following commands in the directory where the foo.orig.tar.gz, foo.debian.tar.gz, and foo.dsc files exist to update the local pbuilder chroot system and to build binary packages in it. $ sudo pbuilder --update $ sudo pbuilder --build foo_version.dsc The newly built packages without the GPG signitures will be located in /var/cache/pbuilder/result/ with non-root ownership. The GPG signitures on the .dsc file and the .changes file can be generated as: $ cd /var/cache/pbuilder/result/ $ debsign foo_version.dsc $ debsign foo_version_arch.changes If you have an updated source tree but have not generated the matching source package, issue the following commands in the source directory where the debian directory exists, instead. $ sudo pbuilder --update $ pdebuild Here, if you are building Debian packages only for your local use, you can skip promptings for the GPG signitures on the .dsc file and the .changes file as: $ AUTO_DEBSIGN=no pdebuild You can log into its chroot environment with the pbuilder --login --save-after-login command and configure it as you wish. This environment can be saved by leaving its shell prompt with ^D (Control-D). The latest version of the lintian command can be executed in the chroot environment using the hook script /var/cache/pbuilder/hooks/B90lintian configured as follows. This assumes HOOKDIR=/var/cache/pbuilder/hooks. You can find many examples of hook scripts in the /usr/share/doc/pbuilder/examples directory. #!/bin/sh set -e install_packages() { apt-get -y --force-yes install $@ } install_packages lintian echo +++ lintian output +++ su -c lintian -i -I --show-overrides /tmp/buildd/*.changes - pbuilder # use this version if you don't want lintian to fail the build #su -c lintian -i -I --show-overrides /tmp/buildd/*.changes; : - pbuilder echo +++ end of lintian output +++ You need to have access to the latest sid environment to build packages properly for sid. In practice, sid may be experiencing issues which makes it undesirable for you to migrate your whole system. The pbuilder package can help you to cope with this kind of situation. You may need to update your stable packages after their release for stable-proposed-updates, stable/updates, etc. There are some restrictions for such updates of your stable package. For such occasions, the fact you may be running a sid system is not a good enough excuse for failing to update them promptly. The pbuilder package can help you to access environments of almost any Debian derivative distribution of the same CPU architecture. See , pdebuild 1 , pbuilderrc 5 , and pbuilder 8 .

If your upstream uses a source code management system (VCS) See Version control systems for more. to maintain their code, you should consider using it as well. This makes merging and cherry-picking upstream patches much easier. There are several specialized wrapper script packages for Debian package building for each VCS. git-buildpackage: a suite to help with Debian packages in Git repositories. svn-buildpackage: helper programs to maintain Debian packages with Subversion. cvs-buildpackage: a set of Debian package scripts for CVS source trees. For advanced audiences, there are packages which automate the building of packages under a VCS-managed source tree. I will not explain them in this tutorial. Here are some web resources available for advanced audiences. Building Debian Packages with git-buildpackage debian packages in git Using Git for Debian Packaging git-dpm: Debian packages in Git manager Using TopGit to generate quilt series for Debian packaging

With a large package, you may not want to rebuild from scratch every time while you're tuning details in debian/rules. For testing purposes, you can make a .deb file without rebuilding the upstream sources like this Environment variables which are normally configured to proper values are not set by this method. Never create real packages to be uploaded using this quick method. : $ fakeroot debian/rules binary Or simply do the following to see if it builds or not: $ fakeroot debian/rules build Once you are finished with your tuning, remember to rebuild following the proper procedure. You may not be able to upload correctly if you try to upload .deb files built this way.

There are some techniques you should know for checking a package for errors before uploading it to the public archives. It's also a good idea to carry out testing on a machine other than your own. You must watch closely for any warnings or errors for all the tests described here.

You must test your package for whether it installs without problem. The debi 1 command helps you to test installing all the generated binary packages. $ sudo debi gentoo_0.9.12-1_i386.changes To prevent installation problem on different systems, you must make sure that there are no filenames conflicting with other existing packages, using the Contents-i386 file downloaded from the Debian archive, The apt-file command may be handy for this task. If there are collisions, please take action to avoid this real problem, whether by renaming the file, moving a common file to a separate package that multiple packages can depend on, using the alternatives mechanism (see update-alternatives 1) in coordination with the maintainers of other affected packages, or declaring a Conflicts relationship in the debian/control file.

All maintainer scripts (that is, preinst, prerm, postinst, and postrm files) are hard to write correctly unless they are auto-generated by the debhelper programs. So do not use them if you are a novice maintainer (see ). If the package makes use of these non-trivial maintainer scripts, be sure to test not only for install but also for remove, purge, and upgrade processes. Many maintainer script bugs show up when packages are removed or purged. Use the dpkg command as follows to test them. $ sudo dpkg -r gentoo $ sudo dpkg -P gentoo $ sudo dpkg -i gentoo_version-revision_i386.deb This should be done with sequences such as the following. install the previous version (if needed). upgrade it from the previous version. downgrade it back to the previous version (optional). purge it. install the new package. remove it. install it again. purge it. If this is your first package, you should create dummy packages with different versions to test your package in advance to prevent future problems. Bear in mind that if your package has previously been released in Debian, people will often be upgrading to your package from the version that was in the last Debian release. Remember to test upgrades from that version too. Although downgrading is not officially supported, supporting it is a friendly gesture.

Run lintian 1 on your .changes file. The lintian command runs many test scripts to check for many common packaging errors. You do not need to provide the lintian option -i -I --show-overrides if you customized /etc/devscripts.conf or ~/.devscripts as described in . $ lintian -i -I --show-overrides gentoo_0.9.12-1_i386.changes Of course, replace the filename with the name of the .changes file generated for your package. The output of the lintian command uses the following flags. E: for error; a sure policy violation or packaging error. W: for warning; a possible policy violation or packaging error. I: for info; information on certain aspects of packaging. N: for note; a detailed message to help your debugging. O: for overridden; a message overridden by the lintian-overrides files but displayed by the --show-overrides option. When you see warnings, tune the package to avoid them or verify that the warnings are spurious. If spurious, set up lintian-overrides files as described in . Note that you can build the package with dpkg-buildpackage and run lintian on it in one command, if you use debuild 1 or pdebuild 1 .

You can list files in the binary Debian package with the debc 1 command. $ debc package.changes

You can compare file contents in two source Debian packages with the debdiff 1 command. $ debdiff old-package.dsc new-package.dsc You can also compare file lists in two sets of binary Debian packages with the debdiff 1 command. $ debdiff old-package.changes new-package.changes These are useful to identify what has been changed in the source packages and to check for inadvertent changes made when updating binary packages, such as unintentionally misplacing or removing files.

You can compare two diff.gz files with the interdiff 1 command. This is useful for verifying that no inadvertent changes were made to the source by the maintainer when updating packages in the old 1.0 source format. $ interdiff -z old-package.diff.gz new-package.diff.gz The new 3.0 source format stores changes in multiple patch files as described in . You can trace changes of each debian/patches/* file using interdiff, too.

Many of these file inspection operations can be made into an intuitive process by using a file manager like mc 1 which will let you browse not only the contents of *.deb package files but also *.udeb, *.debian.tar.gz, *.diff.gz, and *.orig.tar.gz files. Be on the lookout for extra unneeded files or zero length files, both in the binary and source package. Often cruft doesn't get cleaned up properly; adjust your rules file to compensate for this.

Now that you have tested your new package thoroughly, you want to release it to a public archive to share it.

Once you become an official developer, See . you can upload the package to the Debian archive. There are publicly accessible archives such as which work almost the same way as the Debian archive and provide an upload area for non-DDs. You can set up an equivalent archive by yourself using the tools listed at . So this section is useful for non-DDs, too. You can do this manually, but it's easier to use the existing automated tools, like dupload 1 or dput 1 . We'll describe how it's done with dupload. The dput package seems to come with more features and to be becoming more popular than the dupload package. It uses the file /etc/dput for its global configuration and the file ~/.dput.cf for per-user configuration. It supports Ubuntu-related services out-of-the-box, too. First you have to set up dupload's config file. You can either edit the system-wide /etc/dupload.conf file, or have your own ~/.dupload.conf file override the few things you want to change. You can read the dupload.conf 5 manual page to understand what each of these options means. The $default_host option determines which of the upload queues will be used by default. anonymous-ftp-master is the primary one, but it's possible that you will want to use another one. See Debian Developer's Reference 5.6. "Uploading a package". While connected to the Internet, you can upload your package as follows: $ dupload gentoo_0.9.12-1_i386.changes dupload checks that the SHA1/SHA256 file checksums match those listed in the .changes file. If they do not match, it will warn you to rebuild it as described in so it can be properly uploaded. If you encounter an upload problem at , you can fix this by manually uploading a GPG-signed *.commands file to there with ftp. See . Alternatively, you can use the dcut command from the dput package. For example, using hello.commands: -----BEGIN PGP SIGNED MESSAGE----- Hash: SHA1 Uploader: Foo Bar <Foo.Bar@example.org> Commands: rm hello_1.0-1_i386.deb mv hello_1.0-1.dsx hello_1.0-1.dsc -----BEGIN PGP SIGNATURE----- Version: GnuPG v1.4.10 (GNU/Linux) [...] -----END PGP SIGNATURE-----

When you first upload the package to the archive, you need to include the original orig.tar.gz source, too. If the Debian revision number of this package is neither 1 nor 0, you must provide the dpkg-buildpackage option -sa. For the dpkg-buildpackage command: $ dpkg-buildpackage -sa For the debuild command: $ debuild -sa For the debuild command: $ pdebuild --debbuildopts -sa On the other hand, the -sd option will force the exclusion of the original orig.tar.gz source.

If you created multiple entries in debian/changelog by skipping uploads, you must create a proper *_.changes file which includes all changes from the last upload. This can be done by specifying the dpkg-buildpackage option -v with the version, e.g., 1.2. For the dpkg-buildpackage command: $ dpkg-buildpackage -v1.2 For the debuild command: $ debuild -v1.2 For the debuild command: $ pdebuild --debbuildopts "-v1.2"

After you release a package, you will soon need to update it.

Let's say that a bug report was filed against your package as #654321, and it describes a problem that you can solve. Here's what you need to do to create a new Debian revision of the package. If this is to be recorded as a new patch, do the following. dquilt new bugname.patch to set the patch name; dquilt add buggy-file to declare the file to be modified; Correct the problem in the package source for the upstream bug; dquilt refresh to record it to bugname.patch; dquilt header -e to add its description; If this is to update an existing patch, do the following. dquilt pop foo.patch to recall the existing foo.patch; Correct the problem in the old foo.patch; dquilt refresh to update foo.patch; dquilt header -e to update its description; while dquilt push; do dquilt refresh; done to apply all patches while removing fuzz; Add a new revision at the top of the Debian changelog file, for example with dch -i, or explicitly with dch -v version-revision and then insert the comments using your preferred editor. To get the date in the required format, use LANG=C date -R. Include a short description of the bug and the solution in the changelog entry, followed by Closes: #654321. That way, the bug report will be automagically closed by the archive maintenance software the moment your package gets accepted into the Debian archive. Repeat what you did in the above to fix more bugs while updating the Debian changelog file with dch as needed. Repeat what you did in , , and . The difference is that this time, the original source archive won't be included, as it hasn't been changed and it already exists in the Debian archive.

When preparing packages of the a upstream release for the Debian archive, you must check the new upstream release, first. Start by reading the upstream changelog, NEWS, and whatever other documentation they may have released with the new version. You can then inspect changes between the old and new upstream sources as follows, watching out for anything suspicious. $ diff -urN foo-oldversion foo-newversion Changes to some auto-generated files by Autotools such as missing, aclocal.m4, config.guess, config.h.in, config.sub, configure, depcomp, install-sh, ltmain.sh, and Makefile.in may be ignored. You may delete them before running diff on the source for inspection.

If a package foo is properly packaged in the newer 3.0 (native) or 3.0 (quilt) formats, packaging a new upstream version is essentially moving the old debian directory to the new source. This can be done by running tar xvzf /path/to/foo_oldversion.debian.tar.gz in the new extracted source. If a package foo is packaged in the old 1.0 format, this can be done by running zcat /path/to/foo_oldversion.diff.gz|patch -p1 in the new extracted source, instead. Of course, you need to do some obvious chores. Create a copy of the upstream source as the foo_newversion.tar.gz file. Update the Debian changelog file with dch -v newversion-1. Add an entry with New upstream release. Describe concisely the changes in the new upstream release that fix reported bugs and close those bugs by adding Closes: #bug_number. Describe concisely the changes to the new upstream release by the maintainer that fix reported bugs and close those bugs by adding Closes: #bug_number. while dquilt push; do dquilt refresh; done to apply all patches while removing fuzz. If the patch/merge did not apply cleanly, inspect the situation (clues are left in .rej files). If a patch you applied to the source was integrated into the upstream source, dquilt delete to remove it. If a patch you applied to the source conflicted with new changes in the upstream source, dquilt push -f to apply old patches while forcing rejects as baz.rej. Edit the baz file manually to bring about the intended effect of baz.rej. dquilt refresh to update the patch. Continue as usual with while dquilt push; do dquilt refresh; done. This process can be automated using the uupdate 1 command as follows: $ apt-get source foo ... dpkg-source: info: extracting foo in foo-oldversion dpkg-source: info: unpacking foo_oldversion.orig.tar.gz dpkg-source: info: applying foo_oldversion-1.debian.tar.gz $ ls -F foo-oldversion/ foo_oldversion-1.debian.tar.gz foo_oldversion-1.dsc foo_oldversion.orig.tar.gz $ wget http://example.org/foo/foo-newversion.tar.gz $ cd foo-oldversion $ uupdate -v newversion ../foo-newversion.tar.gz $ cd ../foo-newversion $ while dquilt push; do dquilt refresh; done $ dch ... document changes made If you set up a debian/watch file as described in , you can skip the wget command. You simply run uscan 1 in the foo-oldversion directory instead of the uupdate command. This will automagically look for the updated source, download it, and run the uupdate command. If the uscan command downloads the updated source but it does not run the uupdate command, you should correct the debian/watch file to have debian uupdate at the end of the URL. You can release this updated source by repeating what you did in , , and .

Updating the package style is not a required activity for the update of a package. However, doing so lets you use the full capabilities of the modern debhelper system and the 3.0 source format. If your sponsor or other maintainers object to updating the existing packaging style, don't bother arguing. There are more important things to do. If you need to recreate deleted template files for any reason, you can run dh_make again in the same Debian package source tree with the --addmissing option. Then edit them appropriately. If the package has not been updated to use the debhelper v7 dh syntax for the debian/rules file, update it to use dh. Update the debian/control file accordingly. If you want to update the rules file created with the Makefile inclusion mechanism of the Common Debian Build System (cdbs) to the dh syntax, see cdbs-doc.pdf.gz and understand its DEB_* configuration variables. If you have a 1.0 source package without the foo.diff.gz file, you can update it to the newer 3.0 (native) source format by creating debian/source/format with 3.0 (native). The rest of the debian/* files can just be copied. If you have a 1.0 source package with the foo.diff.gz file, you can update it to the newer 3.0 (quilt) source format by creating debian/source/format with 3.0 (quilt). The rest of the debian/* files can just be copied. Import the big.diff file generated by the command filterdiff -z -x '*/debian/*' foo.diff.gz > big.diff to your quilt system, if needed. You can split big.diff into many small incremental patches using the splitdiff command. If it was packaged using another patch system such as dpatch, dbs, or cdbs with -p0, -p1, or -p2, convert it to the quilt command using deb3 at . If it was packaged with the dh command with the --with quilt option or with the dh_quilt_patch and dh_quilt_unpatch commands, remove these and make it use the newer 3.0 (native) source format. You need to do the other tasks described in , too.

Here are few reminders for updating packages. Preserve old changelog entries (sounds obvious, but there have been cases of people typing dch when they should have typed dch -i.) Existing Debian changes need to be reevaluated; throw away stuff that upstream has incorporated (in one form or another) and remember to keep stuff that hasn't been incorporated by upstream, unless there is a compelling reason not to. If any changes were made to the build system (hopefully you'd know from inspecting upstream changes) then update the debian/rules and debian/control build dependencies if necessary. Check the Debian Bug Tracking System (BTS) to see if someone has provided patches to bugs that are currently open. Check the contents of the .changes file to make sure you are uploading to the correct distribution, the proper bug closures are listed in the Closes field, the Maintainer and Changed-By fields match, the file is GPG-signed, etc.