章 5. 基本內容

內容目錄

5.1. 打包工作流
5.1.1. debhelper 套件
5.2. 套件名稱和版本
5.3. 原生 Debian 套件
5.4. debian/rules
5.4.1. dh
5.4.2. 簡單的 debian/rules
5.4.3. 設定 debian/rules
5.4.4. debian/rules 中的變數
5.4.5. 可重現的構建
5.5. debian/control
5.5.1. Debian 二進位制套件的拆分
5.5.1.1. debmake -b
5.5.1.2. 拆包的場景和例子
5.5.1.3. 程式庫套件名稱
5.5.2. Substvar
5.5.3. binNMU 安全
5.6. debian/changelog
5.7. debian/copyright
5.8. debian/patches/*
5.8.1. dpkg-source -x
5.8.2. dquilt 和 dpkg-source
5.9. debian/upstream/signing-key.asc
5.10. debian/watch 和 DFSG
5.11. 其它 debian/* 檔案
5.12. Debian 打包的定製化
5.13. 在版本控制系統中進行記錄(標準)
5.14. 在版本控制系統中進行記錄(備選方案)
5.15. 構建套件時排除不必要的內容
5.15.1. 使用 debian/rules clean 進行修復
5.15.2. 使用版本控制系統修復
5.15.3. 使用 extend-diff-ignore 修復
5.15.4. 使用 tar-ignore 修復
5.16. 上游構建系統
5.16.1. Autotools
5.16.2. CMake
5.16.3. Python distutils
5.17. 除錯資訊
5.17.1. 新的 -dbgsym 套件(Stretch 9.0 或更新)
5.18. 程式庫套件
5.18.1. 程式庫符號
5.18.2. 程式庫變遷
5.19. debconf
5.20. 多體系架構
5.20.1. 多架構程式庫路徑
5.20.2. 多架構標頭檔案路徑
5.20.3. 多架構支援下的 *.pc 檔案路徑
5.21. 編譯強化
5.22. 持續整合
5.23. 自主生成 (Bootstrapping)
5.24. 錯誤報告

這裡展示了 Debian 打包工作中針對非原生套件使用“3.0 (quilt)”格式進行打包所遵循基本規則的一個全域性性概覽。

[注意] 注意

為簡明起見,某些細節被有意跳過。請按需查閱對應命令的手冊頁,例如dpkg-source(1)、dpkg-buildpackage(1)、dpkg(1)、dpkg-deb(1)、deb(5),等等。

Debian 原始碼套件是一組用於構建 Debian 二進位制套件的輸入檔案,而非單個檔案。

Debian 二進位制套件是一個特殊的檔案檔案,其中包含了一系列可安裝的二進位制資料及與它們相關的資訊。

單個 Debian 原始碼套件可能根據 debian/control 檔案定義的內容產生多個 Debian 二進位制套件。

使用 “3.0 (quilt)”格式的非原生 Debian 套件是最普通的 Debian 原始碼套件格式。

[注意] 注意

有許多封裝指令碼可用。合理使用它們可以幫助您理順工作流程,但是請確保您能理解它們內部的基本工作原理。

建立 Debian 二進位制套件的 Debian 打包工作流涉及建立數個特定名稱的檔案(參見 節 5.2, “套件名稱和版本”),與《Debian 政策手冊》的定義保持一致。

The oversimplified method for the Debian packaging workflow can be summarized in 10 steps as follows.

  1. 下載上游原始碼壓縮包(tarball)並命名為 package-version.tar.gz 檔案。
  2. 使上游提供的原始碼壓縮包解壓縮後的所有檔案儲存在 package-version/ 目錄中。
  3. 上游的原始碼壓縮包被複制(或符號連結)至一個特定的檔名 packagename_version.orig.tar.gz

    • 分隔 packageversion 的符號從 -(連字元)更改為 _(下劃線)
    • 副檔名添加了 .orig 部分。
  4. Debian 套件規範檔案將被新增至上游原始碼中,存放在 package-version/debian/ 目錄下。

    • debian/* 目錄下的必需技術說明檔案:

      debian/rules
      構建 Debian 套件所需的可執行指令碼(參見 節 5.4, “debian/rules”
      debian/control
      套件配置檔案包含了原始碼套件名稱、原始碼構建依賴、二進位制套件名稱、二進位制套件依賴,等等。(參見 節 5.5, “debian/control”
      debian/changelog
      Debian 套件歷史檔案,其中第一行定義了上游套件版本號和 Debian 修訂版本號(參見 節 5.6, “debian/changelog”
      debian/copyright
      版權和許可證摘要資訊(參看 節 5.7, “debian/copyright”
    • debian/* 下的可選配置檔案(參見 節 5.11, “其它 debian/* 檔案”):
    • package-version/ 目錄中呼叫 debmake 命令將會提供這些配置檔案的一套模板。

      • 必備的配置檔案總會生成,無論是否提供 -x0 選項。
      • debmake 命令永遠不會覆寫任何已經存在的配置檔案。
    • 這些檔案必須手工編輯以達到理想狀態。請使用《Debian 政策手冊》和《Debian 開發者參考》作為編輯依據。
  5. dpkg-buildpackage 命令(通常由它的封裝命令 debuildpdebuild 所使用)會在 package-version/ 目錄中被呼叫,進而以呼叫 debian/rules 指令碼的方式製作 Debian 原始碼套件和二進位制套件。

    • 當前工作目錄會被設為:$(CURDIR)=/path/to/package-version/
    • 使用 dpkg-source(1) 以“3.0 (quilt)”格式建立 Debian 原始碼套件

      • package_version.orig.tar.gzpackage-version.tar.gz 的副本或符號連結)
      • package_version-revision.debian.tar.xzpackage-version/debian/* 的 tar 壓縮包,即 tarball)
      • package_version-revision.dsc
    • 使用“debian/rules build”構建原始碼並安裝到 $(DESTDIR)

      • DESTDIR=debian/binarypackage/(單二進位制包)
      • DESTDIR=debian/tmp/(多個二進位制包)
    • 使用 dpkg-deb(1)、dpkg-genbuildinfo(1) 和 dpkg-genchanges(1) 建立 Debian 二進位制套件。

      • binarypackage_version-revision_arch.deb
      • ……(可能有多個 Debian 二進位制包檔案。)
      • package_version-revision_arch.changes
      • package_version-revision_arch.buildinfo
  6. 使用 lintian 命令檢查 Debian 套件的質量。(推薦)

  7. Test the goodness of the generated Debian binary package manually by installing it and running its programs.
  8. After confirming the goodness, prepare files for normal source-only uploads to the Debian archive.

    • Remove the source tree under /path/to/package-version/ which may contain artifacts from the build process.
    • Regenerate the clean source tree using “dpkg-source -x package_version-revision.dsc”.
    • Remove package_version-revision.debian.tar.xz.
    • Generate following files using “dpkg-buildpackage -S -d” in the clean source tree.

      • package_version-revision.debian.tar.xz
      • 'package_version-revision’_*source.changes*
      • 'package_version-revision’_*source.buildinfo*
  9. Sign the package_version-revision.dsc and 'package_version-revision’_*source.changes* files with the debsign command using your private GPG key.
  10. Upload the set of the Debian source package files with the dput command to the Debian archive.

Under some exceptional situation such as NEW uploads, uploads to the Debian archive may need to include Debian binary package files. For such situation, skip the step 8, sign package_version-revision_arch.changes instead of 'package_version-revision’_*source.changes* in the step 9, and upload the set of the Debian source and binary package files in the step 10.

這裡,請將檔名中對應的部分使用下面的方式進行替換:

  • package 部分替換為 Debian 原始碼套件名稱
  • binarypackage 部分替換為 Debian 二進位制套件名稱
  • version 部分替換為上游版本號
  • revision 部分替換為 Debian 修訂號
  • arch 部分替換為套件對應架構

See also Source-only uploads.

[提示] 提示

有很多種通過實踐摸索而得到的補丁管理方法和版本控制系統的使用策略與技巧。您沒有必要將它們全部用上。

[提示] 提示

在“Debian 開發者參考”一文的 第 6 章 最佳打包實踐 部分有十分詳盡的相關文件。請讀一讀這些內容。

如果所取得上游原始碼的形式為 hello-0.9.12.tar.gz,您可以將 hello 作為上游原始碼名稱,並將 0.9.12 作為上游版本號。

debmake 的目的是為套件維護者提供開始工作的模板檔案。註釋行以 # 開始,其中包含一些教材文字。您在將套件上傳至 Debian 倉庫之前必須刪除或者修改這樣的註釋行。

許可證資訊的提取和賦值過程應用了大量啟發式操作,因此在某些情況下可能不會正常工作。強烈建議您搭配使用其它工具,例如來自 devscripts 套件的 licensecheck 工具,以配合 debmake 的使用。

組成 Debian 套件名稱的字元選取存在一定的限制。最明顯的限制應當是套件名稱中禁止出現大寫字母。這裡給出正則表示式形式的規則總結:

  • 上游套件名稱(-p):[-+.a-z0-9]{2,}
  • 二進位制套件名稱(-b):[-+.a-z0-9]{2,}
  • 上游版本號(-u):[0-9][-+.:~a-z0-9A-Z]*
  • Debian 修訂版本(-r): [0-9][+.~a-z0-9A-Z]*

請在《Debian 政策手冊》的 第 5 章 - Control 檔案及其欄位 一節中檢視其精確定義。

debmake 所假設的打包情景是相對簡單的。因此,所有與直譯器相關的程式都會預設為“Architecture: all”的情況。當然,這個假設並非總是成立。

您必須為 Debian 打包工作適當地調整套件名稱和上游版本號。

為了能有效地使用一些流行的工具(如 aptitude)管理套件名稱和版本資訊,最好能將套件名稱保持在 30 字元以下;版本號和修訂號加起來最好能不超過 14 個字元。[10]

為了避免命名衝突,對使用者可見的二進位制套件名稱不應選擇任何常用的單詞。

如果上游沒有使用像 2.30.32 這樣正常的版本編號方案,而是使用了諸如 11Apr29 這樣包含日期、某些代號或者一個版本控制系統雜湊值等字串作為版本號的一部分的話,請在上游版本號中將這些部分移除。這些資訊可以稍後在 debian/changelog 檔案中進行記錄。如果您需要為軟體設計一個版本字符串,可以使用 YYYYMMDD 格式,如 20110429 的字串作為上游版本號。這樣能保證 dpkg 命令在升級時能正確地確定版本的先後關係。如果您想要確保萬一上游在未來重新採納正常版本編號方案,例如 0.1 時能夠做到順暢地遷移,可以另行使用 0~YYMMDD 的格式,如 0~110429 作為上游版本號。

版本字串可以按如下的方式使用 dpkg 命令進行比較。

$ dpkg --compare-versions ver1 op ver2

版本比較的規則可以歸納如下:

  • 字串按照起始到末尾的順序進行比較。
  • 字元比數字大。
  • 數字按照整數順序進行比較。
  • 字元按照 ASCII 編碼的順序進行比較。

對於某些字元,如句點(.)、加號(+)和波浪號(~),有如下的特殊規則。

0.0 < 0.5 < 0.10 < 0.99 < 1 < 1.0~rc1 < 1.0 < 1.0+b1 < 1.0+nmu1 < 1.1 < 2.0

有一個稍需注意的情況,即當上游將 hello-0.9.12-ReleaseCandidate-99.tar.gz 這樣的版本當作預釋出版本,而將 hello-0.9.12.tar.gz 作為正式版本時。為了確保 Debian 套件升級能夠順暢進行,您應當修改版本號命名,如將上游原始碼壓縮包重新命名為 hello-0.9.12~rc99.tar.gz

使用“3.0 (quilt)”格式的非原生 Debian 套件是最常見最標準的 Debian 原始碼套件格式。根據 dpkg-source(1) 的描述,此時的 debian/source/format 檔案應當包含“3.0 (quilt) 的文字內容。上述的工作流和接下來給出的打包範例都使用了這種格式。

而原生 Debian 套件是較罕見的一種 Debian 套件格式。它通常只用於打包僅對 Debian 專案有價值、有意義的軟體。因此,該格式的使用通常不被提倡。

[注意] 注意

在上游 tarball 原始碼壓縮包無法使用其正確名稱 package_version.orig.tar.gzdpkg-buildpackage 取得到的時候,會出現意外地構建了原生 Debian 套件的情況。這是新手常見的一個錯誤,通常是因構建中錯誤地在符號連結名稱中使用了“-”字元而非正確的“_”字元。[譯註:此處仍然假設打包的場景是已經取得或形成了名為 package-version.tar.gz 的上游原始碼 tarball。Debian 的打包工作很大程度上是以上游原始碼 tarball 作為基礎的,這一點須時刻牢記在心。]

原生 Debian 套件不對 上游程式碼Debian 的修改 進行區分,僅包含以下內容:

  • package_version.tar.gzpackage-version.tar.gz 檔案的副本或符號連結,包含 debian/* 的各個檔案。)
  • package_version.dsc

如果您需要手動建立原生 Debian 套件,可以使用 dpkg-source(1) 工具以“3.0 (native)”格式進行建立。

[提示] 提示

某些人希望推行對那些即使是僅針對 Debian 編寫的那些軟體也使用非原生套件格式的做法。這種做法所需要的不包含 debian/* 檔案的 tarball 壓縮包事先需要手動生成以符合在 節 5.1, “打包工作流” 中的標準工作流。他們認為使用非原生套件格式可以方便與下游發行版之間的溝通與交流。

[提示] 提示

如果使用原生套件格式,沒有必要事先建立 tarball 壓縮包。要建立一個原生 Debian 套件,應當將 debian/source/format 檔案的內容設定為“3.0 (native)”,適當編寫 debian/changelog 文件使得版本號中不包含 Debian 修訂號(例如,1.0 而非 1.0-1),最後在原始碼樹中調用“dpkg-source -b .”命令。這樣做便可以自動生成包含原始碼的 tarball。

debian/rules 指令碼是用於實際構建 Debian 套件的可執行指令碼。

  • debian/rules 指令碼重新封裝了上游的構建系統(參見 節 5.16, “上游構建系統”)以達到將檔案安裝至 $(DESTDIR)並將生成的檔案存入各個 deb 格式檔案中的目的。

    • 這裡的 deb 檔案用於二進位制的檔案分發,並將被 dpkg 命令所使用以將軟體安裝至系統中。
  • dh 命令通常在 debian/rules 指令碼中使用,用作構建系統的一個前端。
  • $(DESTDIR) 路徑具體值依賴於構建的型別。

    • $(DESTDIR)=debian/binarypackage(單個二進位制套件)
    • $(DESTDIR)=debian/tmp(多個二進位制套件)

受益於 dh 命令對構建目標的抽象化 [11],一個符合 Debian 政策而支援所有必需目標(target)的 debian/rules 檔案可以簡單地寫成如下形式[12]

簡單的 debian/rules:. 

#!/usr/bin/make -f
#export DH_VERBOSE = 1

%:
        dh $@

從本質上來看,這裡的 dh 命令的作用是作為一個序列化工具,在合適的時候呼叫所有所需的 dh_* 命令。

[提示] 提示

設定“export DH_VERBOSE = 1”會輸出構建系統中每一條會修改檔案內容的命令。它同時會在某些構建系統中啟用詳細輸出構建日誌的選項。

通過新增合適的 override_dh_* 目標(target)並編寫對應的規則,可以實現對 debian/rules 指令碼的靈活定製。

如果需要在 dh 命令呼叫某些特定的 dh_foo 命令時採取某些特別的操作,則任何自動執行的操作均可以被 debian/rules 中額外新增的 override_dh_foo 這樣的 Makefile 目標所覆寫。

構建的過程可以使用某些上游提供的介面進行定製化,如使用傳遞給標準的原始碼構建系統的引數。這些構建系統包括但不限於:

  • configure
  • Makefile
  • setup.py,或
  • Build.PL

在這種情況下,您應該新增一個 override_dh_auto_build 目標並在其中執行“dh_auto_build -- 設定引數” 的命令。這樣可以在 dh_auto_build 預設傳遞的引數之後確保將使用者給出的 設定引數 繼續傳遞給那些構建系統。

[提示] 提示

如果上文提到的構建系統命令已知得到了 dh_auto_build 命令的支援的話,請避免直接呼叫這些命令(而讓 dh_auto_build 自動處理)。

debmake 命令所建立的初始模版檔案除了應用了上文提到的簡單 debian/rules 檔案的優點外,同時為後續可能涉及的套件強化等情景添加了一些額外的定製選項。您需要先了解整個構建系統背後的工作原理(參見 節 5.16, “上游構建系統”),之後才能收放自如地定製套件來處理某些非常規的工作情況。

某些對設定 debian/rules 有用的變數定義可以在 /usr/share/dpkg/ 目錄下的檔案中找到。比較重要的包括:

pkg-info.mk
DEB_SOURCEDEB_VERSIONDEB_VERSION_EPOCH_UPSTREAMDEB_VERSION_UPSTREAM_REVISIONDEB_VERSION_UPSTREAMDEB_DISTRIBUTION 變數。它們在向後移植(backport)支援等場景下能起到一定的作用。
vendor.mk
DEB_VENDORDEB_PARENT_VENDOR 變數,以及 dpkg_vendor_derives_from 巨集。它們在系統提供方的支援方面(Debian、Ubuntu 等)有其特定用處。
architecture.mk
設定 DEB_HOST_* 和 DEB_BUILD_* 變數。除此之外存在一種替代方案,即直接呼叫 dpkg-architecture 來取得變數,一次呼叫查詢得到一個變數值。如顯性呼叫 dpkg-architecture 以取得必需變數的話,便不再需要在 debian/rules 中包含 architecture.mk 了(後者會引入全部架構相關的變數)。
buildflags.mk
設定 CFLAGSCPPFLAGSCXXFLAGSOBJCFLAGSOBJCXXFLAGSGCJFLAGSFFLAGSFCFLAGSLDFLAGS 這些構建標誌(build flags)。

如果您希望在 debian/rules 中使用其中的某些變數,您可以將相關的程式碼複製到 debian/rules 檔案中,或是重寫一份簡單的替代實現。總而言之請保持 debian/rules 檔案儘量簡單。

例如,您按如下的方法在 debian/rules 檔案中新增內容,從而為 linux-any 目標架構添加額外的 CONFIGURE_FLAGS

DEB_HOST_ARCH_OS ?= $(shell dpkg-architecture -qDEB_HOST_ARCH_OS)
 ...
ifeq ($(DEB_HOST_ARCH_OS),linux)
CONFIGURE_FLAGS += --enable-wayland
endif
[提示] 提示

歷史上對於 debhelper 相容等級小於等於 8 的情況下,在 debian/rules 檔案中包含 buildflags.mk 檔案是很有用的,它可以合適地設定一些構建標誌,如 CPPFLAGSCFLAGSLDFLAGS 等,同時保證對特定選項,如 DEB_CFLAGS_MAINT_APPENDDEB_BUILD_MAINT_OPTIONS 的合適處理。現在您應當使用的 debhelper 相容等級大於等於 9,故如無特殊原因,請不要繼續包含 buildflags.mk,請交由 dh 命令來處理和設定這些構建標誌。

參見 節 5.20, “多體系架構”dpkg-architecture(1) 和 dpkg-buildflags(1)。

為了做到套件可重現的構建,這裡給出一些相關的建議。

dpkg-genbuildinfo(1) 生成的控制檔案 source-name_source-version_arch.buildinfo 記錄了構建環境資訊。參見 deb-buildinfo(5)

debian/control 檔案包含了由空行分隔的數塊參數資料。每塊元資料按照如下的順序定義了下面這些內容:

  • Debian 原始碼套件的參數資料
  • Debian 二進位制套件的參數

參見《Debian 政策手冊》中的 第 5 章 - Control 檔案及其欄位 一章以瞭解每塊參數的具體定義。

[注意] 注意

The debmake command sets the debian/control file with “Build-Depends: debhelper-compat (= 13)” to set the debhelper compatibility level.

對行為良好的構建系統來說,對 Debian 二進位制包的拆分可以由如下方式實現。

  • 為所有二進位制套件在 debian/control 檔案中建立對應的二進位制套件條目。
  • 在對應的 debian/二進位制套件名.install 檔案中列出所有檔案的路徑(相對於 debian/tmp 目錄)。

請檢視本指南中相關的例子:

debmake 命令的 -b 選項提供了一個符合直覺又靈活的功能,可以用來建立 debian/control 的初始模板檔案,其中可以定義多個 Debian 二進位制套件,每節中含有如下欄位:

  • Package:
  • Architecture:
  • Multi-Arch:
  • Depends:
  • Pre-Depends:

debmake 命令也會在每個適當的依賴欄位中設置合適的變數替換佔位符(substvars)。

我們在這裡直接引用 debmake 手冊頁中的相關一部分內容。

-b "二進位制套件名[:type],…", --binaryspec "二進位制套件名[:type],…"

設定二進位制套件的指定型別內容,使用一個用逗號分隔的二進位制套件名:型別成對列表;例如,使用完整形式“foo:bin,foo-doc:doc,libfoo1:lib,libfoo-dev:dev”或者使用短形式,“-doc,libfoo1,libfoo-dev”。

這裡,二進位制套件是二進位制套件名稱,可選的類型應當從下面的型別值中進行選取:

  • bin:C/C++ 預編譯 ELF 二進位制程式碼套件(any,foreign)(預設,別名:"",即,空字串
  • data:資料(字型、影象、……)套件(all,foreign)(別名:da
  • dev:程式庫開發套件(any,same)(別名:de
  • doc:文件套件(all,foreign)(別名:do
  • lib:程式庫套件(any,same)(別名:l
  • perl:Perl 指令碼套件(all,foreign)(別名:pl
  • python3: Python (version 3) script package (all, foreign) (alias: py3)
  • ruby:Ruby 指令碼套件(all,foreign)(別名:rb
  • nodejs: Node.js based JavaScript package (all, foreign) (alias: js)
  • script:Shell 指令碼套件(all,foreign)(別名:sh

括號內成對的值,例如(any,foreign),是套件的架構多架構(Multi-Arch)特性的值,它們將設定在 debian/control 檔案中。

大多數情況下,debmake 命令可以有效地從二進位制套件的名稱猜測出正確的型別。如果型別的值並不明顯,程式將回退到將型別設定為bin。例如,libfoo 設定型別lib,而 font-bar 會令程式設定型別data,……

如果原始碼樹的內容和型別的設定不一致,debmake 命令會發出警告。

我們考慮 libfoo 這個程式庫的上游 tarball 原始碼壓縮包的名字從 libfoo-7.0.tar.gz 更新為了 libfoo-8.0.tar.gz,同時帶有一次 SONAME 大版本的跳躍(並因此影響了其它套件)。

程式庫的二進位制套件將必須從 libfoo7 重新命名為 libfoo8 以保持使用 unstable 套件的系統上所有依賴該程式庫的套件在上傳了基於 libfoo-8.0.tar.gz 的新程式庫後仍然能夠正常運行。

[警告] 警告

如果這個二進位制程式庫套件沒有得到更名,許多使用 unstable 套件的系統上的各個依賴該程式庫的套件會在新的程式庫包上傳後立刻破損,即便立刻請求進行 binNMU 上傳也無法避免這個問題。由於種種原因,binNMU 不可能在上傳後立刻開始進行,故無法緩解問題。

-dev 套件必須遵循以下命名規則:

[提示] 提示

如果包內資料檔案編碼方案有所變化(如,從 latin1 變為 utf-8),該場景應比照 API 變化做類似的考慮與處理。

參見 節 5.18, “程式庫套件”

debian/control 也定義了套件的依賴關系,其中變數替換機制(substvar)的功能可以用來將套件維護者從追蹤(大多數簡單的)套件依賴的重複勞動中解放出來。請參見 deb-substvars(5)。

debmake 命令支援下列變數替換指令:

  • ${misc:Depends},可用於所有二進位制套件
  • ${misc:Pre-Depends},可用於所有 multiarch 套件
  • ${shlibs:Depends},可用於所有含有二進位制可執行檔案或程式庫的套件
  • ${python:Depends},可用於所有 Python 套件
  • ${python3:Depends},可用於所有 Python3 套件
  • ${perl:Depends},用於所有 Perl 套件
  • ${ruby:Depends},用於所有 Ruby 套件

對共享連結程式庫來說,所需要的依賴程式庫是由執行“objdump -p /path/to/program | grep NEEDED”這樣的命令來得到的,由 shlib 佔位符進行變數替換。

對於 Python 和其它直譯器來說,所需的模組通常由對包含類似“import”、“use”、“require”等等關鍵字的行進行解析,並會體現在各自對應的變數替換佔位符所在位置上。

對其它沒有部署屬於自己範疇內的變數替換機制的情況,misc 變數替換佔位符通常用來覆蓋對應的依賴替換需求。

對 POSIX shell 程式來說,並沒有簡單的辦法來驗證其依賴關係,substvar 的變數替換也無法自動得出它們的依賴。

對使用動態載入機制,包括 GObject introspection 機制的程式庫和模組來說,現在沒有簡單的方法可以檢查依賴關係,變數替換機制也無法自動推匯出所需的依賴。

一個 binNMU(二進位制非維護者上傳) 是為程式庫遷移或其它目的所作的非維護者套件上傳。在一次 binNMU 上傳中,只有“Architecture: any”的套件會被重構建,其版本號會在末尾附加一個編號(例如,原來版本為 2.3.4-3,新上傳的包版本會變成 2.3.4-3+b1)。所有“Architecture: all”的包將不會重新構建。

來自同一個原始碼套件的各個二進位制包如果在 debian/control 檔案中有互相的依賴關係,這些二進位制包通常情況下應當對 binNMU 是安全的(即,進行 binNMU 不會破壞依賴關係)。然而,在“Architecture: any”和“Architecture: all”的套件同時由同一原始碼套件產出,且互相之間有依賴關係時,需要小心對待所依賴的版本,必要時應做出調整。

  • Architecture: any”的套件依賴於“Architecture: anyfoo 套件

    • Depends: foo (= ${binary:Version})
  • Architecture: any”的套件依賴於“Architecture: allbar 套件

    • Depends: bar (= ${source:Version}
  • Architecture: all”的套件依賴於“Architecture: anybaz 套件

    • Depends: baz (>= ${source:Version}), baz (<< ${source:Version}.0~)

debian/changelog 檔案記錄了 Debian 軟體包的歷史並在其第一行定義了上游套件的版本和 Debian 修訂版本。所有改變的內容應當以明確、正式而簡明的語言風格進行記錄。

  • 即便您在自己獨立進行套件上傳,您也必須記錄所有較重要、使用者可見的變更,例如:

    • 安全相關的漏洞修復。
    • 使用者介面變動。
  • 如果您需要他人協助您進行上傳,您應當更詳盡地記錄變更內容,包括所有打包相關的變動,從而方便他人對您的套件進行審查。

    • 協助上傳的人員不應該也通常不會猜測您沒有寫出來的想法,所以請認真書寫變更信息。
    • 通常來說,協助您上傳的人的時間比您的時間更寶貴。

debmake 命令會建立初始的模板檔案,其中帶有上游套件版本和 Debian 打包修訂編號。發行版部分被設定為 UNRELEASED 以避免半成品不小心被上傳進入 Debian 倉庫。

通常使用 debchange 命令(它具有一個別名,即 dch)對其進行編輯。

[提示] 提示

您也可以手動使用任何文字編輯器修改 debian/changelog 檔案,只要您能夠遵循 debchange 命令所使用的特定文字排版格式即可。

[提示] 提示

debian/changelog 檔案使用的日期字串可以使用“LC_ALL=C date -R”命令手動生成。

該檔案將由 dh_installchangelogs 命令安裝到 /usr/share/doc/binarypackage 目錄,檔名為 changelog.Debian.gz

上游的變更日誌則會安裝至 /usr/share/doc/binarypackage 目錄中,檔名為 changelog.gz

上游的變更日誌是由 dh_installchangelogs 程式自動進行搜尋和處理的;它會使用大小寫不敏感的搜尋方式尋找上游程式碼中特定名稱的檔案,如 changelogchangeschangelog.txtchanges.txthistoryhistory.txtchangelog.md。除了根目錄,程式還會在 doc/ 目錄和 docs/ 目錄內進行搜尋。

當您完成了主要打包工作並驗證了其質量之後,請考慮執行“dch -r”命令並將最終完成的 debian/changelog 檔案中發行版(distribution)部分進行設定,通常該欄位應當使用 unstable[13] 如果您的打包是一次向後移植(backports)、是安全更新或是對長期支援版的上傳等等其它情況,請使用相應合適的發行版名稱。

Debian 以十分嚴肅的態度對待版權和許可證資訊。《Debian 政策手冊》強制規定軟體包的 debian/copyright 檔案中需要提供相關資訊的摘要。

您應當按照 機器可解析的 debian/copyright 檔案(DEP-5)對其進行排版。

[注意] 注意

這裡的 debian/copyright 檔案中描述的許可證資訊匹配資訊應當合適地進行排序,以確保越寬泛的檔案匹配越靠前。請參見 節 6.4, “debmake -k”

debmake 命令會以掃描整個原始碼樹的方式建立初步的、相容 DEP-5 的模板檔案。它會內部呼叫許可證檢查工具來對許可證文字進行分類。[14]

除非明確指定(有些嚴格過頭的) -P 選項,debmake 命令會為了實用性而跳過對自動生成的檔案的檢查與報告,預設它們採用寬鬆的許可證。

[注意] 注意

如果您發現了這個許可證檢查工具存在一些問題,請對 debmake 套件提交缺陷報告並提供包含出現問題的許可證和版權資訊在內的相關文字內容。

[注意] 注意

debmake 命令專注於在建立 debian/copyright 模板時聚合相同的授權和許可證資訊並收錄其詳細內容。為了在有限的時間內儘可能完成工作,工具將只會提取檔案中第一塊看起來像授權文字或許可證宣告的部分。因此,生成的許可證資訊可能並不完美。請同時考慮使用其它工具,如 licensecheck 輔助進行檢查。

[提示] 提示

我們強烈推薦您使用 licensecheck(1) 命令再次檢查原始碼許可證的狀態,並在有必要的情況下進行人工程式碼審查。

構建過程開始之前,debian/patches/ 目錄內的 -p1 等級的補丁將會按照在 debian/patches/series 檔案中指定的順序依次應用於上游程式碼樹中。

[注意] 注意

原生 Debian 套件(參見 節 5.3, “原生 Debian 套件”)將不使用這些檔案。

要準備這一系列 -p1 等級的補丁,有幾種不同的方式可供您選擇。

  • diff 命令

    • 參見 節 4.8.1, “使用 diff -u 處理補丁”
    • 原始但萬能的方法

      • 補丁的來源多種多樣,它可以來自其它發行版、郵件列表中的帖文或是來自上游 git 倉庫的揀選補丁,由“git format-patches”生成
    • 不涉及 .pc/ 目錄的問題
    • 不修改上游原始碼樹
    • 手工更新 debian/patches/series 檔案
  • dquilt 命令

    • 參見 節 3.4, “quilt”
    • 基本的便利方案
    • 會以合適方式生成 .pc/ 目錄及其中的資料
    • 會修改上游原始碼樹
  • dpkg-source --commit”命令

  • dpkg-buildpackage 自動生成補丁

  • gbp-pq 命令

    • 配合 git-buildpackage 工具的基本 git 工作流
    • 不涉及 .pc/ 目錄的問題
    • 在可丟棄分支上儲存經過修改的上游原始碼樹(patch-queue/master
    • 在 Debian 分支中(常見為 master 分支)存儲未經修改的原始碼樹
  • gbp-dpm 命令

    • 配合 git-dpm 套件的更細緻的 git 工作流
    • 不涉及 .pc/ 目錄的問題
    • 在補丁分支中(通常命名為 patched/隨便啥名字)儲存經過修改的上游原始碼樹
    • 在 Debian 分支中(通常命名為 master/隨便啥名字)儲存未經修改的上游原始碼樹

無論這些補丁的來源如何,都建議使用兼容於 DEP-3 的頭部資訊對其進行標記。

[提示] 提示

dgit 套件提供了另外一套直接使用 git 集成操作 Debian 套件倉庫的工具。

dpkg-source 工具 1.16.1 版本之前,該工具還未提供 --commit 選項對應的功能,此時需要 quilt 命令(或者對它的封裝,dquilt 命令)來管理 debian/patches/ 目錄中的 -p1 等級的補丁。

在使用 dpkg-source 命令時,補丁應當能夠乾淨地進行應用。因此在補丁行數出現偏移或者其它情況出現時,您不能直接將舊補丁原封不動地複製到新版上游釋出對應打包版本的目錄中。

與此相對的是 dquilt 命令(參見 節 3.4, “quilt”)對補丁的處理更加寬容。您可以呼叫 dquilt 命令對補丁進行正常化。

 $ while dquilt push; do dquilt refresh ; done
 $ dquilt pop -a

使用 dpkg-source 命令比起使用 dquilt 命令來說存在一大優勢:dquilt 命令無法自動處理二進位制檔案出現變更的情況,而 dpkg-source 命令能夠探測出現內容變動的二進位制檔案,並將其列入 debian/source/include-binaries 檔案以便在 Debian 打包用壓縮包中將檔案囊括其中。

某些套件由 GPG 金鑰進行了簽名。

例如,GNU hello 可使用 HTTP 協議從 https://ftp.gnu.org/gnu/hello/ 下載。它含有以下檔案:

  • hello-version.tar.gz(上游原始碼)
  • hello-version.tar.gz.sig(分離的簽名)nature)

我們現在來選擇最新的版本套裝。

$ wget https://ftp.gnu.org/gnu/hello/hello-2.9.tar.gz
 ...
$ wget https://ftp.gnu.org/gnu/hello/hello-2.9.tar.gz.sig
 ...
$ gpg --verify hello-2.9.tar.gz.sig
gpg: Signature made Thu 10 Oct 2013 08:49:23 AM JST using DSA key ID 80EE4A00
gpg: Can't check signature: public key not found

如果您從郵件列表獲知上游維護者所使用的 GPG 公鑰資訊,請將它作為 debian/upstream/signing-key.asc 檔案進行儲存。否則,請使用 hkp 公鑰伺服器並經由您的信任網進行驗證。

$ gpg --keyserver hkp://keys.gnupg.net --recv-key 80EE4A00
gpg: requesting key 80EE4A00 from hkp server keys.gnupg.net
gpg: key 80EE4A00: public key "Reuben Thomas <rrt@sc3d.org>" imported
gpg: no ultimately trusted keys found
gpg: Total number processed: 1
gpg:               imported: 1
$ gpg --verify hello-2.9.tar.gz.sig
gpg: Signature made Thu 10 Oct 2013 08:49:23 AM JST using DSA key ID 80EE4A00
gpg: Good signature from "Reuben Thomas <rrt@sc3d.org>"
  ...
Primary key fingerprint: 9297 8852 A62F A5E2 85B2  A174 6808 9F73 80EE 4A00
[提示] 提示

如果您的網路環境阻擋了對 HKP 11371 埠的連線,請考慮使用“hkp://keyserver.ubuntu.com:80”。

在確認金鑰身份 80EE4A00 值得信任之後,應當下載其公鑰並將其儲存在 debian/upstream/signing-key.asc 檔案中。

$ gpg --armor --export 80EE4A00 >debian/upstream/signing-key.asc

之後,應相應地在 debian/watch 檔案中做如下的修改。

version=4
pgpsigurlmangle=s/$/.sig/  https://ftp.gnu.org/gnu/hello/ hello-(\d[\d.]*)\.tar\.(?:gz|bz2|xz)

現在 uscan 命令會在掃描時自動使用 GPG 籤名驗證上游原始碼套件的真實性。

Debian 嚴肅地對待軟體自由,遵循 Debian 自由軟體指導方針(DFSG)

在使用 uscan 命令來更新 Debian 打包所用程式碼時,上游原始碼套件(tarball)中不符合Debian 自由軟體指導方針(DFSG)的部分可以利用該工具簡單地進行移除。

  • debian/copyright 檔案中的 Files-Excluded 一節中列出需要移除的檔案。
  • debian/watch 檔案中列出下載上游原始碼套件(tarball)所使用的 URL。
  • 執行 uscan 命令以下載新的上游原始碼套件(tarball)。

    • 作為替代方案,您也可以使用“gbp import-orig --uscan --pristine-tar”命令。
  • 最後得到 tarball 的版本編號會附加一個額外的字尾 +dfsg

另外也可以新增一些可選的配置檔案並放入 debian/ 目錄。它們大多用於控制由 debhelper 套件提供的 dh_* 命令的行為,但也有一些檔案會影響 dpkg-sourcelintiangbp 這些命令。

[提示] 提示

請檢查 debhelper(7) 的內容以瞭解當前可用的 dh_* 命令列表。

這些 debian/binarypackage.* 的檔案提供了設定檔案安裝路徑的強大功能。即使上游原始碼沒有構建系統,這個軟體依然可以利用這裡提到的這些文件來進行打包。請參考 節 8.2, “無 Makefile(shell,命令列介面)” 的範例。

下面列表中出現的“-x[1234]”上標指示了 debmake -x 選項生成對應模板檔案所需要的最小值。請參考 debmake(1) 以瞭解詳情。

下面按照字母表順序列出一些值得注意的可選配置檔案。

binarypackage.bug-control -x3
將安裝至 binarypackage 套件的 usr/share/bug/binarypackage/control 位置。另請參考節 5.24, “錯誤報告”
binarypackage.bug-presubj -x3
將安裝至 binarypackage 套件的 usr/share/bug/binarypackage/presubj 位置。另請參考節 5.24, “錯誤報告”
binarypackage.bug-script -x3
將安裝至 binarypackage 套件的 usr/share/bug/binarypackage or usr/share/bug/binarypackage/script 位置。另請參考節 5.24, “錯誤報告”
binarypackage .bash-completion

列出需要安裝的 bash 補全指令碼。

需要在構建環境和使用者環境內均安裝 bash-completion 套件。

另請參考dh_bash-completion(1)。

clean -x2

列出(構建前)未被 dh_auto_clean 命令清理,且需要手工清理的檔案。

另請參考 dh_auto_clean(1) 和 dh_clean(1)。

compat -x3

Preciously, this set the debhelper compatibility level.

Now, use Build-Depends: debhelper-compat (= 13) in debian/control to specify the compatibility level.

另請參考 debhelper(8) 中“COMPATIBILITY LEVELS”一節。

binarypackage .conffile

如果相容等級大於 3(“compat >= 3”),您沒有建立該檔案的必要,因為所有 etc/ 目錄下的檔案都是配置檔案(conffiles)。

如果您正要打包的程式要求每個使用者都對 /etc 目錄下的配置檔案進行修改,可以採取兩種常見辦法使其不作為 conffile 配置檔案出現,避免 dpkg 命令處理套件時給出不必要的處理選項。

  • /etc 目錄下建立一個符號連結,指向 /var 目錄下的某些檔案;實際存在的檔案則使用維護者指令碼(maintainer script)予以建立。
  • 使用維護者指令碼(maintainer script)在 /etc 目錄下建立並維護配置所需的檔案。

另請參考 dh_installdeb(1)。

binarypackage .config
這是 debconf config 指令碼,用來在配置套件時向用戶詢問任何必需的問題。另請參見節 5.19, “debconf”
binarypackage.cron.hourly -x3

安裝至 binarypackage 包內的 etc/cron/hourly/binarypackage 檔案。

另請參見 dh_installcron(1) 和 cron(8)。

binarypackage.cron.daily -x3

安裝至 binarypackage 包內的 etc/cron/daily/binarypackage 檔案。

另請參見 dh_installcron(1) 和 cron(8)。

binarypackage.cron.weekly -x3

安裝至 binarypackage 包內的 etc/cron/weekly/binarypackage 檔案。

另請參見 dh_installcron(1) 和 cron(8)。

binarypackage.cron.monthly -x3

安裝至 binarypackage 包內的 etc/cron/monthly/binarypackage 檔案。

另請參見 dh_installcron(1) 和 cron(8)。

binarypackage.cron.d -x3

安裝至 binarypackage 包內的 etc/cron.d/binarypackage 檔案。

參見 dh_installcron(1)、cron(8) 和 crontab(5)。

binarypackage.default -x3

若該檔案存在,它將被安裝至 binarypackage 包中的 etc/default/binarypackage 位置。

參見 dh_installinit(1)。

binarypackage.dirs -x3

列出 binarypackage 包中要建立的目錄。

參見 dh_installdirs(1)。

通常情況下您並不需要這麼做,因為所有的 dh_install* 命令都會自動建立所需的目錄。請僅在遇到問題時考慮使用這一工具。

binarypackage.doc-base -x2

作為 binarypackage 包中的 doc-base 控制檔案進行安裝。

參見 dh_installdocs(1) 和 doc-base 套件提供的 Debian doc-base 手冊

binarypackage.docs -x2

列出要安裝在 binarypackage 包中的文件檔案。

參見 dh_installdocs(1)。

binarypackage.emacsen-compat -x3

安裝至 binarypackage 包中的 usr/lib/emacsen-common/packages/compat/binarypackage 檔案。

參見 dh_installemacsen(1)。

binarypackage.emacsen-install -x3

安裝至 binarypackage 包中的 usr/lib/emacsen-common/packages/install/binarypackage 檔案。

參見 dh_installemacsen(1)。

binarypackage.emacsen-remove -x3

安裝至 binarypackage 包中的 usr/lib/emacsen-common/packages/remove/binarypackage 檔案。

參見 dh_installemacsen(1)。

binarypackage.emacsen-startup -x3

安裝至 binarypackage 包中的 usr/lib/emacsen-common/packages/startup/binarypackage 檔案。

參見 dh_installemacsen(1)。

binarypackage.examples -x2

列出要安裝至 binarypackage 包中 usr/share/doc/binarypackage/examples/ 位置下的範例檔案或目錄。

參見 dh_installexamples(1)。

gbp.conf

如果該檔案存在,它將作為 gbp 命令的配置檔案發揮作用。

參見 gbp.conf(5)、gbp(1) 和 git-buildpackage(1)。

binarypackage.info -x2

列出要安裝至 binarypackage 包中的 info 檔案。

參見 dh_installinfo(1)。

binarypackage.init -x3

安裝至 binarypackage 包中的 etc/init.d/binarypackage 檔案。

參見 dh_installinit(1)。

binarypackage.install -x2

列出未被 dh_auto_install 命令安裝的其它應當安裝的檔案。

參見 dh_install(1) 和 dh_auto_install(1)。

license-examples/* -x4

這是 debmake 命令生成的版權宣告檔案示例,請用它們作為 debian/copyright 檔案的參考。

請在最終工作成果中刪除這些檔案。

binarypackage.links -x2

列出要生成符號連結的原始檔和目標檔案對。每一對連結均應在單獨的一行中列出,源檔案和目標檔案之間使用空白字元分隔。

參見 dh_link(1)。

binarypackage.lintian-overrides -x3

安裝至套件構建目錄的 usr/share/lintian/overrides/binarypackage 位置。該檔案用於消除 lintian 錯誤生成的診斷資訊。

參見 dh_lintian(1)、lintian(1) 和 Lintian 使用者手冊

manpage.* -x3

這些檔案是 debmake 命令生成的 man 手冊頁模板檔案。請將其重新命名為合適的檔名並更新其內容。

Debian 的政策要求套件為其包含的每個程式、工具和函式同時提供一份相關的手冊頁。手冊頁使用 nroff(1) 語法寫成。

如果您不熟悉如何編寫使用者手冊頁,請以 manpage.asciidocmanpage.1 為起點。

binarypackage.manpages -x2

列出要安裝的 man 手冊頁。

參見 dh_installman(1)。

binarypackage.menu (已過時,不再安裝)

tech-ctte #741573 決定“Debian 應該在合適的情況下使用 .desktop 檔案”。

安裝至 binarypackage 包中的 usr/share/menu/binarypackage Debian 選單文件。

參見 menufile(5) 以瞭解其格式。另請參見 dh_installmenu(1)。

NEWS

安裝至 usr/share/doc/binarypackage/NEWS.Debian 檔案。

參見 dh_installchangelogs(1)。

patches/*

這是 -p1 補丁檔案的集合,它們將在使用源程式碼構建之前應用在上游原始碼上。

參見 dpkg-source(1)、節 3.4, “quilt”節 4.8, “第三步(備選):修改上游原始碼”

debmake 預設不會生成補丁檔案。

patches/series -x1
patches/* 補丁檔案的應用順序。
binarypackage.preinst -x2, binarypackage.postinst -x2, binarypackage.prerm -x2, binarypackage.postrm -x2

這些維護者指令碼將安裝至套件的 DEBIAN 目錄下。

在這些指令碼中,#DEBHELPER# 記號將由其它 debhelper 命令進行處理,將其替換為相應的 shell 指令碼片段。

參考《Debian 政策手冊》的 dh_installdeb(1) 和 第六章 - 套件維護指令碼和安裝過程 一節。

參考《Debian 政策手冊》的 debconf-devel(7) 和 3.9.1 維護者指令碼中的使用者互動提示 一節。

README.Debian -x1

安裝至 debian/control 檔案列出的第一個二進位制套件中的 usr/share/doc/binarypackage/README.Debian 位置。

參見 dh_installdocs(1)。

該檔案提供了針對該 Debian 套件的資訊。

binarypackage.service -x3

如果該檔案存在,它將被安裝到 binarypackage 包下面的 lib/systemd/system/binarypackage.service 位置。

參見 dh_systemd_enable(1)、dh_systemd_start(1) 和 dh_installinit(1)。

source/format -x1

Debian 套件格式。

  • 使用“3.0 (quilt)”以製作這個非原生套件(推薦)
  • 使用“3.0 (native)”以製作這個原生套件

參見 dpkg-source(1) 的“原始碼套件格式”一節。

source/lintian-overridessource.lintian-overrides -x3

這些檔案不會最終被安裝,但 lintian 會對它們進行掃描以提供原始碼套件的 override 資訊。

另請參考 dh_lintian(1) 和 lintian(1)。

source/local-options -x1

dpkg-source 命令使用此內容作為它的選項,比較重要的選項有:

  • unapply-patches
  • abort-on-upstream-changes
  • auto-commit
  • single-debian-patch

該檔案不會包含在生成的原始碼套件中,僅對維護者在版本控制系統中維護套件有意義。

參見 dpkg-source(1) 中的“檔案格式”一節。

source/local-patch-header

自由格式的文字,將被包含在自動生成補丁的頂部。

該檔案不會包含在生成的原始碼套件中,僅對維護者在版本控制系統中維護套件有意義。

+ 參見 dpkg-source(1) 的“檔案格式”一節。

binarypackage.symbols -x2

這些符號檔案如果存在,將交由 dpkg-gensymbols 命令進行處理和安裝。

參見 dh_makeshlibs(1) 和 節 5.18.1, “程式庫符號”

binarypackage .templates
這是 debconf 模板檔案,用於在安裝過程中向用戶詢問必需的問題以正確配置套件。請參閱 節 5.19, “debconf”
tests/control
這是一個 RFC822 格式的測試元資料檔案,定義在 DEP-8。參見 autopkgtest(1) 和節 5.22, “持續整合”
TODO

安裝至 debian/control 檔案列出的第一個二進位制包中的 usr/share/doc/binarypackage/TODO.Debian 檔案。

參見 dh_installdocs(1)。

binarypackage.tmpfile -x3

如果該檔案存在,它將被安裝至 binarypackage 包中的 usr/lib/tmpfiles.d/binarypackage.conf 檔案。

參見 dh_systemd_enable(1)、dh_systemd_start(1) 和 dh_installinit(1)。

binarypackage.upstart -x3

如果該檔案存在,它將被安裝至套件構建目錄的 etc/init/package.conf 位置。(已棄用)

參見 dh_installinit(1) 和 節 8.1, “挑選最好的模板”

watch -x1

用於下載最新上游版本的 uscan 命令的控制檔案。

該控制檔案也可配置以使用其 GPG 簽名自動驗證上游 tarball 的真實性(參見 節 5.9, “debian/upstream/signing-key.asc”)。

參見 節 5.10, “debian/watch 和 DFSG”uscan(1)。

這裡給出針對上面列表中資訊的一些額外提醒。

  • 對只生成一個二進位制包的情況,列表檔名中的 binarypackage. 這一部分可以不出現。
  • 對有多個二進位制包的原始碼套件,一個缺少檔名裡 binarypackage. 部分的配置檔案,會被應用於 debian/control 裡列出的第一個二進位制包。
  • 在生成多個二進位制包的情況下,各個二進位制包可以分別指定配置檔案;只需在其對應配置檔案的檔名之前加上它們各自對應的包名即可,如 package-1.installpackage-2.install 等等。
  • debmake 可能沒有自動生成某些模板配置文件。如遇到這種情況,您可以使用文字編輯器手動建立遺失的檔案。
  • debmake 命令生成的帶額外 .ex 字尾名的配置檔案必須在移除這個多餘字尾名後才能發揮作用。
  • 您應當刪除 .ex 命令生成但對您無用的配置模板檔案。
  • 請按需複製配置模板檔案以匹配其對應的二進位制包名稱以及您的需求。

我們來重新歸納一下 Debian 打包定製化的相關內容。

所有對 Debian 套件進行定製化的資料都存在於 debian/ 目錄中。我們在節 4.6, “第三步:編輯模板檔案”這裡給出了一個簡單的例子。通常情況下,定製化會涉及以下各個專案:

  • Debian 套件構建系統可以經由 debian/rules 檔案進行定製(參見節 5.4.3, “設定 debian/rules”)。
  • 可以使用額外的配置檔案(如 debian/ directory 目錄下的 package.installpackage.docs 檔案)以配合來自 debhelper 套件的 dh_* 命令設定 Debian 套件檔案的安裝路徑等資訊(請參見 節 5.11, “其它 debian/* 檔案”)。

如果以上提到的手段仍然不足以製作滿足要求的 Debian 套件的話,對上游原始碼的修改應當使用 -p1 補丁檔案存放在打包原始碼樹 debian/patches/ 目錄下。這些補丁將按照 debian/patches/series 檔案所規定的順序在構建套件之前應用(參見 節 5.8, “debian/patches/*”)。節 4.8, “第三步(備選):修改上游原始碼” 這裡給出了一些簡單的例子。

您應當以引入最少修改的方式解決打包中出現的根本問題。所生成的套件應當考慮到未來的更新需求並有一定的健壯性。

[注意] 注意

如果補丁對上游有所幫助的話,也請將解決根本問題的補丁反饋給上游作者和維護者。

通常情況下,Debian 打包活動使用 Git 作為版本控制系統(VCS)進行記錄;通常會用到下列的分支。

  • master 分支

    • 記錄用於 Debian 打包的原始碼樹。
    • 原始碼樹的上游部分將照原樣記錄,不做修改。
    • Debian 打包中需要對上游原始碼所作的修改記錄在 debian/patches/ 目錄中,以 -p1 等級的補丁形式存在。
  • upstream 分支

    • 記錄從上游釋出的 tarball(原始碼壓縮檔案)解壓縮所得到的原始碼樹。
[提示] 提示

新增一個 .gitignore 檔案並將 .pc 檔案列入其中也是一個好主意。

[提示] 提示

可以在 debian/source/local-options 檔案中新增 unapply-patchesabort-on-upstream-changes 這兩行以保持上游原始碼處於未修改狀態。

[提示] 提示

您也可以使用除 upstream 分支以外其它名稱的分支追蹤上游版本控制資料以方便揀選補丁。

您也可以選擇不建立 -p1 等級的補丁。這時,您可以使用下列分支來記錄 Debian 打包活動。

  • master 分支

    • 記錄用於 Debian 打包的原始碼樹。
    • 原始碼樹的上游部分在應用了為 Debian 打包所作的修改之後進行記錄。
  • upstream 分支

    • 記錄從上游釋出的 tarball(原始碼壓縮檔案)解壓縮所得到的原始碼樹。

如下在 debian/ 目錄下額外新增一些檔案即可達到目的。

 $ tar -xvzf <package-version>.tar.gz
 $ ln -sf <package_version>.orig.tar.gz
 $ cd <package-version>/
 ... hack...hack...
 $ echo "single-debian-patch" >> debian/source/local-options
 $ cat >debian/source/local-patch-header <<END
 This patch contains all the Debian-specific changes mixed
 together. To review them separately, please inspect the VCS
 history at https://git.debian.org/?=collab-maint/foo.git.

如此可讓 Debian 打包過程(dpkg-buildpackagedebuild 等)所呼叫的 dpkg-source 命令自動生成一個 -p1 等級的補丁檔案 debian/patches/debian-changes

[提示] 提示

這種做法可以應用在任何版本控制工具中。這麼做會把所有修改合併到同一個補丁檔案中而丟失其開發歷史,因此請務必保持版本控制系統的資料公開可見。

[提示] 提示

debian/source/local-optionsdebian/source/local-patch-header 檔案只用於在版本控制系統中記錄資訊。它們不應包含在 Debian 原始碼套件中。

在某些情況下,直接使用自動生成的 Debian 原始碼套件會引入不必要的一些內容。

  • 上游原始碼樹可能由某個版本控制系統進行管理。直接從這個原始碼樹進行構建時,所生成的 Debian 原始碼套件會包含來自版本控制系統的多餘檔案。
  • 上游原始碼樹可能包含了一些自動生成的檔案。當從這個原始碼樹重新構建套件時,所生成的 Debian 原始碼套件會包含這些自動生成的不必要的檔案。

通常情況下,節 3.5, “devscripts” 中設定的用於 dpkg-source 命令的 -i-I 選項可以避免這些問題。這裡 -i 針對非原生套件而 -I 則針對原生套件。請參見 dpkg-source(1) 和“dpkg-source --help”的輸出。

以下幾種方法均可避免引入不必要的內容。

上游的構建系統設計為經過數個步驟以從原始碼發行檔案得到並在系統中安裝所生成的二進位制檔案。

[提示] 提示

在嘗試製作 Debian 套件之前,您應當熟悉瞭解上游原始碼所使用的構建系統並嘗試構建軟體。

Debian 軟體吧在構建時都會帶上除錯資訊;但打包生成二進位制套件時,這些打包資訊會按照《Debian 政策手冊》中第十章 - 檔案的要求進行移除。

參見

打包軟體程式庫需要您投入更多的工作。下面有一些打包軟體程式庫的提醒和建議:

在打包共享程式庫軟體之前,請查閱:

如需研究其歷史背景,請參見:

Debian lenny(5.0,2009年5月)中引入的 dpkg 符號支援可以幫助我們管理同一共享鏈接程式庫套件的向後 ABI 相容性(backward ABI compatibility)。二進位制套件中的 DEBIAN/symbols 檔案提供了每個符號及其對應的最小版本號。

一個極其簡化的軟體程式庫打包流程大概如下所示。

  • 從前一個二進位制套件中使用“dpkg-deb -e”命令解壓縮得到舊有的 DEBIAN/symbols 檔案。

    • 或者,mc 命令也可以用來解壓得到 DEBIAN/symbols 檔案。
  • 將其複製為 debian/binarypackage.symbols 檔案。

    • 如果這是第一次打包的話,可以只建立一個空檔案。
  • 構建二進位制套件。

    • 如果 dpkg-gensymbols 命令警告添加了新的符號的話:

      • 使用“dpkg-deb -e”命令解壓得到更新的 DEBIAN/symbols 檔案。
      • 將其中的 Debian 修訂版本號,例如 -1,從檔案中去除。
      • 將其複製為 debian/binarypackage.symbols 檔案。
      • 重新構建二進位制套件。
    • 如果 dpkg-gensymbols 命令不報和新連結符號有關的警告:

      • 您已完成了共享程式庫的打包工作。

如需瞭解詳細資訊,您應當閱讀下列第一手參考資料。

您也應當檢視:

[提示] 提示

對於 C++ 軟體程式庫或者其它一些難以追蹤符號變化的場景,請遵循《Debian 政策手冊》的 -1 一節的內容。請確保這樣操作時事先刪除 debmake 命令生成的空的 debian/binarypackage.symbols 檔案。在這種情況下,應當轉而使用 DEBIAN/shlibs 檔案。

當您打包新版本的程式庫套件而且此次更新影響到其它的套件時,您必須對 release.debian.org 偽套件提交一個變遷 bug 報告並附帶一個ben 檔案;您可以使用 reportbug 工具進行提交。提交後,請等待發行團隊的稽核批准方可進行下一步。

發行團隊提供了變遷追蹤系統。參見 變遷(Transition)

[注意] 注意

請確保您按照 節 5.5.1.3, “程式庫套件名稱” 的描述正確地對二進位制套件進行了重命名。

debconf 套件可以幫助我們在下列兩種情況下配置套件:

  • debian-installer(Debian 安裝程式)預安裝時進行非互動式配置。
  • 使用選單介面進行互動式配置(對話方塊(dialog)gnomekde 等等)

    • 套件安裝時:由 dpkg 命令呼叫
    • 對已安裝套件:由 dpkg-reconfigure 命令呼叫

套件安裝時的所有使用者互動都必須由這裡的 debconf 系統進行處理,下列配置檔案對這個過程進行控制。

  • debian/ binarypackage .config

    • 這是 debconf config 指令碼,用於對使用者詢問對於配置套件必需的問題。
  • debian/ binarypackage .template

    • 這是 debconf templates(模板)檔案,用於對使用者詢問對於配置套件必需的問題。
  • 套件配置指令碼

    • debian/ binarypackage .preinst
    • debian/ binarypackage .prerm
    • debian/ binarypackage .postinst
    • debian/ binarypackage .postrm

參見 dh_installdebconf(1)、debconf(7)、debconf-devel(7) 和《Debian 政策手冊》中的 3.9.1 維護者指令碼中的使用者互動提示

Debian wheezy(7.0,2013年5月)在 dpkgapt 中引入了對跨架構二進位制套件安裝的多架構支援(特別是 i386 架構和 amd64 架構,但也支援其它的組合),這部分內容值得我們額外關注。

您應當詳細閱讀下列參考內容。

多架構支援使用三元組(<triplet>)的值,例如 i386-linux-gnux86_64-linux-gnu;它們出現在共享連結程式庫的安裝路徑中,例如 /usr/lib/<triplet>/,等等。

  • 三元組 <triplet> 的值由 debhelper 指令碼隱性提前設定好,套件維護者無需擔心。
  • 不過,在 debian/rules 檔案中用於 override_dh_* 目標的三元組 <triplet> 值需要由維護者手動進行顯性設定。三元組 <triplet> 的值可由 $(DEB_HOST_MULTIARCH) 變數在 debian/rules 檔案中取得到,具體方法如下:

    DEB_HOST_MULTIARCH = $(shell dpkg-architecture -qDEB_HOST_MULTIARCH)
    ...
    override_dh_install:
            mkdir -p package1/lib/$(DEB_HOST_MULTIARCH)
            cp -dR tmp/lib/. package1/lib/$(DEB_HOST_MULTIARCH)

參見:

Debian 政策要求遵守檔案系統層級標準。其中 /usr/lib:程式和套件的程式庫 宣告“/usr/lib 包含目標檔案、程式庫和其它不應由使用者或 shell 指令碼直接呼叫的內部二進位制檔案。”

Debian 在檔案系統層級標準的基礎上新增一項例外,即使用 /usr/lib/<triplet>/ 而非 /usr/lib<qual>/(例如,/lib32//lib64/)以對多架構程式庫提供支持。


對基於 Autotools 且由 debhelper (compat>=9)管理的套件來說,這些路徑設定已由 dh_auto_configure 命令自動處理。

對於其它使用不支援的構建系統的套件,您需要按照下面的方式手動調整安裝路徑。

  • 如果在 debian/rules 檔案中設定了 override_dh_auto_configure 目標且其中手動呼叫了“./configure”命令,請確保將其替換為“dh_auto_configure --”,這樣可以將安裝路徑從 /usr/lib/ 替換為 /usr/lib/$(DEB_HOST_MULTIARCH)/
  • 請在 debian/foo.install 檔案中將所有出現的 /usr/lib/ 字串替換為 /usr/lib/*/

