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


Debian 新维护人员手册
第 4 章 - debian 目录中的必须内容


运行 dh_make 后,程序源代码目录下新出现了一个名为 debian 的子目录。这个目录中有很多用于定制软件包行为的文件,需要我们编辑。其中最重要的几个是 controlchangelogcopyrightrules,它们是所有软件包必须的。


4.1 control 文件

这个文件包含了很多供 dpkgdselectapt-getapt-cacheaptitude 等软件包管理工具提取信息以进行管理时所使用的变量。这些变量均在 Debian Policy Manual, 5 'Control files and their fields' 中定义。

这是 dh_make 为我们创建的 control 文件:

      1 Source: gentoo
      2 Section: unknown
      3 Priority: extra
      4 Maintainer: Josip Rodin <joy-mg@debian.org>
      5 Build-Depends: debhelper (>= 7.0.50~)
      6 Standards-Version: 3.8.4
      7 Homepage: <insert the upstream URL, if relevant>
      8
      9 Package: gentoo
     10 Architecture: any
     11 Depends: ${shlibs:Depends}, ${misc:Depends}
     12 Description: <insert up to 60 chars description>
     13  <insert long description, indented with spaces>

(注:我为它添加了行号。)

第 1-6 行是源代码包的控制信息。

第 1 行是源代码包的名称。

第 2 行是该源码包要进入发行版中的分类。

你可能已经注意到,Debian 仓库被分为几个类别:main (自由软件)、non-free (非自由软件)以及 contrib (依赖于非自由软件的自由软件)。在这些大的分类之下还有多个逻辑上的子分类,用以简短描述软件包的用途类别。admin 为仅供系统管理员使用的程序,base 为基本工具,devel 为开发工具,doc 为文档,libs 为库,mail 为电子邮件阅读器或邮件系统守护程序,net 为网络应用程序或网络服务守护进程,x11 为不属于其他分类的为 X11 程序。更多的子分类见 Debian Policy Manual, 2.4 'Sections'List of sections in 'sid'

我们将本例设置为 x11。( main/ 前缀是默认值,可以省略。)

第 3 行描述了用户安装此软件包的优先级。具体说明参看 Debian Policy Manual, 2.5 'Priorities'

Section 和 Priority 常被如 aptitude 的前端所使用,以分类软件包并计算默认值。一旦你把软件包上传到 Debian,这两项的值可以被仓库维护人员修改,在被修改时你将收到邮件。

由于这是一个常规优先级的软件,并不与其他软件包冲突,我们将优先级改为 optional

第 4 行是维护者的姓名和电子邮件地址。请确保此处的值可以直接用于电子邮件头的 To 项。因为一旦你将软件包上传至仓库,Bug 跟踪系统将使用其向你发送可能的 Bug 报告邮件。避免使用逗号、“&”符号或括号。

第 5 行中的 Build-Depends 项列出了编译此软件包需要的软件包。一些情况下你还需要这里添加一行 Build-Depends-Indep (参看 Debian Policy Manual, 7.7 'Relationships between source and binary packages - Build-Depends, Build-Depends-Indep, Build-Conflicts, Build-Conflicts-Indep')。build-essential 依赖的软件包,如 gccmake 等,已经默认安装而不需再写到此处。如果你需要其他工具来编译这个软件包,请将它们加到这里。多个软件包应使用半角逗号分隔,继续阅读二进制包依赖关系以增进对这些行的语法的理解。

如果你不知道应该使用哪一个,则使用 Build-Depends 以保证安全。[16]

要找出编译你的软件所需的软件包可以使用这个命令:

     $ dpkg-depcheck -d ./configure

要手工地找到 /usr/bin/foo 的编译依赖,可以执行:

     $ objdump -p /usr/bin/foo | grep NEEDED

对于列出的每个库,例如 libfoo.so.6,运行:

     $ dpkg -S libfoo.so.6

接下来直接将相应的 -dev 软件包的名称放到 Build-Depends 项内。如果你使用 ldd,它也会报告出间接的库依赖关系,这可能造成填写了某些不必要的依赖。

