Tugger Starlark 中的 SnapApp 类型:用 Starlark 声明式配置 snapcraft.yaml 应用入口

原创2026-10-09 09:18:081,416 阅读
文章标签:开发工具CLI

Tugger Starlark 中的 SnapApp 类型:用 Starlark 声明式配置 snapcraft.yaml 应用入口

导读

SnapApp 是 Tugger 项目在 Starlark 配置方言中提供的核心类型之一,它精确对应 snapcraft.yaml 中 apps.<app-name> 键的值,用于声明一个 snap 包内可执行应用/服务的启动命令、守护进程行为、接口插槽(plugs/slots)与运行环境。阅读本文后,你将掌握如何通过 Tugger 的 Starlark 构建脚本创建并配置 SnapApp 实例、理解其全部可写属性的类型与序列化行为,以及它与 Snap、SnapPart、SnapcraftBuilder 协同完成 snap 打包的完整调用链。

Tugger 是 PyOxidizer 项目的一部分,专注于应用分发,能够生成 Windows .msi、Debian .deb 与 Snapcraft .snap 等分发产物(见 tugger/docs/tugger.rst)。Tugger 的 Starlark 方言本质上是其 Rust 内部能力的可脚本化接口(见 tugger/docs/tugger_starlark.rst),而本文所讲的 SnapApp 正是其中负责「snap 应用条目」的那一块拼图。

SnapApp 的定位:snapcraft.yaml 的 apps.<app-name> 条目

在 Snapcraft 打包体系中,一个 snapcraft.yaml 文件通过 apps 顶层键声明该 snap 对外暴露的应用或服务。Tugger 的 SnapApp 类型正是为此设计的:它表示 snapcraft.yaml 中 apps.<app-name> 键的值(见 tugger/docs/tugger_starlark_type_snap_app.rst)。其底层 Rust 数据结构位于 tugger-snapcraft/src/yaml.rs,是一个用 serde 标注、默认按 kebab-case 序列化的结构体,字段与 snapcraft.yaml 的官方键一一对应。

关键行为约束如下:

  • 属性仅可写(write only):SnapApp 实例上的属性目前只能赋值,不能读取,这与 Tugger 对 Snap、SnapPart 等其他配置类型的处理一致;
  • 赋 None 即删除:将某个属性设置为 None,其副作用是从最终序列化的 snapcraft.yaml 文件中移除该属性,对应底层 skip_serializing_if = "Option::is_none" / Vec::is_empty / HashMap::is_empty 的序列化逻辑;
  • 属性名映射键名:实例上的属性与 apps.<app-name> 条目内的键一一对应,属性名采用蛇形命名(如 command_chain、post_stop_command),序列化时由 serde 的 rename_all = "kebab-case" 转换为 snapcraft.yaml 的连字符键(如 command-chain、post-stop-command)。

从源码实现看,tugger/src/starlark/snapcraft.rs 中的 SnapAppValue 实现了 Starlark 的 TypedValue trait,其 set_attr 方法把每个属性赋值直接写入内部 SnapApp 结构体字段;而 starlark_module! 宏在 tugger/src/starlark/snapcraft.rs 中注册了无参构造函数 SnapApp(),即文档所述「创建空实例、不接受任何参数」。

创建 SnapApp 实例

SnapApp 的构造函数签名如下(见 tugger/docs/tugger_starlark_type_snap_app.rst):

SnapApp() -> SnapApp

SnapApp() 不接受任何参数,返回一个空实例。所有配置都必须通过后续的属性赋值完成。在 Tugger 的 Starlark 环境中,可以这样创建一个应用条目:

app = SnapApp()
app.command = "bin/myapp"
app.daemon = "simple"
app.plugs = ["network", "home"]

SnapApp() 构造在源码中对应 tugger/src/starlark/snapcraft.rs 的 Ok(Value::new(SnapAppValue::default())),SnapAppValue 与内部 SnapApp 均实现了 Default,因此初始状态是一个所有字段为空的配置对象。

一个典型的 SnapApp 实例与 snapcraft.yaml 片段的对应关系如下:

app = SnapApp()
app.command = "bin/myapp"
app.autostart = "autostart"
app.command_chain = ["chain0", "chain1"]
app.environment = {"env0": "env0_value"}
app.daemon = "oneshot"
app.restart_condition = "on-failure"

序列化后大致对应:

