章 4. `debian` 目錄中的必須內容

# 章 4. `debian` 目錄中的必須內容

本教程文件已被重寫為另外的 Debian 維護者指導 文件，其中包含了更新的內容與更多實際例子。請使用新的教程作為主要的教程文件。

在程序源代碼目錄下有一個叫做 `debian` 的新的子目錄。這個目錄中存放着許多文件，我們將要修改這些文件來定製軟件包行爲。其中最重要的文件當屬 `control`, `changelog`, `copyright`, 以及 `rules`, 所有的軟件包都必須有這幾個文件。[27]

## 4.1. `control`

這個文件包含了很多供 dpkg、dselect、apt-get、apt-cache、aptitude 等包管理工具進行管理時所使用的許多變量。這些變量均在 Debian Policy Manual, 5 "Control files and their fields" 中被定義。

這裏的 `control` 文件是 dh_make 命令爲我們創建的：

     1 Source: gentoo
     2 Section: unknown
     3 Priority: optional
     4 Maintainer: Josip Rodin <joy-mg@debian.org>
     5 Build-Depends: debhelper (>=10)
     6 Standards-Version: 4.0.0
     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–7 行是原始碼包的控制資訊。第 9–13 行是二進位制包的控制資訊。

第 1 行是原始碼套件的名稱。

第 2 行是該源碼包要進入發行版中的分類。

你可能已經注意到，Debian 倉庫被分爲幾個類別：`main` (自由軟件)、`non-free` (非自由軟件)以及 `contrib` (依賴於非自由軟件的自由軟件)。在這些大的分類之下還有多個邏輯上的子分類，用以簡短描述軟件包的用途類別。`admin` 爲供系統管理員使用的程序，`devel` 爲開發工具，`doc` 爲文檔，`libs` 爲庫，`mail` 爲電子郵件閱讀器或郵件系統守護程序，`net` 爲網絡應用程序或網絡服務守護進程，`x11` 爲不屬於其他分類的爲 X11 程序，此外還有很多很多。[28]

我們將本例設置爲 x11。( `main/` 前綴是默認值，可以省略。)

第 3 行描述了用戶安裝此軟件包的優先級。[29]

- `optional` 優先級適用於與優先級爲 `required`、`important` 或 `standard` 的軟件包不衝突的新軟件包。

Section 和 Priority 常被如 aptitude 的前端所使用，以分類軟件包並選擇默認值。一旦你把軟件包上傳到 Debian，這兩項的值可以被倉庫維護人員修改，此時你將收到提示郵件。

由於這是一個常規優先級的軟體，並不與其他套件衝突，我們將優先級改爲 `optional`。

第 4 行是維護者的姓名和電子郵件地址。請確保此處的值可以直接用於電子郵件頭的 `To` 項。因爲一旦你將軟件包上傳至倉庫，Bug 跟蹤系統將使用它向你發送可能的 Bug 報告郵件。請避免使用逗號、“&”符號或括號。

第 5 行中的 `Build-Depends` 項列出了編譯此軟體包需要的軟體包。你還可以在這裡新增一行 `Build-Depends-Indep` 作為附加。[30] 有些被 `build-essential` 依賴的軟體包，如 `gcc` 和 `make` 等，已經會被預設安裝而不需再寫到此處。如果你需要其他工具來編譯這個軟體包，請將它們加到這裡。多個軟體包應使用半形逗號分隔。繼續閱讀二進位制包依賴關係以增進對這些行的語法的理解。

- 對於所有在 `debian/rules` 文件中使用 dh 命令打包的軟件包，必須在 `Build-Depends` 中包含 `debhelper (>=9)` 以滿足 Debian Policy 中對 `clean` target 的要求。

- 對於生成有標記過 `Architecture: any` 的二進位制包的原始碼包，它們將被 autobuilder 重構建。因為 autobuilder 過程在僅安裝 `Build-Depends` 中列出的程式前便執行 `debian/rules build` 中的內容(參看 節 6.2, “自動編譯系統”)，`Build-Depends` 欄位需要列出所有必須的編譯依賴，而 `Build-Depends-Indep` 則很少使用。

- 對於生成全標記 `Architecture: all` 二進制包的源碼包，`Build-Depends-Indep` 中應列出所有要求的軟件包，除非 `Build-Depends` 中已經列出，這樣以便滿足Debian Policy 中對 `clean` target 的要求。

