第 4 章 debian 目录中的必须内容

目录

4.1. control
4.2. copyright
4.3. changelog
4.4. rules
4.4.1. Targets of the rules file
4.4.2. 默认的 rules 文件
4.4.3. 定制 rules 文件

There is a new subdirectory under the program's source directory, called debian. There are a number of files in this directory that we should edit in order to customize the behavior of the package. The most important of them are control, changelog, copyright, and rules, which are required for all packages. [27]

4.1. control

This file contains various values which dpkg, dselect, apt-get, apt-cache, aptitude, and other package management tools will use to manage the package. It is defined by the Debian Policy Manual, 5 "Control files and their fields".

Here is the control file dh_make created for us:

 1 Source: gentoo
 2 Section: unknown
 3 Priority: extra
 4 Maintainer: Josip Rodin <joy-mg@debian.org>
 5 Build-Depends: debhelper (>=9)
 6 Standards-Version: 3.9.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>

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

Lines 1-7 are the control information for the source package. Lines 9-13 are the control information for the binary package.

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

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

As you may have noticed, the Debian archive is divided into multiple areas: main (the free software), non-free (the not really free software) and contrib (free software that depends on non-free software). Each of these is divided into sections that classify packages into rough categories. So we have admin for administrator-only programs, devel for programmer tools, doc for documentation, libs for libraries, mail for email readers and daemons, net for network apps and daemons, x11 for X11 programs that don't fit anywhere else, and many more. [28]

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

Line 3 describes how important it is that the user installs this package. [29]

  • The optional priority will usually work for new packages that do not conflict with others claiming required, important, or standard priority.

  • extra 优先级适用于与其他非 extra 优先级软件包冲突的新软件包。

Section and priority are used by front-ends like aptitude when they sort packages and select defaults. Once you upload the package to Debian, the value of these two fields can be overridden by the archive maintainers, in which case you will be notified by email.

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

Line 4 is the name and email address of the maintainer. Make sure that this field includes a valid To header for email, because after you upload it, the bug tracking system will use it to deliver bug emails to you. Avoid using commas, ampersands, or parentheses.

Line 5 includes the list of packages required to build your package as the Build-Depends field. You can also have the Build-Depends-Indep field as an additional line, here. [30] Some packages like gcc and make which are required by the build-essential package are implied. If you need to have other tools to build your package, you should add them to these fields. Multiple entries are separated with commas; read on for the explanation of binary package dependencies to find out more about the syntax of these lines.

  • For all packages packaged with the dh command in the debian/rules file, you must have debhelper (>=9) in the Build-Depends field to satisfy the Debian Policy requirement for the clean target.

  • Source packages which have binary packages with Architecture: any are rebuilt by the autobuilder. Since this autobuilder procedure installs only the packages listed in the Build-Depends field before running debian/rules build (see 第 6.2 节 “自动编译系统”), the Build-Depends field needs to list practically all the required packages and Build-Depends-Indep is rarely used.

  • For source packages with binary packages all of which are Architecture: all, the Build-Depends-Indep field may list all the required packages unless they are already listed in the Build-Depends field to satisfy the Debian Policy requirement for the clean target.

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

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

$ dpkg-depcheck -d ./configure

To manually find exact build dependencies for /usr/bin/foo, execute

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

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

$ dpkg -S libfoo.so.6

Then just take the -dev version of every package as a Build-Depends entry. If you use ldd for this purpose, it will report indirect lib dependencies as well, resulting in the problem of excessive build dependencies.

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

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

On line 7 you can put the URL of the software's upstream homepage.

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

Line 10 describes the architectures the binary package can be compiled for. This value is usually one of the following depending on the type of the binary package. [32]

  • Architecture: any

    • The generated binary package is an architecture dependent one usually in a compiled language.

  • Architecture: all

    • The generated binary package is an architecture independent one usually consisting of text, images, or scripts in an interpreted language.

We leave line 10 as is since this is written in C. dpkg-gencontrol(1) will fill in the appropriate architecture value for any machine this source package gets compiled on.

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

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

The package management tools usually behave the same way when dealing with these relations; if not, it will be explained. (See dpkg(8), dselect(8), apt(8), aptitude(1), etc.)

