[ 上一頁 ] [ 目錄 ] [ 1 ] [ 2 ] [ 3 ] [ 4 ] [ 5 ] [ 6 ] [ 7 ] [ 8 ] [ 9 ] [ 下一頁 ]


Debian 新維護人員手冊
第 5 章 - debian 目錄下的其他檔案


要控制 debhelper 在構建套件過程中的行爲,可以在 debian 目錄中放置可選的設定檔案。本章將會對這些檔案和它們的格式進行概述。請閱讀 Debian Policy ManualDebian Developer's Reference 來了解更多內容。

dh_make 命令會在 debian 目錄中創建一些設定檔案模板,它們的檔案名多帶有 .ex 的後綴。其中的一些可能以套件名作爲前綴,如 package。現在對它們進行一個大致的瞭解。

還有一些 debhelper 的設定檔案模板 dh_make 命令沒有直接創建。在這種情況下如果你需要它們,則要使用文本編輯器手工創建。

如果你希望或需要激活它們中的任意一個或多個,請按照下面的方法做。

不帶有二進位套件名(例如 package)前綴的 debhelper 設定檔案則默認用於 control 檔案中列出的第一個二進位套件,如默認情況下的 install 檔案。如果需要爲其他二進位套件使用設定,則應在設定檔案名前加上二進位套件名,如 package-1.installpackage-2.install 等。


5.1 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)


5.2 compat 檔案

compat 檔案定義了 debhelper 的兼容級別。目前你應當使用以下命令將其設置爲 debhelper V7。

     $ echo 7 > debian/compat

5.3 conffiles 檔案

系統管理中有件很惱人的事,就是當你付出了很多時間和經歷來自定義一個程式,但是升級後所有的修改都被覆蓋掉了。Debian 通過將設定檔案單獨標記來解決這個問題,當套件升級的時候,你將會被詢問是否要保留你的舊設定檔案。

debhelper V3 開始,dh_installdeb(1)自動 識別所有在 /etc 目錄下的檔案爲設定檔案。所以如果你的程式只有在那裏的設定檔案,則不需再指定它們。

如果你的程式使用設定檔案,但程式會自動對設定進行改寫,則最好也將其標記爲設定檔案,這樣 dpkg 總是會要求用戶校驗發生了的變更。

如果你正在打包的程式需要所有用戶都爲自己修改 /etc 目錄中的設定,有兩種常見的方法讓 dpkg 不將其記錄爲設定檔案。

更多關於 maintainer scripts 的訊息,參考 {post|pre}{inst|rm} 檔案, 第 5.18 節


5.4 package.cron.* 檔案

如果你的套件需要有計劃運行的操作以保證正常工作,可以使用這個檔案進行設置。既可以設置常規的任務使其在每小時、每天、每星期、每月或其他情況或時間下運行。相應的檔案名是:

對於前幾個檔案,其格式爲 shell 腳本。唯一不同的是 package.cron.d,它的格式需要參照 crontab(5)

注意這裏的操作不包含日誌旋轉,如果需要日誌旋轉,參考 dh_installlogrotate(1)logrotate(8)


5.5 dirs 檔案

這個檔案指定了我們需要,但正常安裝過程(dh_auto_install 觸發 make install DESTDIR=...)裏沒有被安裝的目錄。通常這是由於 Makefile 中存在問題。

install 檔案中列出的檔案不需要提前創建目錄,參考 install 檔案, 第 5.11 節

最好是先嚐試安裝,如果遇到了相關的問題再使用這個檔案。目錄名中不應有前導的 / 符號。


5.6 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 節


5.7 docs 檔案

這個檔案制定了我們使用 dh_installdocs(1) 安裝到臨時目錄的檔案名。

默認情況下它會加入程式碼目錄頂層的所有名爲 BUGSREADME*TODO 等的檔案。

對於 gentoo,我還加入了一些其他檔案:

     BUGS
     CONFIG-CHANGES
     CREDITS
     NEWS
     README
     README.gtkrc
     TODO

5.8 emacsen-* 檔案

如果你的套件提供可以在安裝時編譯爲字節碼的 Emacs 檔案,你可以使用這些檔案設置。

它們會被 dh_installemacsen(1) 安裝到臨時目錄。

如果你不需要這些,就刪除它們。


5.9 package.examples 檔案

dh_installexamples(1) 會將列出的檔案和目錄作爲範例檔案安裝。


5.10 package.initpackage.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

如果你不需要這些,就刪除它們。


5.11 install 檔案

如果你的套件需要標準的 make install 沒有安裝的檔案,可以把檔案名和目標路徑寫入 install 檔案,它們將被 dh_install(1) 安裝。[34] 你需要首先檢査要安裝的檔案是否有更有針對性的特定工具會對其進行安裝,例如範例、文件應寫在 docs 檔案中安裝。

這個 install 檔案每行安裝一份檔案,格式上先是相對於編譯目錄的源目錄,然後是一個空格,接下來是相對於安裝目錄的目標目錄。假設某個二進位檔案沒有被默認安裝,則應在 install 檔案添加如下內容:

     src/foo/mybin usr/bin

這意味着安裝這個套件時將有一個二進位檔案 /usr/bin/mybin

當然 install 檔案也可以只包含相對的源路徑而不帶目標位置。這樣的格式通常用於使用 package-1.installpackage-2.install 等將大套件分割爲多個二進位套件的情況。

