跳转至内容

Arch 软件包指南

来自 ArchWiki
Arch 软件包指南

32位 – CLR – CMake – 交叉编译 – DKMS – Eclipse 插件 – Electron – 字体 – Free Pascal – GNOME – Go – Haskell – Java – KDE – 内核模块 – Lisp – Meson – MinGW – Node.js – 非自由软件 – OCaml – Perl – PHP – Python – R – Ruby – Rust - 安全 – Shell – VCS – Web 应用 – Wine

相关文章

在为 Arch Linux 构建软件包时，请遵守以下软件包指南，特别是当您打算为 Arch Linux 贡献新软件包时。您还应该查看 PKGBUILD(5) 和 makepkg(8) 的 man 页。

本页列出的重要事项不会在其他软件包指南页上重复。这些特定指南旨在作为对以下标准进行补充。

提交到 Arch 用户仓库 的软件包还必须遵守 AUR 提交指南。

请参阅 /usr/share/pacman/ 目录 中的 .proto 文件作为 PKGBUILD 示例。

软件包礼仪

  • 软件包绝对不应安装到 /usr/local/。
  • 请勿在 PKGBUILD 构建脚本中引入新的变量或函数，除非软件包无法在没有它们的情况下构建，因为这些可能会与 makepkg 本身使用的变量和函数冲突。
  • 如果绝对需要新的变量或函数，请在名称前加上下划线 (_)，例如
    _customvariable=
  • 避免使用 /usr/libexec/。请使用 /usr/lib/$pkgname/ 代替。
  • 软件包构建者可以通过修改 /etc/makepkg.conf 文件中的相应选项，或通过创建 ~/.makepkg.conf 来覆盖，来自定义软件包元文件中的 packager 字段。
  • 请勿使用 makepkg 子例程 (例如 error, msg, msg2, plain, warning)，因为它们可能会随时更改。要打印数据，请使用 printf 或 echo。
  • 所有重要的消息都应在安装过程中通过 .install 文件 回显。例如，如果软件包需要额外的设置才能工作，应包含说明。
  • 依赖项是最常见的打包错误。请花时间仔细验证它们，例如通过对动态可执行文件运行 ldd，检查脚本所需的工具或查看软件的文档。namcap 实用程序可以在这方面为您提供帮助。此工具可以分析 PKGBUILD 和生成的软件包 tarball，并会警告您权限不当、缺少依赖项、重复的依赖项以及其他常见错误。
  • 任何可选依赖项，如果不是运行软件包或使其正常运行所必需的，则不应包含在 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 软件包。optdepends 信息会在安装/升级时自动打印出来，因此不应将此类信息保留在 .install 文件中。
  • 创建软件包的软件包描述时，请勿以自我引用方式包含软件包名称。例如，“Nedit is a text editor for X11”可以简化为“A text editor for X11”。另外，请尽量将描述保持在 80 个字符以内。
  • 尽量将 PKGBUILD 中的行长度保持在 100 个字符以内。
  • 在可能的情况下，删除 PKGBUILD 中的空行（provides, replaces 等）。
  • 通常的做法是保持 PKGBUILD 字段的顺序，使其与 PKGBUILD 文章中给出的顺序相同。但是，这并非强制要求，因为在此上下文中唯一的要求是正确的 Bash 语法。
  • 引用可能包含空格的变量，例如 "$pkgdir" 和 "$srcdir"。

包命名

  • 软件包名称只能包含字母数字字符以及 @, ., _, +, -。名称不允许以连字符或点开头。所有字母都应为小写。
  • 软件包名称不应附加上游主版本号（例如，我们不希望 libfoo2 如果上游称之为 libfoo v2.3.4），因为库及其依赖项预计能够继续使用每个相应上游版本发布的最新库版本。然而，对于某些软件或依赖项，不能假定这一点。过去，这对于 GTK 和 Qt 等小部件工具包尤其如此。依赖于此类工具包的软件通常无法轻易移植到新的主版本。因此，在软件无法轻松与依赖项保持同步的情况下，软件包名称应带有主版本后缀（例如，gtk2, gtk3,qt4,qt5）。对于大多数依赖项可以与最新版本保持同步但有些不能（例如需要 libpng12 或类似库的闭源软件）的情况，该软件包的已弃用版本可能称为 libfoo1，而当前版本仅称为 libfoo。

软件包版本

  • 软件包版本 — pkgver — 应与作者发布的版本相同。
  • 如有需要，版本可以包含字母，例如版本可以是 2.54BETA32。
  • 版本标签可能不包含连字符，只能包含字母、数字和句点。如果上游版本包含连字符，则必须将其替换为下划线。


  • 软件包发布 — pkgrel — 特定于 Arch Linux 软件包。这些允许用户区分新旧软件包构建。当新软件包版本首次发布时，发布计数从 1 开始。然后，随着修复和优化，软件包将被重新发布给 Arch Linux 公众，并且发布编号将递增。
  • 当新版本发布时，发布计数将重置为 1。
  • 软件包发布标签遵循与版本标签相同的命名限制。

软件包依赖

软件包关系