如果你不知道應該使用哪一個，則使用 `Build-Depends` 以保證安全。[31]

要找出編譯你的軟體所需的套件可以使用這個命令：

    $ 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-dev`、`libgtk1.2-dev` 和 `libglib1.2-dev` 才能編譯，所以我們將這些套件加在 `debhelper` 之後。

第 6 行是此套件所依據的 Debian Policy Manual 標準版本號。

在第 7 行你可以放置上游項目首頁的URL。

第 9 行是二進位套件的名稱。通常情況下與原始碼套件相同，但不是必須的。

第 10 行描述了可以編譯本二進制包的體繫結構。根據二進制包的類型，這個值常常是下列中的一個： [32]

- `Architecture: any`

  - 一般而言，包含 編譯型語言編寫的程序 生成的二進制包依賴於具體的體繫結構。

- `Architecture: all`

  - 一般而言，包含 文本、圖像、或解釋型語言腳本 生成的二進制包獨立於體繫結構。

我們不管第 10 行，鑑於本程序是用 C 語言編寫的。 dpkg-gencontrol(1) 命令將根據這個軟件包可以編譯的平臺 而爲此處填寫合適的信息。

如果你的套件是平臺獨立的(例如一個 shell 或 Perl 腳本，或一些文件)，將這項改變爲 `all`，然後繼續閱讀 節 4.4, “`rules`” 中關於使用 `binary-indep` 指令替代 `binary-arch` 來編譯套件的內容。

第 11 行顯示了 Debian 套件系統中最強大的特性之一。每個套件都可以和其他套件有各種不同的關係。除 `Depends` 外，還有 `Recommends`、`Suggests`、`Pre-Depends`、`Breaks`、`Conflicts`、`Provides` 和 `Replaces`。

軟件包管理工具通常對這些關係採取相同的操作；如果有例外，本教程將會詳細解釋。(參看 dpkg(8)、dselect(8)、apt(8)、aptitude(1) 等。)

這裏有一篇關於軟件包關係的簡述： [33]

- `Depends`

  此套件僅當它依賴的套件均已安裝後纔可以安裝。此處寫明你的程式所必須的套件。

- `Recommends`

  這項中的軟件包不是嚴格意義上必須安裝纔可以保證程序運行。當用戶安裝軟件包時，所有前端工具都會詢問是否要安裝這些推薦的軟件包。aptitude 和 apt-get 會在安裝你的軟件包的時候自動安裝推薦的軟件包(用戶可以禁用這個默認行爲)。dpkg 則會忽略此項。

- `Suggests`

  此項中的軟件包可以和本程序更好地協同工作，但不是必須的。當用戶安裝程序時，所有的前端程序可能不會詢問是否安裝建議的軟件包。aptitude 可以被配置爲安裝軟件時自動安裝建議的軟件包，但這不是默認。dpkg 和 apt-get 將忽略此項。

- `Pre-Depends`

  此項中的依賴強於 `Depends` 項。套件僅在預依賴的套件已經安裝後纔可以正常安裝並且 正確設定 後纔可以正常安裝。在使用此項時應 非常慎重，僅當在 debian-devel@lists.debian.org 郵件列表討論後才能使用。記住：根本就不要用這項。 :-)

- `Conflicts`

  僅當所有衝突的套件都已經刪除後此套件纔可以安裝。當程式在某些特定套件存在時根本無法運行或存在嚴重問題時使用此項。

- `Breaks`

  此軟件包安裝後列出的軟件包將會受到損壞。通常 `Breaks` 要附帶一個“版本號小於多少”的說明。這樣，軟件包管理工具將會選擇升級被損壞的特定版本的軟件包作爲解決方案。

- `Provides`

  某些型別的軟體包會定義有多個備用的虛擬名稱。你可以在 virtual-package-names-list.txt.gz檔案中找到完整的列表。如果你的程式提供了某個已存在的虛擬軟體包的功能則使用此項。

- `Replaces`

  當你的程式要替換其他套件的某些檔案，或是完整地替換另一個套件(與 `Conflicts` 一起使用)。列出的套件中的某些檔案會被你的套件所覆蓋。

所有的這些項都使用相同的語法。它們是一個套件列表，套件名稱間使用半形逗號分隔。也可以寫出有多個可選的套件名稱，這些套件使用 `|` 符號分隔。

這些項內還可以限定與某些軟件包的某個版本區間之間的關係。版本號限定在括號內，這緊隨軟件包名稱之後，並在以下邏輯符號後寫清具體版本：`<<`、`<=`、`=`、`>=` 和 `>>`，分別代表嚴格小於、小於或等於、嚴格等於、大於或等於以及嚴格大於。例如，

    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}`, 之類。

