Aurorix GTAGS

Aurorix GTAGS 是一个面向 Linux 工作区的 GNU GLOBAL 插件，用于 C/C++ 工程的定义跳转、引用查询、符号大纲、调用层次、GTAGS/GRTAGS/GPATH 索引管理，以及 htags HTML 源码浏览页面生成和预览。它既适用于本机 Linux VS Code，也适用于 VS Code Remote 连接到 Linux 主机的场景。

本插件保留了 sailsxu.gtags 中在当前工程里验证可用的核心跳转方式：

global --path-style=absolute --from-here=<line>:<file> --result=grep <symbol>

但插件身份、命令 ID、配置项、菜单项和市场发布元信息均已改为 Aurorix 独立命名空间。

主要功能

1. GNU GLOBAL 导航能力

支持：

定义跳转；
查找引用；
当前文件符号；
工作区符号；
调用层次；
基础补全。

常用快捷键：

F12               跳转定义
Shift + F12       查找引用
Shift + Alt + H   调用层次
Ctrl + Shift + O  当前文件符号
Ctrl + T          工作区符号

2. 资源管理器文件夹/空白处右键菜单

右键菜单有两种使用方式：

右键某个文件夹：作用范围是这个文件夹及其子目录。
右键资源管理器空白处：作用范围是当前 VS Code 打开的项目根目录，也就是整个项目。

文件上不显示这些菜单。

菜单项包括：

Aurorix GTAGS：在此文件夹初始化 GTAGS
Aurorix GTAGS：更新此文件夹的 GTAGS
Aurorix GTAGS：重建此文件夹的 GTAGS
Aurorix GTAGS：在此文件夹初始化 HTAGS HTML
Aurorix GTAGS：更新此文件夹的 HTAGS HTML
Aurorix GTAGS：重建此文件夹的 HTAGS HTML
Aurorix GTAGS：预览 HTAGS HTML
Aurorix GTAGS：停止 HTAGS 预览
Aurorix GTAGS：卸载 HTAGS 预览文件

3. GTAGS 初始化、更新、重建

Init GTAGS

如果当前文件夹或其上级目录已经存在：

GTAGS
GRTAGS
GPATH

插件不会重复生成，会提示已经存在。

如果不存在，会在右键选中的文件夹执行：

unset GTAGSLABEL
gtags -v

执行过程在 VS Code Terminal 中进行，可以看到 -v 进度信息。

Update GTAGS

插件会自动向上查找已有 GTAGS/GRTAGS/GPATH 的目录，然后执行：

unset GTAGSLABEL
global -u -v

Rebuild GTAGS

重建前会弹出二次确认。

确认后执行：

unset GTAGSLABEL
rm -f GTAGS GRTAGS GPATH
gtags -v

4. HTAGS HTML 源码浏览

htags 会根据 GTAGS/GRTAGS/GPATH 生成 HTML 源码浏览页面。

默认输出目录：

HTML/

Init HTAGS HTML

如果 HTML/index.html 已存在，插件会提示已经存在，不重复生成。

否则执行：

unset GTAGSLABEL
htags -v

Update HTAGS HTML

执行：

unset GTAGSLABEL
global -u -v
htags -v

Rebuild HTAGS HTML

重建前会二次确认。

确认后执行：

unset GTAGSLABEL
rm -rf HTML
htags -v

Preview HTAGS HTML

插件会在 workspace 端启动一个本地 HTTP server，并给出可打开链接。

默认端口：

默认链接：

http://127.0.0.1:57658/index.html

可通过设置修改端口：

{
  "aurorixGtags.htagsPreviewPort": 57658
}

停止 HTAGS 预览

停止当前文件夹对应的 HTAGS HTTP 预览服务，释放端口占用和内存资源。

卸载 HTAGS 预览文件

删除选中文件夹内的：

HTML/

执行前会二次确认，并会先停止该文件夹对应的预览服务。

5. 自动写入 Git 本地排除

插件执行 GTAGS / HTAGS 初始化、更新、重建时，会自动写入：

.git/info/exclude

GTAGS 相关排除：

/GTAGS
/GRTAGS
/GPATH

HTAGS 相关排除：

/HTML/

这些规则只在本机生效，不会提交，不会 push。