所有啟用多架構的套件安裝至相同路徑的檔案必須內容完全相同。您必須小心處理,避免資料位元組序或者壓縮演算法等等問題帶來的檔案內容差異。

[注意] 注意

./configure--libexecdir選項指定了由程式而非使用者所使用的可執行檔案的預設安裝路徑。其 Autotools 的預設值為 /usr/libexec/ 但在未啟用多架構特性的 Debian 系統上其預設值是 /usr/lib/。如果這些可執行程式屬於被標記為“Multi-arch: foreign”的套件,最好還是使用例如 /usr/lib/ 或者 /usr/lib/套件名 這樣的路徑而非使用 dh_auto_configure 設定的 /usr/lib/<triplet>/ 路徑。GNU 程式設計規範:7.2.5 用於安裝目錄的變數libexecdir 的描述是“libexecdir 的定義對所有套件相同,所以您應當將您的資料安裝在其下的一個子目錄中。大多數套件將資料安裝至 $(libexecdir)/package-name/ 之中……”(在與 Debian 政策不衝突的前提下,遵守 GNU 的標準總是更好的。)

位於預設路徑 /usr/lib//usr/lib/<triplet>/ 的共享程式庫可被自動載入。

對位於其它路徑的共享程式庫,必須使用 pkg-config 命令設定 GCC 選項 -l 以正確進行載入。

