Sourcetrail 如何配置空 C/C++ 源组的待索引文件、Include 路径与编译器标志

Sourcetrail 如何配置空 C/C++ 源组的待索引文件、Include 路径与编译器标志

【免费下载链接】SourcetrailSourcetrail - free and open-source interactive source explorer项目地址: https://gitcode.com/GitHub_Trending/so/Sourcetrail

当你的 C/C++ 项目既不能从构建系统导出 JSON Compilation Database，也不是 Visual Studio 工程时，官方文档给出的做法是创建一个Create Empty的 C/C++ 源组（Source Group）：手动指定待索引的文件、Include 路径与编译器标志，再让 Sourcetrail 执行索引。本文按一次真实操作走通这条路径：在 Project Setup Wizard 中配置这三类设置，创建项目并启动索引，最后用索引结果和错误列表验证配置是否生效。Sourcetrail 的 C/C++ 索引由 Clang 11.0.0 提供支持；遇到加载 C/C++ 代码的兼容性问题，文档指向 Clang 官方的语言兼容性说明。

前提条件是已安装并能运行 Sourcetrail（Windows：解压 zip 后运行setup.exe按向导安装；macOS：打开 dmg 把Sourcetrail.app拖入 Applications；Linux：运行 tarball 中的Sourcetrail.sh，或给 AppImage 赋予执行权限后运行）。

什么情况下选择 Create Empty 源组

C 与 C++ 的源组设置类型相同，共有三种：

• From Compilation Database：使用 CMake 时通过定义CMAKE_EXPORT_COMPILE_COMMANDS标志导出compile_commands.json（Visual Studio 的 CMake 生成器不支持）；Make 项目用 Bear 在模拟构建过程中生成该文件；Qt Creator 4.8 起可从 Build 菜单选择 "Generate Compilation Database"。Compilation Database 包含构建所需的信息（源文件、Include 路径、编译器标志），文档建议能用就用；基于它创建的源组会在每次 refresh 时与 compilation database 的变化保持同步。
• From Visual Studio：通过 Sourcetrail 的 Visual Studio 插件导出 Compilation Database，后续步骤与上一致。
• Create Empty：以上都不适用时才选择它，即本文走通的路径。

进入 Project Setup Wizard

启动 Sourcetrail 后在 Start Window 点击New Project（也可以用 Project 菜单的New Project项，快捷键 Windows/LinuxCtrl + N、macOSCmd + N），先填两项基本设置：

• Sourcetrail Project Name：项目名称，同时是 Sourcetrail 生成的.srctrlprj文件的名字；
• Sourcetrail Project Location：.srctrlprj项目文件的存放位置。

点击Add Source Group（或 Source Group 列表下方的+）进入源组创建，在下一步选择语言与源组类型后点Next继续。

同一个对话框也用于事后修改：从左侧列表选中某个 Source Group 即可编辑其内容与名称，+新增、-删除、☐复制；还可以把某个源组的active标志设为 false，使其在项目刷新时不被索引。

配置待索引文件

选择 C 或 C++ 语言、源组类型 Create Empty 后进入配置页。与"索引哪些文件"相关的设置有三项：

