[ 上一页 ] [ 目录 ] [ 1 ] [ 2 ] [ 3 ] [ 4 ] [ 5 ] [ 6 ] [ 7 ] [ 8 ] [ 9 ] [ 下一页 ]


Debian 新维护人员手册
第 5 章 - debian 目录下的其他文件


要控制 debhelper 在构建软件包过程中的行为,可以在 debian 目录中放置可选的配置文件。本章将会对这些文件和它们的格式进行概述。请阅读 Debian Policy ManualDebian Developer's Reference 来了解更多内容。

dh_make 命令会在 debian 目录中创建一些配置文件模板,它们的文件名多带有 .ex 的后缀。其中的一些可能以软件包名作为前缀,如 package。现在对它们进行一个大致的了解。

还有一些 debhelper 的配置文件模板 dh_make 命令没有直接创建。在这种情况下如果你需要它们,则要使用文本编辑器手工创建。

如果你希望或需要激活它们中的任意一个或多个,请按照下面的方法做。

不带有二进制软件包名(例如 package)前缀的 debhelper 配置文件则默认用于 control 文件中列出的第一个二进制软件包,如默认情况下的 install 文件。如果需要为其他二进制包使用配置,则应在配置文件名前加上二进制包名,如 package-1.installpackage-2.install 等。


5.1 README.Debian 文件

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

dh_make 创建了一个默认的文件,以下是它的样子:

     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 文件

compat 文件定义了 debhelper 的兼容级别。目前你应当使用以下命令将其设置为 debhelper V7。

     $ echo 7 > debian/compat

5.3 conffiles 文件

系统管理中有件很恼人的事,就是当你付出了很多时间和经历来自定义一个程序,但是升级后所有的修改都被覆盖掉了。Debian 通过将配置文件单独标记来解决这个问题,当软件包升级的时候,你将会被询问是否要保留你的旧配置文件。

debhelper V3 开始,dh_installdeb(1)自动 识别所有在 /etc 目录下的文件为配置文件。所以如果你的程序只有在那里的配置文件,则不需再指定它们。

如果你的程序使用配置文件,但程序会自动对配置进行改写,则最好也将其标记为配置文件,这样 dpkg 总是会要求用户校验发生了的变更。

如果你正在打包的程序需要所有用户都为自己修改 /etc 目录中的配置,有两种常见的方法让 dpkg 不将其记录为配置文件。

更多关于 maintainer scripts 的信息,参看 {post|pre}{inst|rm} 文件, 第 5.18 节


5.4 package.cron.* 文件

如果你的软件包需要有计划运行的操作以保证正常工作,可以使用这个文件进行设置。既可以设置常规的任务使其在每小时、每天、每星期、每月或其他情况或时间下运行。相应的文件名是:

对于前几个文件,其格式为 shell 脚本。唯一不同的是 package.cron.d,它的格式需要参照 crontab(5)

注意这里的操作不包含日志旋转,如果需要日志旋转,参看 dh_installlogrotate(1)logrotate(8)


5.5 dirs 文件

这个文件指定了我们需要,但正常安装过程(dh_auto_install 触发 make install DESTDIR=...)里没有被安装的目录。通常这是由于 Makefile 中存在问题。

install 文件中列出的文件不需要提前创建目录,参看 install 文件, 第 5.11 节

最好是先尝试安装,如果遇到了相关的问题再使用这个文件。目录名中不应有前导的 / 符号。


5.6 package.doc-base 文件

如果你的软件包在 man 手册页和 info 信息文档外还有其他文档,你应该使用 doc-base 文件注册它们,这样用户可以使用例如 dhelp(1)dwww(1)doccentral(1) 的工具找到它们。

这通常包括 HTML、PS 和 PDF 文件,放置在 /usr/share/doc/packagename/

以下是 gentoo 的 doc-base 文件 gentoo.doc-base 的样子:

     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

关于文件格式的更多信息,参看 install-docs(8)/usr/share/doc/doc-base/doc-base.html/ 中的 doc-base 手册。

关于安装附加文档的更多信息,查看 把文件安装到目的位置, 第 3.3 节


5.7 docs 文件

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

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

对于 gentoo,我还加入了一些其他文件:

     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.initpackage.default 文件

如果你的软件包需要在系统启动时运行一个守护进程,那么你显然没有按照我最初的建议做事,不是吗? :-)

package.init 文件会被安装为 /etc/init.d/package 脚本。dh_make 创建的 init.d.ex 是一个很好的骨架文件。你可能要对其改名并做很多修改,同时还要提供文件系统层级标准(FHS,参看 /usr/share/doc/debian-policy/fhs/)所要求的文件头。它们会被 dh_installinit(1) 安装到临时目录。

package.default 文件会被安装为 /etc/default/package。该文件会被 init 脚本引用为默认设置。多数情况下这个文件被用于禁止运行一个守护程序、设置默认的标识或超时。如果你的脚本有特定的可设置特性,请把它们安装到这个文件,而不是 init 脚本。

