ffx debug symbol-index
指令可協助在開發環境中管理 Fuchsia 元件的偵錯符號。
概念
在開發期間,系統會產生 Fuchsia 元件的偵錯符號,做為建構構件的一部分。包含偵錯符號的檔案會有 .symbol-index.json
做為後置字串 (例如 my-component.symbol-index.json
)。
在開發環境中註冊 Fuchsia 元件的偵錯符號,即可啟用以下工作流程:
- 以 symbolized 格式查看元件記錄。
- 在元件在裝置上執行時,使用 Fuchsia 偵錯工具執行程式碼。
- 即時監控裝置上的元件 FIDL 流量。
除了註冊本機產生的偵錯符號外,您也可以設定環境,以便從線上儲存空間 (例如 Google Cloud Storage) 擷取偵錯符號。在全域 symbol-index
設定中加入線上儲存空間後,各種 Fuchsia 偵錯工具 (例如 ffx log
和 ffx debug connect
) 就能自動下載並使用線上儲存空間中提供的偵錯符號。
在 Fuchsia 開發環境中,通常系統會在背景中註冊偵錯符號。部分 Fuchsia 工具會設定,在偵測偵錯符號時叫用偵錯符號 (使用 ffx debug symbol-index add
),因此您無需在開發期間手動註冊 Fuchsia 元件的偵錯符號。舉例來說,如果您使用 Fuchsia 的 Bazel 規則,系統會在建構時自動註冊偵錯符號。不過,在必要時,您可以使用 ffx debug symbol-index
指令直接管理偵錯符號。
列出已註冊的偵錯符號
如要查看全域 symbol-index
設定,請執行下列指令:
ffx debug symbol-index list
這個指令會輸出類似以下的輸出內容:
$ ffx debug symbol-index list
SymbolIndex {
includes: [
"/usr/alice/home/my-fuchsia-project/my-component.symbol-index.json",
],
build_id_dirs: [],
ids_txts: [],
gcs_flat: [
GcsFlat {
url: "gs://our-fuchsia-project/debug",
require_authentication: false,
},
],
debuginfod: []
}
新增 debuginfod 符號伺服器
使用非在 Fuchsia 樹狀結構中建構的第三方二進位檔時,您或許可以新增 debuginfod 伺服器來擷取符號。上游發布功能提供偵錯資訊伺服器 (例如 debuginfod.debian.net 或「聯合」伺服器),例如 debuginfod.elfutils.org,其可提供多個不同上游來源的符號。請與上游來源聯絡,找出其偵錯資訊伺服器 (如果有的話)。通常會以環境變數的形式呈現,例如:
export DEBUGINFOD_URLS="https://debuginfod.debian.net
如要將上述偵錯伺服器 (例如上述) 新增至符號索引,請使用下列指令:
ffx debug symbol-index add <URL>
將 URL
替換成您要新增的偵錯資訊伺服器網址。舉例來說,如要新增 Debian 的 debuginfod 伺服器,請執行下列指令:
ffx debug symbol-index add https://debuginfod.debian.net
註冊成功後,指令會在沒有輸出內容的情況下結束。偵錯工具會自動查詢伺服器,找出無法在本機找到的符號。
如要驗證註冊,請參閱「列出已註冊的偵錯符號」。
移除偵錯符號伺服器
如要從全域 symbol-index
設定中移除 debuginfod 伺服器,請執行下列指令:
ffx debug symbol-index remove <URL>
將 URL
替換為要移除的偵錯伺服器網址。以下範例會移除 debian debuginfod 伺服器:
ffx debug symbol-index remove https://debuginfod.debian.net
手動註冊本機偵錯符號
如要在環境中註冊偵錯符號,請執行下列指令:
ffx debug symbol-index add <PATH_TO_DEBUG_SYMBOLS>
將 PATH_TO_DEBUG_SYMBOLS
替換為偵錯符號檔案的絕對路徑。
以下範例會註冊 my-component
元件的偵錯符號:
$ ffx debug symbol-index add /usr/alice/home/my-fuchsia-project/my-component.symbol-index.json
註冊成功後,指令會在沒有輸出內容的情況下結束。
如要驗證註冊,請參閱「列出已註冊的偵錯符號」。
移除已註冊的本機偵錯符號
如要從全域 symbol-index
設定中移除偵錯符號,請執行下列指令:
ffx debug symbol-index remove <PATH_TO_DEBUG_SYMBOLS>
將 PATH_TO_DEBUG_SYMBOLS
替換為要移除的已註冊偵錯符號檔案的確切路徑。
以下範例會移除 my-component
元件的偵錯符號:
$ ffx debug symbol-index remove /usr/alice/home/my-fuchsia-project/my-component.symbol-index.json
移除成功後,指令會在無訊息的情況下結束,且不會輸出。
清除忘記放在哪裡的偵錯符號
刪除主機上已註冊的偵錯符號檔案,並不代表全域 symbol-index
設定也會自動更新。
如要從全域 symbol-index
設定中移除任何過時路徑 (指向已刪除的偵錯符號檔案),請執行下列指令:
ffx debug symbol-index clean
舉例來說,如果主機上已不存在 /usr/alice/home/my-fuchsia-project
目錄,這個指令會從全域 symbol-index
設定中移除 /usr/alice/home/my-fuchsia-project/my-component.symbol-index.json
項目。