TscanCode 静态代码分析实战：C/C++、C、Lua 三语言缺陷检测的编译、使用与规则原理剖析

• 静态分析
• 代码质量
• 开发工具
• 质量保障

TscanCode 是腾讯开源的静态代码分析工具，面向 C/C++、C# 和 Lua 三类语言，目标是帮助程序员在编码阶段尽早发现代码缺陷。本文基于项目根目录的 README.md 展开，完整覆盖其功能定位、编译方式与一行命令上手流程，并结合 trunk 源码进一步剖析命令参数的底层实现、README 中示例错误的检测原理以及cfg.xml规则配置体系，帮助读者既能开箱即用，也能读懂 TscanCode 的检测机制与可定制点。

一、项目定位与核心特性

TscanCode 的自我定位是一句直白的话："A fast and accurate static analysis solution for C/C++, C#, Lua codes"，即帮助开发者在缺陷刚出现时就把它找出来（help programmers to find out code defects at the very beginning）。README 中列出了四条核心特性：

从仓库的组织结构看，README 描述的语言分布是清晰的：

• C/C++ 分析引擎：完整开源，位于 trunk，包含lib/（核心分析库）、cli/（命令行入口）、common/（路径与文件枚举等公共模块）、externals/tinyxml/（XML 输出依赖）；
• C# 与 Lua 版本：README 明确说明"codes under trunk are only for TscanCode CPP version, C# and Lua version are in the internal review process"，即这两种语言的引擎源码未随仓库开放，但release/目录下提供了各平台的可执行程序（如 TscSharp、tsclua），且 samples 下配有完整的三语言示例。

版本演进方面，README 记录了几个关键节点：

• v2.15.02（2022-04-28）：修复 Lua 崩溃问题，开放更多 checker；
• v2.15.01（2022-01-19）：支持 Lua 5.4，并带来一批 bug 修复与新特性；
• v2.14.24（2018-02-24）：GUI 发布 Rule Package 便于规则定制，GUI 支持标记误报。

更完整的变更历史可查阅 CHANGELOG.md，例如其中还记录了 2.11.27 版本新增的lua_VarSpellWrongError（Lua 变量拼写错误检查）、CS_UnityMessgeSpellWrong（Unity 消息函数拼写检查，如把OnDestroy误拼成OnDestory）等细节。

二、编译构建：一条make命令的完整工程拆解

2.1 编译器要求

README 给出的编译前提是：

• 任意支持 C++11 的编译器均可编译；部分支持 C++11 的编译器也可能工作，最低参考线是 Visual Studio 2015 所具备的 C++11 特性；
• 若编译器不支持nullptr，可以通过 lib/cxx11emu.h 头文件做模拟兼容；
• 平台选项：Windows 用 Visual Studio 2015+，Linux 用 g++ 4.6+，macOS 用 clang++。

2.2 Visual Studio 构建

Windows 下使用解决方案文件 trunk/tscancode.sln：该文件默认配置为 Visual Studio 2015，但可以方便地切换到新旧版本的平台工具集；解决方案同时包含 x86 与 x64 两个平台目标，选择Release配置即可产出发布版本。

2.3 Linux/macOS：make构建细节

在 trunk 目录下执行：

make

这条"零依赖"命令背后的构建规则定义在 trunk/Makefile 中，值得逐条看一下：

ifndef CXX CXX=g++ endif ifndef CXXFLAGS CXXFLAGS=-std=c++0x -O2 -include lib/cxx11emu.h -DNDEBUG -Wall -Wno-sign-compare -Wno-unknown-pragmas -Wno-reorder endif # Force including libpthread LIBS+=-lpthread

几个关键点：