dh_shlibdeps(1) 會爲二進制包計算共享庫依賴關係。它會爲每個二進制包生成一份 ELF 可執行文件和共享庫列表。 這個列表用於替換 `${shlibs:Depends}`。

dh_perl(1) 會計算 Perl 依賴。它會爲每個二進制包生成一個叫作 `perl` 或 `perlapi` 的依賴列表。這個列表用於替換 `${perl:Depends}`。

一些 `debhelper` 命令可能會使生成的軟件包需要依賴於某些其他的軟件包。所有這些命令將會爲每一個二進制包生成一個列表。這些列表將用於替換 `${misc:Depends}` 。

dh_gencontrol(1) 會爲每個二進制包生成 `DEBIAN/control` 當替換 `${shlibs:Depends}`, `${perl:Depends}`, `${misc:Depends}`, 之類的時候。

說過這些以後，我們可以讓 `Depends` 項保持現狀，並在其下插入一行 `Suggests: file`，因爲 `gentoo` 可以使用 `file` 軟件包提供的某些特性。

第 9 行是主頁的URL。我們假設它是 http://www.obsession.se/gentoo/。

第 12 行是簡述。絕大多數人的屏幕是 80 列寬，所以描述不應超過 60 個字符。在這個例子裏我把它寫爲 `fully GUI-configurable, two-pane X file manager`。

第 13 行是長描述開始的地方。這應當是一段更詳細地描述軟件包的話。每行的第一個格應當留空。描述中不應存在空行，如果必須使用空行，則在行中僅放置一個 `.` (半角句點)來近似。同時，長描述後也不應有超過一行的空白。[34]

接下來我們在第 6 和第 7 行之間添加版本控制系統位置 `Vcs-*` 項。[35] 這裏我們假設 `gentoo` 軟件包的VCS 處於 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 (>=10), xlibs-dev, libgtk1.2-dev, libglib1.2-dev
     6 Standards-Version: 3.9.4
     7 Vcs-Git: https://anonscm.debian.org/git/collab-maint/gentoo.git
     8 Vcs-browser: https://anonscm.debian.org/git/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`

這個文件包含了上游軟件的版權以及許可證信息。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、3-Clause BSD、CC0-1.0、MPL-1.1、MPL-2.0 或 Artistic 許可證，你可以直接將其指向所有 Debian 系統都有的 `/usr/share/common-licenses/` 目錄下的檔案。否則，許可證則必須包含完整的許可證文字。

簡言之，`gentoo` 的 `copyright` 文件如下所示：

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

(注：我爲它添加了行號。)

另外還可以參看 ftpmasters 發送到 debian-devel-announce 的 HOWTO： announce: 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=medium
    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`。除非有特殊原因，緊急程度預設設定為 medium（中等）。

第 3-5 行是一個很長的條目，記錄了你在這個 Debian 修訂版本中做出的修改(非上游修改——上游修改由上游作者建立並由另外一個檔案維護，它們應被安裝為 `/usr/share/doc/gentoo/changelog.gz`)。假設你的 ITP (Intent To Package，計劃打包)的 Bug 號為 `12345`。新行必須插入在上一個以星號 `*` 開頭的行的正下方。你可以使用 dch(1) 完成這個工作，也可以使用普通的文字編輯器手工完成，只要你遵循 dch(1) 所使用的格式。

為了阻止軟體包在打包完成之前被意外上傳，將發行版值改成一個不可用的 `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

(注：我爲它添加了行號。)

如果你已經對自己所作出的改動感到滿意，而且它們都被記錄在了 `changelog` 中，那麼你就可以將發行版值由 `UNRELEASED` 修改至目標發行版值 `unstable` (甚至 `experimental`)。 [36]

你可以在關於更新的 章 8, 更新套件 中瞭解更多關於 `changelog` 的內容。

## 4.4. `rules`

