C++ 调试¶

本指南将向您展示如何使用调试符号构建 PyTorch C++ 代码，以及如何使用 VSCode 配合 GDB 或 LLDB 来调试 PyTorch。

为什么要需要这个？¶

本指南适用于 PyTorch 或 PyTorch/XLA 的贡献者，他们使用 C++ 来构建功能，例如自定义 C++ 操作。

安装 GDB：GNU 项目调试器¶

您可以使用官方说明来安装 GDB。如果您使用的是 conda 环境，也可以使用以下命令安装 GDB：

conda install -c conda-forge gdb

使用调试符号构建 PyTorch¶

调试选项在 GitHub 上的 setup.py 中进行了描述。

# Environment variables you are probably interested in:
#
#   DEBUG
#     build with -O0 and -g (debug symbols)
#
#   [...]
#
#   USE_CUSTOM_DEBINFO="path/to/file1.cpp;path/to/file2.cpp"
#     build with debug info only for specified files

当定义时，DEBUG 将导致构建过程为所有源文件生成调试符号。它还会阻止编译器执行任何优化，这将导致生成的二进制文件运行速度过慢，无法执行有意义的工作。我们建议使用 USE_CUSTOM_DEBINFO 环境变量来指定一个分号分隔的源文件列表，您希望为其生成调试符号。这允许您仅为您想要调试的源文件生成调试符号。所有其他源文件都像往常一样构建和优化。

我们建议采取以下步骤：

确定您要调试的源文件。
使用类似于 USE_CUSTOM_DEBINFO="aten/src/ATen/native/Linear.cpp" python setup.py develop 的命令，用调试符号构建该文件。
设置断点并启动调试器会话。在调试过程中，您会发现需要调试的其他文件。
将这些文件添加到 USE_CUSTOM_DEBINFO 环境变量中。
使用类似于 USE_CUSTOM_DEBINFO="aten/src/ATen/native/Linear.cpp;newfile.cpp" python setup.py develop 的命令重新构建。
再次启动您的调试器会话。

此时，您的 PyTorch 已经使用调试符号构建，并准备好使用 GDB 进行调试。但是，我们建议使用 VSCode 进行调试。有关更多信息，请参阅使用 VSCode 进行调试。

验证您的文件已构建¶

对于 PyTorch，我们建议您每次都进行一次完整的清理和重新构建。不幸的是，修改文件以更新其时间戳并不能可靠地导致该文件被重新构建。

在 python setup.py develop 命令的输出中，查找以 Source files with custom debug infos 开头的行，以确保您的文件已使用调试符号构建。例如：

--  USE_ROCM_KERNEL_ASSERT : OFF
-- Performing Test HAS_WMISSING_PROTOTYPES
-- Performing Test HAS_WMISSING_PROTOTYPES - Failed
-- Performing Test HAS_WERROR_MISSING_PROTOTYPES
-- Performing Test HAS_WERROR_MISSING_PROTOTYPES - Failed
-- Source files with custom debug infos: aten/src/ATen/Utils.cpp aten/src/ATen/ScalarOps.cpp aten/src/ATen/EmptyTensor.cpp aten/src/ATen/core/Tensor.cpp aten/src/ATen/native/Linear.cpp

在开始新的调试会话之前，请确保您已关闭任何之前的调试会话。

VSCode 配置¶

要使用 VSCode 进行调试，您必须安装 Microsoft 发布的 C/C++ 扩展包。在 VSCode 的扩展选项卡中搜索 ms-vscode.cpptools-extension-pack。

Microsoft C/C++ Extension Pack

接下来，在 pytorch/.vscode 文件夹中创建一个名为 launch.json 的文件。以下是一个可供参考的示例文件。您需要根据您的具体安装情况调整文件路径。

{
    "version": "0.2.0",
    "configurations": [
        {
            "name": "GDB a python interpreter",
            "type": "cppdbg",
            "request": "launch",
            "program": "/home/USERNAME/miniconda3/envs/torch310/bin/python", // Replace with your executable's path
            "args": [],
            "cwd": "${workspaceFolder}",
            "environment": [],
            "externalConsole": false,
            "MIMode": "gdb",
            "setupCommands": [
                {
                    "description": "Enable pretty-printing for gdb",
                    "text": "-enable-pretty-printing",
                    "ignoreFailures": true
                },
                {
                    "description": "Set Disassembly flavor to Intel",
                    "text": "-gdb-set disassembly-flavor intel",
                    "ignoreFailures": true
                }
            ],
            // "preLaunchTask": "C/C++: g++ build active file",
            "miDebuggerPath": "/home/USERNAME/miniconda3/envs/torch310/bin/gdb" // Replace with your gdb location
        }
    ]
 }

LLDB¶

您也可以使用 LLDB 进行调试。根据我们的经验，LLDB 速度更快。但两者都有其怪癖，您可能会从两者之间的切换中受益。

通过在 VSCode 的扩展中搜索 vadimcn.vscode-lldb 来为 VSCode 安装 LLDB。

然后将以下代码片段添加到您的 launch.json 文件中。

    {
        "name": "LLDB Python",
        "type": "lldb",
        "request": "launch",
        "program": "/home/your-user-id/miniconda3/envs/torch310/bin/python",

    }

将 program 的值替换为您虚拟环境中的 python 的路径。

使用 VSCode 进行调试¶

打开您要调试的文件。
单击行号左侧以设置断点。此时会显示一个红点，表示断点已设置。断点也会列在调试器选项卡中。
使用绿色播放按钮右侧的下拉菜单选择 GDB 或 LLDB 配置。
单击绿色播放按钮以开始调试会话。调试器将处理 launch.json 文件中设置的规则。

启动调试会话后，红点将变为一个空的白色圆圈，表示 torch 符号尚未加载。
在 Python 解释器中，执行 import torch。这将加载您构建的 torch 库。断点将再次显示为红点。
运行一个将触发断点的命令，例如 torch.einsum()。一个黄色的箭头指示当前文件位置。变量和调用栈信息显示在左侧。

一个实际的构建命令¶

随着时间的推移，您将为您的构建命令收集额外的标志，例如不构建某些库以加快构建速度，或添加诊断信息。以下设置将关闭 CUDA 构建并启用处理一个环境变量来打印调度程序跟踪。

USE_CUSTOM_DEBINFO="aten/src/ATen/native/Linear.cpp" USE_CUDA=0 LD_LIBRARY_PATH=/home/USERNAME/miniconda3/envs/torch310/lib CFLAGS="-DHAS_TORCH_SHOW_DISPATCH_TRACE" python setup.py develop

未来工作¶

本指南演示了如何为 PyTorch C++ 文件构建调试符号。未来的工作将演示如何为 PyTorch/XLA C++ 文件添加调试符号。