[ previous ] [ Contents ] [ 1 ] [ 2 ] [ 3 ] [ 4 ] [ 5 ] [ 6 ] [ 7 ] [ 8 ] [ 9 ] [ next ]

Debian New Maintainers' Guide
Chapter 5 - Other files under the debian directory

To control most of what debhelper does while building the package, you put optional configuration files under the debian directory. This chapter will make an overview of what each of these does and its format. Please read Debian Policy Manual and Debian Developer's Reference for guidelines for the 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.

The dh_make command may not create some template configuration files for debhelper. In such cases, you need to create them with the editor.

If you wish or need to activate any of those, please do the following.

Those debhelper configuration files without 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.

5.1 README.Debian file

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).

5.2 compat file

The compat file defines the debhelper compatibility level. Currently, you should set it to the debhelper V7 by the following. 

     $ echo 7 > debian/compat

5.3 conffiles file

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 configuration files so that when you upgrade a package, you'll be prompted whether you want to keep your old configuration or not.

Since debhelper V3, dh_installdeb(1) will automatically flag 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 there is (and should be conffiles) 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 as 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 2 popular ways to make them not as conffiles to keep dpkg quiet.

For more information on the maintainer scripts, see {post|pre}{inst|rm} files, Section 5.18.

5.4 package.cron.* files

If your package requires regularly scheduled tasks to operate properly, you can use this file to set it up. You can either setup regular tasks that happen hourly, daily, weekly or monthly or alternatively happen any other time that you wish. The filenames are:

For the named files, the format of them is the shell script. The different one is package.cron.d which follows the format of crontab(5).

Note that this doesn't include log rotation; for that, see dh_installlogrotate(1) and logrotate(8).

5.5 dirs file

This file specifies the directories which we need but the normal installation procedure ("make install DESTDIR=..." invoked by "dh_auto_install") somehow doesn't create. This generally means there is a problem with the Makefile.

Files listed in the install file doesn't need the directories created first. See install file, Section 5.11.

It is best to first try to run the installation first and only use this if you run into trouble. There is no preceding slash on the directory names.

5.6 package.doc-base file

If your package has documentation other than manual pages and info docs, 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 how 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 /usr/share/doc/doc-base/doc-base.html/.

For more details on installing additional documentation, look in Installation of files to the destination, Section 3.3.

5.7 docs file

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, I also included some other files: 

     BUGS
     CONFIG-CHANGES
     CREDITS
     NEWS
     README
     README.gtkrc
     TODO

5.8 emacsen-* file

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.

5.9 package.examples file

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

5.10 package.init and package.default files

If your package is a daemon that needs to be run at the 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. 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 Filesystem Hierarchy Standard (see /usr/share/doc/debian-policy/fhs/) compliant headers. It gets installed into the temporary directory by dh_installinit(1).

The package.default file will be installed into /etc/default/package. This file sets defaults that are sourced by the init script. Most times this default file is used to disable running a daemon, set some default flags or timeouts. If your init script has certain settable features you want to install these into the default file, not the init script.

If your upstream program has an init file you can either use it or not. If you don't use their init.d script then create a new one in debian/package.init. However if the upstream init script looks fine and installs in the right place you still need to setup 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.

5.11 install file

If there are files that need to be installed into your package but your standard "make install" won't do it, you put the filenames and destinations into this install file. They are installed by dh_install(1).[34] 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 where a binary is forgotten to be installed, the install file would look like: 

     src/foo/mybin usr/bin

This will mean when this package is installed, there will be a binary file /usr/bin/mybin.

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 build result into multiple binary packages using package-1.install, package-2.install, etc.

The dh_install command will fall back to look 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).

5.12 package.info file

If your package has info pages, you should install them using dh_installinfo(1) by listing them in the package.info files.

5.13 {package.|source/}lintian-overrides files

If lintian reports an erroneous diagnostics for a case when the policy allows exceptions to some rule, you can use package.lintian-overrides or source/lintian-overrides to quiet it. Please read /usr/share/doc/lintian/lintian.html/index.html and refrain from abusing this.

package.lintian-overrides is for the binary package named as 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.

5.14 manpage.* files

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

5.14.1 manpage.1.ex file

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 include 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 commands          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                  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 edit it by using information from the example and from upstream docs.

You can use the help2man command to generate a man page out of "--help" and "--version" output of each program, too. [35]