如果你的上游程序中包含了 init 文件,你可以选择是否使用它。如果不使用,则创建相应的 debian/package.init 文件;如果上游的 init 脚本很好且被安装到正确的位置,你仍然需要设置 rc* 符号链接。你需要按照以下的方法在 rules 文件中覆盖 dh_installinit

     override_dh_installinit:
             dh_installinit --onlyscripts

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


5.11 install 文件

如果你的软件包需要标准的 make install 没有安装的文件,可以把文件名和目标路径写入 install 文件,它们将被 dh_install(1) 安装。[34] 你需要首先检查要安装的文件是否有更有针对性的特定工具会对其进行安装,例如示例、文档应写在 docs 文件中安装。

这个 install 文件每行安装一份文件,格式上先是相对于编译目录的源目录,然后是一个空格,接下来是相对于安装目录的目标目录。假设某个二进制文件没有被默认安装,则应在 install 文件添加如下内容:

     src/foo/mybin usr/bin

这意味着安装这个软件包时将有一个二进制文件 /usr/bin/mybin

当然 install 文件也可以只包含相对的源路径而不带目标位置。这样的格式通常用于使用 package-1.installpackage-2.install 等将大软件包分割为多个二进制包的情况。

如果 dh_install 命令没有在当前目录(或者你可能使用 --sourcedir 参数指定的位置)找到文件,它会回滚至使用 debian/tmp 目录。


5.12 package.info 文件

如果你的软件包有 info 信息页,应该使用 dh_installinfo(1) 安装,要安装的文件列于 package.info 文件中。


5.13 {package.|source/}lintian-overrides 文件

如果 lintian 报告了一个 Debian Policy 允许的例外的错误诊断,你可以使用 package.lintian-overridessource/lintian-overrides 使其不再警告。请阅读 /usr/share/doc/lintian/lintian.html/index.html 并应严格避免滥用。

package.lintian-overrides 是对于名为 package 有效的配置,会由 dh_lintian 命令安装到usr/share/lintian/overrides/package

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


5.14 manpage.* 文件

你的程序应该有 man 手册页,如果它们没有自带则需要由你来创建。dh_make 命令创建了几个 man 手册页的模板。它们需要被妥善地编辑,并且要删除未使用的模板。


5.14.1 manpage.1.ex 文件

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

最终的 man 手册页文件名应当包含它所描述的程序名,所以我们把它从 manpage 改名为 gentoo;文件名还应以类似 .1 的数字结尾作为后缀,.1 代表它是一个用户命令的 man 手册页。请确认这个章节号是否使用正确。以下是一个 man 手册 章节简表::

     章节  |     描述      |      注释
      1        用户命令          可执行命令或脚本。
      2        系统调用          内核提供的函数。
      3        函数库调用        系统库提供的函数。
      4        特殊文件          常见于 /dev
      5        文件格式          例如 /etc/passwd 的格式。
      6        游戏             游戏或其他无足轻重的程序。
      7        宏包             例如 man 宏。
      8        系统管理          典型由 root 运行的程序。
      9        内核函数          非标准调用和内部控制结构。

所以 gentoo 的 man 手册页应叫 gentoo.1。如果原始代码中没有 gentoo.1 man 手册页,你需要重命名 manpage.1.ex 模板为 gentoo.1 并按照示例和上游文档编辑它。

你也可以使用 help2man 命令来通过程序的 --help--version 参数的输出创建 man 手册页。[35]


5.14.2 manpage.sgml.ex 文件

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


5.14.3 manpage.xml.ex 文件

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


5.15 package.manpages 文件

如果你的软件包有 man 手册页,你应该将它们列在 package.manpages 文件中以便 dh_installman(1) 安装。

要将 doc/gentoo.1 安装为 gentoo 的 man 手册页,创建一个 gentoo.manpages,内容如下:

     docs/gentoo.1

5.16 menu 文件

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

以下是 dh_make 创建的默认的 menu.ex 文件:

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

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

接下来是 section,包含菜单和子菜单项。当前可用的章节列表[36]位于:/usr/share/doc/debian-policy/menu-policy.html/ch2.html#s2.1

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

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

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

     ?package(gentoo): needs="X11" \
             section="Applications/Tools" \
             title="Gentoo" command="gentoo"

你还可以添加诸如 longtitleiconhints 等域。参看 dh_installmenu(1)menufile(5)update-menus(1)/usr/share/doc/debian-policy/menu-policy.html/ 了解更多信息。


5.17 NEWS 文件

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


5.18 {post|pre}{inst|rm} 文件

postinstpreinstpostrmprerm 文件 [37] 被称为 maintainer scripts。它们是放置于软件包控制信息区域,并由 dpkg 在软件包安装、升级或卸载时执行的脚本。

作为一个新维护人员,你应当避免手工编辑 maintainer scripts,因为它们常存在各种问题。更多信息请阅读 Debian Policy Manual, 6 'Package maintainer scripts and installation procedure' 并查看 dh_make 给出的示例。