1. -include lib/cxx11emu.h：Makefile 默认把cxx11emu.h强制包含进每个编译单元，这正是 README 中"不支持 nullptr 时用它模拟"的落地方式；
2. -lpthread强制链接：分析引擎内置多线程执行器（对应 cli/tscthreadexecutor.cpp），因此 Linux 构建必须链接 pthread；
3. 产物构成：最终目标tscancode由四组对象文件链接而成——LIBOBJ（trunk/lib 下约 50 个分析核心源文件，如check*.o、tokenize.o、valueflow.o等）、CLIOBJ（trunk/cli 下的main.o、cmdlineparser.o、tscexecutor.o、tscthreadexecutor.o）、COMMONOBJ（trunk/common 下的路径与文件枚举模块）以及外置的externals/tinyxml/tinyxml2.o；
4. 支持通过CXX、CXXFLAGS环境变量覆盖默认编译器与编译选项。

三、一分钟上手：从空指针示例到 XML 报告

README 用了一个经典空指针缺陷作为"Usage at a glance"示例。下面这段代码的问题在于：对p做判空只说明p可能为空，因此在if作用域之外解引用*p是不安全的：

// func.cpp void func(int* p) { if(p == NULL) { printf("p is null!"); } printf("p is %d", *p); }

执行检查：

./tscancode --xml func.cpp 2>result.xml

注意--xml会把结果以 XML 格式写到错误流（stderr），因此用2>result.xml重定向。报告内容如下：

<?xml version="1.0" encoding="UTF-8"?> <results> <error file="func.cpp" line="7" id="nullpointer" subid="dereferenceAfterCheck" severity="error" msg="Comparing [p] to null at line 3 implies [p] might be null. Dereferencing null pointer [p]." /> </results>

报告字段含义：file/line定位到第 7 行的解引用；id为检查类别nullpointer；subid为具体缺陷子类dereferenceAfterCheck（先判空、后在判空作用域外解引用）；severity为严重级别；msg是可读的诊断说明。

3.1 这个错误是谁报出来的？——源码级溯源

dereferenceAfterCheck这个 subid 的报错实现位于 trunk/lib/checktscnullpointer2.cpp 的nullPointerError函数中。该函数根据表达式取值状态（CExprValue）分派到不同 subid：