• Files & Directories to Index：定义哪些文件和目录会被索引。填入一个目录会递归加入其中所有源文件和头文件；如果项目源码在一处、而生成的源文件放在另一处，需要把那个目录也加进来。
• Source File Extensions：定义合法的源文件扩展名，含点号，例如.cpp。Sourcetrail 只尝试索引匹配这些扩展名的文件。
• Excluded Files & Directories：定义要从索引中排除的文件和目录。支持两个通配符，文档给出的匹配示例是：
  • *表示除\或/之外的字符：src/*/test.h匹配src/app/test.h，但不匹配src/app/widget/test.h和src/test.h；
  • **表示任意字符：src**test.h同时匹配src/app/test.h、src/app/widget/test.h和src/test.h。

这些路径都支持环境变量，写法为${VARIABLE_NAME}或%VARIABLE_NAME%（设置表中以${ENV_VAR}出现，ENV_VAR即变量名的占位写法，替换为你系统里真实的变量名即可）。

配置 Include 路径

Include Paths用于解析被索引源文件和头文件中的#include指令，通常对应编译器的-I或-iquote标志。文档给出的填写规则：

• 如果项目中所有#include指令都相对于项目根目录，就把根目录加进来；
• 如果项目还包含外部库的文件，也要加入对应目录。文档示例是path/to/boost_home/include，即把示例中的库路径替换为你实际使用的外部库的 include 目录。

Global Include Paths在你的所有项目中生效，并与项目级 Include Paths 叠加使用，通常对应-isystem标志，适合放系统头文件路径。该字段提供自动检测（文档说明支持对 Clang、GCC 和 Visual Studio 编译器的自动检测），也可以手动添加。

需要手动找系统头文件位置时，文档按平台给出方法：

• Linux：运行gcc -x c++ -v -E /dev/null或clang -x c++ -v -E /dev/null；
• macOS：运行gcc -x c++ -v -E /dev/null；

两个命令的输出中，编译器的头文件搜索路径位于这两行之间：

#include <...> search starts here: . . . End of search list.

• Windows：系统头文件通常随编译器提供。使用 Visual Studio IDE 时位于<path_to_visual_studio>/VC/include/（path_to_visual_studio为 Visual Studio 安装目录的占位，替换为实际安装路径）；不使用 Visual Studio 时，可在C:/Program Files (x86)/Windows Kits/的子目录中查找。

macOS 上另有两个只与该平台相关的字段：Framework Search Paths 与 Global Framework Search Paths，用于定位项目使用的.framework文件，后者同样作用于所有项目。

配置编译器标志与其他编译选项

Compiler Flags定义索引期间使用的额外编译器标志，要带上前导短横线。文档示例：-DRELEASE会为RELEASE增加一个#define。

同一页面还有几个与编译相关的选项：

• Standard：索引使用的语言标准，通常已预选最近的标准；
• Cross-compilation：勾选Use specific target后在下拉框中指定目标平台，具体目标平台写法参考 clang 交叉编译文档；
• Precompiled Header File：指定用于生成 Precompiled Header File 的头文件路径，PCH 会在索引前作为预索引步骤生成；不提供路径则不生成；
• Precompiled Header Flags：定义是否复用已提供的编译器标志来生成 PCH，以及只为 PCH 生成额外定义的标志。

用 Path List Box 添加路径

页面上所有路径字段都是 Path List Box 控件，交互方式一致：

• 点+图标添加一行新路径，点-删除选中的行；
• 点击某行选中后可直接键入；行内的...会打开文件对话框供选择文件或目录；
• 可以从文件系统直接把文件/目录拖进框内一次添加多个路径；
• 点右下角的钢笔图标进入纯文本编辑：每行一个列表项，编辑完点Save保存，Cancel放弃修改。

创建项目并启动索引

配置完成后，在 Project Setup Wizard 点击Create，关闭窗口并创建项目。随后 Sourcetrail 会询问是否开始索引，点击Start并等待完成；索引期间进度显示在 Indexing Dialog 和 Status Bar 中。

Start Indexing Dialog 会先显示待索引与待清除的文件数量，并提供刷新模式：

• Updated files：重新索引自上次索引以来被修改的文件、依赖这些文件的所有文件以及新增文件；
• Incomplete & updated files：在前者基础上加上上次索引时出过错的文件；
• All files：删除旧索引并重新索引全部文件。

索引进行中的 Indexing Dialog 显示已索引文件数、最后开始索引的文件、错误数量和百分比估计；点Stop或按ESC可中断，之后可以通过 refresh 继续。索引结束后弹出 Finished Indexing Dialog，给出已索引文件、耗时与错误的信息。

验证配置是否生效

索引完成且没有错误时，Sourcetrail 在 graph view 中展示所有已索引符号的概览，并在 code view 中显示一些统计信息，说明待索引文件已被正确拾取。

如果索引产生错误，status view 会列出错误列表：点击状态栏右侧的 errors 标签或错误表中的某一行，可以在 code view 中查看错误位置。Errors Tab 提供以下字段：

点击列头可按字段排序，下方复选框可按条件过滤。错误常见的原因是#include无法解析或缺少宏定义——回到源组设置补充 Include Paths 或 Compiler Flags（Errors Tab 里点Edit Project可直接打开 Edit Project Dialog），然后用Refresh（F5，macOS 为Cmd + R）重新索引变更文件及其依赖文件。注意：只要某个具体文件没有变化，Sourcetrail 就不会重新索引它，这种情况使用 Edit 菜单中的Force Refresh选项。也可以选择不修复错误、带着不完整索引继续使用。

限制与注意

• Global Include Paths作用于所有项目而不是单个项目，项目专属的 include 目录应放在项目级Include Paths中；
• Sourcetrail 只尝试索引Source File Extensions中列出的扩展名匹配的文件，遗漏的扩展名意味着对应文件根本不会被索引；
• 如果项目能够导出compile_commands.json，优先使用 Compilation Database 源组，可省去手动维护 Include 路径与编译器标志；
• 索引使用的语言标准由Standard设置决定，C/C++ 的语言特性支持边界以 Clang 11.0.0 的兼容性说明为准。

【免费下载链接】SourcetrailSourcetrail - free and open-source interactive source explorer项目地址: https://gitcode.com/GitHub_Trending/so/Sourcetrail