构建与配置
Debug 和 Release 的区别，scheme / target / 配置怎么选，怎么覆盖构建设置，产物在哪，.ipa 什么时候出，Swift Package 依赖何时解析。
VS Code 中的「构建」和命令行的 kxbuild build 做同一件事，按工程中的 scheme、配置和构建设置编译、链接、签名、打包。默认 Debug，Release 构建的 iOS 应用直接在工程目录的 build\<App>.ipa 得到可上传的包。参数说明见kxbuild 命令参考。
> kxbuild build .\MyApp.xcodeproj -s MyApp -c Releasescheme、target 与配置
构建对象是 .xcodeproj、.xcworkspace 或含 Package.swift 的目录。不指定 scheme 或 target 时构建默认 scheme，配置默认取 scheme 的运行配置，没有则为 Debug。工程有哪些 scheme、target 和 Bundle ID 可用 kxbuild project info 查看。
| 选项 | VS Code | 命令行 |
|---|---|---|
| 工程 | KXBuild 视图中的启动项目 | 第一个参数 |
| scheme / target | 启动项目的默认 scheme，多个 target 时弹出选择。target 节点上的「构建」只构建该 target | -s NAME / -t NAME，加 --ignoreDependence 不带依赖 |
| 配置 | KXBuild 视图的「构建配置」节点或「KXBuild: 选择构建配置」 | -c Debug|Release 或自定义配置名 |
| SDK / 架构 | 固定 iphoneos · arm64 | --sdk、--arch |
Debug 与 Release
| Debug | Release | |
|---|---|---|
| 用途 | 真机断点调试 | TestFlight、App Store 或 Ad Hoc 分发 |
| 优化 | 不优化，断点位置准确 | 开启优化，断点会跳 |
| 证书 | 通常为 Apple Development | 上架需要 Apple Distribution |
| .ipa | 默认不生成，加 --ipa PATH 生成 | iOS 应用默认生成到 build\<App>.ipa，--no-ipa 不生成 |
临时覆盖构建设置
-D KEY=VALUE 临时覆盖任意构建设置，可重复，优先级和 xcodebuild 的 KEY=VALUE 一样。--xcconfig FILE 一次套用整个文件。
> kxbuild build .\MyApp.xcodeproj -c Release -D CODE_SIGN_IDENTITY="Apple Distribution" -D DEVELOPMENT_TEAM=ABCDE12345> kxbuild build .\MyApp.xcodeproj -D MARKETING_VERSION=1.2.0 -D CURRENT_PROJECT_VERSION=45长期修改用工程设置编辑器改工程文件本身。
产物位置
| 产物 | 位置 | 说明 |
|---|---|---|
| .app 与中间文件 | ~\DerivedData\<工程名>-<哈希>\ | --derivedDataDir DIR 更换根目录，--clean 先清空再构建 |
| .ipa | <工程目录>\build\<App>.ipa | iOS 应用默认生成，非 Release 配置的文件名是 <App>-<配置>.ipa。-o, --ipa PATH 指定位置，--no-ipa 不生成 |
| <App>.AppStoreInfo.plist | .ipa 旁边 | 上传用的描述文件，供命令行版 Transporter 的 -assetDescription 使用 |
WSL 中工程要放在 Linux 侧目录，放在 /mnt/c 下会慢一个数量级。
模拟器 SDK
--sdk iphonesimulator 用来确认代码在模拟器目标下能否编译。模拟器目标通常不签名。
> kxbuild build .\MyApp.xcodeproj --sdk iphonesimulator -D CODE_SIGNING_ALLOWED=NOSwift Package 依赖
工程引用 Swift Package 时构建前自动解析。要强制重新解析，相当于 Xcode 的 Reset Package Caches，执行
> kxbuild resolve .\MyApp.xcworkspace --forceCI 中通常加 --only-use-versions-from-resolved-file 严格按 Package.resolved，加 --skip-package-updates 不访问远程仓库，build 和 resolve 都支持。
Metal 着色器
工程里有 .metal 文件时，Windows 上要先装 Apple 的 Metal Developer Tools for Windows。下载需要登录 Apple 账号，所以体检不会自动安装，要自己下载一次。打开 Apple 下载页，登录后下载列表中最新的 Metal Developer Tools for Windows，按默认选项安装，工具介绍见 Metal 开发者工具。装好后直接构建，KXBuild 会自动找到它，不用加进 PATH。Linux 上没有 Metal 编译器，这类工程要在 Windows 上构建。
构建后安装到手机
> kxbuild build .\MyApp.xcodeproj --install构建成功后把签好名的 App 安装到连接的 iPhone 上，多台时安装到第一台。VS Code 中对应「构建并运行」，它还会附加调试器，见运行与调试。
常用组合
| 目的 | 命令 |
|---|---|
| Debug 安装到手机 | kxbuild build .\MyApp.xcodeproj --install |
| Release 出 ipa 上架 | kxbuild build .\MyApp.xcodeproj -c Release |
| Debug 包放到指定位置发给测试 | kxbuild build .\MyApp.xcodeproj --ipa D:\out\MyApp-dev.ipa |
| 只编译某个库 target | kxbuild build .\MyApp.xcodeproj -t MyKit --ignoreDependence |
| 只确认能编译，不签名 | kxbuild build .\MyApp.xcodeproj -D CODE_SIGNING_ALLOWED=NO |
脚本和 CI 中的用法见kxbuild 命令参考。