GDBFrontend 是一个简单、灵活且可扩展的图形化调试器。

安装

必要条件

• GDB >= 8.2（带 python3）
• python3 >= 3.6
• tmux

PIP 包（Python Wheel）[推荐]

你可以使用 pip 安装 GDBFrontend。

sudo python3 -m pip install gdbfrontend

如果已经安装并且你在升级

sudo python3 -m pip install --upgrade gdbfrontend

或者如果你想安装特定的 GIT 快照：

sudo python3 setup.py install

然后你可以运行

gdbfrontend

从 GIT 运行

你可以下载最新源码并运行它。

你可以通过以下命令运行 gdb-frontend：

git clone https://github.com/rohanrhu/gdb-frontend.git gdb-frontend
cd gdb-frontend
./gdbfrontend

然后你可以通过以下地址打开它：

http://127.0.0.1:5550/

你可以使用以下命令打开 GDB shell：

tmux a -t gdb-frontend

Arch Linux（AUR）

你可以为基于 Arch 的发行版安装 Arch Linux 包。（AUR 包）

yay -S gdb-frontend-bin

然后运行它：

gdbfrontend

Flatpak

Flatpak 包是待办事项。

使用 GDBFrontend 调试 Docker 化的 C/C++ 应用

按照这个教程学习如何使用 GDBFrontend 调试 Docker 化的 C/C++ 应用。

使用 GDBFrontend 进行嵌入式调试

按照这个快速教程使用 GDBFrontend 调试嵌入式设备。

使用 GDBFrontend 调试 Python C 扩展

按照这个快速教程调试原生 C Python 扩展。

如何开发 GDBFrontend 插件？

GDBFrontend 拥有强大且可扩展的 API。按照这个快速教程学习开发 GDBFrontend 插件。

如何将 GDBFrontend 集成到你的 Makefile 中？

按照这个快速教程了解针对特殊开发/调试需求的集成思路。

在 Linux 上使用 OpenOCD、GDB 和 GDBFrontend 调试 STM32

按照这个教程使用 OpenOCD 和 GDBFrontend 调试 STM32。

功能特性

表达式求值器

GDBFrontend 有一个表达式求值器，你可以同时使用多个。

指针可视化

链表可视化

条件断点

右键单击断点可以设置其条件。

连接表达式

所有变量、成员和项的表达式在 GDBFrontend 的 VariablesExplorer 中都是连接的。

进程管理器

你可以通过进程管理器查看、筛选或管理进程。

数组图可视化

增强协作

GDBFrontend 有一组名为“增强协作”的协作功能。

协作绘图

启用增强协作后，可以使用协作绘图。点击“绘图”或使用 Ctrl + Shift + X 快捷键绘图，使用 Ctrl + Shift + C 清除所有绘图。

同步源码查看

启用增强协作后，所有调试器客户端在源码查看上是同步的。

表达式悬停弹出变量浏览器

可扩展性

GDBFrontend 非常可扩展，并拥有强大的 API。以下是 GDBFrontend 可扩展性的一些示例。

./gdbfrontend

$ gdbfrontend --help
GDBFrontend 是一个简单、灵活且可扩展的图形化调试器。

选项：
  --help, -h:                                   显示此帮助信息。
  --version, -v:                                显示版本。
  --gdb-args="ARGS", -G "ARGS":                 指定 GDB 命令行参数。（可选）
  --gdb-executable=PATH, -g PATH:               指定 GDB 可执行文件路径（默认为 PATH 环境变量中的 "gdb" 命令。）
  --tmux-executable=PATH, -tmux PATH:           指定 Tmux 可执行文件路径（默认为 PATH 环境变量中的 "tmux" 命令。）
  --terminal-id=NAME, -t NAME:                  指定 tmux 终端标识符名称（默认为 "gdb-frontend"。）
  --credentials=USER:PASS, -c USER:PASS:        指定访问调试器的用户名和密码。
  --host=IP, -H IP:                             指定当前主机地址，可通过 HTTP 和 WS 服务器访问。
  --listen=IP, -l IP:                           指定 HTTP 和 WS 服务器的监听地址。
  --port=PORT, -p PORT:                         指定 HTTP 端口。（0 表示随机端口。）
  --url-base=PATH, -u PATH:                     指定 URL 基础路径。（默认：/）
  --readonly, -r:                               使代码编辑器只读。（注意：此选项与安全性无关。）
  --workdir, -w:                                指定工作目录。
  --plugin-dir, -P:                             指定插件目录。
  --dontopenuionstartup, -D:                    避免在启动后打开 UI。
  --verbose, -V:                                启用详细输出。