Here is a simplified description of package relationships. [33]

  • Depends

    此软件包仅当它依赖的软件包均已安装后才可以安装。此处写明你的程序所必须的软件包。

  • Recommends

    Use this for packages that are not strictly necessary but are typically used with your program. When a user installs your program, all front-ends will probably prompt them to install the recommended packages. aptitude and apt-get install recommended packages along with your package by default (but the user can disable this behavior). dpkg will ignore this field.

  • Suggests

    Use this for packages which will work nicely with your program but are not at all necessary. When a user installs your program, they will probably not be prompted to install suggested packages. aptitude can be configured to install suggested packages along with your package but this is not its default. dpkg and apt-get will ignore this field.

  • Pre-Depends

    此项中的依赖强于 Depends 项。软件包仅在预依赖的软件包已经安装后才可以正常安装并且 正确配置 后才可以正常安装。在使用此项时应 非常慎重,仅当在 debian-devel@lists.debian.org 邮件列表讨论后才能使用。记住:根本就不要用这项。 :-)

  • Conflicts

    仅当所有冲突的软件包都已经删除后此软件包才可以安装。当程序在某些特定软件包存在时根本无法运行或存在严重问题时使用此项。

  • Breaks

    When installed the package will break all the listed packages. Normally a Breaks entry specifies that it applies to versions earlier than a certain value. The resolution is generally to use higher-level package management tools to upgrade the listed packages.

  • Provides

    For some types of packages where there are multiple alternatives virtual names have been defined. You can get the full list in the virtual-package-names-list.txt.gz file. Use this if your program provides a function of an existing virtual package.

  • Replaces

    当你的程序要替换其他软件包的某些文件,或是完整地替换另一个软件包(与 Conflicts 一起使用)。列出的软件包中的某些文件会被你的软件包所覆盖。

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

The fields may restrict their applicability to particular versions of each named package. The restriction of each individual package is listed in parentheses after its name, and should contain a relation from the list below followed by a version number value. The relations allowed are: <<, <=, =, >=, and >> for strictly lower, lower or equal, exactly equal, greater or equal, and strictly greater, respectively. For example,

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

The last feature you need to know about is ${shlibs:Depends}, ${perl:Depends}, ${misc:Depends}, etc.

dh_shlibdeps(1) calculates shared library dependencies for binary packages. It generates a list of ELF executables and shared libraries it has found for each binary package. This list is used for substituting ${shlibs:Depends}.

dh_perl(1) calculates Perl dependencies. It generates a list of a dependencies on perl or perlapi for each binary package. This list is used for substituting ${perl:Depends}.

Some debhelper commands may cause the generated package to depend on some additional packages. All such commands generate a list of required packages for each binary package. This list is used for substituting ${misc:Depends}.

dh_gencontrol(1) generates DEBIAN/control for each binary package while substituting ${shlibs:Depends}, ${perl:Depends}, ${misc:Depends}, etc.

Having said all that, we can leave the Depends field exactly as it is now, and insert another line after it saying Suggests: file, because gentoo can use some features provided by the file package.

Line 9 is the Homepage URL. Let's assume this to be at http://www.obsession.se/gentoo/.

Line 12 is the short description. Terminals are conventionally 80 columns wide so this shouldn't be longer than about 60 characters. I'll change it to fully GUI-configurable, two-pane X file manager.

Line 13 is where the long description goes. This should be a paragraph which gives more details about the package. Column 1 of each line should be empty. There must be no blank lines, but you can put a single . (dot) in a column to simulate that. Also, there must be no more than one blank line after the long description. [34]

We can insert Vcs-* fields to document the Version Control System (VCS) location between lines 6 and 7. [35] Let's assume that the gentoo package has its VCS located in the Debian Alioth Git Service at 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 (>=9), xlibs-dev, libgtk1.2-dev, libglib1.2-dev
 6 Standards-Version: 3.9.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 an 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 utilizes the GTK+ toolkit
30  for its interface.

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

4.2. copyright

This file contains information about the copyright and license of the upstream sources. Debian Policy Manual, 12.5 "Copyright information" dictates its content and DEP-5: Machine-parseable debian/copyright provides guidelines for its format.

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

You must fill in missing information to complete this file, such as the place you got the package from, the actual copyright notice, and the license. For certain common free software licenses (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, or the Artistic license), you can just refer to the appropriate file in the /usr/share/common-licenses/ directory that exists on every Debian system. Otherwise, you must include the complete license.

In short, here's what gentoo's copyright file should look like:

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

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

Please follow the HOWTO provided by the ftpmasters and sent to debian-devel-announce: http://lists.debian.org/debian-devel-announce/2006/03/msg00023.html.

4.3. changelog

This is a required file, which has a special format described in Debian Policy Manual, 4.4 "debian/changelog". This format is used by dpkg and other programs to obtain the version number, revision, distribution, and urgency of your package.

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

dh_make created a default one, and this is what it looks like:

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

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

Line 1 is the package name, version, distribution, and urgency. The name must match the source package name; distribution should be unstable, and urgency shouldn't be changed to anything higher than low. :-)

