第 5 章 debian 目录下的其他文件

目录

5.1. README.Debian
5.2. compat
5.3. conffiles
5.4. package.cron.*
5.5. dirs
5.6. package.doc-base
5.7. docs
5.8. emacsen-*
5.9. package.examples
5.10. package.init and package.default
5.11. install
5.12. package.info
5.13. package.links
5.14. {package.,source/}lintian-overrides
5.15. manpage.*
5.15.1. manpage.1.ex
5.15.2. manpage.sgml.ex
5.15.3. manpage.xml.ex
5.16. package.manpages
5.17. menu
5.18. NEWS
5.19. {pre,post}{inst,rm}
5.20. package.symbols
5.21. TODO
5.22. watch
5.23. source/format
5.24. source/local-options
5.25. source/options
5.26. patches/*

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. 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. [54]

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:

Any debhelper configuration files without a 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.

5.1. README.Debian

所有关于你的 Debian 版本与原始版本间的额外信息或差别都应在这里记录。

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

如果你没有需要写在这里的东西,则删除这个文件。参看 dh_installdocs(1)

5.2. compat

The compat file defines the debhelper compatibility level. Currently, you should set it to the debhelper v9 as follows:

$ echo 9 > debian/compat

5.3. 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 such configuration files as conffiles. [55] 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 第 5.19 节 “{pre,post}{inst,rm}.

5.4. package.cron.*

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 - Installed as /etc/cron.hourly/package; run once an hour.

  • package.cron.daily - Installed as /etc/cron.daily/package; run once a day.

  • package.cron.weekly - Installed as /etc/cron.weekly/package; run once a week.

  • package.cron.monthly - Installed as /etc/cron.monthly/package: run once a month.

  • package.cron.d - Installed as /etc/cron.d/package: for any other time.

Most of these files are shell scripts, with the exception of package.cron.d which follows the format of crontab(5).

No explicit cron.* file is needed to set up log rotation; for that, see dh_installlogrotate(1) and logrotate(8).

5.5. dirs

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 第 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.

5.6. package.doc-base

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).

这通常包括 HTML、PS 和 PDF 文件,放置在 /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.

关于安装附加文档的更多信息,查看 第 3.3 节 “Installation of files to their destination”

5.7. docs

这个文件制定了我们使用 dh_installdocs(1) 安装到临时目录的文件名。

默认情况下它会加入代码目录顶层的所有名为 BUGSREADME*TODO 等的文件。

For gentoo, some other files are also included:

BUGS
CONFIG-CHANGES
CREDITS
NEWS
README
README.gtkrc
TODO

5.8. emacsen-*

如果你的软件包提供可以在安装时编译为字节码的 Emacs 文件,你可以使用这些文件设置。

它们会被 dh_installemacsen(1) 安装到临时目录。

如果你不需要这些,就删除它们。

5.9. package.examples

dh_installexamples(1) 会将列出的文件和目录作为示例文件安装。

5.10. package.init and package.default

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? :-)

The package.init file is installed as the /etc/init.d/package script which starts and stops the daemon. 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 Linux Standard Base (LSB) compliant headers. It gets installed into the temporary directory by dh_installinit(1).

The package.default file will be installed as /etc/default/package. This file sets defaults that are sourced by the init script. This package.default file is most often used to disable running a daemon, or to set some default flags or timeouts. If your init script has certain configurable features, you can set them in the package.default file, instead of in the init script itself.

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.init. However if the upstream init script looks fine and installs in the right place you still need to set up 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

如果你不需要这些,就删除它们。

5.11. install

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).[56] 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 if a binary src/bar is left uninstalled; the install 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.install, package-2.install, etc.

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).

5.12. package.info

If your package has info pages, you should install them using dh_installinfo(1) by listing them in a package.info file.

5.13. package.links

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 file.

5.14. {package.,source/}lintian-overrides

If lintian reports an erroneous diagnostic for a case where Debian policy allows exceptions to some rule, you can use package.lintian-overrides or source/lintian-overrides to quieten it. Please read Lintian User's Manual (/usr/share/doc/lintian/lintian.html/index.html) and refrain from abusing this.

package.lintian-overrides is for the binary package named package and is installed into usr/share/lintian/overrides/package by the dh_lintian command.

source/lintian-overrides 是针对源代码包的,不会安装。

5.15. manpage.*

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.

5.15.1. manpage.1.ex

man 手册页通常是使用 nroff(1) 的格式编写的。manpage.1.ex 模板也是使用 nroff 格式的。参看 man(7) 手册页来简要了解如何编辑这个文件。

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:

SectionDescriptionNotes
1User commandExecutable commands or scripts
2System callsFunctions provided by the kernel
3Library callsFunctions within system libraries
4Special filesUsually found in /dev
5File formatsE.g. /etc/passwd's format
6GamesGames or other frivolous programs
7Macro packagesSuch as man macros
8System administrationPrograms typically only run by root
9Kernel routinesNon-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. [57]

5.15.2. manpage.sgml.ex

如果你希望使用 SGML 而非 nroff 格式编写 man 手册页,可以使用 manpage.sgml.ex 模板。如果你要这样,需要进行以下步骤:

  • 重命名文件为类似 gentoo.sgml 的名称。

  • 安装 docbook-to-man 软件包。

  • 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
    

5.15.3. manpage.xml.ex

如果你希望使用XML 而非 SGML,可以使用 manpage.xml.ex 模板。如果你要这样,需要进行以下步骤:

  • 重命名源文件为类似 gentoo.1.xml 的名称。

  • 安装 docbook-xsl 软件包和一个 XSLT 处理器,例如 xsltproc (推荐)。

  • 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
    

5.16. package.manpages

If your package has manual pages, you should install them using dh_installman(1) by listing them in a package.manpages file.

To install docs/gentoo.1 as a manpage for the gentoo package, create a gentoo.manpages file as follows.

docs/gentoo.1

5.17. menu

X Windows 系统用户通常有窗口管理器,并且带有可定制的菜单用于启动程序。如果他们安装了 Debian 的 menu 软件包,整个系统中所有已安装软件的一系列菜单将会被自动创建。

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

冒号后的第一个域是 needs,它指定了程序需要何种界面。修改此处为列出的选项之一,例如 textX11

The next is the section that the menu and submenu entry should appear in. [58]

title 域是程序的名称,它可以用大写字母开头,只需保证它不要很长。

最后的 command 域是运行此程序时使用的命令。

我们把文件名修改为 menu,并修改其内容为:

?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 The Debian Menu sub-policy for more information.

5.18. NEWS

dh_installchangelogs(1) 命令会安装这个文件。

5.19. {pre,post}{inst,rm}

These postinst, preinst, postrm, and prerm files [59] 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.

5.20. package.symbols

Packaging of library is not easy for a novice maintainer and should be avoided. Having said it, if your package has libraries, you should have debian/package.symbols files. See 第 A.2 节 “Managing debian/package.symbols.

5.21. TODO

dh_installdocs(1) 命令会安装这个文件。

5.22. watch

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 the Debian External Health Status (DEHS) 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 an 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/project/tar-name-(.+)\.tar\.gz. This solves issues related to periodically changing SourceForge URLs.

5.23. source/format

debian/source/format 中只包含一行,写明了此源代码包的格式(查看 dpkg-source(1) 获得完整列表)。在 squeeze 后,它应该是以下二者之一:

  • 3.0 (native) - Debian native 软件

  • 3.0 (quilt) - 其他所有软件

全新的 3.0 (quilt) 源代码格式将所有修改使用 quilt 补丁系列记录到 debian/patches。这些修改会在解压源代码包时自动应用。[60] Debian 修改保存于 debian.tar.gz 归档文件,其中包含了整个 debian 目录。这个新格式支持直接添加例如 PNG 图标等的二进制文件。[61]

dpkg-source 解压 3.0 (quilt) 格式的源码包时会自动应用所有列于 debian/patches/series 的补丁。你可以使用 --skip-patches 选项避免在解压后自动应用补丁。

5.24. source/local-options

如果你希望使用版本控制系统(VCS)时,你可以创建一个分支(例如叫做 upstream) 来跟踪上游代码,和另一个分支(对于 Git 而言典型的是 master 分支)来跟踪你的 Debian 软件包。对于后者,通常会将未应用补丁的上游代码和你的 debian/* 文件放在一起以便容易合并上游的新代码。

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

5.25. source/options

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 第 4.4.3 节 “定制 rules 文件”.

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)$"

5.26. patches/*

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. [62]

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. [63]

For 第 3 章 修改源代码, 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 第 3.1 节 “Setting up quilt.

When anyone (including yourself) provides a patch foo.patch to the source later, modifying a 3.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] In this chapter, files in the debian directory are referred to without the leading debian/ for simplicity whenever the meaning is obvious.

[56] 这取代了已经废弃的 dh_movefiles(1) 命令,它本是用 files 文件所配置的。

[57] 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.

[58] The current list of sections is in The Debian Menu sub-policy 2.1 "Preferred menu structure". There was a major reorganization of menu structure for squeeze.

[59] 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.

[60] See DebSrc3.0 for a summary on the switch to the new 3.0 (quilt) and 3.0 (native) source formats.

[61] 实际上新格式还支持多个上游 tarball 和更多的压缩方法,但这已超出本文档讲述的范围。

[62] 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.

[63] 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.