執行 Winscope

Winscope 追蹤是 Android 架構的一部分。本頁面說明如何在本機下載、建構及執行 Winscope 追蹤檢視器。

在本機建構 Winscope

請按照下列步驟設定電腦，以執行 Winscope 追蹤器：

  1. 下載 Android 來源。

  2. 前往 Winscope 資料夾：

    cd development/tools/winscope

  3. 使用下列指令安裝依附元件：

    npm install

    如要查看可用指令清單，請執行：npm run

  4. 使用下列指令建構所有正式版和測試版目標：

    npm run build:prod

  5. 使用下列指令執行 Winscope：

    npm run start

分別建構各個部分

您可以使用下列指令，分別建構 Winscope 的個別部分：

指令 說明
build:trace_processor 檢查並重建最新版 Perfetto 的
trace_processor。
build:protos 重新編譯 Proto 定義。

執行測試

Winscope 包含單元測試和端對端測試。如要執行這些測試，請使用 npm run <command>：

指令 說明
test:unit:ci 以較不冗長的格式執行單元測試，適用於 CI
或預先提交的 Hook。
test:unit:dev 以更詳細的格式執行單元測試，適用於
本機開發。這個模式會監控變更，並自動重新執行正確的測試。
test:e2e 執行端對端測試，例如跨工具通訊協定的測試。
test:presubmit:quiet 以較不冗長的格式，為 CI 或預先提交的 Hook 建構所有預先提交的單元測試、Linter 和圖表分析。
test:presubmit 以更詳細的格式建構所有預先提交的單元測試、Linter 和圖表分析，以供本機開發使用。
test:all 以更詳細的格式在本機開發環境中執行所有測試 (單元和端對端)、Linter 和圖表分析。

端對端測試

執行端對端測試前，請先啟動遠端工具，並安裝正確版本的 Chrome 驅動程式。在下列程式碼片段中，run test:e2e 指令會自動安裝 Chrome 驅動程式。

$ npm run start
$ npm run start:remote_tool_mock
$ npm run test:e2e

下表列出必要指令及其說明。如要執行這些測試，請使用 npm run command：

指令 說明
start:remote_tool_mock 啟動遠端工具模擬，測試跨工具通訊協定。
install:chromedriver 安裝執行端對端測試所需的 Chrome 驅動程式。

更新 @IntDef 對應

@IntDef 是 Android 中用來限制整數可能值的註解。Winscope 會使用這些註解的對應，顯示值名稱而非整數。

如果新的 @IntDef 值已新增至 Android 架構，但 Winscope 未更新，系統會以原始整數值而非說明字串顯示這些值。如要修正這個問題，請更新 IntDef 對應檔案 (development/tools/winscope/src/common/intDefMapping.json)。

如要自動更新 @IntDef 對應，請按照下列步驟操作：

  1. 從本機 Android 樹狀結構的 development/tools/winscope/scripts/ 目錄執行 update_intdef_mappings.sh 指令碼。這個指令碼會觸發註解程序，從程式碼中擷取最新的 @IntDef 值，並更新 intDefMapping.json：

    cd development/tools/winscope
./scripts/update_intdef_mappings.sh

  2. 使用 git commit 指令將變更提交至 src/common/intDefMapping.json，並使用 repo upload 指令上傳變更。

如果沒有可用的指令碼，請按照下列步驟，從 Android 根目錄 ($ANDROID_BUILD_TOP) 手動更新 @IntDef對應：

  1. 建構 framework-minus-apex-intdefs，供註解前置處理器執行：

    m framework-minus-apex-intdefs

  2. 將產生的 intDefMapping.json 檔案複製到預先建構的存放區：

    $ python3 -c 'import sys,json,collections; print(json.dumps(collections.OrderedDict(sorted(collections.ChainMap(*map(lambda x:json.load(open(x)), sys.argv[1:])).items())), indent=2))' $(find out/soong/.intermediates/frameworks/base -iname intDefMapping.json) > ./development/tools/winscope/src/common/intDefMapping.json

  3. 使用 repo upload 上傳 Winscope 中的變更。

其他指令

除了建構和測試，Winscope 指令碼還包含其他功能，如表格所示。如要執行這些測試，請使用 npm run command：

指令 說明
format:check 使用 prettier 檢查程式碼格式問題。
format:fix 使用 prettier 檢查並自動修正程式碼格式問題。
eslint:check 使用 eslint 檢查程式碼格式問題。
eslint:fix 使用 eslint 檢查並自動修正程式碼格式問題。
tslint:check 使用 tslint 檢查程式碼格式問題。
tslint:fix 使用 tslint 檢查並自動修正程式碼格式問題。
deps_graph:check_cycles 分析程式碼的循環依附元件。

疑難排解

請參考下列疑難排解提示：

  • 錯誤 ProtocolError: missing required '<FIELD>' 或 TypeError: Cannot read property '<PROP>' of null

    • 如果追蹤檔是使用含有新必要欄位的新 proto 定義建立，就會發生這種情況。

      1. 請確認您是在正確的 Winscope 版本 (master、S 或 R) 中開啟追蹤記錄。

      2. 如果您在 Proto 中建立新欄位，請使用 npm run build:protos 在 Winscope 中重新編譯 Proto。

  • 部分已安裝的依附元件版本有誤 (建構失敗)

    • 還原對 package.json 和 package-lock.json 的變更。移除 node_modules。再次執行 npm install。

  • 我在其中一個原型檔案中新增了欄位。如何顯示？

    • Winscope 使用的是編譯時的 proto 定義，因此預設不會顯示新欄位。如要顯示新欄位，請使用 npm run build:protos 重新建構 Proto。