xtool示例项目全解析:从Hello World到TCA架构的5个实战Demo详解
xtool示例项目全解析:从Hello World到TCA架构的5个实战Demo详解
xtool 是一款跨平台的 Xcode 替代工具,基于 SwiftPM 在 Linux、Windows、macOS 上构建和部署 iOS 应用。本文带你完整解析仓库 Examples/ 目录下的 5 个实战示例项目——从最简单的 Hello World,到资源打包、动态库、Widget 扩展,再到 TCA 架构,每个 Demo 都是可直接运行的完整 iOS 应用,也是学习 xtool 构建体系的最佳教材。
示例项目是什么?先看懂目录结构
Examples/ 目录下的每个 Demo 都承担双重身份:
- 集成测试固件:每个 Demo 启动后会自动做一些断言,然后退出。成功时标准输出会包含
xtool test succeeded,供 CI 校验 - 可运行的代码样本:展示了 xtool 支持的各种真实场景
整个目录的关键文件如下:
| 文件/目录 | 作用 |
|---|---|
| Examples/README.md | 示例总览与测试方法 |
| Examples/test.sh | 一键构建/运行所有 Demo 的脚本 |
| Examples/ExampleSupport/ | 所有 Demo 共享的基础库 |
Examples/Demo*/ |
5 个独立的 Demo 项目 |
每个 Demo 都遵循相同的三件套结构:Package.swift(SwiftPM 定义)、xtool.yml(xtool 配置,指定 bundleID)、Sources/(应用源码)。
Demo 1:DemoSimple —— 3行代码的 Hello World
最简单的一个示例。全部核心代码只有 3 行(见 App.swift):
@main struct DemoApp: ExampleApp {}
为什么 3 行就够?因为 xtool 提供了 模板代码机制:实现 ExampleApp 协议后,xtool 会自动为你的应用套上完整的 SwiftUI 模板(一个带地球图标和 "Hello, world!" 的界面),模板中还内置了自动断言逻辑。
对应的 xtool.yml 也极简:
version: 1
bundleID: sh.xtool.examples.DemoSimple
📌 学习要点:xtool 项目的最小骨架 = SwiftPM Package + 一个声明 bundleID 的 xtool.yml。
Demo 2:DemoResources —— 资源打包两种姿势
这个 Demo 演示了 xtool 中打包资源的两种方式(见 App.swift):
- SwiftPM 内置资源:在
Package.swift中用resources: [.process("bundled.txt")]声明,运行时通过#bundle.url(...)访问 - 项目顶层资源:在 xtool.yml 中声明
resources: [Resources/top.txt],打包时放入主 Bundle,运行时通过Bundle.main.url(...)访问
App 启动后会自动读取这两个文件并校验内容,验证无误即宣布测试成功。
📌 学习要点:无论资源放在 Sources 内还是独立目录,xtool 都能正确打包进最终的 .app。
Demo 3:DemoDynamic —— 动态库链接
DemoDynamic 演示了 iOS 应用中依赖动态库的场景:
- 共享库 ExampleDynamicLibrary 通过
type: .dynamic声明为动态库产品 - Demo 在
init中调用库函数,并读取库自带的资源文件,校验返回内容是否符合预期
这是很多实际项目会遇到的场景(如依赖第三方动态框架),xtool 会自动处理动态库的打包与链接,无需手动配置 rpath 等细节。
Demo 4:DemoExtensions —— Widget 扩展打包
DemoExtensions 展示了如何构建带 App Extension 的应用:
Package.swift中定义两个 target:主应用DemoExtensions和小组件DemoExtensionsWidget(基于 WidgetKit,见 Widget.swift)- xtool.yml 通过
extensions字段声明扩展,并指定扩展所需的 Info.plist 路径(DemoExtensionsWidget-Info.plist)
xtool 会把扩展自动打包进主应用的 PlugIns 目录,并正确处理扩展签名——这正是纯 SwiftPM 做不到的部分。
Demo 5:DemoTCA —— TCA 架构实战
最后一个 Demo 最有含金量:DemoTCA 基于 swift-composable-architecture(TCA)框架构建了一个计数器应用,完整拆解为三个文件:
| 文件 | 职责 |
|---|---|
| DemoTCAApp.swift | 创建 Store 并挂载 SwiftUI 入口 |
| CounterFeature.swift | 定义 State / Action / Reducer,用 continuousClock 实现每秒自增 |
| ContentView.swift | 纯展示层,监听 count 变化,到达 1 时自动通过测试 |
它证明了 xtool 与第三方架构框架(TCA、Observation 等)完全兼容,Package.swift 中声明依赖即可直接使用。
共享基座:ExampleSupport 与一键测试
5 个 Demo 共同依赖 ExampleSupport:
- ExampleApp.swift:提供 Demo 1 使用的模板协议
- ExampleSupport.swift:
Example.pass()会打印xtool test succeeded并退出进程,是所有 Demo 的"成功信号"
在 macOS 上可以用 test.sh 一键验证所有 Demo(见 integration-tests/suite/smoke.bats 同款断言逻辑):
./Examples/test.sh # 构建并运行全部 Demo
./Examples/test.sh --build # 仅构建
./Examples/test.sh --run DemoTCA # 仅运行指定 Demo
脚本流程非常清晰:先用 xtool dev build --triple arm64-apple-ios-simulator 构建,再通过 xcrun simctl 安装到已启动的模拟器,最后校验日志中是否出现成功标记(见 test.sh)。
开发体验:Swift 语言支持
xtool 的完整工作流通常搭配 VS Code 使用:安装 Swift 扩展后,可获得语法高亮、自动补全和悬停文档(xtool 通过内置 LSP 提供),配合 xtool.yml 配置即可开始开发。
悬停函数签名时还能查看完整文档注释(如 Hover2 展示的 padding 函数文档):
学习路径总结
| 顺序 | Demo | 解决的问题 | 难度 |
|---|---|---|---|
| 1 | DemoSimple | 最小可运行 iOS 应用 | ⭐ |
| 2 | DemoResources | 资源打包 | ⭐⭐ |
| 3 | DemoDynamic | 动态库依赖 | ⭐⭐ |
| 4 | DemoExtensions | App Extension | ⭐⭐⭐ |
| 5 | DemoTCA | 第三方架构框架 | ⭐⭐⭐ |
📌 下一步建议:先 xtool new --skip-setup MyApp 创建一个新项目,对照 DemoSimple 理解 xtool.yml 配置;再参考 Documentation/xtool.docc/xtool.md 了解完整命令体系。
掌握这 5 个 Demo,就等于掌握了 xtool 构建 iOS 应用的全部核心能力——资源、动态库、扩展、架构框架统统覆盖。