現在我們需要看看 dpkg-buildpackage(1) 用於實際建立軟體包的 rules 檔案。這個檔案事實上是另一個 `Makefile`，但不同於上游原始碼中的那個。和 `debian` 目錄中的其他檔案不同，這個檔案被標記為可執行。

### 4.4.1. `rules` 文件中的 Target

每一個 `rules` 文件， 就像其他的 `Makefile` 一樣，包含着若干 rules，其中每一個都定義了一個 target 以及其具體 操作。 [37] 一個新的 rule 以自己的 target 聲明(置於第一列)來起頭。 後續的行都以 TAB 字符 (ASCII 9) 來開頭，以指示 target 的具體行爲。 空行和以井號 `#` 開頭的行會被當作註釋而被忽略。 [38]

當你想要執行一個 rule 的時候，就將 target（目標）名稱作為命令列引數來呼叫。比如說， `debian/rules `build`` 以及 `fakeroot make -f debian/rules `binary`` 會分別執行 ``build`` 和 ``binary`` 兩個 target。

以下是對各 target 的簡單解釋：

- `clean` target：清理所有編譯的、生成的或編譯樹中無用的文件。(必須)

- `build` target：在編譯樹中將代碼編譯爲程序並生成格式化的文檔。(必須)

- `build-arch` target：在編譯樹中將代碼編譯爲依賴於體繫結構的程序。(必須)

- `build-indep` target：在編譯樹中將代碼編譯爲獨立於平臺的格式化文檔。(必須)

- `install` target：把文件安裝到 `debian` 目錄內爲各個二進制包構建的文件樹。如果有定義，那麼 `binary*` target 則會依賴於此 target。(可選)

- `binary` target：創建所有二進制包(是 `binary-arch` 和 `binary-indep` 的合併)。(必須)[39]

- `binary-arch` target：在父目錄中創建平臺依賴(`Architecture: any`)的二進制包。(必須)[40]

- `binary-indep` target：在父目錄中創建平臺獨立(`Architecture: all`)的二進制包。(必須)[41]

- `get-orig-source` target：從上游站點獲得最新的原始源代碼包。(可選)

可能你現在感到有些迷惑，在接下來講解 dh_make 給出的默認的 `rules` 文件時事情會變得簡單。

### 4.4.2. 默認的 `rules` 檔案

新版本的 dh_make 會生成一個使用 dh 命令的非常簡單但非常強大的默認的 `rules` 檔案：

     1 #!/usr/bin/make -f
     2 # See debhelper(7) (uncomment to enable)
     3 # output every command that modifies files on the build system.
     4 #DH_VERBOSE = 1
     5
     6 # see FEATURE AREAS in dpkg-buildflags(1)
     7 #export DEB_BUILD_MAINT_OPTIONS = hardening=+all
     8
     9 # see ENVIRONMENT in dpkg-buildflags(1)
    10 # package maintainers to append CFLAGS
    11 #export DEB_CFLAGS_MAINT_APPEND  = -Wall -pedantic
    12 # package maintainers to append LDFLAGS
    13 #export DEB_LDFLAGS_MAINT_APPEND = -Wl,--as-needed
    14
    15
    16 %:
    17         dh $@

(注：我添加了行號並刪去了一些註釋。實際的 `rules` 文件裏開頭的空格是 TAB 填充的。)

可能在 shell 或 Perl 腳本中你已經對第一行的形式很熟悉了，它告訴作業系統這個檔案應使用 `/usr/bin/make` 處理。

可以取消第 4 行的註釋，以設置 `DH_VERBOSE` 變量爲 1， 於是 dh 命令就會輸出它將要使用的 dh_* 命令。 你也可以在此添加一行 `export DH_OPTIONS=-v` ， 於是 dh_* 命令 同樣也會輸出它正在調用的命令。 這能幫助你理解在這個簡單的 `rules` 文件背後發生了什麼，以及幫助你進行調試。新的 dh 被設計來作爲 `debhelper` 工具的核心部分，並不向你隱藏任何東西。

第 16 和 17 行使用了 pattern rule，以此隱式地完成所有工作。 其中的百分號意味著“任何 targets”， 它會以 target 名稱作引數呼叫單個程式 dh。 [42] dh 命令是一個包裝指令碼，它會根據引數執行妥當的 dh_* 程式序列。 [43]