Lines 3-5 are a log entry, where you document changes made in this package revision (not the upstream changes - there is a special file for that purpose, created by the upstream authors, which you will later install as /usr/share/doc/gentoo/changelog.gz). Let's assume your ITP (Intent To Package) bug report number was 12345. New lines must be inserted just below the uppermost line that begins with * (asterisk). You can do it with dch(1), or manually with a text editor.

In order to prevent a package being accidentally uploaded before completing the package, it is good idea to change the distribution value to an invalid distribution value UNRELEASED.

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

1  gentoo (0.9.12-1) UNRELEASED; 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

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

Once you are satisfied with all the changes and documented them in changelog, you should change the distribution value from UNRELEASED to the target distribution value unstable (or even experimental). [36]

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

4.4. rules

Now we need to take a look at the exact rules which dpkg-buildpackage(1) will use to actually create the package. This file is in fact another Makefile, but different from the one(s) in the upstream source. Unlike other files in debian, this one is marked as executable.

4.4.1. Targets of the rules file

Every rules file, like any other Makefile, consists of several rules, each of which defines a target and how it is carried out. [37] A new rule begins with its target declaration in the first column. The following lines beginning with the TAB code (ASCII 9) specify the recipe for carrying out that target. Empty lines and lines beginning with # (hash) are treated as comments and ignored. [38]

A rule that you want to execute is invoked by its target name as a command line argument. For example, debian/rules build and fakeroot make -f debian/rules binary execute rules for build and binary targets respectively.

Here is a simplified explanation of the targets:

  • clean target: to clean all compiled, generated, and useless files in the build-tree. (Required)

  • build target: to build the source into compiled programs and formatted documents in the build-tree. (Required)

  • build-arch target: to build the source into arch-dependent compiled programs in the build-tree. (Required)

  • build-indep target: to build the source into arch-independent formatted documents in the build-tree. (Required)

  • install target: to install files into a file tree for each binary package under the debian directory. If defined, binary* targets effectively depend on this target. (Optional)

  • binary target: to create all binary packages (effectively a combination of binary-arch and binary-indep targets). (Required)[39]

  • binary-arch target: to create arch-dependent (Architecture: any) binary packages in the parent directory. (Required)[40]

  • binary-indep target: to create arch-independent (Architecture: all) binary packages in the parent directory. (Required)[41]

  • get-orig-source target: to obtain the most recent version of the original source package from an upstream archive. (Optional)

You are probably overwhelmed by now, but things are much simpler upon examination of the rules file that dh_make gives us as a default.

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 $@