自 Debian jessie(8.0 開始)的編譯器強化支援要求我們在打包時加以注意。

您應當詳細閱讀下列參考內容。

debmake 命令會對 debian/rules 檔案中按需新增 DEB_BUILD_MAINT_OPTIONSDEB_CFLAGS_MAINT_APPENDDEB_LDFLAGS_MAINT_APPEND 的專案(參見 章 4, 簡單例子dpkg-buildflags(1))。

DEP-8 定義了 debian/tests/control 檔案的格式,它是 RFC822 風格的測試元資料檔案,用於 Debian 套件的持續整合(CI)。

它在完成構建包含 debian/tests/control 文件的原始碼套件、得到二進位制包之後發揮作用。在執行 autopkgtest 命令時,所生成的二進位制套件會根據這個檔案在虛擬環境中自動進行安裝和測試。

請參考 /usr/share/doc/autopkgtest/ 目錄下的文件和《Debian 打包指導”中的 3. autopkgtest: 套件的自動測試

您可以在 Debian 系統上探索使用不同的持續整合系統。

  • debci 套件:建立在 autopkgtest 之上的持續整合平臺
  • jenkins 套件:通用持續整合平臺

Debian 關心對新硬體架構的移植工作。新架構的移植工作對自主生成(bootstrapping)操作有所要求,以完成對初始最小本地構建系統的交叉編譯。為了在自主生成時避免構建依賴成環的問題,需要使用 配置型別(profile) 的構建功能特性來縮減所需構建依賴。