选项

--help, -h

显示帮助文本。

--version, -v

显示版本。

--gdb-args="ARGS", -G "ARGS"

指定 GDB 命令行参数。（可选）

--gdb-executable=PATH, -g PATH

你可以指定 GDB 可执行文件路径，例如 gdbfrontend --gdb-executable=/path/to/gdb。（可选）

--tmux-executable=PATH, -tmux PATH

你可以指定 Tmux 可执行文件路径，例如 gdbfrontend --tmux-executable=/path/to/tmux。（可选）

--terminal-id=PATH, -t PATH

你可以指定 Tmux 终端 ID，例如 gdbfrontend --terminal-id=terminal-name。（默认：gdb-frontend）

--credentials=USER:PASS, -c USER:PASS

指定访问调试器的用户名和密码。

--host=IP, -H IP

指定当前主机地址，可通过 HTTP 和 WS 服务器访问。

--listen=IP, -l IP

指定 HTTP 和 WS 服务器的监听地址。

--port=PORT, -p PORT

指定 HTTP 端口。（0 表示随机端口。）

--url-base=PATH, -u PATH

指定 URL 基础路径。（默认：/）

--readonly, -r

使代码编辑器只读。（注意：此选项与安全性无关。）

--workdir, -w

指定工作目录。

--plugin-dir, -P

指定插件目录。

--dontopenuionstartup, -D

避免在启动后打开 UI。

--verbose, -V

启用详细输出。

GDB 命令

GDBFrontend 的 GDB 命令以 gf- 开头。

gf-refresh

刷新所有浏览器客户端。

gf-theme [theme-name]

切换到所需的主题。例如：gf-theme light、gf-theme red 或 gf-theme default 切换到默认主题。

gf-list-plugins

列出插件目录中的所有 GDBFrontend 插件。

gf-load-plugin [plugin-name]

加载 GDBFrontend 插件。

gf-unload-plugin [plugin-name]

卸载 GDBFrontend 插件。

快捷键 / 热键

当前的热键如下所示。

主题

GDBFrontend 内置了主题。

要在主题之间切换，请在 GDB shell 中使用 gf-theme [THEME] 命令。

(gdb) gf-theme doki
(gdb) gf-theme sky
(gdb) gf-theme sakura
(gdb) gf-theme waifu
(gdb) gf-theme cyberpunk
(gdb) gf-theme dark
(gdb) gf-theme green
(gdb) gf-theme light
(gdb) gf-theme red

切换回默认主题：

(gdb) gf-theme

你也可以查阅插件开发教程。

GDBFrontend Python API

你可以通过 gdbfrontend 模块访问 GDBFrontend 的 Python API。

(gdb) python-interactive

>>> dir(gdbfrontend)

例如，你可以像这样获取所有客户端套接字：

>>> gdbfrontend.api.globalvars.httpServer.ws_clients
{1: <server.GDBFrontendSocket object at 0x...>}

或者获取所有插件：

>>> gdbfrontend.plugin.getAll()
['hello', 'theme_cyberpunk', 'theme_dark', 'theme_doki', 'theme_green', 'theme_light', 'theme_red', 'theme_sakura', 'theme_sky', 'theme_waifu']

共享会话的安全性

你可以使用 --credentials=USER:PASS 选项为你的调试器会话添加 HTTP 身份验证。