- `debian/rules clean` 運行了 `dh clean`，接下來實際執行的命令爲：

      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_strip、dh_makeshlibs 和 dh_shlibdeps 除外，其他命令則均附加`-i` 選項。

dh_* 命令的功能依其名稱不言而喻。 [45] 不過其中有一些值得在這裏進行簡要解釋， 假定有一個基於 `Makefile` 的典型構建環境： [46]

- dh_auto_install 通常在 `Makefile` 存在且有 `distclean` target 時執行以下命令[47]

      make distclean

- dh_auto_configure 在 `./configure` 存在時通常執行以下命令(省略了部分參數以方便此處閱讀)。

      ./configure --prefix=/usr --sysconfdir=/etc --localstatedir=/var ...

- dh_auto_build 通常使用以下命令執行 `Makefile` 中的第一個 target。

      make

- dh_auto_install 通常在 `Makefile` 存在且有 `test` target 時執行以下命令。[48]

      make test

- dh_auto_install 通常在 `Makefile` 存在且有 `install` target 時執行以下命令(進行了換行以便閱讀)。

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

所有需要 fakeroot 命令的都包含了 dh_testroot。如果你沒有使用 fakeroot，那將會報錯並退出。

關於 dh_make 生成的 `rules` 文件，你應該知道的最重要的事是，它僅僅是一個建議。它對多數簡單的軟件包有效，但對於更複雜的則要大膽對其進行定製以滿足需要。

儘管 `install` target 不是必須的，但也被支持。`fakeroot dh install` 的操作就像 `fakeroot dh binary`一樣，但停止於 dh_fixperms。

### 4.4.3. 定製 `rules` 檔案

有很多方法來定製使用新的 dh 命令創建的 `rules` 檔案。

`dh $@` 命令可以按以下方式定製：[49]

- 爲 dh_python2 命令添加支持。(對於 Python 的最佳選擇。)[50]

  - 在 `Build-Depends` 中添加 `python` 軟件包。

  - 使用 `dh $@ --with python2`.

  - 這會使用 `python` 框架處理 Python 模塊。

- 添加 dh_pysupport 命令的支持。(已廢棄)

  - 在 `Build-Depends` 中添加 `python-support` 軟件包。

  - 使用 `dh $@ --with pysupport`

  - 這會使用 `python-support` 框架處理 Python 模塊。

- 添加 dh_pycentral 命令支持。(已廢棄)

  - 在 `Build-Depends` 中添加 `python-central` 軟件包。

  - 使用 `dh $@ --with python-central`

  - 這樣會同時停用 dh_pysupport 命令。

  - 這會使用 `python-central` 框架處理 Python 模塊。

- 添加 dh_installtex 命令支持。

  - 在 `Build-Depends` 中添加 `tex-common` 軟件包。

  - 使用 `dh $@ --with tex`

  - 這樣會註冊 Type 1 字體、斷句樣式及其他 TeX 格式。

- 添加 dh_quilt_patch 和 dh_quilt_unpatch 命令支持。

  - 在 `Build-Depends` 中添加 `quilt` 軟件包。

  - 使用 `dh $@ --with quilt`

  - 這會在你使用 `1.0` 格式的源代碼包時自動應用或解除 `debian/patches` 目錄中的補丁。

  - 如果你使用新的 `3.0 (quilt)` 源代碼包格式則不需要這些。

- 爲 dh_dkms 命令添加支持。

  - 在 `Build-Depends` 中添加 `dkms` 軟件包。

  - 使用 `dh $@ --with dkms`

  - 這能使內核模塊軟件包正確使用 DKMS。

- 添加 dh_autotools-dev_updateconfig 和 dh_autotools-dev_restoreconfig 命令支持。

  - 在 `Build-Depends` 中添加 `autotools-dev` 軟件包。

  - 使用 `dh $@ --with autotools-dev`

  - 這會自動更新或還原 `config.sub` 和 `config.guess` 檔案。

- 添加 dh_autoreconf 和 dh_autoreconf_clean 命令支持。

  - 在 `Build-Depends` 中添加 `dh-autoreconf` 軟件包。

  - 使用 `dh $@ --with autoreconf`

  - 這樣會在編譯時更新 GNU 編譯系統檔案並在編譯後對其進行恢復。

