[ 上一頁 ] [ 目錄 ] [ 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
繁簡轉換:陳侃如 koster@debian.org
繁簡轉換:青木修 osamu@debian.org