如果 dh_install 命令沒有在當前目錄(或者你可能使用 --sourcedir 參數指定的位置)找到檔案,它會回滾至使用 debian/tmp 目錄。


5.12 package.info 檔案

如果你的套件有 info 訊息頁,應該使用 dh_installinfo(1) 安裝,要安裝的檔案列於 package.info 檔案中。


5.13 {package.|source/}lintian-overrides 檔案

如果 lintian 報告了一個 Debian Policy 允許的例外的錯誤診斷,你可以使用 package.lintian-overridessource/lintian-overrides 使其不再警告。請閱讀 /usr/share/doc/lintian/lintian.html/index.html 並應嚴格避免濫用。

package.lintian-overrides 是對於名爲 package 有效的設定,會由 dh_lintian 命令安裝到usr/share/lintian/overrides/package

source/lintian-overrides 是針對原始碼套件的,不會安裝。


5.14 manpage.* 檔案

你的程式應該有 man 手冊頁,如果它們沒有自帶則需要由你來創建。dh_make 命令創建了幾個 man 手冊頁的模板。它們需要被妥善地編輯,並且要刪除未使用的模板。


5.14.1 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]


5.14.2 manpage.sgml.ex 檔案

如果你希望使用 SGML 而非 nroff 格式編寫 man 手冊頁,可以使用 manpage.sgml.ex 模板。如果你要這樣,需要進行以下步驟:


5.14.3 manpage.xml.ex 檔案

如果你希望使用XML 而非 SGML,可以使用 manpage.xml.ex 模板。如果你要這樣,需要進行以下步驟:


5.15 package.manpages 檔案

如果你的套件有 man 手冊頁,你應該將它們列在 package.manpages 檔案中以便 dh_installman(1) 安裝。

要將 doc/gentoo.1 安裝爲 gentoo 的 man 手冊頁,創建一個 gentoo.manpages,內容如下:

     docs/gentoo.1

5.16 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,它指定了程式需要何種界面。修改此處爲列出的選項之一,例如 textX11

接下來是 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"

你還可以添加諸如 longtitleiconhints 等欄位。參考 dh_installmenu(1)menufile(5)update-menus(1)/usr/share/doc/debian-policy/menu-policy.html/ 瞭解更多訊息。


5.17 NEWS 檔案

dh_installchangelogs(1) 命令會安裝這個檔案。


5.18 {post|pre}{inst|rm} 檔案

postinstpreinstpostrmprerm 檔案 [37] 被稱爲 maintainer scripts。它們是放置於套件控制訊息區域,並由 dpkg 在套件安裝、升級或反安裝時執行的腳本。

作爲一個新維護人員,你應當避免手工編輯 maintainer scripts,因爲它們常存在各種問題。更多訊息請閱讀 Debian Policy Manual, 6 'Package maintainer scripts and installation procedure' 並査看 dh_make 給出的範例。

如果你不聽我的勸告,自己爲一個套件創建了 maintainer scripts,你必須保證不僅測試 installupgrade,還應測試 removepurge

升級到新版本應當是靜默的(已有用戶應當只在發現舊的 Bug 被修復或有新特性時注意到升級的變化)。

當更新必須以非靜默模式進行時(例如多個主目錄中的設定檔案都要改爲完全不同的結構時),你應該考慮將套件設置到安全的默認設定(例如禁用服務)並按照 Debian Policy 提供相應的文件(README.DebianNEWS.Debian)。不要在升級時使用 maintainer scripts 觸發 debconf 來打擾用戶。

ucf 套件提供了 類似 conffile 的對不應標記爲 conffiles 的檔案的保留機制。這可以將與 maintainer scripts 相關的問題減少到最低。

這些 maintainer scripts 是 Debian 對於軟體系統的增強特性,它們解釋了 人們爲什麼選擇 Debian。你必須非常小心,保證人們不因此產生煩惱。


5.19 TODO 檔案

dh_installdocs(1) 命令會安裝這個檔案。


5.20 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 變更導致的問題。


5.21 source/format 檔案

debian/source/format 中只包含一行,寫明瞭此原始碼套件的格式(査看 dpkg-source(1) 獲得完整列表)。在 squeeze 後,它應該是以下二者之一:

全新的 3.0 (quilt) 原始碼格式將所有修改使用 quilt 補丁系列記錄到 debian/patches。這些修改會在解壓原始碼套件時自動應用。[38] Debian 修改保存於 debian.tar.gz 壓縮檔,其中包含了整個 debian 目錄。這個新格式支持直接添加例如 PNG 圖示等的二進位檔案。[39]

dpkg-source 解壓 3.0 (quilt) 格式的源碼包時會自動應用所有列於 debian/patches/series 的補丁。你可以使用 --skip-patches 選項避免在解壓後自動應用補丁。


5.22 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))。


5.23 patches/* 檔案

舊的 1.0 原始碼套件格式使用單一的大 diff.gz 檔案保存 debian 檔案夾和補丁。這樣的套件比較難於在事後檢査和分析。這不是很好。

新的 3.0 (quilt) 原始碼套件格式使用 quilt 管理 debian/patches/* 檔案。這些補丁和其他 debian 目錄下的檔案被歸檔爲 debian.tar.gz 檔案。因爲 dpkg-source 不調用 quilt 就可以處理 3.0 (quilt) 源碼包格式的補丁,故不需要 Build-Dependsquilt 套件。[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 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