[ 上一页 ] [ 目录 ] [ 1 ] [ 2 ] [ 3 ] [ 4 ] [ 5 ] [ 6 ] [ 7 ] [ 8 ] [ 9 ] [ 下一页 ]
debian
目录下的其他文件
要控制 debhelper
在构建软件包过程中的行为,可以在 debian
目录中放置可选的配置文件。本章将会对这些文件和它们的格式进行概述。请阅读
Debian Policy
Manual
和 Debian Developer's
Reference
来了解更多内容。
dh_make
命令会在 debian
目录中创建一些配置文件模板,它们的文件名多带有
.ex
的后缀。其中的一些可能以软件包名作为前缀,如
package。现在对它们进行一个大致的了解。
还有一些 debhelper
的配置文件模板 dh_make
命令没有直接创建。在这种情况下如果你需要它们,则要使用文本编辑器手工创建。
如果你希望或需要激活它们中的任意一个或多个,请按照下面的方法做。
如果模板文件带有 .ex 或 .EX 后缀,则重命名它去掉后缀。
按照需要,把带有软件包名的配置文件的前缀改为实际的二进制软件包名,例如 package。
修改模板文件来满足你的需要。
删除不需要的模板文件。
如果需要,修改 control
文件(参看 control
文件, 第 4.1
节)。
如果需要,修改 rules
文件(参看 rules
文件, 第 4.4
节)。
不带有二进制软件包名(例如 package
)前缀的
debhelper
配置文件则默认用于 control
文件中列出的第一个二进制软件包,如默认情况下的
install
文件。如果需要为其他二进制包使用配置,则应在配置文件名前加上二进制包名,如
package-1.install
、package-2.install
等。
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)
compat
文件
compat
文件定义了 debhelper
的兼容级别。目前你应当使用以下命令将其设置为
debhelper
V7。
$ echo 7 > debian/compat
conffiles
文件系统管理中有件很恼人的事,就是当你付出了很多时间和经历来自定义一个程序,但是升级后所有的修改都被覆盖掉了。Debian 通过将配置文件单独标记来解决这个问题,当软件包升级的时候,你将会被询问是否要保留你的旧配置文件。
从 debhelper
V3 开始,dh_installdeb(1)
将
自动 识别所有在 /etc
目录下的文件为配置文件。所以如果你的程序只有在那里的配置文件,则不需再指定它们。
如果你的程序使用配置文件,但程序会自动对配置进行改写,则最好也将其标记为配置文件,这样
dpkg
总是会要求用户校验发生了的变更。
如果你正在打包的程序需要所有用户都为自己修改
/etc
目录中的配置,有两种常见的方法让
dpkg
不将其记录为配置文件。
用 maintainer scripts 在 /etc
目录中创建指向
/var
相关目录的符号链接。
用 maintainer scripts 在 /etc
目录中生成一个文件。
更多关于 maintainer scripts 的信息,参看 {post|pre}{inst|rm}
文件, 第 5.18
节
package.cron.*
文件如果你的软件包需要有计划运行的操作以保证正常工作,可以使用这个文件进行设置。既可以设置常规的任务使其在每小时、每天、每星期、每月或其他情况或时间下运行。相应的文件名是:
cron.hourly
- 安装为
/etc/cron.hourly/package
:每小时运行一次。
cron.daily
- 安装为
/etc/cron.daily/package
:每天运行一次,通常在早晨。
cron.weekly
- 安装为
/etc/cron.weekly/package
:每星期运行一次,通常在星期日早晨。
cron.monthly
- 安装为
/etc/cron.monthly/package
:每月运行一次,通常在该月第一天的早晨。
cron.d
- 安装为 /etc/cron.d/package
指定的任意时间。
对于前几个文件,其格式为 shell 脚本。唯一不同的是
package.cron.d
,它的格式需要参照
crontab(5)
注意这里的操作不包含日志旋转,如果需要日志旋转,参看
dh_installlogrotate(1)
和 logrotate(8)
dirs
文件
这个文件指定了我们需要,但正常安装过程(dh_auto_install
触发 make install
DESTDIR=...)里没有被安装的目录。通常这是由于
Makefile
中存在问题。
install
文件中列出的文件不需要提前创建目录,参看 install
文件, 第 5.11 节
最好是先尝试安装,如果遇到了相关的问题再使用这个文件。目录名中不应有前导的 / 符号。
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 节。
docs
文件
这个文件制定了我们使用 dh_installdocs(1)
安装到临时目录的文件名。
默认情况下它会加入代码目录顶层的所有名为
BUGS
、README*
、TODO
等的文件。
对于 gentoo
,我还加入了一些其他文件:
BUGS CONFIG-CHANGES CREDITS NEWS README README.gtkrc TODO
emacsen-*
文件如果你的软件包提供可以在安装时编译为字节码的 Emacs 文件,你可以使用这些文件设置。
它们会被 dh_installemacsen(1)
安装到临时目录。
如果你不需要这些,就删除它们。
package.examples
文件
dh_installexamples(1)
会将列出的文件和目录作为示例文件安装。
package.init
和 package.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
如果你不需要这些,就删除它们。
install
文件
如果你的软件包需要标准的 make install
没有安装的文件,可以把文件名和目标路径写入
install
文件,它们将被 dh_install(1)
安装。[34]
你需要首先检查要安装的文件是否有更有针对性的特定工具会对其进行安装,例如示例、文档应写在
docs
文件中安装。
这个 install
文件每行安装一份文件,格式上先是相对于编译目录的源目录,然后是一个空格,接下来是相对于安装目录的目标目录。假设某个二进制文件没有被默认安装,则应在
install
文件添加如下内容:
src/foo/mybin usr/bin
这意味着安装这个软件包时将有一个二进制文件
/usr/bin/mybin
当然 install
文件也可以只包含相对的源路径而不带目标位置。这样的格式通常用于使用
package-1.install
、package-2.install
等将大软件包分割为多个二进制包的情况。
如果 dh_install
命令没有在当前目录(或者你可能使用 --sourcedir
参数指定的位置)找到文件,它会回滚至使用
debian/tmp
目录。
package.info
文件
如果你的软件包有 info 信息页,应该使用
dh_installinfo(1)
安装,要安装的文件列于
package.info
文件中。
{package.|source/}lintian-overrides
文件
如果 lintian
报告了一个 Debian Policy
允许的例外的错误诊断,你可以使用
package.lintian-overrides
或
source/lintian-overrides
使其不再警告。请阅读
/usr/share/doc/lintian/lintian.html/index.html
并应严格避免滥用。
package.lintian-overrides
是对于名为
package
有效的配置,会由
dh_lintian
命令安装到usr/share/lintian/overrides/package
source/lintian-overrides
是针对源代码包的,不会安装。
manpage.*
文件
你的程序应该有 man
手册页,如果它们没有自带则需要由你来创建。dh_make
命令创建了几个 man
手册页的模板。它们需要被妥善地编辑,并且要删除未使用的模板。
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]
manpage.sgml.ex
文件
如果你希望使用 SGML 而非 nroff
格式编写 man
手册页,可以使用 manpage.sgml.ex
模板。如果你要这样,需要进行以下步骤:
重命名文件为类似 gentoo.sgml
的名称。
安装 docbook-to-man
软件包。
在 control
文件的 Build-Depends 中添加
docbook-to-man
软件包。
在 rules
文件里添加 override_dh_auto_build
target:
override_dh_auto_build: docbook-to-man debian/gentoo.sgml > debian/gentoo.1 dh_auto_build
manpage.xml.ex
文件如果你希望使用XML 而非 SGML,可以使用 manpage.xml.ex 模板。如果你要这样,需要进行以下步骤:
重命名源文件为类似 gentoo.1.xml 的名称。
安装 docbook-xsl
软件包和一个 XSLT 处理器,例如
xsltproc
(推荐)。
在 control
文件的 Build-Depends 中添加
docbook-xsl
、docbook-xml
和 xsltproc
软件包。
在 rules
文件里添加 override_dh_auto_build
target:
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
文件
如果你的软件包有 man 手册页,你应该将它们列在
package.manpages
文件中以便
dh_installman(1)
安装。
要将 doc/gentoo.1
安装为 gentoo
的 man
手册页,创建一个 gentoo.manpages
,内容如下:
docs/gentoo.1
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,它指定了程序需要何种界面。修改此处为列出的选项之一,例如 text 或 X11。
接下来是
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"
你还可以添加诸如
longtitle、icon、hints 等域。参看
dh_installmenu(1)
、menufile(5)
、update-menus(1)
和 /usr/share/doc/debian-policy/menu-policy.html/
了解更多信息。
NEWS
文件
dh_installchangelogs(1)
命令会安装这个文件。
{post|pre}{inst|rm}
文件
postinst
、preinst
、postrm
和
prerm
文件 [37] 被称为 maintainer
scripts。它们是放置于软件包控制信息区域,并由
dpkg
在软件包安装、升级或卸载时执行的脚本。
作为一个新维护人员,你应当避免手工编辑 maintainer
scripts,因为它们常存在各种问题。更多信息请阅读
Debian
Policy Manual, 6 'Package maintainer scripts and installation
procedure'
并查看 dh_make
给出的示例。
如果你不听我的劝告,自己为一个软件包创建了 maintainer scripts,你必须保证不仅测试 install 和 upgrade,还应测试 remove 和 purge。
升级到新版本应当是静默的(已有用户应当只在发现旧的 Bug 被修复或有新特性时注意到升级的变化)。
当更新必须以非静默模式进行时(例如多个主目录中的配置文件都要改为完全不同的结构时),你应该考虑将软件包设置到安全的默认配置(例如禁用服务)并按照
Debian Policy 提供相应的文档(README.Debian
和
NEWS.Debian
)。不要在升级时使用 maintainer
scripts 触发 debconf
来打扰用户。
ucf
软件包提供了 类似 conffile
的对不应标记为 conffiles
的文件的保留机制。这可以将与 maintainer scripts
相关的问题减少到最低。
这些 maintainer scripts 是 Debian 对于软件系统的增强特性,它们解释了 人们为什么选择 Debian。你必须非常小心,保证人们不因此产生烦恼。
TODO
文件
dh_installdocs(1)
命令会安装这个文件。
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 变更导致的问题。
source/format
文件
在 debian/source/format
中只包含一行,写明了此源代码包的格式(查看
dpkg-source(1)
获得完整列表)。在 squeeze
后,它应该是以下二者之一:
3.0 (native) - Debian native 软件
3.0 (quilt) - 其他所有软件
全新的 3.0 (quilt) 源代码格式将所有修改使用
quilt
补丁系列记录到
debian/patches
。这些修改会在解压源代码包时自动应用。[38] Debian 修改保存于
debian.tar.gz
归档文件,其中包含了整个
debian
目录。这个新格式支持直接添加例如 PNG
图标等的二进制文件。[39]
dpkg-source
解压 3.0 (quilt)
格式的源码包时会自动应用所有列于
debian/patches/series
的补丁。你可以使用
--skip-patches 选项避免在解压后自动应用补丁。
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)
)。
patches/*
文件
旧的 1.0 源代码包格式使用单一的大
diff.gz
文件保存 debian
文件夹和补丁。这样的软件包比较难于在事后检查和分析。这不是很好。
新的 3.0 (quilt) 源代码包格式使用 quilt
管理 debian/patches/*
文件。这些补丁和其他
debian
目录下的文件被归档为 debian.tar.gz
文件。因为 dpkg-source
不调用 quilt
就可以处理 3.0 (quilt)
源码包格式的补丁,故不需要 Build-Depends 于
quilt
软件包。[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 UTCjoy-mg@debian.org
happyaron.xu@gmail.com
lilingv@gmail.com
ycheng@slat.org