gentoo 需要 xlibs-devlibgtk1.2-devlibglib1.2-dev 才能编译,所以我们将这些软件包加在 debhelper 之后。

第 6 行是此软件包所依据的 Debian Policy Manual 标准版本号。

在第 7 行你可以放置上游项目的首页地址。

第 9 行是二进制软件包的名称。通常情况下与源代码包相同,但不是必须的。

第 10 行描述了这个软件包可以在哪些 CPU 构架上编译。我们将保持它为 any,因为 dpkg-gencontrol(1) 将在这个软件包可以编译的平台上为此处填写合适的信息。

如果你的软件包是平台独立的(例如一个 shell 或 Perl 脚本,或一些文档),将这项改变为 all,然后继续阅读 rules 文件, 第 4.4 节 中关于使用 binary-indep 指令替代 binary-arch 来编译软件包的内容。

第 11 行显示了 Debian 软件包系统中最强大的特性之一。每个软件包都可以和其他软件包有各种不同的关系。除 Depends 外,还有 RecommendsSuggestsPre-DependsBreaksConflictsProvidesReplaces

软件包管理工具通常对这些关系采取相同的操作,如果不是,我将会详细解释。(参看 dpkg(8)dselect(8)apt(8)aptitude(1) 等。)

以下是各种依赖关系的含义:

所有的这些项都使用相同的语法。它们是一个软件包列表,软件包名称间使用半角逗号分隔。也可以写出有多个可选的软件包名称,这些软件包使用 | 符号分隔。

这些项内还可以指定某些软件包的版本号之间的关系。版本号在括号内,紧随软件包名称之后,并在以下逻辑符号后写清具体版本:<<<==>=>>,分别代表严格小于、小于或等于、严格等于、大于或等于以及严格大于。例如:

     Depends: foo (>= 1.2), libbar1 (= 1.3.4)
     Conflicts: baz
     Recommends: libbaz4 (>> 4.0.7)
     Suggests: quux
     Replaces: quux (<< 5), quux-foo (<= 7.6)

你应当知道的最后一个特性是关于 ${shlibs:Depends}${perl:Depends}${misc:Depends} 等。这些条目的值会由 debhelper 的其他组件在 dh_gencontrol(1) 运行时生成。

dh_shlibdeps(1) 会在程序编译完成并被放入临时文件夹后扫描二进制文件和库文件来确定动态库的依赖关系,并检测包含它们的软件包名称。例如 libc6xlib6g。 这些软件包将被列在 ${shlibs:Depends} 的位置。

dh_perl(1) 所生成的软件包列表将用于 ${perl:Depends} 的位置。

一些 debhelper 命令可能会使生成的软件包需要依赖于某些其他软件包,这些软件包将被列于 ${misc:Depends} 的位置。

说过这些以后,我们可以把 Depends 项保持现状不动,并在其下插入一行 Suggests: file",因为 gentoo 可以使用 file 软件包提供的某些特性。

第 12 行是短描述。绝大多数人的屏幕是 80 列宽,所以描述不应超过 60 个字符。在这个例子里我把它写为 fully GUI-configurable, two-pane X file manager

第 13 行是长描述开始的地方。这应当是一段更详细地描述软件包的话。每行的第一个格应当留空。描述中不应存在空行,如果必须使用空行,则在行中仅放置一个 . (半角句点)。同时,长描述后也不应有超过一行的空白。

接下来我们按照 Developer's Reference, 6.2.5. 'Version Control System location' 中记叙的内容在第 6 和第 7 行之间添加 Vcs-* 项。这里我们假设 gentoo 软件包处于 Debian Alioth Git 服务的 git://git.debian.org/git/collab-maint/gentoo.git