5.14.2 manpage.sgml.ex file

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:

5.14.3 manpage.xml.ex file

If you prefer XML over SGML, you can use the manpage.xml.ex template. If you do this, you have to:

5.15 package.manpages file

If your package has manual pages, you should install them using dh_installman(1) by listing them in the package.manpages files.

To install doc/gentoo.1 for the gentoo package as its manpage, you create a gentoo.manpages file as: 

     docs/gentoo.1

5.16 menu file

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 section, where the menu and submenu the entry should appear in. The current list of sections [36] is at: /usr/share/doc/debian-policy/menu-policy.html/ch2.html#s2.1

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 /usr/share/doc/debian-policy/menu-policy.html/ for more information.

5.17 NEWS file

The dh_installchangelogs(1) command installs this.

5.18 {post|pre}{inst|rm} files

These postinst, preinst, postrm, and prerm files [37] 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 look in the Debian Policy Manual, 6 'Package maintainer scripts and installation procedure', and take a look at these example files provided by dh_make.

If you did not listen to me and made your 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 there perhaps are new features).

When the upgrade is necessarily intrusive (eg., config files scattered through various home directories with totally different structure), you may consider to set package to the safe default (e.g., disabled service) and provide proper documentations required by the policy (README.Debian and NEWS.Debian) as the last resort. Don't bother user with the debconf note invoked from these maintainer scripts for upgrades.

The ucf package provides conffile-like handling infrastructure to preserve user changes for files that may not be labeled conffiles such as ones managed by the maintainer scripts. This should minimize issues associated with them.

These maintainer scripts are the Debian enhancements that explain why people choose Debian. You must be very careful not to annoy them with these.

5.19 TODO file

The dh_installdocs(1) command installs this.

5.20 watch file

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 Debian External Health Status (DEHS).

Here's what I put in it: 

     # watch control file for uscan
     version=3
     http://sf.net/gentoo/gentoo-(.+)\.tar\.gz debian uupdate

Normally with this watch file, the URL at "http://sf.net/gentoo" is downloaded and searched for links of the form "<a href=...>". The base name (just the part after the final "/") of these linked URLs are matched against Perl regexp (see perlre(1)) pattern "gentoo-(.+)\.tar\.gz". Out of matched files, the file with the greatest version number is downloaded and the uupdate program is run to create the updated source tree from them.

Although this is true for other sites, the SourceForge download service at http://sf.net is an exception. When the watch file has an URL matching with the Perl regexp "^http://sf\.net/", the uscan program substitutes it with "http://qa.debian.org/watch/sf.php/" and then applies this rule. The URL redirector service at this http://qa.debian.org/ is designed to offer a stable redirect service to the desired file for the watch file having "http://sf.net/project/tar-name-(.+)\.tar\.gz". This solves issues related to the periodically changing URL there.

5.21 source/format file

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:

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. [38] 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. [39]

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.

5.22 source/local-options file

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 "quilt 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)).

5.23 patches/* files

The old 1.0 source format created a single large diff.gz file which contains package maintenance files in debian and patch files to 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 constrained 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 to Build-Depends on the quilt package. [40]

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 are recorded in the debian/patches/series file. You can apply (=push), un-apply (=pop), and refresh patches easily. [41]

For Modifying the source, Chapter 3, we created 3 patches in debian/patches.

Since Debian patches are located in debian/patches, please make sure to setup the quilt command properly as described in Set up quilt, Section 3.1.

When someone (including yourself) provides you with a patch foo.patch to the source later, then the modification of a 3.0 (quilt) source package is quite simple: 

     $ dpkg-source -x gentoo_0.9.12.dsc
     $ cd gentoo-0.9.12
     $ quilt import ../foo.patch
     $ quilt push
     $ quilt refresh
     $ quilt header -e
     ... describe patch

The patches stored in the newer 3.0 (quilt) source format must be fuzz free. You should ensure it as "quilt pop -a; while quilt push; do quilt refresh; done".

[ previous ] [ Contents ] [ 1 ] [ 2 ] [ 3 ] [ 4 ] [ 5 ] [ 6 ] [ 7 ] [ 8 ] [ 9 ] [ next ]

Debian New Maintainers' Guide

version 1.2.25, 2010-12-21 14:06:56 UTC

Josip Rodin joy-mg@debian.org