如果你不听我的劝告,自己为一个软件包创建了 maintainer scripts,你必须保证不仅测试 installupgrade,还应测试 removepurge

升级到新版本应当是静默的(已有用户应当只在发现旧的 Bug 被修复或有新特性时注意到升级的变化)。

当更新必须以非静默模式进行时(例如多个主目录中的配置文件都要改为完全不同的结构时),你应该考虑将软件包设置到安全的默认配置(例如禁用服务)并按照 Debian Policy 提供相应的文档(README.DebianNEWS.Debian)。不要在升级时使用 maintainer scripts 触发 debconf 来打扰用户。

ucf 软件包提供了 类似 conffile 的对不应标记为 conffiles 的文件的保留机制。这可以将与 maintainer scripts 相关的问题减少到最低。

这些 maintainer scripts 是 Debian 对于软件系统的增强特性,它们解释了 人们为什么选择 Debian。你必须非常小心,保证人们不因此产生烦恼。


5.19 TODO 文件

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


5.20 watch 文件

watch 文件的格式被详述于 uscan(1) man 手册页中。watch 文件配置了 uscan 程序(devscripts 中)以便监视你获得原始源代码的网站。它还被用于 Debian External Health Status (DEHS)

以下是我写入的内容:

     # watch control file for uscan
     version=3
     http://sf.net/gentoo/gentoo-(.+)\.tar\.gz debian uupdate

通常,在按照这个 watch 文件执行时,URL http://sf.net/gentoo" 会被下载,程序在其中搜搜 <a href=...>/ 后的基本名称会按照 Perl 正则表达式匹配(参看 perlre(1)) gentoo-(.+)\.tar\.gz。在所有匹配的文件里,将会下载带有最大版本号的,此后由 uupdate 程序创建更新的源代码树。

尽管上述内容对于所有站点都适用,但 SourceForge 下载服务(http://sf.net)仍是一个例外。当 watch 中包含匹配 Perl 正则表达式 ^http://sf\.net/ 的 URL 时,uscan 程序会将其替换为 http://qa.debian.org/watch/sf.php/ 然后应用此规则。http://qa.debian.org/ 的 URL 重定向服务器被设计用于提供一个稳定的重定向服务以满足 watch 文件中的 http://sf.net/project/tar-name-(.+)\.tar\.gz 形式,这样解决了关于经常性 URL 变更导致的问题。


5.21 source/format 文件

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

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

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


5.22 source/local-options 文件

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

在编译软件包之后,源代码通常会被保持在应用补丁后的状态。你需要手工执行 quilt pop -a 来解除这些补丁,然后再提交到 master 分支。你可以向 debian/source/local-options 文件里添加一行 unapply-patches 来自动实现此目的。这个文件不会被加入到生成的源代码包,它只影响本地的编译构建行为。这个文件里还可以包含 abort-on-upstream-changes (参看 dpkg-source(1))。


5.23 patches/* 文件

旧的 1.0 源代码包格式使用单一的大 diff.gz 文件保存 debian 文件夹和补丁。这样的软件包比较难于在事后检查和分析。这不是很好。

新的 3.0 (quilt) 源代码包格式使用 quilt 管理 debian/patches/* 文件。这些补丁和其他 debian 目录下的文件被归档为 debian.tar.gz 文件。因为 dpkg-source 不调用 quilt 就可以处理 3.0 (quilt) 源码包格式的补丁,故不需要 Build-Dependsquilt 软件包。[40]

quilt 命令在 quilt(1) 中有详细描述。它将对源代码的修改维护于 debian/patches 中一系列 -p1 级别的补丁文件中,debian 目录外的文件没有任何修改。这些补丁的顺序记录于 debian/patches/series 文件中。你可以轻松地 apply (=push)、un-apply (=pop) 和 refresh 补丁。[41]

修改源代码, 第 3 章 中,我们在 debian/patches 创建了三个补丁。

因为 Debian 补丁位于 debian/patches,请确定按照 设置 quilt, 第 3.1 节 中的方法正确配置 quilt

如果在之后有人提供了一个补丁 foo.patch,对于 3.0 (quilt) 源代码包格式可以很容易修改:

     $ 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

存储于新的 3.0 (quilt) 源代码包格式的补丁必须有 清晰的边界。你应该通过 quilt pop -a; while quilt push; do quilt refresh; done 来验证这点。


[ 上一页 ] [ 目录 ] [ 1 ] [ 2 ] [ 3 ] [ 4 ] [ 5 ] [ 6 ] [ 7 ] [ 8 ] [ 9 ] [ 下一页 ]


Debian 新维护人员手册

版本 1.2.25, 2010-12-21 14:06:56 UTC

Josip Rodin joy-mg@debian.org

翻译:Aron Xu happyaron.xu@gmail.com
翻译:李凌 lilingv@gmail.com
翻译:郑原真 ycheng@slat.org