內容目錄
Here, a broad overview is presented without using VCS operations for the basic rules of Debian packaging focusing on the non-native Debian package in the “3.0 (quilt)” format.
![]() | 注意 |
---|---|
為簡明起見,某些細節被有意跳過。請按需查閱對應命令的手冊頁,例如dpkg-source(1)、dpkg-buildpackage(1)、dpkg(1)、dpkg-deb(1)、deb(5),等等。 |
Debian 原始碼套件是一組用於構建 Debian 二進位制套件的輸入檔案,而非單個檔案。
Debian 二進位制套件是一個特殊的檔案檔案,其中包含了一系列可安裝的二進位制資料及與它們相關的資訊。
單個 Debian 原始碼套件可能根據 debian/control 檔案定義的內容產生多個 Debian 二進位制套件。
The non-native Debian package in the Debian source format “3.0 (quilt)” is the most normal Debian source package format.
![]() | 注意 |
---|---|
有許多封裝指令碼可用。合理使用它們可以幫助您理順工作流程,但是請確保您能理解它們內部的基本工作原理。 |
The Debian packaging workflow to create a Debian binary package involves generating several specifically named files (see “節 6.3, “套件名稱和版本””) as defined in the “Debian Policy Manual”. This workflow can be summarized in 10 steps with some over simplification as follows.
上游的原始碼壓縮包被複制(或符號連結)至一個特定的檔名 packagename_version.orig.tar.gz。
Debian 套件規範檔案將被新增至上游原始碼中,存放在 package-version/debian/ 目錄下。
debian/* 目錄下的必需技術說明檔案:
The debmake command invoked in the package-version/ directory may be used to provide the initial template of these configuration files.
The dpkg-buildpackage command (usually from its wrapper debuild or sbuild) is invoked in the package-version/ directory to make the Debian source and binary packages by invoking the debian/rules script.
Create the Debian source package in the Debian source format “3.0 (quilt)” using dpkg-source(1)
Build the source using “debian/rules build” into $(DESTDIR)
使用 dpkg-deb(1)、dpkg-genbuildinfo(1) 和 dpkg-genchanges(1) 建立 Debian 二進位制套件。
使用 lintian 命令檢查 Debian 套件的質量。(推薦)
Follow the rejection guidelines from ftp-master.
Sign the Debian package file with the debsign command using your private GPG key.
Upload the set of the Debian package files with the dput command to the Debian archive.
Test building and confirming of the binary package goodness as above is the moral obligation as a diligent Debian developer but there is no physical barrier for people to skip such operations at this moment for the source-only upload.
這裡,請將檔名中對應的部分使用下面的方式進行替換:
See also “Source-only uploads”.
![]() | 提示 |
---|---|
有很多種通過實踐摸索而得到的補丁管理方法和版本控制系統的使用策略與技巧。您沒有必要將它們全部用上。 |
![]() | 提示 |
---|---|
There is very extensive documentation in “Chapter 6. Best Packaging Practices” in the “Debian Developer’s Reference”. Please read it. |
Although a Debian package can be made by writing a debian/rules script without using the debhelper package, it is impractical to do so. There are too many modern “Debian Policy” required features to be addressed, such as application of the proper file permissions, use of the proper architecture dependent library installation path, insertion of the installation hook scripts, generation of the debug symbol package, generation of package dependency information, generation of the package information files, application of the proper timestamp for reproducible build, etc.
Debhelper package provides a set of useful scripts in order to simplify Debian’s packaging workflow and reduce the burden of package maintainers. When properly used, they will help packagers handle and implement “Debian Policy” required features automatically.
現代化的 Debian 打包工作流可以組織成一個簡單的模組化工作流,如下所示:
您幾乎總是應當將 debhelper 列為您的軟體包的構建依賴之一。本文件在接下來的內容中也假設您正在使用一個版本足夠新的 debhelper 協助進行打包工作。
![]() | 注意 |
---|---|
For debhelper “compat >= 9”, the dh command exports compiler flags (CFLAGS, CXXFLAGS, FFLAGS, CPPFLAGS and LDFLAGS) with values as returned by dpkg-buildflags if they are not set previously. (The dh command calls set_buildflags defined in the Debian::Debhelper::Dh_Lib module.) |
![]() | 注意 |
---|---|
debhelper(1) changes its behavior with time. Please make sure to read debhelper-compat-upgrade-checklist(7) to understand the situation. |
如果所取得上游原始碼的形式為 hello-0.9.12.tar.gz,您可以將 hello 作為上游原始碼名稱,並將 0.9.12 作為上游版本號。
組成 Debian 套件名稱的字元選取存在一定的限制。最明顯的限制應當是套件名稱中禁止出現大寫字母。這裡給出正則表示式形式的規則總結:
[-+.a-z0-9]{2,}
[-+.a-z0-9]{2,}
[0-9][-+.:~a-z0-9A-Z]*
[0-9][+.~a-z0-9A-Z]*
See the exact definition in “Chapter 5 - Control files and their fields” in the “Debian Policy Manual”.
您必須為 Debian 打包工作適當地調整套件名稱和上游版本號。
為了能有效地使用一些流行的工具(如 aptitude)管理套件名稱和版本資訊,最好能將套件名稱保持在 30 字元以下;版本號和修訂號加起來最好能不超過 14 個字元。[12]
為了避免命名衝突,對使用者可見的二進位制套件名稱不應選擇任何常用的單詞。
如果上游沒有使用像 2.30.32 這樣正常的版本編號方案,而是使用了諸如 11Apr29 這樣包含日期、某些代號或者一個版本控制系統雜湊值等字串作為版本號的一部分的話,請在上游版本號中將這些部分移除。這些資訊可以稍後在 debian/changelog 檔案中進行記錄。如果您需要為軟體設計一個版本字符串,可以使用 YYYYMMDD 格式,如 20110429 的字串作為上游版本號。這樣能保證 dpkg 命令在升級時能正確地確定版本的先後關係。如果您想要確保萬一上游在未來重新採納正常版本編號方案,例如 0.1 時能夠做到順暢地遷移,可以另行使用 0~YYMMDD 的格式,如 0~110429 作為上游版本號。
版本字串可以按如下的方式使用 dpkg 命令進行比較。
$ dpkg --compare-versions ver1 op ver2
版本比較的規則可以歸納如下:
對於某些字元,如句點(.)、加號(+)和波浪號(~),有如下的特殊規則。
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。
The non-native Debian package in the Debian source format “3.0 (quilt)” is the most normal Debian source package format. The debian/source/format file should have “3.0 (quilt)” in it as described in dpkg-source(1). The above workflow and the following packaging examples always use this format.
而原生 Debian 套件是較罕見的一種 Debian 套件格式。它通常只用於打包僅對 Debian 專案有價值、有意義的軟體。因此,該格式的使用通常不被提倡。
![]() | 注意 |
---|---|
A native Debian package is often accidentally built when its upstream tarball is not accessible from the dpkg-buildpackage command with its correct name package_version.orig.tar.gz . This is a typical newbie mistake caused by making a symlink name with “-” instead of the correct one with “_”. |
原生 Debian 套件不對 上游程式碼 和 Debian 的修改 進行區分,僅包含以下內容:
If you need to create a native Debian package, create it in the Debian source format “3.0 (native)” using dpkg-source(1).
![]() | 提示 |
---|---|
There is no need to create the tarball in advance if the native Debian package format is used. The debian/source/format file should have “3.0 (native)” in it as described in dpkg-source(1) and The debian/source/format file should have the version without the Debian revision (1.0 instead of 1.0-1). Then, the tarball containing is generated when “dpkg-source -b” is invoked in the source tree. |
The debian/rules file is the executable script which re-targets the upstream build system to install files in the $(DESTDIR) and creates the archive file of the generated files as the deb file. The deb file is used for the binary distribution and installed to the system using the dpkg command.
The Debian policy compliant debian/rules file supporting all the required targets can be written as simple as [13]:
簡單的 debian/rules:.
#!/usr/bin/make -f #export DH_VERBOSE = 1 %: dh $@
The dh command functions as the sequencer to call all required “dh target” commands at the right moment. [14]
Here, $(DESTDIR) path depends on the build type.
See “節 9.2, “Customized debian/rules”” and “節 9.3, “Variables for debian/rules”” for customization.
![]() | 提示 |
---|---|
Setting “export DH_VERBOSE = 1” outputs every command that modifies files on the build system. Also it enables verbose build logs for some build systems. |
The debian/control file consists of blocks of metadata separated by blank lines. Each block of metadata defines the following, in this order:
See “Chapter 5 - Control files and their fields” of the "Debian Policy Manual" for the definition of each metadata field.
![]() | 注意 |
---|---|
The debmake command sets the debian/control file with “Build-Depends: debhelper-compat (= 13)” to set the debhelper compatibility level. |
![]() | 提示 |
---|---|
If an existing package has a debhelper compatibility level lower than 13, it’s probably time to update its packaging. |
The debian/changelog file records the Debian package history.
Document changes in a specific, formal, and concise style.
Even if you’re uploading your package yourself, you must document all non-trivial user-visible changes, such as:
If you’re asking a sponsor to upload it, document changes more comprehensively, including all packaging-related ones, to help with package review.
After finishing your packaging and verifying its quality, execute the "dch -r" command and save the finalized debian/changelog file with the suite normally set to unstable. [16] If you’re packaging for backports, security updates, LTS, etc., use the appropriate distribution names instead.
The debmake command creates the initial template file with the upstream package version and the Debian revision. The distribution is set to UNRELEASED to prevent accidental uploads to the Debian archive.
![]() | 提示 |
---|---|
The date string used in the debian/changelog file can be manually generated by the “LC_ALL=C date -R” command. |
![]() | 提示 |
---|---|
Use a debian/changelog entry with a version string like 1.0.1-1~rc1 when experimenting. Later, consolidate such changelog entries into a single entry for the official package. |
The debian/changelog file is installed in the /usr/share/doc/binarypackage directory as changelog.Debian.gz by the dh_installchangelogs command.
上游的變更日誌則會安裝至 /usr/share/doc/binarypackage 目錄中,檔名為 changelog.gz。
上游的變更日誌是由 dh_installchangelogs 程式自動進行搜尋和處理的;它會使用大小寫不敏感的搜尋方式尋找上游程式碼中特定名稱的檔案,如 changelog、changes、changelog.txt、changes.txt、history、history.txt 或 changelog.md。除了根目錄,程式還會在 doc/ 目錄和 docs/ 目錄內進行搜尋。
Debian takes copyright and license matters very seriously. The "Debian Policy Manual" requires a summary of these in the debian/copyright file of the package.
The debmake command creates the initial debian/copyright template file.
Unless specifically requested to be pedantic with the -P option, the debmake command skips reporting auto-generated files with permissive licenses for practicality.
![]() | 注意 |
---|---|
The debian/copyright file should be sorted with generic file patterns at the top of the list. See “節 16.6, “debmake -k””. |
![]() | 注意 |
---|---|
如果您發現了這個許可證檢查工具存在一些問題,請對 debmake 套件提交缺陷報告並提供包含出現問題的許可證和版權資訊在內的相關文字內容。 |
As demonstrated in “節 5.9, “Step 3 (alternatives): Modification to the upstream source””, the debian/patches/ directory holds
See how these files are used in:
![]() | 注意 |
---|---|
Header texts of these patches should conform to “DEP-3”. |
![]() | 注意 |
---|---|
If you want to use VCS tools such as git, gbp and dgit to create and manage these patches after learning basics here, please refer to later in “章 11, Packaging with git”. |
The “dpkg-source --commit” command functions like dquilt but has one advantage over the dquilt command. While the dquilt command can’t handle modified binary files, the “dpkg-source --commit” command detects modified binary files and lists them in the debian/source/include-binaries file to include them in the Debian tarball as a part of the Debian source package.
The uscan(1) command downloads the latest upstream version using the debian/watch file. E.g.:
Basic debian/watch file:
version=4 https://ftp.gnu.org/gnu/hello/ @PACKAGE@@ANY_VERSION@@ARCHIVE_EXT@
The uscan command may verify the authenticity of the upstream tarball with optional configuration (see “節 6.12, “debian/upstream/signing-key.asc file””).
See uscan(1), “節 9.4, “新上游版本””, “節 8.1, “Fix with Files-Excluded””, and “節 11.10, “Manage patch queue with gbp-pq”” for more.
Some packages are signed by a GPG key and their authenticity can be verified using their public GPG key.
For example, “GNU hello” can be downloaded via HTTP from https://ftp.gnu.org/gnu/hello/ . There are sets of files:
我們現在來選擇最新的版本套裝。
Download the upstream tarball and its signature.
$ 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
If you know the public GPG key of the upstream maintainer from the mailing list, use it as the debian/upstream/signing-key.asc file. Otherwise, use the hkp keyserver and check it via your web of trust.
Download public GPG key for the upstream.
$ 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
![]() | 提示 |
---|---|
If your network environment blocks access to the HKP port 11371, use “hkp://keyserver.ubuntu.com:80” instead. |
在確認金鑰身份 80EE4A00 值得信任之後,應當下載其公鑰並將其儲存在 debian/upstream/signing-key.asc 檔案中。
Set public GPG key to debian/upstream/signing-key.asc.
$ gpg --armor --export 80EE4A00 >debian/upstream/signing-key.asc
With the above debian/upstream/signing-key.asc file and the following debian/watch file, the uscan command can verify the authenticity of the upstream tarball after its download. E.g.:
Improved debian/watch file with GPG support:
version=4 opts="pgpsigurlmangle=s/$/.sig/" \ https://ftp.gnu.org/gnu/hello/ @PACKAGE@@ANY_VERSION@@ARCHIVE_EXT@
Install Salsa CI configuration file. See “節 11.3, “Salsa CI service””.
另外也可以新增一些可選的配置檔案並放入 debian/ 目錄。它們大多用於控制由 debhelper 套件提供的 dh_* 命令的行為,但也有一些檔案會影響 dpkg-source、lintian 和 gbp 這些命令。
![]() | 提示 |
---|---|
Even an upstream source without its build system can be packaged just by using these files. See “節 14.2, “無 Makefile(shell,命令列介面)”” as an example. |
The alphabetical list of notable optional debian/binarypackage.* configuration files listed below provides very powerful means to set the installation path of files. Please note:
請按需複製配置模板檔案以匹配其對應的二進位制包名稱以及您的需求。
List bash completion scripts to be installed.
The bash-completion package is required for both build and user environments.
另請參考dh_bash-completion(1)。
列出(構建前)未被 dh_auto_clean 命令清理,且需要手工清理的檔案。
另請參考 dh_auto_clean(1) 和 dh_clean(1)。
Set the debhelper compatibility level. (deprecated)
Use “Build-Depends: debhelper-compat (= 13)” in debian/control to specify the compatibility level and remove debian/compat.
See “COMPATIBILITY LEVELS” in debhelper(7).
This optional file is installed into the DEBIAN directory within the binary package while supplementing it with all the conffiles auto-detected by debhelper.
This file is primarily useful for using "special" entries such as the remove-on-upgrade feature from dpkg(1).
如果您正要打包的程式要求每個使用者都對 /etc 目錄下的配置檔案進行修改,可以採取兩種常見辦法使其不作為 conffile 配置檔案出現,避免 dpkg 命令處理套件時給出不必要的處理選項。
另請參考 dh_installdeb(1)。
安裝至 binarypackage 包內的 etc/cron/hourly/binarypackage 檔案。
另請參見 dh_installcron(1) 和 cron(8)。
安裝至 binarypackage 包內的 etc/cron/daily/binarypackage 檔案。
另請參見 dh_installcron(1) 和 cron(8)。
安裝至 binarypackage 包內的 etc/cron/weekly/binarypackage 檔案。
另請參見 dh_installcron(1) 和 cron(8)。
Installed into the *etc/cron/monthly/*binarypackage file in binarypackage.
另請參見 dh_installcron(1) 和 cron(8)。
安裝至 binarypackage 包內的 etc/cron.d/binarypackage 檔案。
參見 dh_installcron(1)、cron(8) 和 crontab(5)。
若該檔案存在,它將被安裝至 binarypackage 包中的 etc/default/binarypackage 位置。
參見 dh_installinit(1)。
列出 binarypackage 包中要建立的目錄。
參見 dh_installdirs(1)。
通常情況下您並不需要這麼做,因為所有的 dh_install* 命令都會自動建立所需的目錄。請僅在遇到問題時考慮使用這一工具。
作為 binarypackage 包中的 doc-base 控制檔案進行安裝。
See dh_installdocs(1) and “Debian doc-base Manual (doc-base.html)” provided by the doc-base package.
列出要安裝在 binarypackage 包中的文件檔案。
參見 dh_installdocs(1)。
安裝至 binarypackage 包中的 usr/lib/emacsen-common/packages/compat/binarypackage 檔案。
參見 dh_installemacsen(1)。
安裝至 binarypackage 包中的 usr/lib/emacsen-common/packages/install/binarypackage 檔案。
參見 dh_installemacsen(1)。
安裝至 binarypackage 包中的 usr/lib/emacsen-common/packages/remove/binarypackage 檔案。
參見 dh_installemacsen(1)。
安裝至 binarypackage 包中的 usr/lib/emacsen-common/packages/startup/binarypackage 檔案。
參見 dh_installemacsen(1)。
列出要安裝至 binarypackage 包中 usr/share/doc/binarypackage/examples/ 位置下的範例檔案或目錄。
參見 dh_installexamples(1)。
如果該檔案存在,它將作為 gbp 命令的配置檔案發揮作用。
參見 gbp.conf(5)、gbp(1) 和 git-buildpackage(1)。
列出要安裝至 binarypackage 包中的 info 檔案。
參見 dh_installinfo(1)。
Installed into etc/init.d/binarypackage in binarypackage. (deprecated)
參見 dh_installinit(1)。
列出未被 dh_auto_install 命令安裝的其它應當安裝的檔案。
參見 dh_install(1) 和 dh_auto_install(1)。
列出要生成符號連結的原始檔和目標檔案對。每一對連結均應在單獨的一行中列出,源檔案和目標檔案之間使用空白字元分隔。
參見 dh_link(1)。
安裝至套件構建目錄的 usr/share/lintian/overrides/binarypackage 位置。該檔案用於消除 lintian 錯誤生成的診斷資訊。
參見 dh_lintian(1)、lintian(1) 和 “Lintian 使用者手冊”。
If this optional file exists, debhelper uses this as the template to generate DEBIAN/binarypackage.{pre,post}{inst,rm} files within the binary package while adding “-- "$@"” to the dpkg-maintscript-helper(1) command.
See dh_installdeb(1) and “Chapter 6 - Package maintainer scripts and installation procedure” in the “Debian Policy Manual”.
這些檔案是 debmake 命令生成的 man 手冊頁模板檔案。請將其重新命名為合適的檔名並更新其內容。
Debian Policy requires that each program, utility, and function should have an associated manual page included in the same package. Manual pages are written in nroff(1). If you are new to making a manpage, use manpage.asciidoc or manpage.1 as the starting point.
列出要安裝的 man 手冊頁。
參見 dh_installman(1)。
tech-ctte #741573 decided “Debian should use .desktop files as appropriate”.
安裝至 binarypackage 包中的 usr/share/menu/binarypackage Debian 選單文件。
參見 menufile(5) 以瞭解其格式。另請參見 dh_installmenu(1)。
安裝至 usr/share/doc/binarypackage/NEWS.Debian 檔案。
參見 dh_installchangelogs(1)。
這是 -p1 補丁檔案的集合,它們將在使用源程式碼構建之前應用在上游原始碼上。
debmake 預設不會生成補丁檔案。
參見 dpkg-source(1)、“節 4.4, “quilt setup”” 和 “節 5.9, “Step 3 (alternatives): Modification to the upstream source””。
If these optional files exist, the corresponding files are installed into the DEBIAN directory within the binary package after enriched by debhelper. Otherwise, these files in the DEBIAN directory within the binary package is generated by debhelper.
Whenever possible, simpler binarypackage.maintscript should be used instead.
See dh_installdeb(1) and “Chapter 6 - Package maintainer scripts and installation procedure” in the “Debian Policy Manual”.
See also debconf-devel(7) and “3.9.1 Prompting in maintainer scripts” in the “Debian Policy Manual”.
安裝至 debian/control 檔案列出的第一個二進位制套件中的 usr/share/doc/binarypackage/README.Debian 位置。
該檔案提供了針對該 Debian 套件的資訊。
參見 dh_installdocs(1)。
Installed into the first binary package listed in the debian/control file as usr/share/doc/binarypackage/README.source.
If running “dpkg-source -x” on a source package doesn’t produce the source of the package, ready for editing, and allow one to make changes and run dpkg-buildpackage to produce a modified package without taking any additional steps, creating this file is recommended.
如果該檔案存在,它將被安裝到 binarypackage 包下面的 lib/systemd/system/binarypackage.service 位置。
參見 dh_systemd_enable(1)、dh_systemd_start(1) 和 dh_installinit(1)。
Debian 套件格式。
See “SOURCE PACKAGE FORMATS” in dpkg-source(1).
These file is not installed, but are scanned by the lintian command to provide overrides for the source package.
另請參考 dh_lintian(1) 和 lintian(1)。
dpkg-source 命令使用此內容作為它的選項,比較重要的選項有:
該檔案不會包含在生成的原始碼套件中,僅對維護者在版本控制系統中維護套件有意義。
See “FILE FORMATS” in dpkg-source(1).
自由格式的文字,將被包含在自動生成補丁的頂部。
該檔案不會包含在生成的原始碼套件中,僅對維護者在版本控制系統中維護套件有意義。
See “FILE FORMATS” in dpkg-source(1).
這些符號檔案如果存在,將交由 dpkg-gensymbols 命令進行處理和安裝。
參見 dh_makeshlibs(1) 和 “節 10.16, “程式庫符號””。
安裝至 debian/control 檔案列出的第一個二進位制包中的 usr/share/doc/binarypackage/TODO.Debian 檔案。
參見 dh_installdocs(1)。
如果該檔案存在,它將被安裝至 binarypackage 包中的 usr/lib/tmpfiles.d/binarypackage.conf 檔案。
參見 dh_systemd_enable(1)、dh_systemd_start(1) 和 dh_installinit(1)。
If this exists, it is installed into etc/init/package.conf in the package build directory. (deprecated)
參見 dh_installinit(1)。
[11] This is the default up to debhelper v13. At debhelper v14, it warns the default change. After debhelper v15, it will change the default to DESTDIR=debian/tmp/ .
[12] 對九成以上的套件來說,套件名稱都不會超過 24 個字元;上游版本號通常不超過 10 個字元,而 Debian 修訂版本號也通常不超過 3 個字元。
[13] debmake 命令會產生稍微複雜一些的 debian/rules 檔案。雖然如此,其核心結構沒有什麼變化。
[14] This simplicity is available since version 7 of the debhelper package. This guide assumes the use of debhelper version 13 or newer.
[15] This is the default up to debhelper v13. At debhelper v14, it warns the default change. After debhelper v15, it will change the default to DESTDIR=debian/tmp/ .
[16] If you’re using the vim editor, make sure to save this with the ":wq" command.