[ previous ] [ Contents ] [ 1 ] [ 2 ] [ 3 ] [ 4 ] [ 5 ] [ 6 ] [ 7 ] [ 8 ] [ 9 ] [ 10 ] [ A ] [ next ]
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:
take a look at the related documentation (hint: the Policy Manual),
if necessary modify the files to suit your needs,
rename them to remove the `.ex' suffix if they have one,
rename them to remove the `ex.' prefix if they have one,
modify the `rules' file if necessary.
Some of those files, the commonly used ones, are explained in the following sections.
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.
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.
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.
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/bin
usr/man/man1
but those directories are already created in the Makefile, so we won't need this file, and we will instead delete it.
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:
BUGS
CONFIG-CHANGES
CREDITS
ONEWS
README
README.gtkrc
TODO
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.
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.
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.
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:
install the docbook-to-man package
add docbook-to-man to the Build-Depends line in the control file
remove the comment from the docbook-to-man invocation in the `build' rule of your rules file
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.
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.
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! :)
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.
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
[email protected]