using-tuist-generated-projects

使用 Tuist 生成的项目

快速入门

# Generate workspace without opening Xcode
tuist generate --no-open

# Build a scheme with xcodebuild
xcodebuild build -workspace App.xcworkspace -scheme App

# Run tests with xcodebuild
xcodebuild test -workspace App.xcworkspace -scheme AppTests -only-testing AppTests/MyTestCase

项目定义

优先使用可构建文件夹

使用 buildableFolders，而不是 sources 和 resources 通配符。可构建文件夹会与文件系统保持同步，因此添加或移除文件无需重新生成项目。

let target = Target(
  name: "App",
  buildableFolders: [
    "App/Sources",
    "App/Resources",
  ]
)

为目标添加标签以便聚焦

使用目标标签对项目区域进行分组，例如：

• tag:team:*
• tag:feature:*
• tag:layer:*

这些标签便于之后限定生成和测试的范围。

带标签的目标元数据示例：

let target = Target(
  name: "PaymentsUI",
  metadata: .metadata(tags: [
    "tag:team:commerce",
    "tag:feature:payments",
    "tag:layer:ui",
  ])
)

专注于某个区域时，只生成所需内容：

tuist generate tag:feature:payments
tuist generate PaymentsUI PaymentsTests

保持构建配置一致

确保项目与外部依赖项的构建配置一致。使用 PackageSettings(settings: .settings(configurations: [])) 镜像项目配置；配置不匹配时会发出警告。

工作流

有目的地生成

• 在自动化和脚本中使用 tuist generate --no-open，以避免启动 Xcode。
• 任何清单发生更改（或依赖关系图发生变化）时，都要重新生成。
• 如果生成因缺少产品而失败，请运行 tuist install 以解析依赖项，然后重试。

使用 xcodebuild 构建

使用 xcodebuild build 对生成的工作区和方案进行构建。

xcodebuild build \
  -workspace App.xcworkspace \
  -scheme App \
  -destination "generic/platform=iOS Simulator"

使用 xcodebuild 测试

使用 xcodebuild test 在本地运行测试。优先使用它而不是 tuist test，因为 tuist test 每次调用都会重新生成项目，从而减慢迭代速度。

优化测试运行时间：

• 使用 --only-testing，仅运行正在处理的特定测试套件或测试用例，而不是整个目标。
• 选择编译目标最少且仍包含所需测试目标的方案。 这样可以最大限度地缩短测试运行前的构建时间。

# Run a specific test suite
xcodebuild test \
  -workspace App.xcworkspace \
  -scheme AppTests \
  -only-testing AppTests/MyTestSuite

# Run a single test case
xcodebuild test \
  -workspace App.xcworkspace \
  -scheme AppTests \
  -only-testing AppTests/MyTestSuite/testMyFunction

指南

• 确保 buildableFolders 路径与目标的实际文件系统布局一致。
• 避免在同一目标中让 buildableFolders 与 sources 或 resources 通配符重叠。
• 运行 tuist generate --no-open 后，如有需要，请手动打开 Xcode。

故障排除

静态副作用警告： 有意调整产品类型。本地目标使用 Target.product，外部产品使用 PackageSettings(productTypes:)。将所有内容都设为动态 .framework 虽然可以编译和运行，但可能会增加启动时间。尽可能优先使用静态产品（静态框架或库），前提是它们不会引入副作用。

Objective-C 依赖项崩溃： 根据需要，通过使用方目标上的 OTHER_LDFLAGS 添加 -ObjC 或 -force_load。参考：https://tuist.dev/en/docs/guides/features/projects/dependencies#objectivec-dependencies。