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

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

To control most of what debhelper is doing when it builds the package, you put files under the debian/ directory. This chapter will describe what each of the files does and its format.

dh_make will create some example files in this directory, you will see that there are several other files in the debian/ subdirectory, most of them with the ex suffix or prefix, meaning that they are examples. Take a look at all of them. If you wish or need to use any of those features:

Some of those files, the commonly used ones, are explained in the following sections. If there is no package name then the first binary package uses these files. When there are many binary packages, each binary package uses filenames such as gentoo1.dirs, gentoo1.dirs, etc.

5.1 README.Debian file

Any extra details or discrepancies between the original package and your debianized 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

Since we don't have anything to put there, we'll delete the file.

5.2 compat file

The compat file defines the debhelper compatibility level. Currently, you should set it to 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 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 mark 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 file in order to work at all, also consider not marking the file as a conffile.

You can handle example configuration files from the maintainer scripts, for more information see {post|pre}{inst|rm}.ex files, Section 5.13.

5.4 dirs file

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

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. dh_install when it uses the install file doesn't need the directories created first.

5.5 docs file

This file specifies the file names of documentation files we can have dh_installdocs 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
     ONEWS
     README
     README.gtkrc
     TODO

5.6 emacsen-*.ex 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.7 init.d.ex and package.default file

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? :-)

init.d.ex is a fairly generic init skeleton file for an /etc/init.d/ script, so you'll likely have to 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).

package.default 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 package 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/init.d. 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.8 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. They are installed by dh_install(1). You should first check there is not a more specific tool to use before; for example documents should be in the docs file and not this one.

This install 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.

From debhelper compatibility level 7 on, dh_install 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).

5.9 manpage.*.ex files

Your program(s) should have a manual page. If they don't, each of these files is a template that you can fill out.

5.9.1 manpage.1.ex file

Manual pages are normally written in nroff(1). The manpage.1.ex example 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. There was no gentoo.1 man page in the original source so I wrote it using information from the example and from upstream docs.

5.9.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.9.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 two choices:

5.10 menu.ex 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 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.

Now we'll 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 menufile(5), update-menus(1) and /usr/share/doc/debian-policy/menu-policy.html/ for more information.

5.11 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 a 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.12 package.doc-base.EX 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/package/.

This is how gentoo's doc-base file gentoo.doc-base.EX 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 in a subdirectory, Section 3.1.

5.13 {post|pre}{inst|rm}.ex files

These postinst.ex, preinst.ex, postrm.ex, and prerm.ex files [5] 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.

For now, you should try to avoid any manual editing of maintainer scripts if you possibly can because they tend to get complex. For more information look in the Policy Manual, chapter 6, and take a look at these example files provided by dh_make.

If you create 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.

5.14 watch.ex file

This file is used to configure the uscan(1) and uupdate(1) programs (in the devscripts package). These are used to watch the site you got the original source from.

Here's what I put in it: 

     # watch control file for uscan
     version=3
     #
     http://ftp.obsession.se/gentoo/ gentoo-(.*)\.tar\.gz

Hint: connect to the Internet, and try running "uscan" in the program directory once you create the file. And read the manuals! :)

5.15 source/format file

In the file debian/source/format there should be a single line describing the type of dpkg format your source file will be as defined in dpkg-source(1). After squeeze, it should say either:

The newer dpkg 3.0 (quilt) source format integrates the quilt patch system into the Debian package system. [6] This enables (but not requires) a packager to create a Debian source package not just with a single large diff.gz file but with multiple patch files. [7]

When dpkg-source extracts sources, it normally applies all patches in debian/patches/* files to them. You can avoid applying patches at the end of the extraction with --skip-patches option.

5.16 debian/patches/* files

The simple use of dh_make and dpkg-buildpackage commands will create 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.

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.

A package which is packaged properly with the quilt system for the newer dpkg format 3.0 (quilt) source format has modifications to the source clearly documented as a set of -p1 patch files with header in debian/patches/ and the source tree is untouched outside of debian/ directory. When dpkg-source extracts sources, it applies all patches in debian/patches/* files to them. [8]

The quilt command is explained in quilt(1). You can apply (=push), un-apply(=pop), and refresh patches easily using quilt as if they are a stack. Since Debian patches are located in debian/patches/, please make sure to export QUILT_PATCHES=debian/patches in your shell resource file and reload it.

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

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

Debian New Maintainers' Guide

version 1.2.16-svn, 20100317

Josip Rodin joy-mg@debian.org