跳至內容

已生成嘅 Xcode 項目

Note

自動生成嘅 Scheme 會自動包含 tuist inspect build 後置動作。

如果你唔想喺已生成嘅 Scheme 中追蹤構建洞察,可以透過 buildInsightsDisabled 停用。

如果你使用帶有自訂 Scheme 嘅已生成項目,你需要自行加入後置動作。對於 Mise:

swift
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 喺 Scheme 嘅環境中可用,因為 Xcode 後置動作唔會繼承你 Shell 嘅 PATH。對於 Homebrew 安裝:

swift
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。
  • 將 -resultBundlePath 添加到你的 xcodebuild 命令中。

如果沒有 -resultBundlePath,則不會生成所需的活動日誌和結果包,tuist inspect build 也無法分析構建。

喺私人網絡進行免憑證報告#

自託管部署可以允許開發人員無需登入就發布已完成嘅報告。營運者必須喺實例上設定 TUIST_NETWORK_TRUSTED_INSIGHTS_ACCESS=true,並按照 自託管指南 所述重新啟動。呢個設定適用於每個受支援嘅項目;儀表板入面無相關設定。請喺你嘅 Scheme 後置動作或終端機使用嘅環境中,設定自託管 URL 同項目。當缺少憑證時,CLI 會自動偵測實例政策:

bash
export TUIST_URL="https://tuist.internal.example"
tuist inspect build
# To publish local test results:
tuist inspect test

當確實缺少憑證時,活動日誌同 XCResult 捆綁包會喺本地解析,並作為結構化報告發送。唔會提交任何原始歸檔、附件、覆蓋率/歷史記錄上傳、遠程處理器、分片參考或選擇性執行證據。報告仍然可見,但無法更新已認證測試用例狀態或觸發隔離/失敗自動化流程。儀表板同其他特權命令仍然需要登入。除非實例單獨啟用網絡可信緩存訪問或已提供憑證,否則請保持緩存集成禁用。

現有憑證保持認證狀態。無效、損壞、空白或被拒絕刷新嘅憑證會以安全方式失敗並保留喺磁盤上,因此後續命令唔會無聲地變成未簽名狀態。請重新登入或明確登出作為刻意嘅恢復操作。喺升級免憑證客戶端之前,請將每個服務器副本升級到支持發現功能嘅版本,並配置最終服務器 URL 且唔包含重定向。舊版不支持發現功能嘅服務器、禁用實例同發現失敗情況仍然需要認證。無需客戶端選擇加入。獨立設定 TUIST_ACTOR_ID="" 以省略配置嘅參與者聲明;已驗證憑證身份不受影響。

機器指標#

構建洞察可以包含在構建期間捕獲的機器級別性能指標(CPU、記憶體、網絡和磁碟使用量)。要啟用此功能,請設置一個輕量級的後台守護進程,持續採樣系統指標:

bash
tuist setup insights

這會運行一個本地守護進程,在後台採樣指標。數據會由 tuist inspect build 自動收集並隨構建報告一起上傳。

磁碟指標包括讀/寫活動,並且在兼容的 CLI 和服務器上,還包括 macOS 系統 Data 卷(/System/Volumes/Data)的總空間和可用空間。可用空間不包括可清除空間。磁碟空間圖表顯示已用空間(總空間減去可用空間)以及構建過程中的總容量,而不僅是上傳時的狀態。它不測量用於檢出或 DerivedData 的獨立外部卷。

升級 CLI 後,使用 tuist teardown insights 重啟現有的採樣器,然後執行 tuist setup insights。採樣必須在構建期間運行;較舊的報告和失敗的測量沒有磁碟空間值,也不會顯示為零。磁碟空間採樣遵循現有的 90 天機器指標保留策略。

CI

在構建之前,在你的 CI 機器上運行 tuist setup insights,以便在那裡也捕獲機器指標。

要停止收集機器指標,請運行:

bash
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 明確抑制已設定的聲明,請使用:

bash
export PATH="/opt/homebrew/bin:/usr/local/bin:$PATH"
export TUIST_ACTOR_ID=""
tuist inspect build

使用 Mise 時,請在 Mise 載入其環境後覆寫該值:

bash
$HOME/.local/bin/mise x -C "$SRCROOT" -- env TUIST_ACTOR_ID="" tuist inspect build

使用明確的標籤而非空白值來選擇加入。

自訂元數據#

你可以透過環境變數將元數據附加到構建,以改善篩選功能。

環境變數#

變數 格式 描述
TUIST_BUILD_TAGS 逗號分隔 一個變數中包含多個標籤。
TUIST_BUILD_VALUE_* 單一值 鍵值對,其中後綴為鍵。

範例#

在呼叫構建之前,於 CI 或你的 shell 中設定這些值:

bash
export TUIST_BUILD_TAGS="nightly,ios-team,release-candidate"
bash
export TUIST_BUILD_VALUE_TICKET="PROJ-1234"
export TUIST_BUILD_VALUE_PR_URL="https://github.com/myorg/myrepo/pull/123"