Tugger Starlark 中的 SnapApp 类型:用 Starlark 声明式配置 snapcraft.yaml 应用入口
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。