到此为止,我们做好了 control 文件:

      1 Source: gentoo
      2 Section: x11
      3 Priority: optional
      4 Maintainer: Josip Rodin <joy-mg@debian.org>
      5 Build-Depends: debhelper (>= 7.0.5), xlibs-dev, libgtk1.2-dev, libglib1.2-dev
      6 Standards-Version: 3.8.4
      7 Vcs-Git: git://git.debian.org/git/collab-maint/gentoo.git
      8 Vcs-browser: http://git.debian.org/?p=collab-maint/gentoo.git
      9 Homepage: http://www.obsession.se/gentoo/
     10
     11 Package: gentoo
     12 Architecture: any
     13 Depends: ${shlibs:Depends}, ${misc:Depends}
     14 Suggests: file
     15 Description: fully GUI-configurable, two-pane X file manager
     16  gentoo is a two-pane file manager for the X Window System. gentoo lets the
     17  user do (almost) all of the configuration and customizing from within the
     18  program itself. If you still prefer to hand-edit configuration files,
     19  they're fairly easy to work with since they are written in an XML format.
     20  .
     21  gentoo features a fairly complex and powerful file identification system,
     22  coupled to a object-oriented style system, which together give you a lot
     23  of control over how files of different types are displayed and acted upon.
     24  Additionally, over a hundred pixmap images are available for use in file
     25  type descriptions.
     26  .
     29  gentoo was written from scratch in ANSI C, and it utilises the GTK+ toolkit
     30  for its interface.

(注:我为它添加了行号。)


4.2 copyright 文件

这个文件包含了上游软件的资源、版权以及许可证信息。它的形式没有在 Debian Policy 中详述,但其内容为 (Debian Policy Manual, 12.5 'Copyright information')。你还可以查看 DEP-5: Machine-parseable debian/copyright

dh_make 可以给出一个 copyright 文件的模板。在这里我们使用 --copyright gpl2 参数来获得一个模板写明 gentoo 软件包是发布于 GPL-2 许可证下。

你必须填写上其余的信息,如你从何处获得此软件,实际的版权声明和它们的许可证。对于常见的自由软件许可证,如 GNU GPL-1、GNU GPL-2、GNU GPL-3、LGPL-2、LGPL-2.1、LGPL-3、GNU FDL-1.2、GNU FDL-1.3、Apache-2.0 或 Artistic 许可证,你可以直接将其指向存在于所有 Debian 系统的 /usr/share/common-licenses/ 目录下的相关文件。其他的许可证则必须包含完整的许可证文本。

