Chapter 5. Other files under the debian directory |
||
|---|---|---|
 |
 |
|
Chapter 5. Other files under the debian directory |
||
|---|---|---|
| |
|
|
Table of Contents
README.Debian
compat
conffiles
package.cron.*dirs
package.doc-basedocs
emacsen-*
package.examplespackage.initpackage.defaultinstall
package.infopackage.links{package.,source/}lintian-overrides
manpage.*
package.manpagesNEWS
{pre,post}{inst,rm}
package.symbolsTODO
watch
source/format
source/local-options
source/options
patches/*
The dh_make command had major updates since this old document was written. So some parts of this document aren't applicable any more.
The rewrite of this tutorial document with updated contents and more practical examples is available as Guide for Debian Maintainers. Please use this new tutorial as the primary tutorial document.
The debmake command is used in place of the dh_make command in my new Guide for Debian Maintainers.
To control most of what debhelper does
while building the package, you put optional configuration files under the
debian directory. This chapter will provide an overview of
what each of these does and its format. Please read the Debian Policy
Manual and Debian Developer's
Reference for guidelines for packaging.
The dh_make command will create some template configuration
files under the debian directory.
Take a look at all of them.
In this chapter, files in the debian directory are
referred to without the leading debian/ for simplicity whenever
the meaning is obvious.
Some template configuration files for debhelper
may not be created by the dh_make command. In
such cases, you need to create them with an editor.
If you wish or need to activate any of these, please do the following:
rename the configuration files to use the actual binary package
name in place of package
modify template file contents to suit your needs;
remove template files which you do not need;
modify the control file (see Section 4.1, “control”),
if necessary;
modify the rules file (see Section 4.4, “rules”), if
necessary.
Any debhelper configuration files
without a packageinstall, 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.installpackage-2.install
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).
The compat file defines the debhelper compatibility level. Currently, you
should set it to the debhelper v10 as
follows:
$ echo 10 > debian/compat
You may use compat level v9 in certain circumstances for compatibility with older systems. However, using any level below v9 is not recommended and should be avoided for new packages.
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 such configuration files as conffiles. [54] When you upgrade a package, you'll be asked whether you want to keep your old configuration files or not.
dh_installdeb(1) automatically flags 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 conffiles should ever be 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 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 two popular ways to
arrange for them to not be conffiles, keeping dpkg quiet:
Create a symlink under the /etc directory pointing to a
file under the /var directory generated by the
maintainer scripts.
Create a file generated by the maintainer scripts under the /etc directory.
For information on maintainer scripts, see Section 5.18, “{pre,post}{inst,rm}”.
If your package requires regularly scheduled tasks to operate properly, you can use these files to set that up. You can set up regular tasks that either happen hourly, daily, weekly, or monthly, or alternatively happen at any other time that you wish. The filenames are:
package.cron.hourly/etc/cron.hourly/; run
once an hour.
package
package.cron.daily/etc/cron.daily/; run
once a day.
package
package.cron.weekly/etc/cron.weekly/; run
once a week.
package
package.cron.monthly/etc/cron.monthly/: run
once a month.
package
package.cron.d/etc/cron.d/: for any
other time.
package
Most of these files are shell scripts, with the exception of
package.cron.d
No explicit cron.* file is needed to set up log rotation;
for that, see
dh_installlogrotate(1) and
logrotate(8).
This file specifies any directories which we need but which are not created by the normal installation
procedure (make install DESTDIR=... invoked by
dh_auto_install). This generally
means there is a problem with the Makefile.
Files listed in an install file don't need their
directories created first. See Section 5.11, “install”.
It is best to try to run the installation first and only use this if you
run into trouble. There is no preceding slash on the directory names listed in
the dirs file.
If your package has documentation other than manual and info pages, 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 what 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 Debian doc-base
manual at the local copy /usr/share/doc/doc-base/doc-base.html/index.html provided by the
doc-base package.
For more details on installing additional documentation, look in Section 3.3, “Installation of files to their destination”.
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, some other files
are also included:
BUGS CONFIG-CHANGES CREDITS NEWS README README.gtkrc TODO
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.
The dh_installexamples(1) command installs files and directories listed in this file as example files.
If your package is a daemon that needs to be run at system start-up, you've obviously disregarded my initial recommendation, haven't you? :-)
Please read dh_installinit(1) dh_installsystemd(1) to provide startup script.
The package.default/etc/default/. This
file sets defaults that are sourced by the init script. This
packagepackage.defaultpackage.default
If your upstream program provides a file for the init script, you can either use it or not. If you
don't use their init script then create a new one in
package.initrc* 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.
If there are files that need to be installed into your package but your
standard make install won't do it, put the filenames and
destinations into this install file. They are installed
by dh_install(1).[55] You should first check that
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 if a binary src/ is left uninstalled; the
barinstall file might look like:
src/bar usr/bin
This means when this package is installed, there will be an executable command
/usr/bin/.
bar
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 the
output of its build into multiple binary packages using
package-1.installpackage-2.install
The dh_install command 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).
If your package has info pages, you should install them using dh_installinfo(1) by listing them in a
package.info
If you need to create additional symlinks in package build directories as package maintainer, you should install them using dh_link(1) by listing their full paths of source and destination files in a
package.links
If lintian reports an erroneous
diagnostic for a case where Debian policy allows exceptions to some rule, you can
use package.lintian-overridessource/lintian-overrides to quieten it. Please read
the Lintian User's Manual (https://lintian.debian.org/manual/index.html) and refrain
from abusing this.
package.lintian-overridespackageusr/share/lintian/overrides/
by the dh_lintian command.
package
source/lintian-overrides is for the source package. This
is not installed.
Your program(s) should have a manual page. If they don't, you should create them. The dh_make command creates some template files for manual pages. These need to be copied and edited for each command missing its manual page. Please make sure to remove unused templates.
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 give 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 | 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
editing it using information from the example and from the upstream docs.
You can use the help2man command to generate a man page out
of the --help and --version output of each
program, too. [56]
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:
rename the file to something like gentoo.sgml.
install the docbook-to-man package
add docbook-to-man to the Build-Depends
line in the control file
add an override_dh_auto_build target to your
rules file:
override_dh_auto_build:
docbook-to-man debian/gentoo.sgml > debian/gentoo.1
dh_auto_build
If you prefer XML over SGML, you can use the manpage.xml.ex
template. If you do this, you have to:
rename the source file to something like gentoo.1.xml
install the docbook-xsl package and an
XSLT processor like xsltproc
(recommended)
add the docbook-xsl, docbook-xml, and
xsltproc packages to the Build-Depends
line in the control file
add an override_dh_auto_build target to your
rules file:
override_dh_auto_build:
xsltproc --nonet \
--param make.year.ranges 1 \
--param make.single.year.ranges 1 \
--param man.charmap.use.subset 0 \
-o debian/ \
http://docbook.sourceforge.net/release/xsl/current/manpages/docbook.xsl\
debian/gentoo.1.xml
dh_auto_build
If your package has manual pages, you should install them using dh_installman(1) by listing them in a
package.manpages
To install docs/gentoo.1 as a manpage for the gentoo package, create a
gentoo.manpages file as follows:
docs/gentoo.1
These postinst, preinst,
postrm, and prerm files
[57] 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 refer to the Debian Policy Manual, 6 "Package maintainer scripts and installation procedure", and take a look at the example files provided by dh_make.
If you did not listen to me and have created 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 perhaps that there are new features).
When the upgrade is necessarily intrusive (eg., config files scattered through
various home directories with totally different structure), you may
consider as the last resort switching the package to a safe fallback state
(e.g., disabling a service) and providing the proper documentation
required by policy (README.Debian and
NEWS.Debian). Don't bother the user with
debconf notes invoked from these maintainer scripts
for upgrades.
The ucf package provides a
conffile-like handling infrastructure to preserve user
changes for files that may not be labeled as conffiles such
as those managed by the maintainer scripts. This should
minimize issues associated with them.
These maintainer scripts are among the Debian enhancements that explain why people choose Debian. You must be very careful not to turn them into a source of annoyance.
Packaging of a library is not easy for a novice maintainer and should be avoided. Having said it, if your package has libraries, you should have debian/ files. See Section A.2, “Managing package.symbolsdebian/”.
package.symbols
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. This is also used by the
Debian Package Tracker service.
Here are its contents:
# watch control file for uscan version=3 http://sf.net/gentoo/gentoo-(.+)\.tar\.gz debian uupdate
Normally with a watch file, the URL at
http://sf.net/gentoo is downloaded and searched for links of
the form <a href=...>. The basename (just the part
after the final /) of each linked URL is compared against
the Perl regular expression pattern (see perlre(1))
gentoo-(.+)\.tar\.gz. Out of the files that match, the one with
the greatest version number is downloaded and the uupdate
program is run to create an updated source tree.
Although this is true for other sites, the SourceForge download service at
http://sf.net is an exception. When the
watch file has a URL matching the Perl regexp
^http://sf\.net/, the uscan program
replaces it with http://qa.debian.org/watch/sf.php/ and
then applies this rule. The URL redirector service at http://qa.debian.org/ is designed to offer
a stable redirect service to the desired file for any
watch pattern of the form
http://sf.net/.
This solves issues related to periodically changing SourceForge URLs.
project/tar-name-(.+)\.tar\.gz
If the upstream offers the cryptographic signature of the tarball, it is
recommended to verify its authenticity using the
pgpsigurlmangle option as described in uscan(1).
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:
3.0 (native) for native Debian packages or
3.0 (quilt) for everything else.
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. [58] 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. [59]
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.
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 dquilt 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)).
unapply-patches abort-on-upstream-changes
The autogenerated files in the source tree can be quite annoying for packaging
since they generate meaningless large patch files. There are custom modules
such as dh_autoreconf to ease this problem as described in
Section 4.4.3, “Customization of rules file”.
You can provide a Perl regular expression to the
--extend-diff-ignore option argument of dpkg-source(1) to ignore changes made to the autogenerated files while
creating the source package.
As a general solution to address this problem of the autogenerated files,
you can store such a dpkg-source option argument in the
source/options file of the source package. The following
will skip creating patch files for config.sub,
config.guess, and Makefile.
extend-diff-ignore = "(^|/)(config\.sub|config\.guess|Makefile)$"
The old 1.0 source format created a single large
diff.gz file containing package maintenance files in
debian and patch files for 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 contained 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 a
Build-Depends on quilt.
[60]
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 is recorded in the
debian/patches/series file. You can apply (=push),
un-apply (=pop), and refresh patches easily. [61]
For Chapter 3, Modifying the source, we created three patches in
debian/patches.
Since Debian patches are located in debian/patches, please
make sure to set up the dquilt command properly as described
in Section 3.1, “Setting up quilt”.
When anyone (including yourself) provides a patch
foo.patch3.0 (quilt) source package is
quite simple:
$ dpkg-source -x gentoo_0.9.12.dsc
$ cd gentoo-0.9.12
$ dquilt import ../foo.patch
$ dquilt push
$ dquilt refresh
$ dquilt header -e
... describe patch
The patches stored in the newer 3.0 (quilt) source format
must be fuzz free. You can ensure this with dquilt
pop -a; while dquilt push; do dquilt refresh; done.
[54] See dpkg(1) and Debian Policy Manual, "D.2.5 Conffiles".
[55] This replaces the
deprecated dh_movefiles(1) command which is configured by the
files file.
[56] Note that help2man's placeholder man page will claim that more detailed documentation is available in the info system. If the command is missing an info page, you should manually edit the man page created by the help2man command.
[57] Despite this use of the bash
shorthand expression {pre,post}{inst,rm} to indicate these
filenames, you should use pure POSIX syntax for these maintainer scripts for
compatibility with dash as the system shell.
[58] See
DebSrc3.0 for a summary on the switch to the new 3.0
(quilt) and 3.0 (native) source formats.
[59] Actually, this new format also supports multiple upstream tarballs and more compression methods. These are beyond the scope of this document.
[60] Several methods of patch set maintenance have been proposed and are in use for Debian
packages. The quilt system is the preferred maintenance
system in use. Others include dpatch,
dbs, and cdbs. Many of these keep such
patches as debian/patches/* files.
[61] If you are asking a sponsor to upload your package, this kind of clear separation and documentation of your changes is very important to expedite the package review by your sponsor.
| |
|
|
Chapter 4. Required files under the debian directory |
|
Chapter 6. Building the package |