符號套件可用於記錄中的符號化和偵錯當機事件。包含 Fuchsia ELF 二進位檔的 CIPD 預先建構套件,必須具備伴隨符號套件,其中包含二進位檔的偵錯資訊。
符號套件的規定
原始 CIPD 套件中的每個 ELF 二進位檔都必須包含 ELF
NT_GNU_BUILD_ID
附註區段,其中包含專屬的build-id
雜湊值,可用於唯一識別與除錯無關的內容。這個註解會在產生 ELF 二進位檔時,在連結期間建立。最新版的 GCC 或預先建構的 Fuchsia Clang 工具鍊會自動產生此檔案。不過,一般 Clang 需要傳遞特殊連結器標記 (即
-Wl,--build-id
)。符號套件必須使用
.build-id
目錄的典型目錄版面配置,用於儲存在個別檔案中偵錯資訊。也就是說,每個檔案都必須儲存為
<xx>/<xxxxxxxxxx>.debug
,其中<xx>
和<xxxxxxxxx>
是從未經過去除的二進位檔的build-id
雜湊值衍生的十六進位字串。每個.debug
檔案都應是未經精簡的 ELF 二進位檔本身的副本,而非僅擷取偵錯資訊。這些檔案應對應至經過去除的 ELF 二進位檔,並與原始套件的build-id
相同。以下範例顯示含有未去除的 ELF 二進位檔的 CIPD 符號套件目錄結構:
1d/ bca0bd1be33e19.debug 1f/ 512abdcbe453ee.debug 90dd45623deab1.debug 2b/ 0e519bcf3942dd.debug 3d/ aca0b11beff127.debug 5b/ 66bc85af2da641697328996cbc04d62b84fc58.debug
符號套件必須使用與所參照原始 CIPD 套件相同的版本 ID (標記)。這樣一來,就能將這些項目合併。
如果包含經過精簡的 ELF 二進位檔的多個 CIPD 套件會一起推出 (使用相同的版本 ID),則可將所有套件的偵錯符號群組在單一 CIPD 符號套件中,但這並非必要。
符號套件的 CIPD 路徑必須使用以下後置字串:
-debug-symbols-<ARCH>
例如,
myproject/fuchsia/mypackage-debug-symbols-amd64
包含myproject/fuchsia/mypackage-amd64
預先建構套件的符號。所有符號套件的 Jiri 結帳路徑必須為
${FUCHSIA_DIR}/prebuilt/.build-id
。
產生符號套件
如要產生符號套件,您必須:
使用 DWARF 偵錯資訊編譯所有 ELF 二進位檔 (例如,即使處於發布模式,也要將
-g
標記傳遞至編譯器)。為 ELF 二進位檔產生
NT_GNU_BUILD_ID
附註。這是最新 GCC 版本和 Fuchsia 預先建構的 Clang 工具鍊的預設值,但一般 Clang 需要將特殊標記 (
-Wl,--build-id
) 傳遞至連結器。
產生符號套件的建議做法是使用預先建構的 buildidtool
工具:
- 如要使用此工具建構樹狀結構外結構,請從 CIPD 取得。
使用 buildidtool
產生符號套件目錄結構:
# Example assuming your unstripped binary is at out/libfoo.so and you want to
# create the symbols directory at ./symbols
UNSTRIPPED_BINARY=out/libfoo.so
SYMBOLS_DIR=./symbols
BUILDIDTOOL="${FUCHSIA_DIR}/prebuilt/tools/buildidtool/linux-x64/buildidtool" # Adjust path as needed
mkdir -p "${SYMBOLS_DIR}" # Ensure symbols directory exists
"${BUILDIDTOOL}" --build-id-dir="${SYMBOLS_DIR}" -entry .debug="${UNSTRIPPED_BINARY}" -stamp "$(mktemp)"
針對預先建構套件中的每個未經精簡的 ELF 二進位檔重複執行此 buildidtool
指令,以填入 symbols/
目錄。
接著,將 symbols/
目錄的內容 (而非目錄本身) 上傳至 CIPD 做為符號套件。
在本機測試符號套件
在本機測試符號套件之前,您應瞭解符號套件的 jiri
項目長什麼樣子:
<package name=$CIPD_PATH-debug-symbols-$cpu # Example: ~/fuchsia/mypackage-debug-symbols-amd64
path="prebuilt/.build-id"
version=$CIPD_VERSION
attributes="debug-symbols,debug-symbols-$cpu,debug-symbols-$project"/>
屬性說明:
path="prebuilt/.build-id"
:所有符號套件都必須下載至專案結帳作業的${FUCHSIA_DIR}/prebuilt/.build-id
目錄。attributes="debug-symbols,debug-symbols-$cpu, debug-symbols-$project"
:此屬性可控制下載符號套件的時間。debug-symbols-$cpu
(例如debug-symbols-arm64
、debug-symbols-amd64
) 時發生當機。debug-symbols-$project
:這個屬性可用來下載與特定專案相關的符號套件。如要進行本機測試,請參閱下列操作說明。debug-symbols
:一般慣例。
如要使用 jiri
擷取本機測試的符號套件,您必須設定 jiri
。舉例來說,如要將 jiri 設為擷取 debug-symbols-$project
,請按照下列步驟操作:
jiri init -fetch-optional=debug-symbols-$project
接著,請擷取套件:
jiri fetch-packages --local-manifest
請注意,透過 Jiri 屬性選擇下載符號套件,可能會大幅增加專案檢出的磁碟空間。如要移除已選擇的屬性,請手動編輯結帳系統頂層目錄中的 .jiri_root/attributes.json
檔案。