软件包来源

  • 尽可能使用 HTTPS 源（tarball 使用 https://，git 源使用 git+https://）。
  • 尽可能使用 PGP 签名验证源（这可能需要从 git 标签而不是源 tarball 构建，如果上游对提交和标签进行签名但不对 tarball 进行签名）。

本文或本章节的准确性存在争议。

原因：最近的 pacman 不需要 commit#，因为它支持 git 源的正确校验和。请参阅 [1]。gitea 软件包也已更新为使用以下方法（请在 Talk:Arch package guidelines 中讨论）。
  • 从 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 源。
  • 请勿降低软件包的安全性或有效性（例如，通过删除校验和检查或移除 PGP 签名验证），因为上游版本已损坏或突然缺少某个功能（例如，新版本缺少 PGP 签名）。
  • 源在 srcdir 中必须是唯一的（这可能需要在下载时重命名它们，例如 "${pkgname}-${pkgver}.tar.gz::https://${pkgname}.tld/download/${pkgver}.tar.gz"）。
  • 避免使用特定的镜像（例如，在 sourceforge 上）进行下载，因为它们可能会变得不可用。
  • 使用 SSH 密钥签名的 Git 对象（例如，标签、提交等）可以通过 Git 命令进行验证，其中 gpg.ssh.allowedSignersFile 指向一个指定可能签名密钥的文件。请参阅 [2] 获取示例。

与上游合作

与上游紧密合作被认为是最佳实践。这包括报告软件包构建和测试中的问题。

  • 立即向报告问题给上游。
  • 尽可能对上游进行补丁。
  • 在 PKGBUILD 中添加带有指向相关（上游）错误跟踪器票证链接的注释（这尤其重要，因为它确保了其他打包者能够理解更改并能使用该软件包）。

建议使用 nvchecker、nvrsAUR 或 urlwatch 等工具跟踪上游，以便获知新的稳定版本。

目录

  • 配置文件应放置在 /etc 目录中。如果存在多个配置文件，习惯上使用子目录以保持 /etc 区域尽可能整洁。使用 /etc/pkg，其中 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 应用程序许可证
/usr/share/man Man pages
/usr/share/pkg 应用程序数据
/var/lib/pkg 持久性应用程序存储
/etc/pkg pkg 的配置文件
/opt/pkg 大型独立软件包
  • 软件包不应包含以下任何目录
    • /bin
    • /sbin
    • /dev
    • /home
    • /srv
    • /media
    • /mnt
    • /proc
    • /root
    • /selinux
    • /sys
    • /tmp
    • /var/tmp
    • /run

Makepkg 的职责

当使用 makepkg 构建软件包时，它会自动执行以下操作：

  1. 检查软件包依赖项和构建依赖项是否已安装
  2. 从服务器下载源文件
  3. 检查源文件的完整性
  4. 解压源文件
  5. 执行任何必要的补丁
  6. 构建软件并将其安装在假根目录中
  7. 从二进制文件中剥离符号
  8. 从库中剥离调试符号
  9. 压缩手册页和/或 info 页
  10. 生成包含在每个软件包中的软件包元文件
  11. 将假根目录压缩到软件包文件中
  12. 将软件包文件存储在配置的目录中（默认情况下是当前工作目录）

架构

如果编译的软件包是特定于架构的，则 arch 数组应包含 'x86_64'。否则，对于与架构无关的软件包，请使用 'any'。

许可证

关于 Arch 软件包有两种许可证：

PKGBUILD 的 license 字段

PKGBUILD 的 license 字段。它列出了打包软件的上游许可证。它不是软件包源的许可证。此字段中的许可证必须采用SPDX 许可证格式。有关更多详细信息，请参阅 PKGBUILD#license。

软件包来源许可证

软件包来源本身的许可证。在 RFC40 中，Arch Linux 指定软件包来源应使用 0BSD 许可证，而 RFC52 指定应使用 REUSE 来强制执行此规定。

归根结底是这样：

  1. 在源根目录中包含一个 LICENSE 文件，其内容完全与此相同：此内容。这是 Arch Linux 的软件包 0BSD 许可证。
  2. 在源根目录中包含一个 REUSE.toml。您可以使用 pkgctl license setup 来生成一个合理的配置以供开始。
  3. 确保运行 pkgctl license check，并且它不会返回任何错误。

如果您有需要许可的其他文件，您需要为它们选择一个合理的许可证。这通常相当直接：

  • 如果相关文件（例如，启动脚本 launcher.sh 或 systemd 服务文件 myunit.service）完全由您或其他 Arch 员工创建，则将其许可为 0BSD。
    注意 如果您编写了一个补丁并希望将其提交给上游，您仍然可以将其许可为 Arch 的 0BSD，并允许上游在提交时应用其许可证。
  • 如果文件来自上游（例如，图标 tool.png 或补丁 fix.patch），则它应带有上游许可证。

另请参阅介绍 pkgctl-license(1) 的 Arch Linux 开发博客文章。

可复现构建

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。格式已在上游文档中记录。

取自“https://wiki.archlinux.org.cn/index.php?title=Arch_package_guidelines&oldid=857529”