使用偵錯工具

本頁面將詳細說明如何使用 LLDB 進行 OS 開發。如要進行應用程式開發，請改為參閱「偵錯應用程式」一文，瞭解如何使用 Android Studio GUI (以 LLDB 為基礎)。

我們已不再支援或提供 GDB。如果您要從 GDB 改用 LLDB，建議您先參閱 LLDB 教學課程。如果您是 GDB 專家，GDB 到 LLDB 指令對應表在轉換期間非常實用。

必要條件

如何使用偵錯工具：

  • 使用一般 envsetup.sh 指令設定建構環境。
  • 執行建構時使用的 lunch 指令。請注意，lunch 項目應與您要偵錯的裝置完全相符。如果午餐項目與已連結的裝置不符，您會收到以下格式的錯誤訊息： You used the wrong lunch: TARGET_PRODUCT (aosp_arm64) does not match attached device (xyzabc)
  • 將裝置連接到機器。

如需設定環境的詳細說明，請參閱「設定環境」。

對二進位檔進行偵錯

如要對在電腦上建構的二進位檔進行偵錯，您必須先將二進位檔複製到裝置，然後再啟動偵錯工具。例如：

adb push test.exe /data/local/tmp/test.exe
lldbclient.py --port 5038 -r /data/local/tmp/test.exe

對執行中的應用程式或程序進行偵錯

如要連線至執行中的應用程式或原生守護程序，請使用帶有 PID 的 lldbclient.py。舉例來說，如要對 PID 為 1234 的程序進行偵錯，請在主機上執行以下命令：

lldbclient.py -p 1234

指令碼會設定通訊埠轉送、在裝置上啟動適當的遠端偵錯存根目錄、在主機上啟動偵錯工具，並將其設定為尋找符號，然後將其連結至遠端偵錯存根目錄。

對原生程序啟動程序進行偵錯

如要偵錯啟動中的程序，請使用 lldbclient.py 搭配 -r 選項。舉例來說，如要偵錯 ls /bin，請在主機上執行以下指令：

lldbclient.py -r /system/bin/ls /bin

然後在偵錯工具提示中輸入 continue。

偵錯應用程式啟動

有時您可能需要在應用程式啟動時進行偵錯，例如發生當機時，您想逐步檢查程式碼，查看發生當機問題「之前」發生了什麼。附加功能在某些情況下可正常運作，但在其他情況下則無法運作，因為應用程式會在您附加前當機。logwrapper 方法 (用於 strace) 不一定有效，因為應用程式可能沒有開啟通訊埠的權限，而 lldbserver 會繼承這項限制。

如要對應用程式啟動進行偵錯，請使用「設定」中的開發人員選項，指示應用程式等待 Java 偵錯工具附加：

  1. 依序前往「設定」>「開發人員選項」>「選取偵錯應用程式」，然後從清單中選擇應用程式，接著按一下「等待偵錯工具」。
  2. 透過啟動器或指令列啟動應用程式：
    adb shell am start -a android.intent.action.MAIN -n APP_NAME/.APP_ACTIVITY
  3. 等待應用程式載入，畫面上會顯示對話方塊，告知應用程式正在等待偵錯工具。
  4. 正常地附加 lldbserver/lldbclient、設定中斷點，然後繼續執行程序。

如要讓應用程式執行，請附加 Java 偵錯傳輸通訊協定 (JDWP) 偵錯工具，例如 Java 偵錯工具 (jdb)：

adb forward tcp:12345 jdwp:XXX  # (Where XXX is the PID
of the debugged process.)
jdb -attach localhost:12345

偵錯當機的應用程式或程序

如果您希望 debuggerd 暫停當機的程序，以便附加偵錯工具，請設定適當的屬性：

  • 在 Android 11 之後
    adb shell setprop debug.debuggerd.wait_for_debugger true
  • Android 11 以下版本
    adb shell setprop debug.debuggerd.wait_for_gdb true
  • Android 6.0 (Marshmallow) 以下版本
    adb shell setprop debug.db.uid 999999

在一般當機輸出內容的結尾，debuggerd 會在 Logcat 中提供複製和貼上指示，說明如何將偵錯工具連結至當機程序。

使用 VS Code 進行偵錯

LLDB 支援在 Visual Studio Code 上偵錯平台程式碼。您可以使用 VS Code 偵錯工具前端，而非 LLDB CLI 介面，藉此控制及偵錯在裝置上執行的原生程式碼。

使用 VS Code 進行偵錯前，請先安裝 CodeLLDB 擴充功能。

如要使用 VS Code 偵錯程式碼，請按照下列步驟操作：

  1. 請確認執行 lldbclient.py 或 lldbclient.py 所需的所有建構成果物 (例如符號) 都已存在。
  2. 在 VS Code 中按下 Ctrl + Shift + P 鍵執行指令，搜尋「Debug: Add Configuration...」，然後選取「LLDB」。這會開啟 launch.json 檔案，並將新的 JSON 物件新增至清單。
  3. 將新加入的偵錯工具設定替換為兩行註解 - // #lldbclient-generated-begin 和 // #lldbclient-generated-end，讓設定清單如下所示：
    "configurations": [
    // #lldbclient-generated-begin
    // #lldbclient-generated-end
]

    lldbclient.py 會使用這些註解偵測設定檔的寫入位置。如果清單中還有其他項目，請在其他設定後方加上註解行。

  4. 在您執行 envsetup.sh 和 lunch 的終端機中執行下列指令：
    lldbclient.py --setup-forwarding vscode-lldb \
      --vscode-launch-file LAUNCH_JSON_PATH \
      ANY_OTHER_FLAGS -p pid | -n proc-name | -r ...

    lldbclient.py 會將產生的設定寫入 launch.json，並繼續執行。這是正常現象，請勿終止 lldbclient.py 程式。如果省略 --vscode-launch-file，指令碼會列印 JSON 程式碼片段，您必須手動複製並貼到 launch.json。

    由於工具會以特定方式剖析標記，因此 -r 標記 (如果有) 必須是最後一個標記。

  5. 開啟「Run and Debug」側欄，新的設定應會顯示在偵錯工具清單中。按下「開始偵錯 (F5)」。偵錯工具應在 10 到 30 秒後連線。

    如果「Run and Debug」檢視畫面中沒有顯示新設定，請重新載入視窗以重新整理偵錯工具清單 - 按下 Ctrl + Shift + P 鍵並輸入 reload window。

  6. 偵錯完成後，請前往執行 lldbclient.py 的終端機，然後按下 Enter 鍵結束 lldbclient.py 程式。之後執行指令碼時，系統會在 #lldbclient-generated 註解之間產生設定，並取代舊內容，因此您不必手動移除這些內容。

如要在產生的啟動設定檔中新增自訂屬性，您可以使用 --vscode-launch-props 標記。例如：

lldbclient.py --setup-forwarding vscode-lldb \
    --vscode-launch-props \
    '{"initCommands" : ["script print(\"Hello\")"], "preLaunchTask" : "Build"}' \
    ...
 範例屬性會讓 VS Code 在偵錯前執行名為 Build 的工作，並在指令碼產生的步驟中附加新的偵錯初始化步驟。如要查看可用屬性的總覽，請參閱 VS Code 說明文件和 CodeLLDB 擴充功能的使用者手冊。