Cargo 项目生成的 Debian 包

这是一个 Cargo 辅助命令，它可以从 Cargo 项目自动创建二进制 Debian 包 (.deb)。

安装

rustup update   # Debian's Rust is too outdated, use rustup.rs
cargo install cargo-deb

需要 Rust 1.71+，可选 dpkg，dpkg-dev 和 liblzma-dev。兼容 Ubuntu。如果 LZMA 依赖项让你头疼，尝试 cargo install cargo-deb --no-default-features。

如果你遇到编译错误，请运行 rustup update！如果你在运行 rustup update 时遇到错误，请卸载你的 rust/cargo 包，然后安装 官方 Rust。

用法

cargo deb

在Rust项目的根目录下运行 cargo deb 命令后，Debian软件包将创建在 target/debian/<项目名称>_<版本>-1_<架构>.deb 目录（或您可以使用 --output 选项更改位置）。此软件包可以使用 dpkg -i target/debian/*.deb 命令进行安装。

cargo deb --install 命令将构建并安装项目到系统范围内。

配置

从带有二进制的Cargo项目创建基本软件包不需要配置。此命令从 Cargo.toml 文件 获取所需的基本信息。它使用Cargo字段：name、version、license、license-file、description、readme、homepage 和 repository。

对于更完整的Debian软件包，您还可以定义一个新表 [package.metadata.deb]，其中包含 maintainer、copyright、license-file、changelog、depends、conflicts、breaks、replaces、provides、extended-description/extended-description-file、section、priority 和 assets。

对于包含一个或多个systemd单元文件的Debian软件包，您还可以定义一个新（内联）表 [package.metadata.deb.systemd-units]，以便将单元文件自动添加为资产，并正确安装单元。请参阅 Systemd集成

调试符号

默认情况下，从构建的二进制文件中删除调试符号，除非在 Cargo.toml 中设置了 [profile.release] debug = true。如果运行 cargo deb --separate-debug-symbols，调试符号将作为单独的文件打包，并安装到 /usr/lib/debug/<build-id-or-path>.debug。这也可以通过在 separate-debug-symbols 下在 [package.metadata.deb] 中启用。

[package.metadata.deb] 选项

所有选项都是可选的

• name：Debian软件包的名称。如果不存在，则使用crate的名称。
• maintainer：维护Debian软件包的人。如果不存在，则使用第一位作者。可以在命令行上通过 --maintainer 设置。
• 版权：软件版权授予的对象和时间。如果不存在，则使用作者列表。
• 许可文件：包含许可证文件位置和顶部需要跳过的行数的2元素数组。如果不存在，则使用包级别的license-file。
• 依赖：项目的运行时依赖关系。如果不存在或列表包含$auto关键字时，将自动生成。
• 前置依赖：项目的前置依赖关系。默认为空。
• 推荐依赖：项目的推荐依赖关系。默认为空。
• 建议依赖：项目的建议依赖关系。默认为空。
• 增强：此包可以增强的包列表。默认为空。
• 冲突、破坏、替换、提供 — 包转换 控制。
• 扩展描述：项目的扩展描述 — 越详细越好。如果未提供，则使用 扩展描述文件（见下文）或包的 readme 文件。
• 扩展描述文件：包含项目扩展描述的文件。如果指定，则在未提供 扩展描述 时使用。
• 修订版：Debian 包的附加版本（当包更新频率高于项目时）。默认为 "1"，但可以设置为空字符串以省略修订版。可以通过命令行上的 --deb-revision 设置。
• 类别：软件所属的应用程序类别。
• 优先级：定义包是否是 required（必需）或 optional（可选）。
• 资产：要包含在包中的文件和分配给它们的权限。如果没有指定资产，则默认从列出的二进制文件中获取（复制到 /usr/bin/）和包的 readme 文件（复制到 usr/share/doc/…）。
  1. 每个资产的第一个参数是该资产在 Rust 项目中的位置。允许使用通配符模式。您可以在资产路径中使用 target/release/，即使 Cargo 已配置为交叉编译或使用自定义 CARGO_TARGET_DIR。目标目录路径将被自动纠正。
  2. 第二个参数是文件将被复制到的位置。
     • 如果参数以 / 结尾，则将推断目标为文件将被复制的目录。
     • 否则，将推断源参数将在复制时重命名。
  3. 第三个参数是分配给该文件的权限（八进制字符串）。
• 合并资产：请参阅“高级用法”下的“合并资产”部分
• 维护者脚本：包含 templates、preinst、postinst、prerm 或 postrm 脚本 的目录。
• conf-files：在包升级时包管理系统不会覆盖的配置文件列表。
• triggers-file：dpkg触发功能使用的触发控制文件的路径。
• changelog：Debian格式的变更日志文件的路径。
• features：在构建包时使用的Cargo功能列表。
• default-features：是否使用除features列表之外的默认crate功能（默认true）。
• separate-debug-symbols：是否保留调试符号，但将其从可执行文件中剥离并保存到单独的文件中（默认false）。如果启用，则可以使用cargo deb --no-separate-debug-symbols来抑制调试符号的提取。
• preserve-symlinks：是否在资产文件中保留符号链接（默认false）。
• systemd-units：用于自动安装systemd单元的可选配置设置。
• conf-files：位于/etc之外的配置文件的绝对路径列表["/not-etc/app/config"]。您仍然需要在assets中列出文件以将它们打包。

自定义Cargo.toml添加示例

[package.metadata.deb]
maintainer = "Michael Aaron Murphy <[email protected]>"
copyright = "2017, Michael Aaron Murphy <[email protected]>"
license-file = ["LICENSE", "4"]
extended-description = """\
A simple subcommand for the Cargo package manager for \
building Debian packages from Rust projects."""
depends = "$auto"
section = "utility"
priority = "optional"
assets = [
    ["target/release/cargo-deb", "usr/bin/", "755"],
    ["README.md", "usr/share/doc/cargo-deb/README", "644"],
]

高级使用方法

Debian包可以使用多种不同的压缩格式，但目标系统可能只支持其中的一些。默认格式目前是xz，但这可能在任何时候改变以支持新的格式。可以使用--compress-type命令行选项显式指定格式。支持的格式有"gzip"和"xz"。

--fast标志使用较轻的压缩。对于非常大的包或快速部署很有用。

--compress-system强制使用系统命令行工具进行数据压缩。

[package.metadata.deb.variants.$name]

在单个Cargo.toml文件中可以存在多个元数据的变体。使用--variant=name选择要使用的变体。变体中设置的选项会覆盖[package.metadata.deb]选项。它会自动调整包名。

合并资产

在定义变体时，也可以定义不同的资产。如果使用merge-assets选项，则cargo-deb会将提供的选项与父资产列表合并。有三种合并策略：append、by.dest和by.src。

• merge-assets.append：将此资产列表追加到父资产列表。
• merge-assets.by.dest：将此资产列表合并到父资产列表中，按目标路径合并。将替换源路径和权限。
• merge-assets.by.src：将此资产列表合并到父资产列表中，按源路径合并。将替换目标路径和权限。

注意：同时使用 append 和 by.* 选项是被允许的，其中前者在后者之前应用。

merge-assets 的示例

# Example parent asset list
[package.metadata.deb]
assets = [
    # binary
    ["target/release/example", "usr/bin/", "755"],
    # assets
    ["assets/*", "var/lib/example", "644"],
    ["target/release/assets/*", "var/lib/example", "644"],
    ["3.txt", "var/lib/example/3.txt", "644"],
    ["3.txt", "var/lib/example/merged.txt", "644"],
]

# Example merging by appending asset list
[package.metadata.deb.variants.mergeappend]
merge-assets.append = [
    ["4.txt", "var/lib/example/appended/4.txt", "644"]
]

# Example merging by `dest` path
[package.metadata.deb.variants.mergedest]
merge-assets.by.dest = [
    ["4.txt", "var/lib/example/merged.txt", "644"]
]

# Example merging by `src` path
[package.metadata.deb.variants.mergesrc]
merge-assets.by.src = [
    ["3.txt", "var/lib/example/merged-2.txt", "644"]
]

# Example merging by appending and by `src` path
[package.metadata.deb.variants.mergeappendandsrc]
merge-assets.append = [
    ["4.txt", "var/lib/example/appended/4.txt", "644"]
]
merge-assets.by.src = [
    ["3.txt", "var/lib/example/merged-2.txt", "644"]
]

[package.metadata.deb.systemd-units]

参见 systemd 集成.

交叉编译

cargo deb 支持交叉编译。它可以从任何类 Unix 主机运行，包括 macOS，只要构建环境已设置为交叉编译。

• 交叉编译的目标必须通过 rustup 安装（例如 rustup target add i686-unknown-linux-gnu）并且必须在 主机系统上安装（例如 apt-get install libc6-dev-i386）。注意，Rust的 和 Debian的架构名称 是不同的。有关支持 --target 参数的值的列表，请参阅 rustc --print target-list。
• 必须安装与 Linux 兼容的链接器和系统库（例如 glibc 或 musl），并可供 Rust/Cargo 使用。
  • dpkg--添加-架构<Debian 架构名称>
  • apt-get安装 pkg-config build-essential crossbuild-essential-<Debian 架构名称>
• Cargo 必须配置为使用交叉链接器 。
• 使用 C 库的 Cargo 依赖项可能无法正常工作，除非您为 pkg-config 安装目标系统的 sysroot。将 PKG_CONFIG_ALLOW_CROSS=1 设置为 不会有所帮助，并且只会使事情变得更糟。
  • apt-get安装 libssl-dev<Debian 架构名称>
• 构建 C 代码的 Cargo 依赖项可能无法正常工作，除非您为目标系统安装 C 编译器并配置适当的 CC_<target> 变量。
  • 导出 HOST_CC=gcc
  • export CC_x86_64_unknown_linux_gnu=/usr/bin/x86_64-linux-gnu-gcc（根据您的操作系统正确修改目标和路径）
• 除非您安装与目标兼容的版本并在 .cargo/config 中配置它们的路径，否则解包可能无法正常工作，通过添加 [target.<target triple>] strip = { path = "…" } objcopy = { path = "…" }。或者，使用 --no-strip。

是的，这些要求很苛刻。您也可以尝试 cross 或 cargo zigbuild，因为Zig在交叉编译方面表现得更好，然后运行 cargo deb --target=… --no-build。

cargo deb --target=i686-unknown-linux-gnu

交叉编译的存档保存在 target/<target triple>/debian/*.deb。实际存档路径在成功时打印。

请注意，您不能使用交叉编译来为较旧的Debian版本构建。如果您需要支持比宿主系统更早的Debian版本，请考虑使用容器或虚拟机，或者为MUSL制作一个完全静态的二进制文件。

单独的调试信息

要获取调试符号，请在 Cargo.toml 中设置

[profile.release]
debug = true
# or debug="line-tables-only" for smaller files

注意：有意不支持使用 dev 配置文件进行构建。

cargo deb --separate-debug-symbols --compress-debug-symbols

从可执行文件中删除调试符号，并将它们放置在 /usr/lib/debug/.build-id/* 中的单独文件中。需要GNU objcopy 工具。 --compress-debug-symbols 使用zstd，并需要 objcopy 支持。

自定义构建标志

如果您想自己处理构建过程，可以使用 cargo deb --no-build，这样 cargo-deb 命令将不会尝试重新构建您的项目。

cargo deb -- <cargo build flags>

位于 -- 之后的所有标志都传递给 cargo build，因此您可以使用 -Z、--frozen 和 --locked 等选项。请仅用于 cargo-deb 无法原生支持的特性。

工作区

Cargo-deb 理解工作区，并在必要时可以构建工作区中的所有crates。但是，您必须选择一个crates作为包元数据的来源。您可以使用 --p crate_name 或 --manifest-path=<path/to/Cargo.toml> 来选择要构建的crates。

自定义版本字符串

cargo deb --deb-version 1.my-custom-version

覆盖由Cargo清单生成的版本字符串，包括修订版本。或者，可以使用 --deb-revision 仅更改后缀。

故障排除

要获取最大日志记录，请使用

RUST_LOG=debug cargo deb --verbose

对 lzma_stream_encoder_mt 的未定义引用错误

这发生在系统提供的LZMA库太旧时。尝试使用捆绑的版本

cargo install cargo-deb --features=static-lzma

或通过设置 --compress-system 标志使用 xz 命令行工具。

[!NOTE] cargo-deb 使用 xz2 crate，该crate由原始维护者捆绑了一个旧的安全版本liblzma 5.2和一个简单的基于Cargo的构建脚本。它 不受 CVE-2024-3094 影响。