[提示] 提示

如果一個核心套件 foo 構建時依賴於 bar 套件,但後者會引入一長串構建依賴鏈而且 bar 僅在 footest 目標中使用(即僅用於構建後測試),那麼您可以安全地在 foo 套件的 Build-depends 一欄中將 bar 標記為 <!nocheck> 以規避構建依賴環。

reportbug 命令用於提交 binarypackage 套件的錯誤報告;usr/share/bug/binarypackage/ 可以對針對該軟體所提交報告的內容進行設定。

dh_bugfiles 命令將安裝以下位於 debian/ 目錄中的的模板檔案。

  • debian/binarypackage.bug-controlusr/share/bug/binarypackage/control

    • 該檔案包含諸如重定向錯誤報告至其它套件的一些指導性內容。
  • debian/binarypackage.bug-presubjusr/share/bug/binarypackage/presubj

    • 該檔案的內容將由 reportbug 命令對使用者展示。
  • debian/binarypackage.bug-scriptusr/share/bug/binarypackage or usr/share/bug/binarypackage/script

    • reportbug 命令執行此指令碼以生成錯誤報告的模板檔案。

參見 dh_bugfiles(1) 和 為開發者提供的 reportbug 功能特性

[提示] 提示

如果您總是需要提醒提交報告的使用者某些注意事項或詢問他們某些問題,使用這些檔案可以將這個過程自動化。