6. 内置安装命令

命令面板只保留一个安装命令：

Aurorix GTAGS: Install GNU GLOBAL + Universal Ctags

该命令会在 VS Code Terminal 中源码编译安装：

Universal Ctags p5.9.20210829.0
GNU GLOBAL 6.6.13

默认版本的源码包已经内置在插件中，所以用户没有自定义 URL 时不依赖网络下载源码包。

安装脚本会先检测 Linux 架构：

x64
arm64
armv7l
riscv64

如果插件将来内置了对应 linux-<arch> 的预编译工具包，会优先解压安装；如果没有对应预编译包，则自动退回到内置源码包本机编译，因此本机 Linux 和 VS Code Remote Linux 都可以使用。

默认安装到：

$HOME/local

安装脚本会自动清理这些残留配置：

export GTAGSLABEL=ctags
export GTAGSLABEL="ctags"
GTAGSLABEL=ctags
GTAGSLABEL="ctags"

并写入：

unset GTAGSLABEL

这样可以避免 GRTAGS 引用库几乎为空，导致 global -rx 查不到引用。

7. 函数图与函数体内流程图

插件新增了类似 Visor 方向的可视化能力，但不直接照搬其发布元信息或源码结构，而是在 Aurorix GTAGS 内实现同类效果：

编辑器中右键函数名，可在侧边栏显示函数图；
支持独立窗口查看；
支持点击图中节点跳转到对应函数或代码行；
支持函数级调用图：左侧是调用当前函数的函数，中间是当前函数，右侧是当前函数调用的函数；
支持函数体内轻量流程图：显示 if/for/while/switch/return/call 等关键流程节点；
独立窗口快捷键：

Ctrl + Alt + G

该快捷键左手可单手操作，并避开 VS Code 常用默认主快捷键。

路径高亮与 Pin 固定

函数级调用图和函数体内流程图都支持：

点击节点后，高亮从中心函数或流程起点到该节点的路径；
当前选中的节点使用额外强调色；
点击 PIN 后，当前路径会固定为金色背景；
再点击其它节点时，新节点会成为当前选择，但被 Pin 的旧路径会继续保留；
再次点击 PIN 会取消固定。

深度设置

函数体内流程图顶部提供嵌套深度设置，默认值为：

用于控制嵌套很多层 if/for/while/switch 时最多渲染多少层。点击“应用”后会同步写入 VS Code 设置 aurorixGtags.internalFlowMaxDepth，下次重新打开函数图仍然生效。

导出

函数图支持：

复制 Mermaid
导出 .mmd
导出 .svg
导出 .png

导出时会调用 VS Code 原生保存对话框，由用户选择保存路径。

如果用户选择的导出路径位于 Git 仓库内，插件会把该导出文件写入 .git/info/exclude，避免误提交。

配置项

`aurorixGtags.htagsPreviewPort`

HTAGS HTML 预览端口。

默认：

`aurorixGtags.globalExecutable`

global 可执行文件路径。

默认优先使用：

$HOME/local/bin/global

如果不存在，则使用：

global

`aurorixGtags.gtagsExecutable`

gtags 可执行文件路径。

默认优先使用：

$HOME/local/bin/gtags

`aurorixGtags.htagsExecutable`

htags 可执行文件路径。

默认优先使用：

$HOME/local/bin/htags

`aurorixGtags.definitionProviderLanguage`

启用 GNU GLOBAL 导航能力的语言列表。

默认：

cpp,c,proto3,proto

安装方式

安装 VSIX：

code --install-extension /workspace/aurorix-gtags/dist/aurorix-gtags-0.2.9.vsix --force

然后执行：

Developer: Reload Window

发布信息

publisher: Aurorix
name: aurorix-gtags
displayName: Aurorix GTAGS
version: 0.2.9
extensionKind: workspace

English Summary

Aurorix GTAGS is a GNU GLOBAL based VS Code extension for Linux workspaces, including local Linux VS Code and VS Code Remote sessions connected to Linux hosts. It provides C/C++ navigation, GTAGS index management from Explorer folder context menus, HTAGS HTML generation/preview, and a user-level installer for Universal Ctags + GNU GLOBAL.

It keeps the practical global --from-here definition query behavior while using independent Aurorix marketplace metadata and command namespace.

