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

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

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.

5.1 README.Debian

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 <[email protected]>, Wed, 11 Nov 1998 21:02:14 +0100

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

5.2 conffiles.ex

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.

The way to do this in a package is to enter the full path to each configuration file (usually in /etc), one per line, in a file called conffiles. Gentoo has one conffile, /etc/gentoorc, and we'll enter that in the conffiles file.

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 postinst.ex, preinst.ex, postrm.ex, prerm.ex, Section 5.12.

If your program has no conffiles, you can safely delete the conffiles file from the debian/ directory.

5.3 cron.d.ex

If your package requires regularly scheduled tasks to operate properly, you can use this file to set it up.

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

If not, remove it.

5.4 dirs

This file specifies the directories which we need but the normal installation procedure (make install) somehow doesn't create.

By default, it looks like this:


Note that the preceding slash is not included. We would have normally changed it to look like this:


but those directories are already created in the Makefile, so we won't need this file, and we will instead delete it.

5.5 docs

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 stuff:


We can also remove this file and instead list these files on the dh_installdocs command line in the rules file, like this:

             dh_installdocs BUGS CONFIG-CHANGES CREDITS ONEWS README \
                            README.gtkrc TODO

How ever unlikely it may seem, you may not have any such files in your package's sources. In that case you can safely remove this file. But don't remove the dh_installdocs invocation from the rules file because that's used to install the copyright file and other things.

5.6 emacsen-*.ex

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), so don't forget to uncomment that line in the rules file if you use this.

If you don't need these, remove them.

5.7 init.d.ex

If your package is a daemon that needs to be run at system startup, you've obviously disregarded my initial recommendation, haven't you? :-)

This is a fairly generic skeleton file for an /etc/init.d/ script, so you'll likely have to edit it, a lot. It gets installed into the temporary directory by dh_installinit(1).

If you don't need this, remove the file.

5.8 manpage.1.ex, manpage.sgml.ex

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

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.

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:

And remember to rename the file to something like gentoo.sgml!

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. For X programs you can tack on another "x" to the section, i.e. gentoo.1x. 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 menu.ex

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="Apps/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="Apps/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.10 watch.ex

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
     # Site            Directory  Pattern               Version  Script
     ftp.obsession.se  /gentoo    gentoo-(.*)\.tar\.gz  debian   uupdate

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

5.11 ex.package.doc-base

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: Apps/Tools
       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.12 postinst.ex, preinst.ex, postrm.ex, prerm.ex

These files 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.

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

Debian New Maintainers' Guide

version 1.2.11, 12 January 2007.

Josip Rodin [email protected]