- 添加 dh_girepository 命令支持。

  - 在 `Build-Depends` 中添加 `gobject-introspection` 軟件包。

  - 使用 `dh $@ --with quilt`

  - 這會爲帶有 GObject 內省數據的軟件包計算依賴，並生成 `${gir:Depends}` 這一替換變量。

- 添加 bash 補全特性支持。

  - 在 `Build-Depends` 中添加 `bash-completion` 軟件包。

  - 使用 `dh $@ --with bash-completion`

  - 這會使用 `debian/`package`.bash-completion` 中的配置文件來安裝 bash 補全。

很多由新的 dh 命令觸發的 dh_* 都可以通過修改 `debian` 目錄中的設定檔案來對其行爲進行定製。參考 章 5, `debian` 目錄下的其他檔案 和每個命令的 man 手冊頁。

某些由新的 dh 命令所觸發的 dh_* 命令可能需要額外的參數，或需要附加執行或者跳過執行。對於這類情況，你可以在 `rules` 文件中創建一個 `override_dh_`foo`` target，並在其中定義一個 `override_dh_`foo``來使其完成你想要 dh_`foo` 命令作出的改變。它的作用簡單說就是 run me instead (把運行的命令換成我)。[51]

請注意 dh_auto_* 命令爲了照顧所有的邊緣情況，它實際所做的比上述(過度)簡化的步驟中介紹的內容更多。除了 `override_dh_auto_clean` 外把上面的簡化命令寫成 `override_dh_*` 中是不明智的，這樣會使得 `debhelper` 的許多智能特性無法體現。

所以，比如，最近的`gentoo` 軟件包使用了 Autotools，如果你希望把系統配置配置文件安裝到 `/etc/gentoo` 而非通常的 `/etc` 目錄，你可以凌駕 dh_auto_configure 默認的使用的 `--sysconfig=/etc` 參數，改爲向 ./configure 命令傳遞以下參數：

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

在 `--` 其後給出的引數會被追加到被自動執行的程式預設引數後，以此凌駕它們並修改其預設行為。 使用 dh_auto_configure 命令要比直接呼叫 ./configure 命令好很多，因為 它只修改 `--sysconfig` 引數內容，同時保留其他任何對 ./configure 命令良性的引數。

如果 `gentoo` 的 `Makefile` 需要指定 `build` 作爲其編譯用的 target[52]，你可以創建一個 `override_dh_auto_build` target 來啓用它。

    override_dh_auto_build:
            dh_auto_build -- build

這保證了 `$(MAKE)` 會使用 dh_auto_build 傳遞的所有默認參數並編譯處理 `build` 這個 target。

如果 `gentoo` 的 `Makefile` 需要指定 `packageclean` target 來爲 Debian 軟件包作清理，而非 `distclean` 或 `clean` target，那你就可以創建一個 `override_dh_auto_clean` target 來啓用它。

    override_dh_auto_clean:
            $(MAKE) packageclean

如果 `gentoo` 的 `Makefile` 包含了一個 `test` target 但你不想在 Debian 軟件包構建過程中運行它，可以使用空的 `override_dh_auto_test` target 來跳過它。

    override_dh_auto_test:

如果 `gentoo` 有某個不常見的上游 changelog 檔案名爲 `FIXES`，默認情況下 dh_installchangelogs 不會安裝它。dh_installchangelogs 命令需要將 `FIXES` 作爲它的參數來安裝它。[53]

    override_dh_installchangelogs:
            dh_installchangelogs FIXES

如果你使用新的 dh 命令時，還使用 節 4.4.1, “`rules` 文件中的 Target” 中除 `get-orig-source` 的顯式 target ，會使得其效果難以預料。如果可能的話請儘量避免使用獨立的或預設的 target，如果必須修改默認設置則酌情使用 `override_dh_*`。

[27] 在本章節中， 只要不產生歧義，所有提及的 `debian` 目錄下的文件均會省去 `debian/` 前綴以求簡潔方便。

[28] 參見 Debian Policy Manual, 2.4 "Sections" 以及 List of sections in `sid`.

[29] 參見 Debian Policy Manual, 2.5 "Priorities"。

[30] 參見 Debian Policy Manual, 7.7 "Relationships between source and binary packages - Build-Depends, Build-Depends-Indep, Build-Conflicts, Build-Conflicts-Indep"。

