生成的 Xcode 项目
自动生成的方案会自动包含 tuist inspect build 后置操作。
如果你不想在生成的方案中跟踪构建洞察,可以使用 buildInsightsDisabled 禁用它。
如果你在使用带有自定义方案的生成项目,需要自行添加后置操作。对于 Mise:
let project = Project(
name: "MyProject",
targets: [
// Your targets
],
schemes: [
.scheme(
name: "MyApp",
shared: true,
buildAction: .buildAction(
targets: ["MyApp"],
postActions: [
.executionAction(
title: "Inspect Build",
scriptText: """
$HOME/.local/bin/mise x -C $SRCROOT -- tuist inspect build
""",
target: "MyApp"
)
],
runPostActionsOnFailure: true
),
runAction: .runAction(configuration: "Debug")
)
]
)
如果你不使用 Mise,则需要确保 tuist 在方案的环境中可用,因为 Xcode 的后置操作不会继承你 shell 的 PATH。对于 Homebrew 安装:
buildAction: .buildAction(
targets: ["MyApp"],
postActions: [
.executionAction(
title: "Inspect Build",
scriptText: """
export PATH="/opt/homebrew/bin:/usr/local/bin:$PATH"
tuist inspect build
""",
target: "MyApp"
)
],
runPostActionsOnFailure: true
)
CI 中的构建洞察#
要在 CI 中跟踪构建洞察,请确保 CI 已通过身份验证。
对于由 Xcodebuild 驱动的 CI,你需要:
- 在调用
xcodebuild操作时使用tuist xcodebuild。 - 向你的
xcodebuild命令添加-resultBundlePath。
如果没有 -resultBundlePath,将不会生成所需的活动日志和结果包,tuist inspect build 也就无法分析构建。
在私有网络上进行免凭证报告#
自托管部署可以允许开发者在不登录的情况下发布已完成的报告。操作员必须在实例上配置 TUIST_NETWORK_TRUSTED_INSIGHTS_ACCESS=true 并按照 自托管指南 中的说明重启实例。这适用于所有支持的项目;仪表盘中没有相关设置。请在你的 Scheme 后操作或终端使用的环境中配置自托管 URL 和项目。当缺少凭证时,CLI 会自动发现实例策略:
export TUIST_URL="https://tuist.internal.example"
tuist inspect build
# To publish local test results:
tuist inspect test
在确实缺少凭证的情况下,活动日志和 XCResult 包会在本地解析并作为结构化报告发送。不会提交原始归档文件、附件、覆盖率/历史记录上传、远程处理器、分片引用或选择性执行证据。报告仍然可见,但无法更新经过身份验证的测试用例状态或触发隔离/失败自动化流程。仪表盘和其他特权命令仍然需要登录。除非实例单独启用了网络可信缓存访问或已提供凭证,否则请保持缓存集成处于禁用状态。
现有凭证保持经过身份验证的状态。无效、损坏、空白或被拒绝刷新的凭证会以安全失败方式处理并保留在磁盘上,因此后续命令不会静默变为未签名状态。请重新登录或明确登出以作为有意识的恢复操作。在升级免凭证客户端之前,请将每个服务器副本升级到支持发现的版本,并配置最终服务器 URL 且不包含重定向。不支持发现的旧版服务器、已禁用的实例以及发现失败的情况仍然需要身份验证。无需客户端选择加入。独立设置 TUIST_ACTOR_ID="" 以省略配置的参与者声明;已验证的凭证身份不受影响。
机器指标#
构建洞察可以包含在构建过程中捕获的机器级性能指标(CPU、内存、网络和磁盘使用情况)。要启用此功能,请设置一个轻量级后台守护进程,持续采样系统指标:
tuist setup insights
这会运行一个本地守护进程,在后台采样指标。数据会被 tuist inspect build 自动采集并随构建报告一起上传。
磁盘指标包括读/写活动,并且在使用兼容的 CLI 和服务器时,还包括 macOS 系统数据卷(/System/Volumes/Data)上的总空间和可用空间。可用空间不包括可清除空间。磁盘空间图表显示构建期间的已用空间(总空间减去可用空间)以及总容量,而不仅仅是在上传时。它不测量用于检出或 DerivedData 的独立外部卷。
升级 CLI 后,使用 tuist teardown insights 然后执行 tuist setup insights 来重启现有的采样器。采样必须在构建期间运行;旧报告和失败的测量没有磁盘空间值,也不会显示为零。磁盘空间采样遵循现有的 90 天机器指标保留策略。
在构建之前在 CI 机器上运行 tuist setup insights,以便也在那里捕获机器指标。
要停止收集机器指标,请运行:
tuist teardown insights
这会卸载守护进程的 LaunchAgent,移除其 plist,并从 ~/.local/state 删除采样的指标和守护进程日志,因此不会有任何内容在后台运行。
报告参与者声明#
仅当你将 TUIST_ACTOR_ID 显式设置为组织范围内的标签(例如 TUIST_ACTOR_ID=employee-123 tuist inspect build)时,创建报告的请求才会包含可选的 x-tuist-actor-id 标头。默认情况下不会发送任何标签,Tuist 也不会检测操作系统用户名。空的 TUIST_ACTOR_ID 会省略报告的标识符,但不会移除基于凭据的已验证身份。标识符必须是 1–128 字节的非空格可打印 ASCII 字符;无效的覆盖会被省略且不会回退。如果自定义代理拒绝不熟悉的标头,请使用空的环境覆盖来退出。
已验证的个人凭据优先;否则,客户端报告的标识符将显示为 未验证,且绝不会授予权限或自动链接到用户。任何能够查看项目报告的人都可以看到这些标识符,包括项目公开时的公众查看者,并且它们会包含在数据导出中,因此请勿包含机密信息。这适用于构建、测试和命令事件报告。旧服务器会忽略该可选标头,新服务器则接受不带该标头的旧客户端。没有标识符的新共享令牌报告会显示 未知,而不是发布组织;历史报告保留其先前的归属。构建和测试列表会区分已验证用户与未验证的报告标识符。除非自托管实例显式启用无凭据报告且客户端发现该策略,否则仍需要身份验证。
Scheme 后操作#
参与者声明默认处于禁用状态。要为 Scheme 后操作配置一个声明,请在该脚本中设置 TUIST_ACTOR_ID,而不是依赖 shell 导出。从 Dock 启动的 Xcode 不会继承 ~/.zshrc 中的变量。要使用 Homebrew 显式抑制已配置的声明,请使用:
export PATH="/opt/homebrew/bin:/usr/local/bin:$PATH"
export TUIST_ACTOR_ID=""
tuist inspect build
使用 Mise 时,在 Mise 加载其环境后覆盖该值:
$HOME/.local/bin/mise x -C "$SRCROOT" -- env TUIST_ACTOR_ID="" tuist inspect build
使用显式标签而非空值来选择加入。
自定义元数据#
你可以通过环境变量为构建附加元数据,以改进过滤。
环境变量#
| 变量 | 格式 | 描述 |
|---|---|---|
TUIST_BUILD_TAGS |
逗号分隔 | 在一个变量中包含多个标签。 |
TUIST_BUILD_VALUE_* |
单个值 | 键值对,其中后缀作为键。 |
示例#
在调用构建之前,在 CI 或你的 shell 中设置这些值:
export TUIST_BUILD_TAGS="nightly,ios-team,release-candidate"
export TUIST_BUILD_VALUE_TICKET="PROJ-1234"
export TUIST_BUILD_VALUE_PR_URL="https://github.com/myorg/myrepo/pull/123"