[ previous ] [ Contents ] [ 1 ] [ 2 ] [ 3 ] [ 4 ] [ 5 ] [ 6 ] [ 7 ] [ 8 ] [ 9 ] [ next ]
debian
directory
To control most of what debhelper
does while building the package,
you put optional configuration files under the debian
directory.
This chapter will make an overview of what each of these does and its format.
Please read Debian Policy
Manual
and Debian Developer's
Reference
for guidelines for the packaging.
The dh_make
command will create some template configuration files
under the debian
directory. Most of them come with filenames
suffixed by ".ex". Some of them come with filenames
prefixed by the binary package name such as package.
Take a look at all of them.
The dh_make
command may not create some template configuration
files for debhelper
. In such cases, you need to create them with
the editor.
If you wish or need to activate any of those, please do the following.
rename template files by removing the .ex or .EX suffix if the template files have one.
rename the name of these configuration files using 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 control
file, Section 4.1),
if necessary.
modify the rules
file (see rules
file, Section 4.4), if
necessary.
Those debhelper
configuration files without
package
prefix such as install
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.install
,
package-2.install
, etc.
README.Debian
fileAny 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)
.
compat
file
The compat
file defines the debhelper
compatibility
level. Currently, you should set it to the debhelper
V7 by the
following.
$ echo 7 > debian/compat
conffiles
fileOne 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(1)
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 make 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
files in the /etc
directory, there are 2 popular ways to make them
not as conffiles to keep dpkg
quiet.
You make a symlink under the /etc
directory pointing to a file
under the /var
directory generated by the maintainer
scripts.
You make a file generated by the maintainer scripts under the
/etc
directory.
For more information on the maintainer scripts, see {post|pre}{inst|rm}
files, Section
5.18.
package.cron.*
filesIf 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:
cron.hourly
- Installed as
/etc/cron.hourly/package
: run once an hour every hour.
cron.daily
- Installed as
/etc/cron.daily/package
: run once a day, usually early
morning.
cron.weekly
- Installed as
/etc/cron.weekly/package
: run once a week, usually
early Sunday morning.
cron.monthly
- Installed as
/etc/cron.monthly/package
: run once a month, usually
early morning on the first of the month.
cron.d
- Installed as /etc/cron.d/package
:
for any other time
For the named files, the format of them is the 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)
.
dirs
file
This file specifies the directories which we need but the normal installation
procedure ("make install DESTDIR=..." invoked by
"dh_auto_install") somehow doesn't create. This
generally means there is a problem with the Makefile
.
Files listed in the install
file doesn't need the directories
created first. See install
file, Section
5.11.
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.
package.doc-base
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/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: 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 of files to the destination, Section 3.3.
docs
file
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
, I also included some other files:
BUGS CONFIG-CHANGES CREDITS NEWS README README.gtkrc TODO
emacsen-*
fileIf 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.
package.examples
file
The dh_installexamples(1)
command installs files and directories
listed in this file as example files.
package.init
and package.default
filesIf 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? :-)
The package.init
file is installed as the
/etc/init.d/package
script. Its fairly generic
skeleton template is provided by the dh_make
command as
init.d.ex
. You'll likely have to rename and 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)
.
The package.default
file 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 program 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/package.init
. 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.
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
file. They are
installed by dh_install(1)
.[34] You should first check 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 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.
The dh_install
command will fall back to look 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).
package.info
file
If your package has info pages, you should install them using
dh_installinfo(1)
by listing them in the
package.info
files.
{package.|source/}lintian-overrides
files
If lintian
reports an erroneous diagnostics for a case when the
policy allows exceptions to some rule, you can use
package.lintian-overrides
or
source/lintian-overrides
to quiet it. Please read
/usr/share/doc/lintian/lintian.html/index.html
and refrain from
abusing this.
package.lintian-overrides
is for the binary package
named as package
and is installed into
usr/share/lintian/overrides/package
by the
dh_lintian
command.
source/lintian-overrides
is for the source package. This is not
installed.
manpage.*
files
Your program(s) should have a manual page. If they don't, you should create
them. The dh_make
command creates few template files for a manual
page. These need to be copied and edited for each command without its manual
page. Please make sure to remove unused templates.
manpage.1.ex
file
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 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
. 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 edit it by using information from the example and
from upstream docs.
You can use the help2man
command to generate a man page out of
"--help" and "--version" output
of each program, too. [35]
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:
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 a 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
manpage.xml.ex
fileIf 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 a 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
package.manpages
file
If your package has manual pages, you should install them using
dh_installman(1)
by listing them in the
package.manpages
files.
To install doc/gentoo.1
for the gentoo
package as its
manpage, you create a gentoo.manpages
file as:
docs/gentoo.1
menu
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 [36] 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.
Let's change the file name to menu
and 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 dh_installmenu(1)
,
menufile(5)
, update-menus(1)
and
/usr/share/doc/debian-policy/menu-policy.html/
for more
information.
NEWS
file
The dh_installchangelogs(1)
command installs this.
{post|pre}{inst|rm}
files
These postinst
, preinst
, postrm
, and
prerm
files [37]
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 look in the
Debian
Policy Manual, 6 'Package maintainer scripts and installation
procedure'
, and take a look at these example files provided by
dh_make
.
If you did not listen to me and made your 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 there perhaps are new features).
When the upgrade is necessarily intrusive (eg., config files scattered through
various home directories with totally different structure), you may consider to
set package to the safe default (e.g., disabled service) and provide proper
documentations required by the policy (README.Debian
and
NEWS.Debian
) as the last resort. Don't bother user with the
debconf
note invoked from these maintainer scripts for
upgrades.
The ucf
package provides conffile-like handling
infrastructure to preserve user changes for files that may not be labeled
conffiles such as ones managed by the maintainer scripts.
This should minimize issues associated with them.
These maintainer scripts are the Debian enhancements that explain why people choose Debian. You must be very careful not to annoy them with these.
TODO
file
The dh_installdocs(1)
command installs this.
watch
file
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 from. This is also used by Debian External Health Status
(DEHS)
.
Here's what I put in it:
# watch control file for uscan version=3 http://sf.net/gentoo/gentoo-(.+)\.tar\.gz debian uupdate
Normally with this watch
file, the URL at
"http://sf.net/gentoo" is downloaded and searched for
links of the form "<a href=...>". The base name
(just the part after the final "/") of these linked URLs
are matched against Perl regexp (see perlre(1)
) pattern
"gentoo-(.+)\.tar\.gz". Out of matched files, the file
with the greatest version number is downloaded and the uupdate
program is run to create the updated source tree from them.
Although this is true for other sites, the SourceForge download service at
http://sf.net
is an exception. When
the watch
file has an URL matching with the Perl regexp
"^http://sf\.net/", the uscan
program
substitutes it with "http://qa.debian.org/watch/sf.php/"
and then applies this rule. The URL redirector service at this http://qa.debian.org/
is designed to
offer a stable redirect service to the desired file for the watch
file having
"http://sf.net/project/tar-name-(.+)\.tar\.gz".
This solves issues related to the periodically changing URL there.
source/format
file
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 Debian native 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.
[38] 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. [39]
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.
source/local-options
file
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 "quilt 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)
).
patches/*
files
The old 1.0 source format created 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.
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 constrained 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 to Build-Depends on
the quilt
package. [40]
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 are
recorded in the debian/patches/series
file. You can apply
(=push), un-apply (=pop), and refresh patches easily. [41]
For Modifying the source, Chapter 3, we created
3 patches in debian/patches
.
Since Debian patches are located in debian/patches
, please make
sure to setup the quilt
command properly as described in Set up quilt
, Section 3.1.
When someone (including yourself) provides you with a patch
foo.patch
to the source later, then the modification of
a 3.0 (quilt) source package is quite simple:
$ dpkg-source -x gentoo_0.9.12.dsc $ cd gentoo-0.9.12 $ quilt import ../foo.patch $ quilt push $ quilt refresh $ quilt header -e ... describe patch
The patches stored in the newer 3.0 (quilt) source format must be fuzz free. You should ensure it as "quilt pop -a; while quilt push; do quilt refresh; done".
[ previous ] [ Contents ] [ 1 ] [ 2 ] [ 3 ] [ 4 ] [ 5 ] [ 6 ] [ 7 ] [ 8 ] [ 9 ] [ next ]
Debian New Maintainers' Guide
version 1.2.25, 2010-12-22 12:44:34 UTCjoy-mg@debian.org