Tugger Starlark 类型详解:用 SnapPart 在 snapcraft.yaml 中声明构建部件

原创2026-10-09 15:54:471,822 阅读
文章标签:开发工具CLI

Tugger Starlark 类型详解:用 SnapPart 在 snapcraft.yaml 中声明构建部件

SnapPart 是 Tugger 项目 Starlark 方言中用于描述 snapcraft.yaml 文件里 parts.<part-name> 条目值的核心类型,它把传统手写的 Snapcraft 部件配置完整映射为一组可编程的 Starlark 属性。本文基于仓库中的 tugger/docs/tugger_starlark_type_snap_part.rst 文档,并结合 tugger/src/starlark/snapcraft.rs 与 tugger-snapcraft/src/yaml.rs 的源码实现,系统讲解 SnapPart 的每个属性、类型校验规则以及它如何参与 Snap → SnapcraftBuilder → snapcraft 命令的完整构建链路。读完本文,你将能够用 Tugger 的 Starlark 配置语言完整声明一个 Snap 部件的源码获取、构建依赖、环境变量、override 钩子与产物整理规则,并理解每个属性在底层序列化与类型约束上的真实行为。

一、SnapPart 是什么:Snapcraft 部件模型的结构化投影

在 Snapcraft 的 snapcraft.yaml 配置文件中,parts 是顶层键,每个 parts.<part-name> 键值定义了一个"部件(part)":它描述了如何获取源码(source 系列字段)、用什么插件构建(plugin)、需要哪些构建/暂存依赖(build_packages、stage_packages)、如何整理构建产物(organize、stage、prime)以及如何自定义构建过程(override_* 钩子)。

Tugger 将这一结构以 Rust 类型 SnapPart 建模,并在 Starlark 方言层提供同名类型 SnapPart 供配置文件使用。两者之间的对应关系可以从 tugger-snapcraft/src/lib.rs 的导出列表(SnapApp, SnapPart, Snapcraft, SnapcraftBuilder 等)得到印证。

从 tugger/docs/tugger_starlark_type_snap_part.rst 文档的定义可以提炼出以下三条核心语义:

  1. SnapPart 类型表示 snapcraft.yaml 中 parts.<part-name> 键的值,它暴露的属性与 parts.<part-name> 条目内的键一一对应;
  2. 当前所有属性都是"只写"(write only)的——Starlark 侧只能通过赋值构建配置,无法读取回值,这与 Snap、SnapApp 等类型的设计一致;
  3. 将某属性赋值为 None 会产生副作用:从序列化后的 snapcraft.yaml 中移除该属性——这为"动态裁剪配置"提供了便利。

注:关于每个属性在 Snapcraft 语义中的详细含义,文档指向了 Snapcraft 官方 YAML 参考(snapcraft.yaml reference),本文则聚焦于 Tugger 侧的类型、取值约束与序列化行为。

1.1 构造方式

part = SnapPart()

SnapPart() 创建一个空实例,不接受任何参数。这对应 tugger/src/starlark/snapcraft.rs 中注册的 Starlark 全局函数 SnapPart():它直接返回 SnapPartValue::default(),即所有字段均为默认值(空列表、空字典、None)的空部件。

创建后,你可以通过属性赋值逐步填充配置。赋值过程中,每个属性都会经过独立的类型转换与校验函数,非法值会抛出运行时错误(错误码为 TUGGER_SNAPCRAFT)。

二、SnapPart 全部属性速查与类型约束

