為 ELF 二進位檔發布 CIPD 符號套件

符號套件可用於記錄中的符號化和偵錯當機事件。包含 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-arm64debug-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 檔案。