[10] 對九成以上的套件來說,套件名稱都不會超過 24 個字元;上游版本號通常不超過 10 個字元,而 Debian 修訂版本號也通常不超過 3 個字元。

[11] This simplicity is available since version 7 of the debhelper package. This guide assumes the use of debhelper version 13 or newer.

[12] debmake 命令會產生稍微複雜一些的 debian/rules 檔案。雖然如此,其核心結構沒有什麼變化。

[13] 如果您在使用 vim 編輯器,請確保使用“:wq”命令對內容進行儲存。

[14] 程式以前會在內部呼叫來自 devscripts 軟體包的 licensecheck 命令來進行檢查。現在的 licensecheck 命令由獨立的 licensecheck 套件所提供,相較從前的實現也有了較大的改進。

[15] 該文件是在 symbols 檔案被引入之前寫成的。

[16] 第六章 - 開發(-DEV)套件中,存在強烈的使用含有 SONAME 版本號的 -dev 套件名而非僅使用 -dev 作為名稱的偏好,但前 ftp-master 成員(Steve Langasek)對此有不同意見。請注意該文件在 multiarch 系統和 symbols 引入之前寫成,可能有一定程度的過時。

[17] 這個路徑和 FHS 相容。檔案系統層級標準:/usr/lib:程式和套件的程式庫 稱“應用程式可以使用 /usr/lib 下的一個子目錄。如果一個應用程式使用一個子目錄,所有由此程式所使用的架構相關資料均須放置於該子目錄下。”