xtool示例项目全解析:从Hello World到TCA架构的5个实战Demo详解

原创2026-10-15 16:26:42473 阅读
文章标签:开发工具CLI移动开发

xtool示例项目全解析:从Hello World到TCA架构的5个实战Demo详解

xtool 是一款跨平台的 Xcode 替代工具,基于 SwiftPM 在 Linux、Windows、macOS 上构建和部署 iOS 应用。本文带你完整解析仓库 Examples/ 目录下的 5 个实战示例项目——从最简单的 Hello World,到资源打包、动态库、Widget 扩展,再到 TCA 架构,每个 Demo 都是可直接运行的完整 iOS 应用,也是学习 xtool 构建体系的最佳教材。

xtool构建iOS应用并安装到设备的完整流程

示例项目是什么?先看懂目录结构

Examples/ 目录下的每个 Demo 都承担双重身份:

  • 集成测试固件:每个 Demo 启动后会自动做一些断言,然后退出。成功时标准输出会包含 xtool test succeeded,供 CI 校验
  • 可运行的代码样本:展示了 xtool 支持的各种真实场景

xtool配合VS Code开发iOS应用的Swift代码自动补全效果

整个目录的关键文件如下:

文件/目录 作用
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 的应用:

  1. Package.swift 中定义两个 target:主应用 DemoExtensions 和小组件 DemoExtensionsWidget(基于 WidgetKit,见 Widget.swift)
  2. xtool.yml 通过 extensions 字段声明扩展,并指定扩展所需的 Info.plist 路径(DemoExtensionsWidget-Info.plist)

xtool 会把扩展自动打包进主应用的 PlugIns 目录,并正确处理扩展签名——这正是纯 SwiftPM 做不到的部分。

xtool签名应用安装在iPhone上首次信任开发者的提示界面

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:

在 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 配置即可开始开发。

VS Code中安装Swift扩展获得xtool项目的语言支持

悬停函数签名时还能查看完整文档注释(如 Hover2 展示的 padding 函数文档):

xtool内置LSP提供的Swift代码悬停文档提示

学习路径总结

顺序 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 应用的全部核心能力——资源、动态库、扩展、架构框架统统覆盖。

登录后查看全文
xtool