else if (ev.IsCondCheckNull()) { ss << "Comparing [" << sExprLoc.Expr.ExprStr << "] to null at line " << ... // 若表达式含 "(" 归类为 funcDereferenceAfterCheck // 若表达式含 "[" 归类为 arrayDereferenceAfterCheck // 否则（普通指针/变量）走下面分支： reportError(sExprLoc.Begin, Severity::error, ErrorType::NullPointer, "dereferenceAfterCheck", ss.str().c_str(), ...); }

也就是说，README 示例中那句Comparing [p] to null at line 3 implies [p] might be null...的完整错误文本，正是由这段拼接逻辑生成。同一函数还区分了其他变体：invalidDereferenceIterator（迭代器失效解引用）、funcRetNull（函数返回值判空缺陷）、explicitNullDereference（显式空指针解引用）等。

3.2 subid 规则表：cfg.xml 中的规则开关与中文释义

每个 subid 的启用状态（value）、严重级别（severity）、规则中文名与说明集中在 trunk/cfg/cfg.xml 的nullpointer节点中，例如：

<id name="nullpointer" value="1"> <subid name="dereferenceAfterCheck" value="1" severity="Serious" rule_name="先判空后解引用" desc="指针先判空，然后在判空作用域外解引用……"/> <subid name="funcRetNull" value="0" severity="Warning" rule_name="函数返回值未判空解引用" desc="……"/> <subid name="dereferenceIfNull" value="1" severity="Critical" rule_name="指针为空解应用" desc="if条件判断指针等于NULL成立时对指针解引用，通常是判空条件写反了导致的"/> ... </id>

value="1"表示该规则默认启用，value="0"表示默认关闭；severity分Critical/Serious/Warning/Information四级。同文件中还以同样的粒度管理bufoverrun（缓冲区越界）、memleak（内存泄漏）等类别，每类都带有中文rule_name与desc。发布包 release/linux/TscanCodeV2.14.2395.linux/cfg 下除cfg.xml外，还附带std.cfg、windows.cfg、posix.cfg、qt.cfg、gtk.cfg、sdl.cfg、avr.cfg、gnu.cfg、microsoft_sal.cfg等平台/标准库配置，供不同代码库按需加载（C# 侧对应 TscSharp 的 cfg_cs.ini 与 rule.xml，Lua 侧对应 TscLua/cfg 下的lua_cfg.xml、lua_std.cfg等）。

四、命令行参数全景：从帮助文本到解析实现

./tscancode --help（或-h）输出的帮助文本定义在 trunk/cli/cmdlineparser.cpp 的PrintHelp()中。README 只演示了--xml一个参数，下面把ParseFromArgs()（cmdlineparser.cpp）实际支持的参数完整整理如下，均以当前仓库源码为准：

4.1 基础与输出控制

4.2 预处理与包含路径

4.3 抑制与过滤

4.4 性能、平台与语言控制

用法示例（摘自帮助文本）：

# 递归检查当前目录，进度打到屏幕，错误写入文件 tscancode . 2> err.txt # 递归检查项目且不打印进度 tscancode --quiet ../myproject/ # 检查单个文件并启用全部检查 tscancode --enable=all test.cpp # 检查 f.cpp 并从 inc1/、inc2/ 搜索头文件 tscancode -I inc1/ -I inc2/ f.cpp

另外，参数以-开头但无法识别时会报unrecognized command line option并退出；命令行未给任何源文件/目录时报No C or C++ source files found。

五、示例集与目录结构：每个规则都能找到对应样本

README 指向三个示例目录，仓库中确实一一对应，且样本文件名与 subid 同名，可直接用于回归验证某条规则：

• C/C++ 样本：samples/cpp，共 80+ 个样本，如 dereferenceAfterCheck.cpp（README 同类场景：if(obj != NULL)保护之外的obj->dosth2()）、arrayindexoutofbounds.cpp、memleak.cpp、unsignedlessthanzero.cpp、recursivefunc.cpp、stlsortcheck.cpp等，覆盖空指针、越界、内存泄漏、逻辑缺陷、STL 误用等 cfg.xml 中的主要类别；
• C# 样本：samples/csharp，如cs_arrayindexoutofbound.cs、cs_dereferenceifnull.cs、cs_unreleasedlock.cs、cs_inherit/update系列（cs_inefficientupdate.cs、cs_foreachinupdate.cs等 Unity 相关检查）；
• Lua 样本：samples/lua，如lua_Uninitvar.lua、lua_undeclaredvar.lua、lua_UseVarIfNil.lua、lua_keywordspellwrongerror.lua（对应 CHANGELOG 提到的拼写类检查）。

每个样本文件通常只含十几行最小缺陷代码，适合作为规则行为的最小复现样例。

六、发布包与平台适配

release 目录按平台组织，可直接下载使用预编译版本：

发布包命名即版本信息（如 V2.14.2395、V1.14.667）；而源码 trunk/lib/version.h 中当前版本宏为2.14.2397，README 徽标则标注 2.15.02，三者分别对应发布包、源码修订与对外发布的口径，实际使用请以目标二进制自带的--version输出为准。

七、适用边界与注意事项

• 开源范围：trunk/仅包含 C/C++ 版本的分析引擎源码；C# 与 Lua 引擎源码按 README 说明仍在内部评审流程中未开放，但两类语言的发布二进制、配置文件与 samples 均已随仓库提供；
• 性能与准确率：200K 行/分钟与约 90% 的准确率是 README 给出的官方指标，实际吞吐与误报率会随代码库复杂度、#ifdef配置数量和-D/--force用法而变化；
• 静态分析的固有限制：TscanCode 不要求完整编译环境（这正是其易用性的来源），但也因此对跨文件语义的理解依赖cfg配置与内置库定义；对未定义行为的判定部分依赖统计推断（如 cfg.xml 中默认关闭的funcRetNullStatistic、OutOfBoundsStatistic等"基于统计推断"类规则）；
• 若需了解各版本具体改动，请查阅 CHANGELOG.md；若需要扩展自定义规则，可参考--rule/--rule-file的 XML 格式与 cfg.xml 中的rule_name/desc组织方式。

• 静态分析
• 代码质量
• 开发工具
• 质量保障