简言之,gentoocopyright 文件如下所示:

      1 Format-Specification: http://svn.debian.org/wsvn/dep/web/deps/dep5.mdwn?op=file&rev=135
      2 Name: gentoo
      3 Maintainer: Josip Rodin <joy-mg@debian.org>
      4 Source: http://sourceforge.net/projects/gentoo/files/
      5
      6 Copyright: 1998-2010 Emil Brink <emil@obsession.se>
      7 License: GPL-2+
      8
      9 Files: icons/*
     10 Copyright: 1998 Johan Hanson <johan@tiq.com>
     11 License: GPL-2+
     12
     13 Files: debian/*
     14 Copyright: 1998-2010 Josip Rodin <joy-mg@debian.org>
     15 License: GPL-2+
     16
     17 License: GPL-2+
     18  This program is free software; you can redistribute it and/or modify
     19  it under the terms of the GNU General Public License as published by
     20  the Free Software Foundation; either version 2 of the License, or
     21  (at your option) any later version. 
     22  .
     23  This program is distributed in the hope that it will be useful,
     24  but WITHOUT ANY WARRANTY; without even the implied warranty of
     25  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
     26  GNU General Public License for more details.
     27 .
     28  You should have received a copy of the GNU General Public License along
     29  with this program; if not, write to the Free Software Foundation, Inc.,
     30  51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA.
     31  .
     32  On Debian systems, the full text of the GNU General Public
     33  License version 2 can be found in the file
     34  `/usr/share/common-licenses/GPL-2'.

(注:我为它添加了行号。)

另外还可以参看 ftpmasters 发送到 debian-devel-announce 的 HOWTO: http://lists.debian.org/debian-devel-announce/2006/03/msg00023.html


4.3 changelog 文件

这是一个必须的文件,它的格式在 Debian Policy Manual, 4.4 'debian/changelog' 中有详细的描述。这种格式被 dpkg 和其他程序用以获得版本号信息、适应的发行版和紧急程度。

对于你而言,详细描述你所做出的更改也是很好且很重要的。它将帮助下载你的软件包的人了解这个软件包中是否有他们需要知道的事情。它会被作为 /usr/share/doc/gentoo/changelog.Debian.gz 保存在二进制包中。

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

     1  gentoo (0.9.12-1) unstable; urgency=low
     2
     3   * Initial release (Closes: #nnnn)  <nnnn is the bug number of your ITP>
     4
     5  -- Josip Rodin <joy-mg@debian.org>  Mon, 22 Mar 2010 00:37:31 +0100
     6

(注:我为它添加了行号。)

第 1 行是软件包名、版本号、发行版和紧急程度。软件包名必须与实际的源代码包名相同,发行版可以是 unstable(甚至 experimental)[17],紧急程度则不要使用任何高于 low 的内容。 :-)

第 3-5 行是一个很长的条目,记录了你在这个 Debian 版本中做出的修改(不是上游)修改——上游修改由上游作者创建另外一个文件并维护,它们应被安装为 /usr/share/doc/gentoo/changelog.gz)。假设你的 ITP (Intent To Package,计划打包)的 Bug 号为 12345。新行必须插入在上一个以星号 * 开头的行的正下方。你可以使用 dch(1) 完成这个工作,也可以使用普通的文本编辑器手工完成。

最后它会成为以下的样子:

     1  gentoo (0.9.12-1) unstable; urgency=low
     2
     3   * Initial Release. Closes: #12345
     4   * This is my first Debian package.
     5   * Adjusted the Makefile to fix $(DESTDIR) problems.
     6
     7  -- Josip Rodin <joy-mg@debian.org>  Mon, 22 Mar 2010 00:37:31 +0100
     8

(注:我为它添加了行号。)

你可以在关于更新的 更新软件包, 第 9 章 中了解更多关于 changelog 的内容。


4.4 rules 文件

现在我们需要看看 dpkg-buildpackage(1) 用于实际创建软件包的 rules 文件。这个文件是一个 Makefile,但不同于上游源代码中的那个。和 debian 目录中的其他文件不同,这个文件被标记为可执行。


4.4.1 rules 文件中的 target

每个 rules 文件都和其他的 Makefile 一样包含多个 target 和其中指定如何处理源代码的规则。Debian Policy Manual, 4.9 'Main building script: debian/rules' 中对此做出了详细解释。

以下是对各 target 的简单解释:

你希望执行的 target 规则可以通过命令行参数的方式触发(例如 ./debian/rules buildfakeroot make -f debian/rules binary")。target 名称后你可以添加其依赖的 target 或文件。此后是以 TAB 开头的任意数量的名录,每行一个。一个新的 target 则在行首顶格开始。空行和以 # 开头的行将被视为注释而忽略。

可能你现在感到有些迷惑,在接下来讲解 dh_make 给出的默认的 rules 文件时会进行详细的讲解。你还应该阅读 info make 来了解更多信息。


4.4.2 默认的 rules 文件

新版本的 dh_make 会生成一个使用 dh 命令的非常简单但非常强大的默认的 rules 文件:

      1 #!/usr/bin/make -f
      2 # -*- makefile -*-
      3 # Sample debian/rules that uses debhelper.
      4 # This file was originally written by Joey Hess and Craig Small.
      5 # As a special exception, when this file is copied by dh-make into a
      6 # dh-make output file, you may use that output file without restriction.
      7 # This special exception was added by Craig Small in version 0.37 of dh-make.
      8
      9 # Uncomment this to turn on verbose mode.
     10 #export DH_VERBOSE=1
     11
     12 %:
     13        dh $@

(注:我添加了行号。实际的 rules 文件里开头的空格是 TAB 填充的。)

可能在 shell 或 Perl 脚本中你已经对第一行的形式很熟悉了,它告诉操作系统这个文件应使用 /usr/bin/make 处理。

第 10 行可以去掉注释并将 DH_VERBOSE 变量设置为 1。此后,dh 命令会输出哪些 dh_* 命令被执行了。你还可以在这里添加一行 export DH_OPTIONS=-v。此后每个 dh_* 命令会输出它所执行的具体命令。这可以帮助你了解这个简单的 rules 文件所执行的内容并帮助调试问题。这个新的 dhdebhelper 工具的关键部分,其所有操作都可以让你看到。

第 12 和 13 行是整个文件的全部内容。百分号意味着每个 target 都只是调用 dh + target 名称的命令。[21] dh 命令是一个包装脚本并按照参数执行相应的 dh_*。[22]

dh_* 的功能几乎都可以通过它的名称来了解。[24]有几个命令有很值得一提的内容,在此处默认基于此 Makefile 使用典型的编译环境。[25]

需要 fakeroot 命令的都包含了 dh_testroot。如果你没有假装为 root,将会报错并退出。

关于 dh_make 生成的 rules 文件,你应该知道的最重要的事是,它仅仅是一个建议。它对多数简单的软件包有效,但对于更复杂的则要大胆对其进行定制以满足需要。只有一件事不应改变,就是它们的名字,这些名称由 Debian Policy 定义且被所有工具使用。

尽管 install target 不是必须的,但也被支持。fakeroot dh install 的操作就像 fakeroot dh binary一样,但停止于 dh_fixperms


4.4.3 定制 rules 文件

有很多方法来定制使用新的 dh 命令创建的 rules 文件。

dh $@ 命令可以按以下方式定制。[28]

对于使用 Autotools 的源代码,使用 dh --with autotools-dev --with autoreconf $@ 让其使用最新的 GNU 编译系统。

很多由新的 dh 命令触发的 dh_* 都可以通过修改 debian 目录中的配置文件来对其行为进行定制。参看 debian 目录下的其他文件, 第 5 章 和每个命令的 man 手册页。

某些由新的 dh 命令所触发的 dh_* 命令可能需要额外的参数使其一同执行或者跳过执行。对于这类情况,你可以在 rules 文件中创建一个 override_dh_foo target 来使其完成你想要的 dh_foo 命令。它的作用简单说就是 把运行的命令换成我。[30]

请注意 dh_auto_* 命令所做的比上述简化的步骤中介绍的内容更多。除了 override_dh_auto_clean 外把上面的简化命令写成 override_dh_* 中是不明智的,这样会使得 debhelper 的许多智能特性无法体现。

如果你希望把 gentoo 软件包的配置文件安装到 /etc/gentoo 而非默认的 /etc 目录,你可以覆盖 dh_auto_configure 默认的使用的 --sysconfig=/etc 参数,改为向 ./configure 命令传递以下参数:[31]

     override_dh_auto_configure:
             dh_auto_configure -- --sysconfig=/etc/gentoo

-- 后给出的参数被附加于程序自动添加的默认参数后以对其进行覆盖。使用 dh_auto_configure 命令好于直接使用 ./configure,因为这样只覆盖了 --sysconfig 参数而保留了其他参数。

如果 gentooMakefile 需要指定 build 作为其编译用的 target[32],你可以创建一个 override_dh_auto_build target 来启用它。

     override_dh_auto_build:
             dh_auto_build -- build

这保证了 $(MAKE) 会使用 dh_auto_build 传递的所有参数并编译处理 build 这个 target。

如果 gentooMakefile 需要指定 packageclean 作为其清理用的 target,而非 Debian 软件包通常使用的 distcleanclean,你可以创建一个 override_dh_auto_clean target 来启用它。

     override_dh_auto_clean:
             $(MAKE) packageclean

如果 gentooMakefile 包含了一个 test target 但你不想在 Debian 软件包编译过程中运行它,可以使用空的 override_dh_auto_test target 来跳过它。

     override_dh_auto_test:

如果 gentoo 有某个不常见的上游 changelog 文件名为 FIXES,默认情况下 dh_installchangelogs 不会安装它。dh_installchangelogs 命令需要将 FIXES 作为它的参数来安装它。[33]

     override_dh_installchangelogs:
             dh_installchangelogs FIXES

如果你使用新的 dh 命令时,还使用 rules 文件中的 target, 第 4.4.1 节 中除 get-orig-source 的 target ,会使得其效果难以预料。请尽量避免使用独立的或预设的 target,如果必须修改默认设置则酌情使用 override_dh_*


[ 上一页 ] [ 目录 ] [ 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