(I've added the line numbers. In the actual rules file, the leading spaces are a TAB code.)

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

Line 10 can be uncommented to set the DH_VERBOSE variable to 1, so that the dh command outputs which dh_* commands it is executing. You can also add a line export DH_OPTIONS=-v here, so that each dh_* command outputs which commands it is executing. This helps you to understand exactly what is going on behind this simple rules file and to debug its problems. This new dh is designed to form a core part of the debhelper tools, and not to hide anything from you.

Lines 12 and 13 are where all the work is done with an implicit rule using the pattern rule. The percent sign means "any targets", which then call a single program, dh, with the target name. [42] The dh command is a wrapper script which runs appropriate sequences of dh_* programs depending on its argument. [43]

  • debian/rules clean runs dh clean, which in turn runs the following:

    dh_testdir
    dh_auto_clean
    dh_clean
    
  • debian/rules build 运行了 dh build,实际执行的命令为:

    dh_testdir
    dh_auto_configure
    dh_auto_build
    dh_auto_test
    
  • fakeroot debian/rules binary 执行了 fakeroot dh binary; 实际执行的命令为[44]

    dh_testroot
    dh_prep
    dh_installdirs
    dh_auto_install
    dh_install
    dh_installdocs
    dh_installchangelogs
    dh_installexamples
    dh_installman
    dh_installcatalogs
    dh_installcron
    dh_installdebconf
    dh_installemacsen
    dh_installifupdown
    dh_installinfo
    dh_installinit
    dh_installmenu
    dh_installmime
    dh_installmodules
    dh_installlogcheck
    dh_installlogrotate
    dh_installpam
    dh_installppp
    dh_installudev
    dh_installwm
    dh_installxfonts
    dh_bugfiles
    dh_lintian
    dh_gconf
    dh_icons
    dh_perl
    dh_usrlocal
    dh_link
    dh_compress
    dh_fixperms
    dh_strip
    dh_makeshlibs
    dh_shlibdeps
    dh_installdeb
    dh_gencontrol
    dh_md5sums
    dh_builddeb
    
  • fakeroot debian/rules binary-arch 执行了 fakeroot dh binary-arch,其效果等同于 fakeroot dh binary 并附加 -a 参数于每个命令。

  • fakeroot debian/rules binary-indep 执行了 fakeroot dh binary-indep,这会运行几乎和 fakeroot dh binary 一样的命令,但 dh_stripdh_makeshlibsdh_shlibdeps 除外,其他命令则均附加-i 选项。

The functions of dh_* commands are largely self-evident from their names. [45] There are a few notable ones that are worth giving (over)simplified explanations here assuming a typical build environment based on a Makefile. [46]

  • dh_auto_clean usually executes the following if a Makefile exists with the distclean target. [47]

    make distclean
    
  • dh_auto_configure./configure 存在时通常执行以下命令(省略了部分参数以方便此处阅读)。

    ./configure --prefix=/usr --sysconfdir=/etc --localstatedir=/var ...
    
  • dh_auto_build 通常使用以下命令执行 Makefile 中的第一个 target。

    make
    
  • dh_auto_test usually executes the following if a Makefile exists with the test target. [48]

    make test
    
  • dh_auto_install usually executes the following if a Makefile exists with the install target (line folded for readability).

    make install \
      DESTDIR=/path/to/package_version-revision/debian/package
    

All targets which require the fakeroot command will contain dh_testroot, which exits with an error if you are not using this command to pretend to be root.

The important part to know about the rules file created by dh_make is that it is just a suggestion. It will work for most packages but for more complicated ones, don't be afraid to customize it to fit your needs.

Although install is not a required target, it is supported. fakeroot dh install behaves like fakeroot dh binary but stops after dh_fixperms.

4.4.3. 定制 rules 文件

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

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

  • Add support for the dh_python2 command. (The best choice for Python.) [50]

    • Include the python package in Build-Depends.

    • Use dh $@ --with python2.

    • This handles Python modules using the python framework.

  • Add support for the dh_pysupport command. (deprecated)

    • Include the python-support package in Build-Depends.

    • Use dh $@ --with pysupport.

    • 这会使用 python-support 框架处理 Python 模块。

  • Add support for the dh_pycentral command. (deprecated)

    • Include the python-central package in Build-Depends.

    • Use dh $@ --with python-central instead.

    • 这样会同时停用 dh_pysupport 命令。

    • 这会使用 python-central 框架处理 Python 模块。

  • Add support for the dh_installtex command.

    • Include the tex-common package in Build-Depends.

    • Use dh $@ --with tex instead.

    • This registers Type 1 fonts, hyphenation patterns, and formats with TeX.

  • Add support for the dh_quilt_patch and dh_quilt_unpatch commands.

    • Include the quilt package in Build-Depends.

    • Use dh $@ --with quilt instead.

    • This applies and un-applies patches to the upstream source from files in the debian/patches directory for a source package in the 1.0 format.

    • This is not needed if you use the new 3.0 (quilt) source package format.

  • Add support for the dh_dkms command.

    • Include the dkms package in Build-Depends.

    • Use dh $@ --with dkms instead.

    • This correctly handles DKMS usage by kernel module packages.

  • Add support for the dh_autotools-dev_updateconfig and dh_autotools-dev_restoreconfig commands.

    • Include the autotools-dev package in Build-Depends.

    • Use dh $@ --with autotools-dev instead.

    • 这会自动更新或还原 config.subconfig.guess 文件。

  • Add support for the dh_autoreconf and dh_autoreconf_clean commands.

    • Include the dh-autoreconf package in Build-Depends.

    • Use dh $@ --with autoreconf instead.

    • 这样会在编译时更新 GNU 编译系统文件并在编译后对其进行恢复。

  • Add support for the dh_girepository command.

    • Includes the gobject-introspection package in Build-Depends.

    • Use dh $@ --with gir instead.

    • This computes dependencies for packages shipping GObject introspection data and generates the ${gir:Depends} substitution variable for the package dependency.

  • Add support for the bash completion feature.

    • Includes the bash-completion package in Build-Depends.

    • Use dh $@ --with bash-completion instead.

    • This installs bash completions using a configuration file at debian/package.bash-completion.

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

You may need to run dh_* commands invoked via the new dh with added arguments, or to run additional commands with them, or to skip them. For such cases, you create an override_dh_foo target with its rule in the rules file defining an override_dh_foo target for the dh_foo command you want to change. It basically says run me instead. [51]

Please note that the dh_auto_* commands tend to do more than what has been discussed in this (over)simplified explanation to take care of all the corner cases. It is a bad idea to use override_dh_* targets to substitute simplified equivalent commands (except for the override_dh_auto_clean target) since it may bypass such smart debhelper features.

So, for instance, if you want to store system configuration data in the /etc/gentoo directory instead of the usual /etc directory for the recent gentoo package using Autotools, you can override the default --sysconfig=/etc argument given by the dh_auto_configure command to the ./configure command by the following.

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

The arguments given after -- are appended to the default arguments of the auto-executed program to override them. Using the dh_auto_configure command is better than directly invoking the ./configure command here since it will only override the --sysconfig argument and retains any other, benign arguments to the ./configure command.

If the Makefile in the source for gentoo requires you to specify build as its target to build it [52], you create an override_dh_auto_build target to enable this.

override_dh_auto_build:
        dh_auto_build -- build

This ensures $(MAKE) is run with all the default arguments given by the dh_auto_build command plus the build argument.

If the Makefile in the source for gentoo requires you to specify the packageclean target to clean it for the Debian package instead of using distclean or clean targets, you can create an override_dh_auto_clean target to enable thit.

override_dh_auto_clean:
        $(MAKE) packageclean

If the Makefile in the source for gentoo contains a test target which you do not want to run for the Debian package building process, you can use an empty override_dh_auto_test target to skip it.

override_dh_auto_test:

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

override_dh_installchangelogs:
        dh_installchangelogs FIXES

When you use the new dh command, use of explicit targets such as the ones listed in 第 4.4.1 节 “Targets of the rules file”, other than the get-orig-source target, may make it difficult to understand their exact effects. Please limit explicit targets to override_dh_* targets and completely independent ones, if possible.



[27] In this chapter, files in the debian directory are referred to without the leading debian/ for simplicity whenever the meaning is obvious.

[31] This somewhat strange situation is a feature well documented in the Debian Policy Manual, Footnotes 55. This is not due to the use of the dh command in the debian/rules file but due to how the dpkg-buildpackage works. The same situation applies to the auto build system for Ubuntu.

[34] These descriptions are in English. Translations of these descriptions are provided by The Debian Description Translation Project - DDTP.

[36] If you use the dch -r command to make this last change, please make sure to save the changelog file explicitly by the editor.

[37] You can start learning how to write Makefile from Debian Reference, 12.2. "Make". The full documentation is available as http://www.gnu.org/software/make/manual/html_node/index.html or as the make-doc package in the non-free archive area.

[39] 此 target 被 dpkg-buildpackage 用于 第 6.1 节 “完整的(重)构建” 描述的过程中。

[40] 此 target 被 dpkg-buildpackage -B 用于第 6.2 节 “自动编译系统” 描述的过程中。

[41] 此 target 被 dpkg-buildpackage -A 使用。

[42] This uses the new debhelper v7+ features. Its design concepts are explained in Not Your Grandpa's Debhelper presented at DebConf9 by the debhelper upstream. Under lenny, dh_make created a much more complicated rules file with explicit rules and many dh_* scripts listed for each one, most of which are now unnecessary (and show the package's age). The new dh command is simpler and frees us from doing the routine work "manually". You still have full power to customize the process with override_dh_* targets. See 第 4.4.3 节 “定制 rules 文件”. It is based only on the debhelper package and does not obfuscate the package building process as the cdbs package tends to.

