Debian New Maintainers' Guide
Footnotes

1

The document assumes you are using the squeeze system. If you need to follow this text in the lenny system, you must install backported dpkg and debhelper packages, at least.

2

There are few similar but specialized packages such as dh-make-perl, dh-make-php, etc.

3

Having said that, there will of course always be new programs that are worthwhile packaging.

4

You can identify the archive format using the file command when the file extension is not enough.

5

This program is already packaged. Current version 0.15.3 has changed substantially from the version 0.9.12 in the following examples.

6

See Autotools Tutorial and /usr/share/doc/autotools-dev/README.Debian.gz.

7

Version string can be compared by "dpkg --compare-versions ver1 op ver2". See dpkg(1) manpage.

8

The following text assumes you are using Bash as your login shell. If you use other login shells such as Z shell, use their pertinent configuration files instead of ~/.bashrc.

9

If the upstream source provides the debian directory and its contents, run the dh_make command with the --addmissing option, instead. The new source 3.0 (quilt) format is quite robust not to break even for these packages. You may need to update contents provided by the upstream for your Debian package.

10

There are few choices here: "s" for "Single binary", "i" for "Arch-Independent", "m" for "Multiple binary", "l" for "Library", "k" for "Kernel module", "n" for "Kernel patch" and "b" for "cdbs". This document focuses on the use of the debhelper package with the dh command. This document focuses on the use of the new dh command for "Single binary" and touches on it for "Arch-Independent" and "Multiple binary". The cdbs package offers alternative package script infrastructure to the dh command and outside of the scope of this document.

11

You can disable this configuration by starting the quilt command as "quilt --quiltrc /dev/null ...".

12

The debian/patches directory should exist now if you run dh_make as described before. This example operation creates it just in case you are updating the existing package.

13

For multiple binary packages, 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 contents of debian/tmp into debian/package-1 and debian/package-2 temporary directories to create multiple binary *.deb packages.

14

This is just an example to show how the Makefile file should look like. If the Makefile file is created by the ./configure command, the correct way to fix this kind of Makefile is to executed the ./configure command from the dh_auto_configure command with default options including --prefix=/usr.

15

The author realizes that this is not the best example considering our libncurses package now ships with a libcurses.so symlink, but he couldn't think of a better one. Suggestions very welcome :-)

16

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.

17

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.

18

This target is used by "dpkg-buildpackage" as in Complete (re)build, Section 6.1.

19

This target is used by "dpkg-buildpackage -B" as in Autobuilder, Section 6.2.

20

This target is used by "dpkg-buildpackage -A".

21

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 Customization of rules file, Section 4.4.3. It is based only on the debhelper package and does not obfuscate the package building process like the cdbs package.

22

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.

23

This assumes that the python-support package is installed on the system.

24

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.

25

These commands support other build environments such as setup.py which can be listed by executiong "dh_auto_build --list" in a package source directory.

26

It actually looks for the first available target of distclean, realclean or clean in Makefile and execute it.

27

It actually looks for the first available target of test or check in Makefile and execute it.

28

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 $@".

29

Use of the dh_pysupport command is preferred over use of the dh_pycentral command. Do not use the dh_python command.

30

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.

31

The gentoo package uses the GNU build system, also known as the Autotools. See http://en.wikipedia.org/wiki/GNU_build_system.

32

dh_auto_build without any arguments will execute the first target in the Makefile file.

33

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.

34

This replaces the deprecated dh_movefiles(1) command which is configured by the files file.

35

If the command is missing info page but have documentation files in the /usr/share/package directory, you should manually edit generated the man page created by the help2man command.

36

There were a major reorganization of menu structure for squeeze.

37

Although I used Bash short hand expression to indicate these files as "{post|pre}{inst|rm}" here, I recommend you to use pure POSIX (non-Bash) shell for these maintainer scripts as much as possible for the better compatibility.

38

See DebSrc3.0 for the summary information concerning the switch to the new 3.0 (quilt) and 3.0 (native) source formats.

39

Actually, this new format also supports multiple upstream tarballs and more compression methods. These are beyond the scope of this document.

40

Several methods for the patch set maintenance have been proposed and are in use with Debian packages. The quilt system is the preferred maintenance system in use. Other ones are dpatch, dbs, cdbs, etc. Many of these keep such patches as debian/patches/* files.

41

If you are asking a sponsor to upload your package, this kind of clear separation and documentation of your changes are very important to expedite the package review by your sponsor.

42

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 "quilt pop -a" after normal operation.

43

The actual autobuilder system involves much more complicated schemes than the one documented here. Such details are beyond the scope of this document.

44

Unlike under the pbuilder package, the chroot environment under the sbuild package used by the autobuilder system does not force the minimal system and may leave many packages installed.

45

Since the pbuilder package is still evolving, you have to check the actual configuration situation by consulting the latest official documentation.

46

This assumes HOOKDIR="/var/cache/pbuilder/hooks". You can find many examples of the hook script in the /usr/share/doc/pbuilder/examples directory.

47

There are some restrictions for such updates of your stable package.

48

Here are few web resources available for advanced audiences.

49

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.

50

You do not need to provide the lintian option "-i -I --show-overrides" if you customized /etc/devscripts.conf or ~/.devscripts as described in debuild command, Section 6.4.

51

The dput package seems to come with more features and becoming more popular than the dupload package. It uses the /etc/dput file for the global configuration and the ~/.dput.cf file for the per-user one. It supports Ubuntu related services out-of-box, too.

52

See ftp://ftp.upload.debian.org/pub/UploadQueue/README. Alternatively, you may use dcut command from the dput package.

53

To get the date in the required format, use "LANG=C date -R".

54

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.

55

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.

56

If your sponsor or other maintainers object to updating the existing packaging style, it is not worth bothering nor arguing. There are more important things to do.

57

In the cdbs (0.4.74) package, there are some negative descriptions of the rules file created by the dh_make command for the non-cdbs choices. Do not worry about it. It applies only for lenny which created explicit targets with long list of dh_* commands.

58

You may split big.diff into many small incremental patches using the splitdiff command.


Debian New Maintainers' Guide

version 1.2.25, 2010-12-22 12:44:34 UTC

Josip Rodin joy-mg@debian.org