Whole document tree

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

You will see that there exist several other files in the debian/ subdirectory, most of them with the `.ex' suffix, meaning that they are examples. If you wish or need to use any of those features, examine them and the related documentation (hint: the Policy Manual), rename them to remove the `.ex' suffix, and modify them and the rules file if necessary. Some of those files, those 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 <jrodin@jagor.srce.hr>, Wed, 11 Nov 1998 21:02:14 +0100

Since we don't have anything to put there - it is allowed to delete the file.

5.2 conffiles

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 will be prompted whether you want to keep your old configuration or not. You do this by entering the full path to each configuration file (they are 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. It is not actually necessary to have that file, if your program has no configuration files.

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

       usr/bin
       usr/sbin

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

       usr/X11R6/bin
       usr/X11R6/man/man1

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

5.4 manpage.1.ex

The files ending in *.ex are examples of how to add that kind of support into the package. To use one of them, edit it and remove the .ex extension. If you don't want to use it, just delete it.

Your program should have a man page. If it doesn't, this is a skeleton you can fill out. See the man pages for man(7) for a brief description of how to create a man page. Be sure to rename this file to the name of the program and make the extension the manual section it should go into. Here's a short list:

       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 manpage should be called gentoo.1, or gentoo.1x because it is an X11 program. 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.5 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. It isn't required by the Debian Policy, but users will surely appreciate it. We can add Gentoo to the menus by editing this file. Here's the default that dh_make creates:

       ?package(gentoo):needs=X11|text|vc|wm section=Apps/see-menu-manual\
         title="gentoo" command="/usr/bin/gentoo"

The first field specifies what kind of interface the program needs (e.g. text or X11). The next is 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 third field is the name of the program. The fourth is the icon for the program or none if there isn't one. The fifth is the actual text which will appear in the menu. Finally, the sixth field is the command that runs the program.

Now we'll change the menu entry to this:

       ?package(gentoo):needs=X11 section=Apps/Misc \
         title="Gentoo" command="/usr/X11R6/bin/gentoo"

See menufile(5), update-menus(1) and /usr/share/doc/debian-policy/menu-policy.html/ for more information.

5.6 watch.ex

You can use this file in addition to the uscan(1) and uupdate(1) programs (in the devscripts package) 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 manual pages.

5.7 ex.doc-base

If your package has HTML or any other documentation (except 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) or dwww(1).

This is how gentoo's doc-base file 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/doc/doc-base/doc-base.html/index.html.

5.8 postinst.ex, preinst.ex, postrm.ex, prerm.ex

These files are called maintainer scripts, 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 Packaging Manual, section 6, and take a look at these example files provided by dh_make.

We should now be ready to build the package.