apps:
  myapp:
    command: bin/myapp
    autostart: autostart
    command-chain: [chain0, chain1]
    environment:
      env0: env0_value
    daemon: oneshot
    restart-condition: on-failure

这一「赋值即配置」的模式在 tugger/src/starlark/snapcraft.rs 的 test_app_basic 单元测试中得到完整验证:测试逐项赋值全部属性并断言内部 SnapApp 结构体的最终状态,可作为使用本类型的权威参考。

全部属性详解

下表汇总 SnapApp 暴露的全部可写属性及其 Starlark 类型。属性语义与 snapcraft.yaml 官方参考文档保持一致,此处结合 tugger/src/starlark/snapcraft.rs 的赋值处理与 tugger-snapcraft/src/yaml.rs 的类型定义给出实现细节。

属性 Starlark 类型 序列化键 说明
adapter Optional<a href="https://link.gitcode.com/i/d20aaa99ce7b0f2a810b8e7127f01f8d" target="_blank">str] adapter 应用适配器,底层为枚举,支持 none / full(见 [tugger-snapcraft/src/yaml.rs)
autostart Optional[str] autostart 桌面自动启动条目
command_chain Optional[list[str]] command-chain 在 command 之前依次执行的命令链
command Optional[str] command 应用启动命令
common_id Optional[str] common-id 与桌面环境共享的应用标识
daemon Optional<a href="https://link.gitcode.com/i/5f4a1e22c7144f6568b0968132d1f979" target="_blank">str] daemon 守护进程类型,底层枚举支持 simple / oneshot / forking / notify(见 [tugger-snapcraft/src/yaml.rs)
desktop Optional[str] desktop 桌面文件条目
environment Optional[dict[str, str]] environment 应用运行时环境变量(键值对)
extensions Optional[list[str]] extensions 应用到该 app 的 snapcraft 扩展
listen_stream Optional[str] listen-stream 套接字激活的流监听名
passthrough Optional[dict[str, str]] passthrough 透传给 snapcraft 的额外键值
plugs Optional[list[str]] plugs 该应用声明使用的接口插槽
post_stop_command Optional[str] post-stop-command 服务停止后执行的命令
restart_condition Optional<a href="https://link.gitcode.com/i/eabc1ee36c19016f92b11c28a797f3f6" target="_blank">str] restart-condition 服务重启条件,底层枚举支持 on-failure / on-success / on-abnormal / on-abort / always / never(见 [tugger-snapcraft/src/yaml.rs)
slots Optional[list[str]] slots 该应用对外提供的接口槽
stop_command Optional[str] stop-command 停止服务执行的命令
stop_timeout Optional[str] stop-timeout 服务停止超时时间
timer Optional[str] timer 定时触发的 systemd timer 规格
socket_mode Optional[int] socket-mode 套接字文件权限模式(整数)
socket Optional[dict[str, str]] socket 套接字激活条目(键值对)

枚举型属性的取值校验

adapter、daemon、restart_condition 三个属性在赋值时会经过严格的枚举解析:Starlark 值被转为字符串后,通过 TryFrom<&str> 校验合法性,非法取值会抛出带有 TUGGER_SNAPCRAFT 错误码与属性标签的运行时错误(见 tugger/src/starlark/snapcraft.rs、tugger/src/starlark/snapcraft.rs)。因此 app.daemon = "simple" 合法,而 app.daemon = "invalid" 会在配置阶段直接失败,而不是等到 snapcraft 构建时才报错。

其余字符串、字符串列表与字符串字典属性(如 command、command_chain、environment)则直接接受对应 Starlark 值:列表/字典通过 try_to_optional() 解析,None 会被归一化为空集合(见 tugger/src/starlark/snapcraft.rs),这解释了「设置 None 移除该属性」与「不设置即为空」的等价行为。

如何让 SnapApp 生效:接入 Snap、SnapPart 与 SnapcraftBuilder

SnapApp 单独存在没有意义,它必须作为 Snap 的 apps 字典值被引用,再经由 SnapcraftBuilder 驱动 snapcraft 命令完成构建。整体配置骨架如下(Snap 与 SnapcraftBuilder 的完整参考见 tugger/docs/tugger_starlark_type_snap.rst 与 tugger/docs/tugger_starlark_type_snapcraft_builder.rst):

# 1. 创建 Snap 主配置(必须提供 name/version/summary/description)
snap = Snap("myapp", "0.1", "A summary", "A description")
snap.base = "core18"
snap.confinement = "strict"
snap.grade = "stable"

# 2. 定义应用入口
app = SnapApp()
app.command = "bin/myapp"
app.daemon = "simple"
app.plugs = ["network"]
snap.apps = {"myapp": app}

# 3. 定义构建部件(可选,用于声明源码与构建方式)
part = SnapPart()
part.plugin = "nil"
part.source = "."
snap.parts = {"myapp": part}

# 4. 转成 builder 并注册 snapcraft 调用
builder = snap.to_builder()
builder.add_invocation(
    ["snap", "--destructive-mode", "--debug", "-o", "myapp_0.1_amd64.snap"],
    purge_build = True,
)
builder.build("snap-build")

各环节的底层行为如下:

  • snap.apps 赋值:SnapValue.set_attr 通过 value_to_apps 逐项校验字典值必须是 SnapApp 类型,否则报错(见 tugger/src/starlark/snapcraft.rs);
  • to_builder():等价于 SnapcraftBuilder(snap),将 Snap 配置快照进 builder(见 tugger/src/starlark/snapcraft.rs);
  • add_invocation:注册一条 snapcraft 命令调用,可选的 purge_build 参数控制是否在运行前清空构建目录;不指定时,第一条调用默认 purge、后续调用不 purge(见 tugger-snapcraft/src/builder.rs);
  • add_file_manifest:将 FileManifest 中的文件物化到 snapcraft.yaml 所在目录旁的构建环境中;
  • build(target):SnapcraftBuilder::build 会按序执行每个 invocation——依次执行「按需清空构建目录 → 物化注册文件 → 将 Snapcraft 结构体通过 serde 序列化写入 build_path/snap/snapcraft.yaml → 调用 snapcraft 可执行文件」(见 tugger-snapcraft/src/builder.rs)。

在 tugger-snapcraft/src/builder.rs 的 test_build_rust_project 集成测试中,可以看到一个真实的完整案例:测试构造 Snapcraft、通过 SnapPart 声明 nil 插件与 musl 目标交叉编译的 override_build,再通过 SnapApp { command: Some("bin/testapp".into()) } 声明应用入口,最后用 add_invocation_args(["snap", "--destructive-mode", "--debug", "-o", ...]) 构建出 .snap 文件。该测试也提示了两个使用前提:构建 snapcraft 需要本机安装 snapcraft 命令,且 --destructive-mode 要求 snapcraft 支持该参数。

与相关类型的边界

在 Tugger 的 Starlark 方言中,Snapcraft 打包体系由四个类型协作完成,注意不要混淆职责:

类型 对应 snapcraft.yaml 区域 参考文档
Snap 整个文件(顶层键) tugger/docs/tugger_starlark_type_snap.rst
SnapApp apps.<app-name> tugger/docs/tugger_starlark_type_snap_app.rst
SnapPart parts.<part-name> tugger/docs/tugger_starlark_type_snap_part.rst
SnapcraftBuilder 驱动 snapcraft 命令执行 tugger/docs/tugger_starlark_type_snapcraft_builder.rst

其中 SnapApp 只负责「应用/服务条目」的声明,构建原料(源码、插件、构建脚本)属于 SnapPart 的范畴,而顶层元数据(名称、版本、限制级别 confinement、grade、架构等)属于 Snap。四者组合后即可在 Tugger 的 Starlark 配置中完整描述并构建一个 snap 包。

小结

  • SnapApp 是 Tugger Starlark 方言中专用于描述 snapcraft.yaml 中 apps.<app-name> 条目的类型,无参构造函数 SnapApp() 创建空实例;
  • 全部属性只写,赋 None 等价于从序列化输出中移除该键;字符串/列表/字典属性与底层 SnapApp 结构体字段一一对应,并遵循 kebab-case 序列化;
  • adapter、daemon、restart_condition 是带取值校验的枚举属性,非法值在 Starlark 赋值阶段即报错;
  • 让 SnapApp 生效需要依次接入 Snap.apps、SnapPart 与 SnapcraftBuilder,最终由 builder 物化文件、写出 snapcraft.yaml 并顺序执行 snapcraft 调用;
  • 相关实现与测试可直接查阅 tugger/src/starlark/snapcraft.rs、tugger-snapcraft/src/yaml.rs 与 tugger-snapcraft/src/builder.rs。
登录后查看全文
PyOxidizer