Main features:

Definition / references / document symbols / workspace symbols / call hierarchy.
Explorer folder context menu for GTAGS init/update/rebuild.
Explorer folder context menu for HTAGS HTML init/update/rebuild/preview.
Automatic .git/info/exclude updates for GTAGS, GRTAGS, GPATH, and HTML/.
Built-in install command for user-level GNU GLOBAL + Universal Ctags.
Default HTAGS preview port: 57658.

图标

插件内置 128x128 PNG 图标：

icon.png

两个独立侧边栏视图

插件现在提供两个不同图标的侧边栏视图：

函数级调用图：右键函数名后显示函数之间的调用关系图。
函数体流程图：侧边栏打开时，光标位于函数体内部会自动生成函数体内部流程图。

两类图都使用 Mermaid 渲染为一整张可缩放、可拖拽的图画布，不再使用列表式展示。控制按钮悬浮在画布内部，不挤占画布空间。

完全离线图表资源

函数级调用图和函数体流程图使用本地打包资源，不再依赖 CDN：

media/vendor/mermaid.min.js
media/vendor/svg-pan-zoom.min.js

同时已把 Visor 方向使用的 Tree-sitter WASM 资源放入插件包，供后续/增强解析使用：

media/wasm/tree-sitter.wasm
media/wasm/tree-sitter-c.wasm
media/wasm/tree-sitter-cpp.wasm
media/wasm/tree-sitter-go.wasm
media/wasm/tree-sitter-java.wasm
media/wasm/tree-sitter-python.wasm
media/wasm/tree-sitter-rust.wasm
media/wasm/tree-sitter-typescript.wasm

Webview 使用 webview.asWebviewUri(...) 加载插件内资源。

函数级图与函数体图的控制项区别

函数级调用图不会显示嵌套深度，因为函数调用关系没有嵌套深度概念。

函数体流程图才显示嵌套深度，并且点击“应用”后会持久化到 aurorixGtags.internalFlowMaxDepth。

独立窗口按钮会打开或聚焦同一个 Webview Panel，并用当前图刷新内容。

函数级调用图刷新规则

函数级调用图只通过编辑器右键手动触发生成，不会自动跟随光标更新。

函数级调用图里的“刷新”只重新渲染当前图，不重新读取当前光标位置，避免大工程里反复查询造成性能浪费。

函数体流程图仍然是被动自动能力：对应侧边栏打开时，光标位于函数体内部才自动生成。

独立窗口和自动生成规则

Ctrl + Alt + G 会打开或聚焦图表独立窗口，并尝试调用 VS Code 的 workbench.action.moveEditorToNewWindow，效果对齐 Visor 的独立窗口逻辑。

函数体流程图只在以下条件下自动生成：

函数体流程图侧边栏可见；或
独立窗口当前显示的是函数体流程图并且可见。

函数级调用图只通过右键手动触发，不自动跟随光标。

函数体流程图自动刷新规则

函数体流程图在重新显示时会强制重生成当前光标所在函数，即使仍然是同一个函数，也会重新生成，以反映源码修改。

触发条件：

函数体流程图侧边栏变为可见；
独立窗口当前显示函数体流程图并回到前台；
当前活动文档发生修改且函数体流程图正在显示；
光标变化且函数体流程图正在显示。

函数级调用图不参与这些自动刷新，仍然只通过右键手动触发。

按 Visor 图表相关实现补强

图表相关部分按 Visor 的稳定设计补强：

节点 ID 使用 sanitizeId，不再来源于源码文本；
节点显示文本使用 escapeString，按字符转义双引号、反斜杠、换行、尖括号和反引号；
Webview Panel 使用 create/reveal 复用逻辑，并尝试 moveEditorToNewWindow；
Ctrl + Alt + G 不再要求编辑器焦点，可直接打开或聚焦图表独立窗口；
Webview 按钮使用 addEventListener 绑定，不依赖内联点击；
Mermaid 渲染失败时显示可诊断的 Mermaid 源文本。

0.2.9 短描述更新

插件扩展列表中显示在插件名下方的 description 已更新，包含完全离线函数级调用图、函数体流程图、独立窗口、节点跳转、路径高亮、Pin 固定和图表导出等新功能。