概述

1.1 文档目的

本文档旨在提供一套完整的 C++ 代码质量检测工具集合，帮助开发团队在软件开发全生命周期中保证代码质量、安全性和可维护性。

1.2 工具分类

静态分析:

clang-tidy, cppcheck, cpplint ,代码规范、潜在缺陷、风格检查

代码格式化:

clang-format，统一代码风格

内存检测:

AddressSanitizer, Valgrind 。内存泄漏、越界访问、未初始化

头文件优化:

include-what-you-use (IWYU) 优化头文件依赖

CI/CD 集成:

各工具命令行接口，自动化质量检查

工具详细说明

2.1 clang-tidy - 综合静态分析工具

2.1.1 工具简介

clang-tidy 是基于 LLVM/Clang 的模块化静态分析工具，集成了 100+ 个检查器，支持自定义规则扩展。

2.1.2 安装配置

macOS:

```bash

brew install llvm

添加到 PATH

echo 'export PATH="/usr/local/opt/llvm/bin:$PATH"' >> ~/.zshrc

```

Ubuntu/Debian:

```bash

sudo apt-get update

sudo apt-get install clang-tidy clang-tidy-14

```

CentOS/RHEL:

```bash

sudo yum install clang-tools-extra

```

2.1.3 基本使用

```bash

基础检查（需要编译数据库）

clang-tidy -p build/ src/**/*.cpp

无需编译数据库的直接检查

clang-tidy src/main.cpp -- -std=c++17 -Iinclude

启用特定检查类别

clang-tidy -checks='modernize-*,performance-*,bugprone-*' src/*.cpp -- -std=c++17

自动修复

clang-tidy -fix src/*.cpp -- -std=c++17

导出修复建议

clang-tidy -export-fixes=fixes.yaml src/*.cpp -- -std=c++17

```

2.1.4 配置文件 (.clang-tidy)

```yaml

Checks: >

-*,

bugprone-*,

cppcoreguidelines-*,

modernize-*,

performance-*,

readability-*,

-cppcoreguidelines-avoid-magic-numbers,

-readability-magic-numbers,

-modernize-use-trailing-return-type

WarningsAsErrors: '*'

HeaderFilterRegex: '^src/(?!test).*\.h$'

AnalyzeTemporaryDtors: false

CheckOptions:

key: readability-identifier-naming.VariableCase

value: camelBack

key: readability-identifier-naming.ClassCase

value: CamelCase

key: modernize-use-nullptr.NullMacros

value: 'NULL'

```

2.1.5 检查类别说明

bugprone:

易错代码模式，悬空指针、错误转换

cppcoreguidelines:

C++ 核心指南，智能指针使用、RAII

modernize:

现代化建议， auto、override、nullptr

performance:

性能优化，传值 vs 传引用

readability:

可读性改进，命名规范、冗余代码

clang-analyzer:

深度分析，路径敏感检查

2.2 cppcheck - 轻量级静态分析

2.2.1 工具简介

cppcheck 是独立的静态分析工具，无需编译即可运行，专注于检测未定义行为、内存泄漏等安全问题。

2.2.2 安装配置

```

macOS

brew install cppcheck

Ubuntu/Debian

sudo apt-get install cppcheck

cd cppcheck

mkdir build && cd build

cmake .. -DCMAKE_BUILD_TYPE=Release

make -j$(nproc)

sudo make install

```

2.2.3 基本使用

```bash

基础检查

cppcheck src/

启用所有检查

cppcheck --enable=all --std=c++17 src/

生成 XML 报告

cppcheck --enable=all --xml --xml-version=2 src/ 2> report.xml

生成 HTML 报告

cppcheck-htmlreport --file=report.xml --report-dir=cppcheck-report

抑制误报

cppcheck --suppress=unusedFunction --suppress=unmatchedSuppression src/

多线程加速

cppcheck -j 4 --enable=all src/

```

2.2.4 启用选项

--enable=warning ，警告检查，日常开发

--enable=style ，风格检查，代码审查

--enable=performance ，性能分析，优化阶段

--enable=portability ，可移植性，跨平台项目

--enable=unusedFunction ，未使用函数，代码清理

--enable=missingInclude ，缺失头文件，依赖分析

2.3 clang-format - 代码格式化

2.3.1 工具简介

clang-format 提供自动化的代码格式化功能，支持多种主流编码风格。

2.3.2 使用方式

```bash

格式化单个文件

clang-format -i src/main.cpp

批量格式化

find src include -name "*.cpp" -o -name "*.h" | xargs clang-format -i

检查是否需要格式化

clang-format --dry-run -Werror src/main.cpp

使用特定风格

clang-format -style=google -i src/*.cpp

clang-format -style=file -i src/*.cpp # 使用 .clang-format

```

2.3.3 配置文件 (.clang-format)

```yaml

BasedOnStyle: LLVM

Language: Cpp

Standard: c++17

ColumnLimit: 100

IndentWidth: 4

UseTab: Never

BreakBeforeBraces: Attach

PointerAlignment: Left

AlignAfterOpenBracket: Align

AlignConsecutiveAssignments: false

AllowShortFunctionsOnASingleLine: Empty

AllowShortIfStatementsOnASingleLine: false

AlwaysBreakTemplateDeclarations: Yes

```