下面按功能分组列出 tugger/docs/tugger_starlark_type_snap_part.rst 中定义的全部 27 个属性,并补充 tugger-snapcraft/src/yaml.rs 中 SnapPart 结构体的底层字段类型与序列化规则(#[serde(rename_all = "kebab-case")] 意味着 Starlark 属性名在输出 YAML 时会被转换为 kebab-case,例如 build_attributes → build-attributes、stage_packages → stage-packages)。

2.1 源码获取(Source)相关

Starlark 属性 类型 对应 YAML 键 说明
source Optional[str] source 部件的源码位置,可以是本地路径或 URL
source_type Optional[str] source-type 源码类型,见下方枚举
source_checksum Optional[str] source-checksum 源码校验和(如 md5:...、sha256:...)
source_depth Optional[int] source-depth VCS 拉取深度
source_branch Optional[str] source-branch VCS 分支
source_commit Optional[str] source-commit VCS 提交/修订号
source_tag Optional[str] source-tag VCS 标签
source_subdir Optional[str] source-subdir 源码中的子目录

source_type 的取值不是自由字符串,而是由 Rust 枚举 SourceType 严格校验的:bzr、deb、git、hg、local、mercurial、rpm、subversion、svn、tar、zip、7z。序列化时同样使用小写形式输出。从 tugger/src/starlark/snapcraft.rs 的 value_to_optional_source_type 可以看到:除 NoneType 外,字符串会被 SourceType::try_from(...) 解析,无法识别的取值会抛出带 TUGGER_SNAPCRAFT 错误码的 ValueError。

source_depth 是 Optional<a href="https://link.gitcode.com/i/0e7feb5ab542d8cdca47235ce21b5433" target="_blank">int],底层字段为 Option<i64>([tugger-snapcraft/src/yaml.rs),在 tugger/src/starlark/snapcraft.rs 中通过 value.try_to_optional()? 完成整数转换。

2.2 构建定义相关

Starlark 属性 类型 对应 YAML 键 说明
plugin Optional[str] plugin 使用的 Snapcraft 插件(如 nil、rust、python 等)
build_attributes Optional[list[str]] build-attributes 构建属性,见下方枚举
build_environment Optional[list[dict[str, str]]] build-environment 构建期环境变量列表
build_packages Optional[list[str]] build-packages 构建期需要的系统包
build_snaps Optional[list[str]] build-snaps 构建期需要的 snap
parse_info Optional[str] parse-info 定义插件可解析的信息文件路径

build_attributes 同样不是自由字符串:底层枚举 BuildAttribute 只接受 debug、keep-execstack、no-patchelf、enable-patchelf、no-install 五个取值,序列化为 kebab-case。对应的校验函数 value_to_build_attributes(tugger/src/starlark/snapcraft.rs)会遍历列表中的每个元素做 BuildAttribute::try_from 解析,非 None/非 list 的值会直接报错。

build_environment 的类型是 Optional<a href="https://link.gitcode.com/i/cb828ac97175937a5ae105aef68ad7f6" target="_blank">list[dict[str, str]]],即"环境变量字典的列表",这在 Snapcraft 语义中允许按顺序叠加多组环境变量。Rust 侧对应 Vec<HashMap<Cow<str>, Cow<str>>>,转换函数为 optional_vec_str_hashmap_to_vec([tugger/src/starlark/snapcraft.rs)。

2.3 暂存与整理相关

Starlark 属性 类型 对应 YAML 键 说明
stage_packages Optional[list[str]] stage-packages 暂存期引入的系统包(含其依赖)
stage_snaps Optional[list[str]] stage-snaps 暂存期引入的 snap
organize Optional[dict[str, str]] organize 将暂存目录中的文件重新布局(源路径 → 目标路径)
filesets Optional[dict[str, list[str]]] filesets 命名文件集合,可在 stage/prime 中引用
stage Optional[list[str]] stage 暂存阶段包含/排除的文件集合
prime Optional[list[str]] prime 打包进 snap 的最终文件集合

organize 与 filesets 都要求字典类型,转换函数分别是 optional_str_hashmap_to_hashmap(键值均为字符串)和 value_to_filesets(值为字符串列表)。特别注意:filesets 的值不允许为 None——从 tugger/src/starlark/snapcraft.rs 可以看到,如果字典某键的值为 None,会抛出 "filesets values must be lists of strings" 错误。

stage 和 prime 是 Snapcraft 中最常用的文件筛选列表,支持 - 前缀排除语法,例如:

part.stage = ['usr/bin/*', '-usr/share/doc/*']
part.prime = ['usr/bin/*', '-usr/share/doc/*']

2.4 构建钩子(override 系列)

Starlark 属性 类型 对应 YAML 键 说明
override_pull Optional[str] override-pull 自定义 pull 步骤的脚本
override_build Optional[str] override-build 自定义 build 步骤的脚本
override_stage Optional[str] override-stage 自定义 stage 步骤的脚本
override_prime Optional[str] override-prime 自定义 prime 步骤的脚本

这四个属性均为 Optional[str],赋值一个 shell 脚本字符串即可覆盖 Snapcraft 对应阶段的默认行为。它们也是最常用于"接管"构建流程的手段,下文会给出完整示例。

2.5 部件依赖

Starlark 属性 类型 对应 YAML 键 说明
after Optional[list[str]] after 声明当前部件依赖的其他部件名,用于控制执行顺序

2.6 全部属性的"None 即移除"语义

文档明确指出:将任一属性设为 None 会从序列化的 snapcraft.yaml 中移除该属性。这一行为与 Rust 侧的序列化规则完全对应——查看 tugger-snapcraft/src/yaml.rs 中 SnapPart 结构体,可以看到所有 Option 字段都标注了 #[serde(skip_serializing_if = "Option::is_none")],所有集合字段都标注了 #[serde(default, skip_serializing_if = "Vec::is_empty")] / #[serde(default, skip_serializing_if = "HashMap::is_empty")]。也就是说:None、空列表、空字典的属性都不会出现在最终 YAML 中。这对于按条件组装配置(例如"只在特定目标上设置 build_packages")非常实用:

part = SnapPart()

# 条件化:某些平台需要额外构建依赖
if target_platform == "linux":
    part.build_packages = ['libssl-dev', 'pkg-config']

# 需要时再追加,不需要时置 None 即可从 YAML 中剔除
part.stage_packages = None

三、底层实现:属性赋值如何被解析与校验

SnapPart 在 Starlark 层的承载类型是 SnapPartValue,它实现了 TypedValue::set_attr:每个属性名都对应一个专门的 match 分支,把 Starlark 的 Value 转换为 SnapPart 内部字段。从源码结构看,属性校验呈现出如下规律:

  • 自由字符串/字符串数组:直接通过 value.to_optional() 或 optional_str_vec_to_vec(value) 转换,不做内容级校验(如 source、plugin、after、build_packages);
  • 受限枚举字符串:必须通过 TryFrom<&str> 解析,失败即报错(如 source_type、build_attributes);
  • 整数:source_depth 使用 value.try_to_optional()?,需要 Starlark int 值;
  • 字典:organize、filesets、build_environment 各有专属转换函数,结构不匹配时报错;
  • 未知属性:落入兜底分支,抛出 OperationNotSupported 错误,提示该属性对 SnapPart 不支持(tugger/src/starlark/snapcraft.rs)。

这意味着配置阶段的错误能被尽早捕获,而不是等到 snapcraft 运行阶段才暴露。

仓库自带的单元测试 test_part_basic 覆盖了全部属性的赋值路径,是一个极佳的"属性用法速查",例如:

env.eval("part.build_attributes = ['debug', 'no-patchelf']")?;
env.eval("part.build_environment = [{'env0': 'env1'}]")?;
env.eval("part.filesets = {'set0': ['val0', 'val1']}")?;
env.eval("part.source_type = 'hg'")?;
env.eval("part.source_depth = 42")?;

测试中所有属性被赋值后,SnapPartValue 的内部结构与期望值逐字段比对通过,这从侧面验证了属性名、类型与序列化字段之间的一一对应关系。

四、实战示例:声明一个构建 Rust 项目的 SnapPart

将 SnapPart 放入 Snap 的 parts 字典后,即可生成完整的 snapcraft.yaml。综合 tugger-snapcraft/src/builder.rs 中 test_build_rust_project 测试用例的配置模式,下面是一个通过 nil 插件 + override_build 自定义构建的典型部件声明:

snap = Snap(
    name = "testapp",
    version = "0.1",
    summary = "summary",
    description = "description",
)
snap.base = "core18"

part = SnapPart()
part.plugin = "nil"                     # 不使用 snapcraft 内置插件
part.source = "."                       # 使用当前目录作为源码
part.source_type = "local"
part.build_environment = [              # 注入构建期环境变量
    {"PATH": "${HOME}/.cargo/bin:${PATH}"},
]
part.override_build = "RUSTC_WRAPPER= cargo install --target x86_64-unknown-linux-musl --path . --root ${SNAPCRAFT_PART_INSTALL} --force"
part.after = ["some-dependency-part"]   # 声明依赖顺序
part.stage_packages = ["libssl1.1"]     # 暂存期引入的系统库

snap.parts = {"testapp": part}

builder = snap.to_builder()
builder.add_invocation(
    ["snap", "--destructive-mode", "--debug", "-o", "testapp_0.1.amd64.snap"]
)
builder.build("testapp-build-target")

这个示例同时覆盖了本文讲解的多数属性类别:源码定位(source/source_type)、构建定义(plugin/build_environment/override_build)、依赖顺序(after)、暂存产物(stage_packages)。从中可以看到 SnapPart 的设计意图:把原本手写在 YAML 里的部件配置变成可编程、可条件化的 Starlark 表达式。

五、SnapPart 在构建链路中的位置

要完整理解 SnapPart 的价值,需要看它在 Tugger 构建管线中的上下文(相关类型文档见 Snap 与 SnapcraftBuilder):

  1. SnapPart() 创建部件,赋值属性描述"如何构建一个部件";
  2. Snap 聚合:snap.parts = {"part-name": SnapPart()} 把部件挂到 Snap 实例上。Rust 侧 value_to_parts(tugger/src/starlark/snapcraft.rs)强制要求字典的值必须是 SnapPart 类型,否则报错;
  3. snap.to_builder() 得到 SnapcraftBuilder:builder 持有 Snapcraft 配置、一系列 snapcraft 命令调用参数以及待安装的文件清单;
  4. builder.build(target) 触发构建:在 tugger-snapcraft/src/builder.rs 的 build_invocation 中,构建目录被(可选地)清理、文件清单被物化、Snapcraft 实例通过 serde_yaml::to_writer 序列化为 snap/snapcraft.yaml,最后调用外部 snapcraft 命令执行。

在这一链路中,SnapPart 承担的正是"部件配置的数据源"角色:它定义的内容决定了序列化出的 parts.<part-name> 小节,进而决定 snapcraft 实际执行的构建逻辑。

六、使用注意事项

  • 只写属性:SnapPart 的属性赋值后无法在 Starlark 中读取,若需要读取回值,应规划好数据流,避免依赖读取行为;
  • None 即移除:利用这一语义可以实现配置的按需裁剪,但要注意空列表/空字典同样会被跳过序列化,二者在最终 YAML 中表现一致;
  • 枚举取值受限:source_type、build_attributes 必须使用上节列出的受支持取值,传入其他字符串会在配置解析阶段直接报错(错误码 TUGGER_SNAPCRAFT);
  • filesets 值不允许 None:字典值必须是字符串列表,这是少数会明确拒绝 None 的属性;
  • 平台前提:snapcraft 的完整构建(builder.build())依赖系统中安装的 snapcraft 可执行文件,这是 Tugger 中少数依赖外部工具的打包路径之一(tugger/docs/tugger_overview.rst 也说明了 Tugger 尽力将打包能力内置于 Rust 进程、减少外部依赖的设计取向,但 snap 格式仍以调用 snapcraft 为主)。

七、延伸阅读

登录后查看全文
PyOxidizer