[43] You can verify the actual sequences of dh_* programs invoked for a given target without really running them by invoking dh --no-act target or debian/rules -- '--no-act target'.

[44] The following example assumes your debian/compat has a value equal or more than 9 to avoid invoking any python support commands automatically.

[45] For complete information on what all these dh_* scripts do exactly, and what their other options are, please read their respective manual pages and the debhelper documentation.

[46] These commands support other build environments such as setup.py which can be listed by executing dh_auto_build --list in a package source directory.

[47] It actually looks for the first available target in the Makefile out of distclean, realclean, or clean, and executes that.

[48] It actually looks for the first available target in the Makefile out of test or check, and executes that.

[49] If a package installs the /usr/share/perl5/Debian/Debhelper/Sequence/custom_name.pm file, you should activate its customization function by dh $@ --with custom-name.

[50] Use of the dh_python2 command is preferred over use of dh_pysupport or dh_pycentral commands. Do not use the dh_python command.

[51] lenny 下,如果你希望更改某个 dh_* 脚本的行为,你需要在 rules 中找到相应的行然后进行调整。

[52] dh_auto_build without any arguments will execute the first target in the Makefile.

[53] The debian/changelog and debian/NEWS files are always automatically installed. The upstream changelog is found by converting filenames to lower case and matching them against changelog, changes, changelog.txt, and changes.txt.