為 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-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 檔案。