Arch 打包準則
32 位 – CLR – CMake – Cross – DKMS – Eclipse – Electron – Font – Free Pascal – GNOME – Go – Haskell – Java – KDE – 內核模塊 – Lisp – Meson – MinGW – Node.js – Nonfree – OCaml – Perl – PHP – Python – R – Ruby – Rust – VCS – Web – Wine
在為 Arch Linux 構建軟件包時,您應該遵循以下的軟件包指導原則,尤其是當打算貢獻新軟件包至 Arch Linux 時。同時需要閱讀 PKGBUILD(5) 和 makepkg(8) man 手冊。
本頁中列出的重要項將不再於其它軟件包指導頁中指出,這些指導頁將作為以下準則的附加內容。
提交到 Arch 用戶軟件倉庫 (AUR) 的軟件包需要額外遵守 AUR 提交準則。
可在 /usr/share/pacman/
目錄下的 .proto 文件中查看更多 PKGBUILD
示例。
打包規則[編輯 | 編輯原始碼]
- 永遠別將軟件包安裝至
/usr/local/
- 除非非用不可,否則絕對不要在
PKGBUILD
中自定義和使用新的變量,以避免和 makepkg 本身的變量衝突。
- 在非用不可的情況下,需要給自定義變量名前加上下劃線 (
_
)。例如:_customvariable=
- 任何情況下都要避免使用
/usr/libexec/
,應該使用/usr/lib/${pkgname}/
。
- 包信息文件中的
packager
字段可以通過修改/etc/makepkg.conf
文件由編譯者進行自定義。使用~/.makepkg.conf
也可以達到此目的。
- 不要使用 makepkg 子程序(例如
error
,msg
,msg2
,plain
和warning
),這些隨時都可能會更改。請使用printf
或echo
來輸出內容。
- 所有安裝過程中所需輸出的重要的信息,都要放到 .install 文件中。比如說如果某軟件包需要擴展的安裝步驟才能正常運行,你可以將這些步驟的介紹包含在 .install 文件中。
- 依賴包是最容易出現錯誤的地方。請花時間仔細核對,例如對動態可執行文件執行
ldd
,檢查腳本需要的工具,查看軟件文檔等。namcap 可以幫助你,它可以解析 PKGBUILD 和生成的打包文件,報告權限錯誤、缺少依賴、過多依賴等常見問題。
- 任何運行該軟件包不需要,或者該軟件包的通用功能不需要的可選依賴不要加入到 depends 中。這些信息應該加入 optdepends 數組,例如:
optdepends=('cups: printing support' 'sane: scanners support' 'libgphoto2: digital cameras support' 'alsa-lib: sound support' 'giflib: GIF images support' 'libjpeg: JPEG images support' 'libpng: PNG images support')
- 例子取自 wine包 軟件包。這些信息在安裝和升級時會自動打印,所以不要將這些信息加入 .install 文件。
- 在填寫軟件包描述(description)時,請不要使用下定義的方式描述包名稱。比如說,「Nedit is a text editor for X11」 應當簡寫為 "A text editor for X11"。順便注意保持描述在 80 個字符以內.
- 儘量保持
PKGBUILD
文件中每行不超過100字符。
- 如果可能的話,從
PKGBUILD
文件中去掉空行(沒有設置變量值的行)(如provides
、replaces
等)
- 通常實踐建議按照 PKGBUILD 一文中的示例安排
PKGBUILD
各變量順序。當然這不是強制性的,這裡唯一強制要求的是滿足正確的 Bash 語法。
- 變量名可能包含空格時,請使用引號,例如
"$pkgdir"
和"$srcdir"
。
- 請確保軟件包的完整性,確保校驗變量包含正確的數值,可以通過
updpkgsums
工具進行更新。
軟件包命名[編輯 | 編輯原始碼]
- 軟件包應當僅包含字母或數字以及
@
,.
,_
,+
,-
,不能以-
和.
開頭,所有的字母應當保持小寫。
- 軟件包的名稱不應該包含上游的主版本號,例如如果上游軟件包是 libfoo v2.3.4,不應該命名為 libfoo2。這樣在上游發布新的大版本時,就可以保留軟件包名和依賴可以保持不變。只有個別軟件包是例外,例如圖形庫 GTK 和 Qt。這些軟件升級後,應用程序需要花很長時間和經歷才能移植完成,所以系統需要同時安裝多個版本,軟件包名應該包含大版本號,比如 gtk3、gtk4、qt5、qt6。如果出現大部分軟件包都可以同步升級,只有個別軟件沒有被移植的情況,可以把老的軟件包命名為 libfoo1,而新的軟件包繼續使用 libfoo。
軟件包版本號[編輯 | 編輯原始碼]
- 軟件包版本號(即
pkgver
)應當和作者發行版號保持一致。 - 如果需要的話,版本號可以包含字母(例如
2.54BETA32
)。 - 版本號裡不能包含連字符,只能允許字母、數字、下劃線、點號。如果上游版本號中出現了連字符,需要將其替換為下劃線。
- 軟件包發行號(即
pkgrel
)僅和 Arch 相關. 這樣用戶就可以區分不同的編譯版本。發布號從1開始,軟件包被重新(打包)發布時 ,發行號將增加1。 - 當新版本發布的時候,發行號(release)自動回到1。
- 軟件包發布標記和軟件包版本標記遵從同樣的規則。
軟件包依賴[編輯 | 編輯原始碼]
- 不要依賴 PKGBUILD#依賴關係 中的傳遞依存關係,因為依賴更新可能會導致關係中斷。
- 列出所有直接依賴庫,可以通過 find-libdeps(1)(devtools包 的組件)來完成。
軟件包關聯[編輯 | 編輯原始碼]
- 不要將
$pkgname
添加到 PKGBUILD#provides,該步驟由包本身隱式完成。 - 在 PKGBUILD#provides 中列出所有外部共享庫(如
'libsomething.so'
),可通過 find-libprovides(1)(devtools包 的組件)來完成。
軟件源[編輯 | 編輯原始碼]
- 儘可能使用 HTTPS 源:壓縮包使用
https://
,git 源使用git+https://
- 儘可能使用 PGP 簽名對源進行驗證(如果上游對提交進行了簽名,但沒有對壓縮包簽名,可能需要使用 git 標籤而不是源碼壓縮包進行構建。)
- 使用 git 標籤進行構建時,不要使用標籤名,要使用
git rev-parse
獲取到的對象哈希值
_tag=1234567890123456789012345678901234567890 # git rev-parse "v$pkgver" source=(git+https://$url.git?signed#tag=$_tag) pkgver() { cd "$pkgname" git describe }
- 具體案例可參考 gitea包 包。該操作的原因是,標籤可以被強制推送改變指向到的提交,從而導致構建出的包產生變化。強制推送會改變標籤的哈希值,從而使用標籤的對象哈希值可以確保源的完整性。使用
pkgver()
函數可避免在沒有更新_tag
的情況下不小心修改掉pkgver
。關於 VCS 源格式的更多信息請參考 VCS 軟件打包準則#VCS 源。
- Do not diminish the security or validity of a package (e.g. by removing a checksum check or by removing PGP signature verification), because an upstream release is broken or suddenly lacks a certain feature (e.g. PGP signature missing for a new release)
- 源在
srcdir
下的名稱不能相同(可能需要在下載時進行重命名,例如"${pkgname}-${pkgver}.tar.gz::https://${pkgname}.tld/download/${pkgver}.tar.gz"
) - 避免使用特定鏡像源(如 sourceforge)進行下載,因為它們有可能會變得不可用
與上游協作[編輯 | 編輯原始碼]
It is considered best-practice to work closely with upstream wherever possible. This entails reporting problems about building and testing a package.
- Report problems to upstream right away.
- Upstream patches wherever possible.
- Add comments with links to relevant (upstream) bug tracker tickets in the PKGBUILD (this is particularly important, as it ensures, that other packagers can understand changes and work with a package as well).
It is recommended to track upstream with tools such as nvchecker包, nvrsAUR or urlwatch包 to be informed about new stable releases.
目錄[編輯 | 編輯原始碼]
- 配置文件應該放置到
/etc
目錄。如果有多個配置文件,可以使用子目錄,以保持/etc
簡潔。例如,如果包名是pkg
,那就應使用/etc/pkg
(或者其他合適的名稱,比如apache使用的就是/etc/httpd/
)。
- 軟件包文件應該安裝在下列常用目錄:
/etc
系統關鍵配置文件 /usr/bin
二進制文件 /usr/lib
庫 /usr/include
頭文件 /usr/lib/pkg
模塊,插件等 /usr/share/doc/pkg
應用程序文檔 /usr/share/info
GNU Info 系統文件 /usr/share/licenses/pkg
Application licenses /usr/share/man
手冊 /usr/share/pkg
程序數據 /var/lib/pkg
應用持久數據 /etc/pkg
pkg 應用的配置文件 /opt/pkg
大的獨立程序,例如 Java
- 軟件包不應該在下面目錄添加任何文件:
/bin
/sbin
/dev
/home
/srv
/media
/mnt
/proc
/root
/selinux
/sys
/tmp
/var/tmp
/run
Makepkg 的任務[編輯 | 編輯原始碼]
當您使用 makepkg 構建軟件包時,makepkg 會自動執行如下功能:
- 檢查軟件包的依賴和構建依賴是否已安裝
- 從服務器中下載源文件
- 校驗源文件的完整性
- 解壓源文件
- 打上必要的補丁(patch)
- 構建軟件並安裝到 fake root
- 從可執行文件中去掉符號標記
- 從庫文件中去掉調試標記
- 壓縮手冊頁和/或 info 頁
- 生成包信息文件(包含軟件包的基本信息)
- 壓縮 fake root 成為軟件包文件(*.pkg.tar.xz)
- 生成的軟件包文件保存在指定的目錄中(默認在當前目錄)
架構[編輯 | 編輯原始碼]
如果該軟件包是針對特定架構編譯的,那麼 arch
數組應該包含 'x86_64'
,否則使用 'any'
生成架構無關的包。
授權協議[編輯 | 編輯原始碼]
請參考 PKGBUILD#license
可復現構建[編輯 | 編輯原始碼]
Arch 正努力使所有軟件包具有可復現性。打包人員可通過 devtools包 的 makerepropkg
或 archlinux-repro包 的 repro
來檢查包是否有可復現性:
$ makerepropkg $pkgname-1-1-any.pkg.tar.zst
或
$ repro -f $pkgname-1-1-any.pkg.tar.zst
如果在構建時需要使用時間戳,可以使用 SOURCE_DATE_EPOCH
環境變量,具體格式可參考上游文檔。