浏览器兼容性

GDBFrontend 主要在基于 Chromium 的浏览器上测试开发。在其他浏览器（尤其是 Firefox）上也能正常工作，但如果你在其他浏览器上遇到问题，可以提交错误报告。

故障排除

阻塞 GDB shell / 主线程

GDBFrontend 的大多数函数是线程安全的，并在 GDB 的主线程上工作。因此，如果你在 GDB shell 中运行了阻塞操作，GDBFrontend 函数必须等待它完成。

当线程安全的 GDBFrontend 函数需要工作而你在阻塞 GDB 的主线程时，你会收到此警告。

(gdb) shell
$ ...

当你退出 shell 时，阻塞的 GDBFrontend 函数将恢复工作。

注意： 有时你可能会在没有运行任何操作的情况下收到此警告，这意味着 GDB 事件循环中的某个操作耗时较长；在这种情况下，请忽略此警告。

僵尸进程

GDBFrontend 会向其子进程、你的应用程序及其子进程发送 SIGTERM 信号。如果你的应用程序创建了新进程并设置了它们的 PGID，GDBFrontend 可能无法关闭它们。在这种情况下，你应该向你的进程发送 SIGKILL 信号。

pkill -f gdb

表达式求值器性能建议

如果你使用 ExpressionEvaluator 并且展开了深度很大的变量/成员，则滚动和求值器窗口移动的性能可能会受到指针可视化的影响。在这种情况下，你可以关闭该求值器窗口的信号和槽指向。

GDB 相关问题与提示

• 在单步执行一次调用动态链接对象中函数的代码行之前，GDB 可能不会提供动态链接对象的源代码。 你可以在一行上设置断点并单步执行一次，之后在会话期间你将看到动态链接对象的源代码。

Windows

实际上，gdb-frontend 可以在 Windows 上运行，但 Windows 版本的 GDB 存在一些严重问题，导致无法在 Windows 上使用 gdb-frontend。当然，如果你使用 Windows 10，可以在 WSL 上使用 gdb-frontend。

Windows-GDB 的问题

• 在运行进程期间，GDB 的主线程会被阻塞。（gdb-frontend 有一个中断机制来修复此问题，但目前还不够。）
• Windows-GDB 的提示符在运行进程期间会被阻塞，并且中断应用程序时存在一些问题。

WSL

你可以在 WSL（适用于 Linux 的 Windows 子系统）上使用 gdb-frontend。

WSL 的问题

• 在 WSL 1 上，随机端口选项无法使用，因为 /proc/net/tcp 接口在 WSL 上无法正常工作。（WSL 2 没有此问题。）

版本管理

从 v0.2.0-beta 开始，GDBFrontend 采用了新的版本管理策略。

版本解读

在 vX.Y.Z-STABILITY 中：

• X 是主版本号，长期变化，包含主要特性和增强。
• Y 是次版本号，包含新特性和增强。
• Z 是bugfix版本，针对次版本的错误修复。
• STABILITY 是版本的稳定性级别。（alpha、beta、rcN、stable）

文档

文档尚待完善。

API 文档

API 文档尚待完善。

插件开发

你可以阅读插件开发教程。

主题开发

主题作为插件开发。

Discord

加入 Discord 社区。

🎊 贡献

你可以通过提交到项目或开发插件来贡献。欢迎所有提交。

贡献指南

❤️ 捐赠

• Patreon
• GitHub Sponsors

加密货币捐赠

建议捐赠 USDT 或 USDC，但你可以捐赠上述任何一种货币。🥳

许可证

版权所有 (C) 2019, Oğuzhan Eroğlu [email protected] (https://oguzhaneroglu.com/)

GNU 通用公共许可证 v3 (GPL-3)

你可以复制、分发和修改该软件，只要你在源文件中跟踪更改/日期。任何对软件的修改或包含（通过编译器）GPL 许可代码的软件，也必须在 GPL 下提供，并附上构建和安装说明。