2.4 AddressSanitizer - 内存错误检测

2.4.1 工具简介

AddressSanitizer (ASan) 是编译器内置的运行时内存错误检测工具，由 Google 开发，集成在 GCC 和 Clang 中。

2.4.2 编译配置

Clang/GCC 编译选项:

```bash

基础配置

g++ -fsanitize=address -fno-omit-frame-pointer -g -O1 main.cpp -o program

完整配置（推荐）

CXXFLAGS = -fsanitize=address \

-fno-omit-frame-pointer \

-fsanitize-address-use-after-scope \

-g \

-O1

```

CMake 集成:

```cmake

CMakeLists.txt

set(CMAKE_CXX_FLAGS_DEBUG "${CMAKE_CXX_FLAGS_DEBUG} -fsanitize=address -fno-omit-frame-pointer")

set(CMAKE_EXE_LINKER_FLAGS_DEBUG "${CMAKE_EXE_LINKER_FLAGS_DEBUG} -fsanitize=address")

或通过命令行

cmake -DCMAKE_CXX_FLAGS="-fsanitize=address -fno-omit-frame-pointer -g" ..

```

2.4.3 运行时配置

```bash

检测内存泄漏

ASAN_OPTIONS=detect_leaks=1 ./program

输出详细信息

ASAN_OPTIONS=verbosity=1:detect_leaks=1 ./program

设置抑制文件

ASAN_OPTIONS=suppressions=asan.supp ./program

日志文件输出

ASAN_OPTIONS=log_path=/tmp/asan.log ./program

```

2.4.4 检测能力

堆缓冲区溢出:

访问超出分配内存，例如: arr[10] 当 size=5

栈缓冲区溢出:

函数局部变量越界，数组越界访问

全局缓冲区溢出:

全局变量越界，全局数组越界

Use-After-Free :

使用已释放内存，delete ptr; *ptr = 1;

Double-Free :

重复释放， delete ptr; delete ptr;

内存泄漏:

未释放内存， new 后无 delete

2.5 Valgrind - 内存调试套件

2.5.1 工具简介

Valgrind 是完整的内存调试和分析套件，包含 Memcheck（内存检查）、Cachegrind（缓存分析）、Callgrind（调用图）等多个工具。

2.5.2 安装

```bash

macOS

brew install valgrind

Ubuntu/Debian

sudo apt-get install valgrind

CentOS/RHEL

sudo yum install valgrind

```

2.5.3 Memcheck 使用

```bash

基础内存检查

valgrind --leak-check=full ./program

详细检查（显示所有泄漏类型）

valgrind --leak-check=full \

--show-leak-kinds=all \

--track-origins=yes \

./program

生成 suppression 文件

valgrind --gen-suppressions=yes ./program 2> suppressions.txt

使用 suppression

valgrind --suppressions=suppressions.txt ./program

```

2.5.4 其他 Valgrind 工具

```bash

缓存分析

valgrind --tool=cachegrind ./program

cg_annotate cachegrind.out.* --auto=yes

调用图分析

valgrind --tool=callgrind ./program

callgrind_annotate callgrind.out.*

堆分析

valgrind --tool=massif ./program

ms_print massif.out.*

线程调试

valgrind --tool=helgrind ./program

valgrind --tool=drd ./program

```

2.6 cpplint - Google 风格检查

2.6.1 工具简介

cpplint 是 Google 开发的 Python 脚本，用于检查 C++ 代码是否符合 Google C++ 风格指南。

2.6.2 安装与使用

```bash

安装

pip install cpplint

基础检查

cpplint src/*.cpp include/*.h

递归检查

find src/ -name "*.cpp" -o -name "*.h" | xargs cpplint

过滤检查项

cpplint --filter=-build/include_order,-readability/todo src/*.cpp

设置输出格式

cpplint --output=vs7 src/*.cpp # Visual Studio 格式

```

2.6.3 常见过滤规则

build/include_order:

头文件顺序，-build/include_order

readability/todo:

TODO 注释， -readability/todo

whitespace/braces:

大括号空格， -whitespace/braces

legal/copyright:

2.7 IWYU - 头文件优化

2.7.1 工具简介

Include What You Use (IWYU) 分析并优化头文件包含关系，移除不必要的依赖，提高编译速度。

2.7.2 安装

```bash

macOS

brew install include-what-you-use

Ubuntu/Debian

sudo apt-get install iwyu

从源码编译（配合 LLVM）

git clone https://github.com/include-what-you-use/include-what-you-use.git

cd include-what-you-use

mkdir build && cd build

cmake -DCMAKE_PREFIX_PATH=/usr/lib/llvm-14 ..

make -j$(nproc)

sudo make install

```

2.7.3 使用方式