[31] 這種奇怪的情況是 Debian Policy Manual, Footnotes 55 中詳細描述的一種特性。這不是由於在 `debian/rules` 中使用 dh 命令所致的，真正的原因是 dpkg-buildpackage 的運行方式。相同的情形也適用於 Ubuntu 的自動編譯系統。

[32] 確切信息請參見 Debian Policy Manual, 5.6.8 "Architecture"。

[33] 參見 Debian Policy Manual, 7 "Declaring relationships between packages"。

[34] 這些描述都使用英語。相應的翻譯由 The Debian Description Translation Project - DDTP （Debian 描述翻譯項目）項目提供。

[35] 參見 Debian Developer's Reference, 6.2.5. "Version Control System location"。

[36] 如果你用 `dch -r` 命令來使它成爲最後一筆更改， 請確保用編輯器顯式地保存 `changelog` 文件。

[37] 你可以透過該資源來學習編寫 `Makefile` ：Debian Reference, 12.2. "Make"。 完整文件在 http://www.gnu.org/software/make/manual/html_node/index.html 或者 `make-doc` 軟體包 (該包位於 `non-free` 部分）。

[38] Debian Policy Manual, 4.9 "Main building script: debian/rules" 針對細節進行瞭解釋。

[39] 此 target 被 `dpkg-buildpackage` 用於 節 6.1, “完整的(重)構建” 描述的過程中。

[40] 此 target 被 `dpkg-buildpackage -B` 用於節 6.2, “自動編譯系統” 描述的過程中。

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

[42] 此處使用了新版本 `debhelper` v7+ 的特性。 它的設計理念在 Not Your Grandpa's Debhelper 中進行了闡明，這在 DebConf9 中被 `debhelper` 上游進行了演示。 在 `lenny` 下， dh_make 會建立一個更為複雜 的 `rules` 檔案，伴有許多顯式的 rule 和許多為每個 rule 所用的dh_* 指令碼，其中有大部分在現在已經是不必要的了(這也顯示了軟體包的年齡)。 新一代的 dh 命令更為簡潔，並能將我們從"手工的重複工作"中解放出來。當然，你仍然擁有完全的力量來定製整個過程，只要使用 `override_dh_*` target。參見 節 4.4.3, “定製 `rules` 檔案”。 它僅僅基建於 `debhelper` 軟體包，而且不會像 `cdbs` 軟體包所傾向的那樣混淆軟體包構建過程。

[43] 你可以檢驗每一個已有的 ``target`` 所呼叫的實際 dh_* 程式序列，而並不需要真的透過 `dh `target` --no-act` 或 `debian/rules -- '`target` --no-act'` 來執行以檢視。

[44] 下邊的例子假定你的 `debian/compat` 有一個 值大於或等於 9 ，以此避免自動調用任何 python 支持命令。

[45] 關於所有 dh_* 腳本具體行爲， 以及 它們有什麼選項 的完整信息，請閱讀它們各自的 man 手冊頁 以及 `debhelper` 的文檔。

[46] 這些構建系統同樣支援其他的構建環境，比如 `setup.py` ，這可以透過在軟體包原始碼目錄中執行 `dh_auto_build --list` 來列出。

[47] 它實際上在 `Makefile` 中搜尋第一個可用的 target ，除了 `distclean`, `realclean`, 或 `clean`， 接下來再執行它。

[48] 實際上它在 `Makefile` 中搜索第一個可用的 target，除了 `test` 或 `check`，然後執行它。

[49] 如果一個軟件包安裝了 `/usr/share/perl5/Debian/Debhelper/Sequence/`custom_name`.pm` 文件，你應當使用 `dh $@ --with `custom-name`` 命令激活其功能。

[50] 在 dh_python2 和 dh_pysupport 以及dh_pycentral 命令之間更推薦使用前者。不要使用 dh_python 命令。

[51] 在 `lenny` 下，如果你希望更改某個 dh_* 腳本的行爲，你需要在 `rules` 中找到相應的行然後進行調整。

[52] 沒有參數的 dh_auto_build命令將執行 `Makefile` 中的第一個 target。

[53] `debian/changelog` 和 `debian/NEWS` 總是會被自動安裝。程序會將文件名轉爲小寫並搜索以下文件名來檢測上游 changelog：`changelog`、`changes`、`changelog.txt`和`changes.txt`。

章 3. 修改原始碼 |  | 章 5. `debian` 目錄下的其他檔案