使用调试程序

本页详细介绍了如何使用 LLDB 进行操作系统开发。对于应用开发，请参阅调试应用，其中介绍了如何使用 Android Studio GUI（基于 LLDB）。

我们不再支持或提供 GDB。如果您是从 GDB 改用 LLDB，应该先阅读 LLDB 教程。如果您是 GDB 专家用户，那么在过渡期间，GDB 到 LLDB 命令映射表会非常有用。

前提条件

如需使用调试程序，请执行以下操作：

使用常规 envsetup.sh 命令设置构建环境。
运行您在构建时使用的同一 lunch 命令。请注意，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

调试运行中的应用或进程

如需连接到正在运行的应用或原生守护程序，请配合使用 lldbclient.py 和 PID。例如，如需调试 PID 为 1234 的进程，请在主机上运行以下命令：

注意：请勿将 -p 与 --port 混淆。-p 用于提供 PID，--port 用于提供未使用的端口号。如需了解详情，请查看 lldbclient.py --help。

lldbclient.py -p 1234

此脚本会设置端口转发，在设备上启动相应的远程调试桩，在主机上启动调试程序，配置该调试程序以查找符号，然后将该调试程序连接到远程调试桩。

注意：在 Android 6 及更低版本的系统中，该脚本是一个名为 lldbclient 的 Shell 脚本，而不是名为 lldbclient.py 的 Python 脚本。

调试启动的原生进程

如需在进程启动时对其进行调试，请使用 lldbclient.py 及 -r 选项。例如，如需调试 ls /bin，请在主机上运行以下命令：

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

然后，在调试程序的提示符处输入 continue。

调试启动的应用

有时，您需要在应用启动时对其进行调试；例如在应用发生崩溃时，您需要逐步检查代码，以查看崩溃之前发生的情况。附加调试程序有时能解决问题，但有时不能，因为应用有可能在你还没来得及附加调试程序时已经崩溃。logwrapper 方法（用于 strace）不一定能解决所有的问题，因为应用可能没有权限打开端口，而 lldbserver 会继承这项限制。

如需调试应用启动，请使用“设置”中的开发者选项来指示应用等待附加 Java 调试程序：

依次转到设置 > 开发者选项 > 选择调试应用，并从列表中选择您的应用，然后点击等待调试程序。
启动应用。您可以从启动器启动，也可以在命令行中运行以下命令来启动：
```
adb shell am start -a android.intent.action.MAIN -n APP_NAME/.APP_ACTIVITY
```
等待应用加载，然后会出现一个对话框，它会提示您应用正在等待附加调试程序。
正常附加 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 调试代码的步骤：

确保运行 lldbclient.py 或 lldbclient.py 所需的所有构建工件（例如符号）都存在。
在 VS Code 中，按 Ctrl + Shift + P 运行命令，搜索 Debug: Add Configuration…，然后选择 LLDB。这将打开一个 launch.json 文件，并将新的 JSON 对象添加到列表中。
将新添加的调试程序配置替换为两个注释行（// #lldbclient-generated-begin 和 // #lldbclient-generated-end），让您的配置列表如下所示：
```
"configurations": [
    // #lldbclient-generated-begin
    // #lldbclient-generated-end
]
```
lldbclient.py 使用这些注释来检测在哪里写入配置。如果列表中还有其他项，请将注释行添加到末尾（在其他配置之后）。
在您运行 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 标记必须是最后一个标记（如果存在）。
打开 Run and Debug 边栏，新配置应显示在调试程序列表中。按 Start Debugging (F5)。调试程序应在 10 到 30 秒后连接。
如果新配置未出现在“Run and Debug”视图中，请重新加载窗口以刷新调试程序列表：按 Ctrl + Shift + P 并输入 reload window。
完成调试后，请前往运行 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 扩展程序的用户手册中找到可用属性概览。