```bash

直接使用

include-what-you-use src/main.cpp -- -std=c++17 -Iinclude

配合编译数据库

iwyu_tool.py -p build/ -- -std=c++17

自动修复

iwyu_tool.py -p build/ -- -std=c++17 | fix_includes.py

CMake 集成

cmake -DCMAKE_CXX_INCLUDE_WHAT_YOU_USE="include-what-you-use;-Xiwyu;--cxx17ns" ..

```

集成配置

3.1 编译数据库生成

编译数据库 (compile_commands.json) 是许多工具的基础。

CMake:

```bash

cmake -DCMAKE_EXPORT_COMPILE_COMMANDS=ON -B build/

```

Makefile 项目:

```bash

使用 Bear 工具

brew install bear # macOS

apt-get install bear # Ubuntu

bear -- make

```

自定义脚本:

```bash

使用 compiledb

pip install compiledb

compiledb make

```

3.2 统一配置文件

项目根目录创建 .clang-tidy、.clang-format、.cppcheck 等配置文件。

项目结构示例:

```

project/

├── .clang-tidy # clang-tidy 配置

├── .clang-format # 格式化配置

├── .cppcheck # cppcheck 配置

├── .cpplint # cpplint 配置

├── .gitignore

├── CMakeLists.txt

├── src/

│ ├── main.cpp

│ └── utils.cpp

├── include/

│ └── utils.h

└── tests/

└── test_main.cpp

```

最佳实践

4.1 工具组合策略

开发时:

clang-format ，每次保存统一风格

提交前:

cppcheck ，每次提交快速检查

CI 构建 :

clang-tidy ，每次构建深度分析

测试阶段:

ASan ，每次测试内存检测

发布前:

Valgrind ，里程碑全面检查

4.2 配置管理

```bash

项目级配置（团队共享）

project/

├── .clang-format # 团队统一格式

├── .clang-tidy # 团队检查规则

└── .gitattributes # 确保跨平台一致性

本地配置（个人偏好）

~/.clang-format # 个人默认格式

```

4.3 误报处理

```yaml

.clang-tidy - 抑制特定检查

Checks: '-*,bugprone-*'

CheckOptions:

key: bugprone-suspicious-enum-usage.StrictMode

value: false

cppcheck 抑制

行级抑制

// cppcheck-suppress unusedFunction

void helper() { ... }

文件级抑制

// cppcheck-suppress-file unusedFunction

```

4.4 性能优化

```bash

增量检查

clang-tidy -p build/ --use-color --header-filter=".*" src/**/*.cpp

并行执行

cppcheck -j $(nproc) --enable=all src/

缓存编译数据库

ccache -s

```

故障排查

5.1 常见问题

No such file or directory :

原因:缺少编译数据库

解决方案: 生成 compile_commands.json

Unknown argument:

原因:编译器标志不兼容

解决方案:检查 -std=c++17 等标志

Too many errors :

原因:检查过于严格调整检查级别

解决方案:抑制误报

ASan:

原因: 运行缓慢内存开销大

解决方案:使用 -O1 优化，减少测试范围

Valgrind:

原因: 无法运行架构不支持

解决方案:macOS 使用 brew install valgrind

5.2 调试技巧

```bash

查看 clang-tidy 支持的检查

clang-tidy --list-checks

调试 cppcheck 规则

cppcheck --check-config src/

查看 ASan 详细输出

ASAN_OPTIONS=verbosity=1 ./program

分析 clang-format 差异

clang-format --style=file src/main.cpp | diff -u src/main.cpp -

```

参考资料:

https://clang.llvm.org/extra/clang-tidy/

https://cppcheck.sourceforge.io/manual.pdf

https://clang.llvm.org/docs/ClangFormatStyleOptions.html

https://github.com/google/sanitizers/wiki/AddressSanitizer

https://valgrind.org/docs/manual/manual.html

https://google.github.io/styleguide/cppguide.html

C++ 代码质量检测工具集合技术文档

添加到 PATH

基础检查（需要编译数据库）

无需编译数据库的直接检查

启用特定检查类别

自动修复

导出修复建议

macOS

Ubuntu/Debian

从源码编译（获取最新版本）

基础检查

启用所有检查

生成 XML 报告

生成 HTML 报告

抑制误报

多线程加速

格式化单个文件

批量格式化

检查是否需要格式化

使用特定风格

基础配置

完整配置（推荐）

CMakeLists.txt

或通过命令行

检测内存泄漏

输出详细信息

设置抑制文件

日志文件输出

macOS

Ubuntu/Debian

CentOS/RHEL

基础内存检查

详细检查（显示所有泄漏类型）

生成 suppression 文件

使用 suppression

缓存分析

调用图分析

堆分析

线程调试

安装

基础检查

递归检查

过滤检查项

设置输出格式

macOS

Ubuntu/Debian

从源码编译（配合 LLVM）

直接使用

配合编译数据库

自动修复

CMake 集成

使用 Bear 工具

使用 compiledb

项目级配置（团队共享）

本地配置（个人偏好）

.clang-tidy - 抑制特定检查

cppcheck 抑制

行级抑制

文件级抑制

增量检查

并行执行

缓存编译数据库

查看 clang-tidy 支持的检查

调试 cppcheck 规则

查看 ASan 详细输出

分析 clang-format 差异