C/C++ 和 Cmake 格式化

安装 Clang-Format

ArchLinux 系统级安装

运行以下命令安装 clang 包，其中包含了 clang-format：

1
sudo pacman -S clang

之后你就可以在全局执行 clang-format 命令来格式化代码。可执行文件一般位于 /usr/bin/clang-format 。但是这里安装的而二进制程序使用的是动态库，你把二进制程序分发到其他没有安装 clang 动态库的计算机上，就会报找不到动态库的错误。

如果你有系统权限，或者是在你自己的计算机上开发，这样就可以了即使是把可执行程序拷贝的项目目录下，执行项目目录下的可执行程序，也可以正常运行（动态库还是使用系统目录下的）。

如果你想使用单独的使用静态库的可执行程序，需要手动构建。

手动用户级安装

方法 1：直接下载 clang-format 二进制文件

LLVM 官方提供了单独的 clang-format 二进制文件，可以直接下载并解压到项目目录中。

  • 访问 LLVM Download Page。

  • 找到适合你系统的预编译包（例如 Linux x86_64）。

  • 下载 clang+llvm-<version>-<arch>-linux-gnu.tar.xz。

  • 解压文件并提取 clang-format ：

    1
    tar -xvf clang+llvm-<version>-<arch>-linux-gnu.tar.xzcp clang+llvm-<version>-<arch>-linux-gnu/bin/clang-format /path/to/your/project/

这个包里面的 clang-format 不知道是如何构建的，笔者没有尝试。

方法 2：从源码构建仅 clang-format

  1. 下载 LLVM 源码
    从 LLVM GitHub 下载源码，或者直接克隆：

    1
    2
    git clone https://github.com/llvm/llvm-project.git
    cd llvm-project

  2. 配置并仅构建 clang-format

    • 创建构建目录并配置：

      1
      2
      mkdir build && cd build
      cmake -G Ninja -DCMAKE_BUILD_TYPE=Release -DLLVM_ENABLE_PROJECTS="clang" -DBUILD_SHARED_LIBS=OFF -DLLVM_BUILD_TOOLS=OFF -DCLANG_BUILD_TOOLS=OFF -DCLANG_ENABLE_FORMAT=ON ../llvm

    • 构建 clang-format ：

      1
      ninja clang-format

  3. 提取 clang-format 二进制文件
    构建完成后，clang-format 二进制文件位于 build/bin/clang-format。可以将其复制到项目目录中，可以直接使用该可执行程序格式化。

注：即便使用了静态库，但是你在你的机器上构建的 clang-format 依赖于你的版本的 GLIBC 和 libstdc++，而其他的系统上安装的 GLIBC 和 libstdc++ 版本可能较旧，无法满足要求。你可以升级 GLIBC 和 libstdc++ 或者在使用旧 GLIBC 和 libstdc++ 的版本系统上构建。

使用和配置 clang-format

基本使用

将可执行文件 clang-format 复制到项目目录下后，你可以运行

1
clang-format -i your_code.cpp

来格式化代码。

vscode 扩展

可以在 vscode 中安装 clang-format 扩展来使用在 vscode 中集成的格式化操作。

安装后，可以进行以下配置：

  • Clang-Format: Path 指定了正确的 clang-format 可执行文件路径（如果 VS Code 没有自动找到它的话）。
  • Editor: Format On Save：在每次保存文件时，VS Code 会自动运行 clang-format 格式化代码。
  • Clang-Format: Style：选择格式化风格（例如 Google、LLVM、Chromium 等）。如果你有 .clang-format 文件，它会覆盖此设置。

自定义代码格式化规则

创建配置文件

.clang-format 文件是用来指定代码格式化规则的配置文件。你可以在项目根目录或用户级别目录下创建一个 .clang-format 文件。

你可以手动创建 .clang-format 文件然后自行配置格式化规则。

不过推荐使用以下命令生成默认配置文件，然后在其基础上进行修改：

1
clang-format -style=llvm -dump-config > .clang-format

这会创建一个基于 llvm 风格的默认配置文件。

你也可以选择其他风格，如 LLVM、Microsoft、Google、Chromium 等，例如：

1
clang-format -style=llvm -dump-config > .clang-format

.clang-format 配置文件例子（中文注释）：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
---
Language:        Cpp            # 指定格式化语言为 C++
AccessModifierOffset: -2        # 访问修饰符（如 public、private）的缩进偏移量，负数表示向左缩进
AlignAfterOpenBracket: Align    # 在开括号后对齐内容
AlignArrayOfStructures: None    # 不对齐结构体数组
AlignConsecutiveAssignments:
  Enabled:         false        # 不启用连续赋值对齐
  AcrossEmptyLines: false       # 跨空行不对齐赋值
  AcrossComments:  false        # 跨注释不对齐赋值
  AlignCompound:   false        # 不对齐复合赋值运算符
  AlignFunctionPointers: false  # 不对齐函数指针
  PadOperators:    true         # 在操作符周围填充空格
AlignConsecutiveBitFields:
  Enabled:         false        # 不启用连续位字段对齐
  AcrossEmptyLines: false       # 跨空行不对齐位字段
  AcrossComments:  false        # 跨注释不对齐位字段
  AlignCompound:   false        # 不对齐复合位字段
  AlignFunctionPointers: false  # 不对齐函数指针
  PadOperators:    false        # 不在操作符周围填充空格
AlignConsecutiveDeclarations:
  Enabled:         false        # 不启用连续声明对齐
  AcrossEmptyLines: false       # 跨空行不对齐声明
  AcrossComments:  false        # 跨注释不对齐声明
  AlignCompound:   false        # 不对齐复合声明
  AlignFunctionPointers: false  # 不对齐函数指针
  PadOperators:    false        # 不在操作符周围填充空格
AlignConsecutiveMacros:
  Enabled:         false        # 不启用连续宏对齐
  AcrossEmptyLines: false       # 跨空行不对齐宏
  AcrossComments:  false        # 跨注释不对齐宏
  AlignCompound:   false        # 不对齐复合宏
  AlignFunctionPointers: false  # 不对齐函数指针
  PadOperators:    false        # 不在操作符周围填充空格
AlignConsecutiveShortCaseStatements:
  Enabled:         false        # 不启用连续短 case 语句对齐
  AcrossEmptyLines: false       # 跨空行不对齐 case 语句
  AcrossComments:  false        # 跨注释不对齐 case 语句
  AlignCaseArrows: false        # 不对齐 case 箭头
  AlignCaseColons: false        # 不对齐 case 冒号
AlignConsecutiveTableGenBreakingDAGArgColons:
  Enabled:         false        # 不启用连续 TableGen DAG 参数冒号对齐
  AcrossEmptyLines: false       # 跨空行不对齐 DAG 参数冒号
  AcrossComments:  false        # 跨注释不对齐 DAG 参数冒号
  AlignCompound:   false        # 不对齐复合 DAG 参数冒号
  AlignFunctionPointers: false  # 不对齐函数指针
  PadOperators:    false        # 不在操作符周围填充空格
AlignConsecutiveTableGenCondOperatorColons:
  Enabled:         false        # 不启用连续 TableGen 条件操作符冒号对齐
  AcrossEmptyLines: false       # 跨空行不对齐条件操作符冒号
  AcrossComments:  false        # 跨注释不对齐条件操作符冒号
  AlignCompound:   false        # 不对齐复合条件操作符冒号
  AlignFunctionPointers: false  # 不对齐函数指针
  PadOperators:    false        # 不在操作符周围填充空格
AlignConsecutiveTableGenDefinitionColons:
  Enabled:         false        # 不启用连续 TableGen 定义冒号对齐
  AcrossEmptyLines: false       # 跨空行不对齐定义冒号
  AcrossComments:  false        # 跨注释不对齐定义冒号
  AlignCompound:   false        # 不对齐复合定义冒号
  AlignFunctionPointers: false  # 不对齐函数指针
  PadOperators:    false        # 不在操作符周围填充空格
AlignEscapedNewlines: Right     # 对齐转义换行符到右侧
AlignOperands:   Align          # 对齐操作数
AlignTrailingComments:
  Kind:            Always       # 总是对齐尾随注释
  OverEmptyLines:  0            # 跨空行不对齐注释
AllowAllArgumentsOnNextLine: true                # 允许所有参数在下一行
AllowAllParametersOfDeclarationOnNextLine: true  # 允许声明中的所有参数在下一行
AllowBreakBeforeNoexceptSpecifier: Never         # 不允许在 noexcept 说明符前换行
AllowShortBlocksOnASingleLine: Never             # 不允许短块在一行内
AllowShortCaseExpressionOnASingleLine: true      # 允许短 case 表达式在一行内
AllowShortCaseLabelsOnASingleLine: false         # 不允许短 case 标签在一行内
AllowShortCompoundRequirementOnASingleLine: true # 允许短复合要求在一行内
AllowShortEnumsOnASingleLine: true               # 允许短枚举在一行内
AllowShortFunctionsOnASingleLine: All            # 允许所有短函数在一行内
AllowShortIfStatementsOnASingleLine: Never       # 不允许短 if 语句在一行内
AllowShortLambdasOnASingleLine: All              # 允许所有短 lambda 在一行内
AllowShortLoopsOnASingleLine: false              # 不允许短循环在一行内
AlwaysBreakAfterDefinitionReturnType: None       # 不在定义返回类型后换行
AlwaysBreakBeforeMultilineStrings: false         # 不在多行字符串前换行
AttributeMacros:
  • __capability              # 定义属性宏
BinPackArguments: true         # 打包函数调用参数
BinPackParameters: true        # 打包函数声明参数
BitFieldColonSpacing: Both     # 在位字段冒号两侧添加空格
BraceWrapping:
  AfterCaseLabel:  false       # 不在 case 标签后换行
  AfterClass:      false       # 不在类定义后换行
  AfterControlStatement: Never # 不在控制语句后换行
  AfterEnum:       false       # 不在枚举定义后换行
  AfterExternBlock: false      # 不在 extern 块后换行
  AfterFunction:   false       # 不在函数定义后换行
  AfterNamespace:  false       # 不在命名空间定义后换行
  AfterObjCDeclaration: false  # 不在 Objective-C 声明后换行
  AfterStruct:     false       # 不在结构体定义后换行
  AfterUnion:      false       # 不在联合体定义后换行
  BeforeCatch:     false       # 不在 catch 前换行
  BeforeElse:      false       # 不在 else 前换行
  BeforeLambdaBody: false      # 不在 lambda 体前换行
  BeforeWhile:     false       # 不在 while 前换行
  IndentBraces:    false       # 不缩进大括号
  SplitEmptyFunction: true     # 拆分空函数
  SplitEmptyRecord: true       # 拆分空记录
  SplitEmptyNamespace: true    # 拆分空命名空间
BreakAdjacentStringLiterals: true           # 拆分相邻字符串字面量
BreakAfterAttributes: Leave                 # 在属性后换行
BreakAfterJavaFieldAnnotations: false       # 不在 Java 字段注解后换行
BreakAfterReturnType: None                  # 不在返回类型后换行
BreakArrays:     true                       # 拆分数组
BreakBeforeBinaryOperators: None            # 不在二元操作符前换行
BreakBeforeConceptDeclarations: Always      # 总是在概念声明前换行
BreakBeforeBraces: Attach                   # 大括号前不换行
BreakBeforeInlineASMColon: OnlyMultiline    # 只在多行内联汇编冒号前换行
BreakBeforeTernaryOperators: true           # 在三元操作符前换行
BreakConstructorInitializers: BeforeColon   # 在构造函数初始化列表冒号前换行
BreakFunctionDefinitionParameters: false    # 不拆分函数定义参数
BreakInheritanceList: BeforeColon           # 在继承列表冒号前换行
BreakStringLiterals: true                   # 拆分字符串字面量
BreakTemplateDeclarations: MultiLine        # 多行模板声明
ColumnLimit:  120                           # 列限制为 120
CommentPragmas:  '^ IWYU pragma:'           # 注释 pragma 正则表达式
CompactNamespaces: false                    # 不压缩命名空间
ConstructorInitializerIndentWidth: 4        # 构造函数初始化列表缩进宽度为 4
ContinuationIndentWidth: 4                  # 续行缩进宽度为 4
Cpp11BracedListStyle: true                  # 使用 C++11 大括号列表样式
DerivePointerAlignment: false               # 不推导指针对齐
DisableFormat:   false                      # 不禁用格式化
EmptyLineAfterAccessModifier: Never         # 不在访问修饰符后添加空行
EmptyLineBeforeAccessModifier: LogicalBlock # 在逻辑块前添加空行
ExperimentalAutoDetectBinPacking: false     # 不启用实验性自动检测参数打包
FixNamespaceComments: true                  # 修复命名空间注释
ForEachMacros:
  • foreach        # 定义 foreach 宏
  • Q_FOREACH      # 定义 Q_FOREACH 宏
  • BOOST_FOREACH  # 定义 BOOST_FOREACH 宏
IfMacros:
  • KJ_IF_MAYBE           # 定义 KJ_IF_MAYBE 宏
IncludeBlocks:   Preserve  # 保留 include 块顺序
IncludeCategories:
  • Regex:           '^"(llvm|llvm-c|clang|clang-c)/'  # LLVM 相关头文件优先级
    Priority:        2
    SortPriority:    0
    CaseSensitive:   false
  • Regex:           '^(<|"(gtest|gmock|isl|json)/)'  # 测试相关头文件优先级
    Priority:        3
    SortPriority:    0
    CaseSensitive:   false
  • Regex:           '.*'  # 其他头文件优先级
    Priority:        1
    SortPriority:    0
    CaseSensitive:   false
IncludeIsMainRegex: '(Test)?$'       # 主文件正则表达式
IncludeIsMainSourceRegex: ''         # 主源文件正则表达式
IndentAccessModifiers: false         # 不缩进访问修饰符
IndentCaseBlocks: false              # 不缩进 case 块
IndentCaseLabels: false              # 不缩进 case 标签
IndentExternBlock: AfterExternBlock  # 在 extern 块后缩进
IndentGotoLabels: true               # 缩进 goto 标签
IndentPPDirectives: None             # 不缩进预处理指令
IndentRequiresClause: true           # 缩进 requires 子句
IndentWidth:     2                   # 缩进宽度为 2
IndentWrappedFunctionNames: false    # 不缩进换行函数名
InsertBraces:    false               # 不插入大括号
InsertNewlineAtEOF: false            # 不在文件末尾插入换行
InsertTrailingCommas: None           # 不插入尾随逗号
IntegerLiteralSeparator:
  Binary:           0        # 二进制字面量分隔符
  BinaryMinDigits:  0        # 二进制字面量最小位数
  Decimal:          0        # 十进制字面量分隔符
  DecimalMinDigits: 0        # 十进制字面量最小位数
  Hex:              0        # 十六进制字面量分隔符
  HexMinDigits:     0        # 十六进制字面量最小位数
JavaScriptQuotes: Leave      # 保留 JavaScript 引号
JavaScriptWrapImports: true  # 包装 JavaScript 导入
KeepEmptyLines:
  AtEndOfFile:     false # 不在文件末尾保留空行
  AtStartOfBlock:  true  # 在块开头保留空行
  AtStartOfFile:   true  # 在文件开头保留空行
LambdaBodyIndentation: Signature  # lambda 体缩进与签名对齐
LineEnding:      DeriveLF         # 推导行结束符为 LF
MacroBlockBegin: ''               # 宏块开始标记
MacroBlockEnd:   ''               # 宏块结束标记
MainIncludeChar: Quote            # 主文件包含字符为引号
MaxEmptyLinesToKeep: 1            # 最大保留空行数为 1
NamespaceIndentation: None        # 不缩进命名空间
ObjCBinPackProtocolList: Auto     # 自动打包 Objective-C 协议列表
ObjCBlockIndentWidth: 2           # Objective-C 块缩进宽度为 2
ObjCBreakBeforeNestedBlockParam: true  # 在嵌套块参数前换行
ObjCSpaceAfterProperty: false          # 不在 Objective-C 属性后添加空格
ObjCSpaceBeforeProtocolList: true      # 在 Objective-C 协议列表前添加空格
PackConstructorInitializers: BinPack   # 打包构造函数初始化列表
PenaltyBreakAssignment: 2              # 赋值换行惩罚
PenaltyBreakBeforeFirstCallParameter: 19  # 在第一个调用参数前换行惩罚
PenaltyBreakComment: 300              # 注释换行惩罚
PenaltyBreakFirstLessLess: 120        # 第一个 << 换行惩罚
PenaltyBreakOpenParenthesis: 0        # 开括号换行惩罚
PenaltyBreakScopeResolution: 500      # 作用域解析换行惩罚
PenaltyBreakString: 1000              # 字符串换行惩罚
PenaltyBreakTemplateDeclaration: 10   # 模板声明换行惩罚
PenaltyExcessCharacter: 1000000       # 超出字符数惩罚
PenaltyIndentedWhitespace: 0           # 缩进空白惩罚
PenaltyReturnTypeOnItsOwnLine: 60     # 返回类型单独一行惩罚
PointerAlignment: Right        # 指针对齐到右侧
PPIndentWidth:   -1            # 预处理指令缩进宽度为 -1
QualifierAlignment: Leave      # 保留限定符对齐
ReferenceAlignment: Pointer    # 引用对齐与指针相同
ReflowComments:  true     # 重新格式化注释
RemoveBracesLLVM: false   # 不删除 LLVM 大括号
RemoveParentheses: Leave  # 保留括号
RemoveSemicolon: false    # 不删除分号
RequiresClausePosition: OwnLine  # requires 子句单独一行
RequiresExpressionIndentation: OuterScope  # requires 表达式缩进与外部作用域对齐
SeparateDefinitionBlocks: Leave  # 保留定义块分离
ShortNamespaceLines: 1           # 短命名空间行数为 1
SkipMacroDefinitionBody: false   # 不跳过宏定义体
SortIncludes:    CaseSensitive   # 区分大小写排序 include
SortJavaStaticImport: Before     # 在 Java 静态导入前排序
SortUsingDeclarations: LexicographicNumeric  # 按字典序和数字排序 using 声明
SpaceAfterCStyleCast: false  # 不在 C 风格转换后添加空格
SpaceAfterLogicalNot: false  # 不在逻辑非后添加空格
SpaceAfterTemplateKeyword: true        # 在模板关键字后添加空格
SpaceAroundPointerQualifiers: Default  # 默认在指针限定符周围添加空格
SpaceBeforeAssignmentOperators: true   # 在赋值操作符前添加空格
SpaceBeforeCaseColon: false            # 不在 case 冒号前添加空格
SpaceBeforeCpp11BracedList: false      # 不在 C++11 大括号列表前添加空格
SpaceBeforeCtorInitializerColon: true  # 在构造函数初始化列表冒号前添加空格
SpaceBeforeInheritanceColon: true      # 在继承冒号前添加空格
SpaceBeforeJsonColon: false            # 不在 JSON 冒号前添加空格
SpaceBeforeParens: ControlStatements   # 在控制语句括号前添加空格
SpaceBeforeParensOptions:
  AfterControlStatements: true         # 在控制语句后添加空格
  AfterForeachMacros: true             # 在 foreach 宏后添加空格
  AfterFunctionDefinitionName: false   # 不在函数定义名后添加空格
  AfterFunctionDeclarationName: false  # 不在函数声明名后添加空格
  AfterIfMacros:   true             # 在 if 宏后添加空格
  AfterOverloadedOperator: false    # 不在重载操作符后添加空格
  AfterPlacementOperator: true      # 在 placement 操作符后添加空格
  AfterRequiresInClause: false      # 不在 requires 子句后添加空格
  AfterRequiresInExpression: false  # 不在 requires 表达式后添加空格
  BeforeNonEmptyParentheses: false  # 不在非空括号前添加空格
SpaceBeforeRangeBasedForLoopColon: true  # 在范围 for 循环冒号前添加空格
SpaceBeforeSquareBrackets: false       # 不在方括号前添加空格
SpaceInEmptyBlock: false         # 不在空块中添加空格
SpacesBeforeTrailingComments: 1  # 在尾随注释前添加 1 个空格
SpacesInAngles:  Never           # 不在尖括号内添加空格
SpacesInContainerLiterals: true  # 在容器字面量内添加空格
SpacesInLineCommentPrefix:
  Minimum:         1    # 行注释前缀最小空格数
  Maximum:         -1   # 行注释前缀最大空格数
SpacesInParens:  Never  # 不在括号内添加空格
SpacesInParensOptions:
  ExceptDoubleParentheses: false  # 不在双括号内添加空格
  InCStyleCasts:   false          # 不在 C 风格转换括号内添加空格
  InConditionalStatements: false  # 不在条件语句括号内添加空格
  InEmptyParentheses: false       # 不在空括号内添加空格
  Other:           false       # 不在其他括号内添加空格
SpacesInSquareBrackets: false  # 不在方括号内添加空格
Standard:        Latest        # 使用最新的 C++ 标准
StatementAttributeLikeMacros:
  • Q_EMIT        # 定义类似语句属性的宏
StatementMacros:
  • Q_UNUSED      # 定义语句宏
  • QT_REQUIRE_VERSION  # 定义 QT_REQUIRE_VERSION 宏
TableGenBreakInsideDAGArg: DontBreak  # 不在 TableGen DAG 参数内换行
TabWidth:        8      # 制表符宽度为 8
UseTab:          Never  # 不使用制表符
VerilogBreakBetweenInstancePorts: true  # 在 Verilog 实例端口间换行
WhitespaceSensitiveMacros:
  • BOOST_PP_STRINGIZE  # 定义对空格敏感的宏
  • CF_SWIFT_NAME       # 定义对空格敏感的宏
  • NS_SWIFT_NAME       # 定义对空格敏感的宏
  • PP_STRINGIZE        # 定义对空格敏感的宏
  • STRINGIZE           # 定义对空格敏感的宏
...


应用配置文件

未指定时自动查找

clang-format 在格式化代码时，会自动查找并使用 .clang-format 文件中的规则。查找规则如下：

  1. 当前工作目录：clang-format 会首先检查当前工作目录下是否存在 .clang-format 文件。
  2. 父目录：如果当前目录没有找到 .clang-format 文件，clang-format 会递归地向父目录查找，直到找到 .clang-format 文件或到达文件系统的根目录。
  3. 用户主目录：如果以上目录都没有找到 .clang-format 文件，clang-format 会检查用户的主目录（~/.clang-format）。
  4. 内置默认规则：如果以上位置都没有找到 .clang-format 文件，clang-format 会使用其内置的默认格式化规则。
使用指定配置文件

可以通过以下方式明确指定使用某个 .clang-format 文件：

  • 使用 -style=file 参数，并确保 .clang-format 文件位于当前目录或其父目录中。即 yourfile.cpp 要位于 .clang-format 文件所在目录下或者其子目录下。例如：

    1
    clang-format -style=file -i yourfile.cpp

    你也可以使用下面的命令还使用默认规则，若不指定 -style 参数，则默认是使用 LLVM 规则：

    1
    clang-format -style=LLVM -i yourfile.cpp

    -style 可选 LLVM、Microsoft、Google、Chromium 等。

    这会强制 clang-format 使用 .clang-format 文件中的规则。

  • 如果你想直接指定某个 .clang-format 文件的路径，可以使用 -style 参数并传递文件内容。例如：

    1
    clang-format -style="$(cat /path/to/.clang-format)" -i yourfile.cpp

格式化脚本

当项目内代码文件过多时，一个个格式化代码太过繁琐了，我们可以写一个简单的脚本来帮我们遍历处理项目内的代码文件。

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
#!/bin/zsh

# 定义颜色代码
GREEN='\033[0;32m'  # 绿色
BLUE='\033[0;34m'   # 蓝色
NC='\033[0m'        # 重置颜色

# 获取脚本所在文件夹路径
SCRIPT_DIR=$(dirname "$0")
NEED_FORMAT_FILE="$SCRIPT_DIR/clang-format-files.txt"

# 获取 C/C++ 相关源文件和头文件的函数（当前目录，不递归）
function get_cpp_files_in_dir {
    find "$1" -maxdepth 1 \( -name "*.cpp" -o -name "*.hpp" -o -name "*.h" -o -name "*.cc" \) -type f 2>/dev/null
}

# 获取 C/C++ 相关源文件和头文件的函数（递归遍历）
function get_cpp_files_recursive {
    find "$1" \( -name "*.cpp" -o -name "*.hpp" -o -name "*.h" -o -name "*.cc" \) -type f 2>/dev/null
}

# 交互式询问用户是否格式化
function ask_user {
    local files=("${(@f)1}")  # 按行读取文件列表

    local total_lines=0
    local lines=0
    echo "匹配到以下 ${#files[@]} 个文件："
    for file in "${files[@]}"; do
        lines=$(wc -l < "$file" 2>/dev/null | tr -d ' ')  # 获取行数，忽略错误
        total_lines=$((total_lines + lines))

        # 使用制表符对齐，并添加颜色
        printf "  ${GREEN}%s${NC}\t(${BLUE}%d 行${NC})\n" "$file" "$lines"
    done

    echo "总计：$total_lines 行"
    echo -n "是否格式化这些文件？ (y/n, 默认 y): "
    read -r answer

    if [[ -z "$answer" || "$answer" == "y" ]]; then
        local count=0
        for file in "${files[@]}"; do
            clang-format -i "$file"
            count=$((count + 1))
            # 打印进度，\r 将光标移动到行首，\c 表示不换行
            printf "\r已按顺序格式化 %d 个文件。" "$count"
        done
        printf "\n"  # 格式化完成后换行
        echo "格式化完成。"
    else
        echo "跳过格式化。"
    fi
}


# 处理 clang-format-files.txt 文件
if [ -f "$NEED_FORMAT_FILE" ]; then
    matched_files=()
    ignored_files=()
    
    while IFS= read -r line || [[ -n "$line" ]]; do
        # 去除行首尾的空格
        line=$(echo "$line" | sed -e 's/^[ \t]*//' -e 's/[ \t]*$//')
        
        # 如果行以 + 开头，表示需要格式化的路径
        if [[ "$line" == +* ]]; then
            pattern="${line:1}"
            matched_files+=($(eval "ls -d $SCRIPT_DIR/$pattern" 2>/dev/null | grep -E '\.(cpp|hpp|h|cc)$'))
        # 如果行以 - 开头，表示不需要格式化的路径
        elif [[ "$line" == -* ]]; then
            pattern="${line:1}"
            ignored_files+=($(eval "ls -d $SCRIPT_DIR/$pattern" 2>/dev/null | grep -E '\.(cpp|hpp|h|cc)$'))
        fi
    done < "$NEED_FORMAT_FILE"

    # 输出需要格式化的文件
    if [ ${#matched_files[@]} -eq 0 ]; then
        echo "没有匹配到 clang-format-files.txt 中需要格式化的文件"
    else
        echo "已匹配到 clang-format-files.txt 中需要格式化的文件"
        ask_user "${(F)matched_files}"
    fi

    # 输出不需要格式化的文件
    if [ ${#ignored_files[@]} -ne 0 ]; then
        echo "以下文件被忽略，不会格式化："
        for file in "${ignored_files[@]}"; do
            printf "  ${GREEN}%s${NC}\n" "$file"
        done
    fi

    exit 0
fi

# 如果没有 need-format-files 文件，则先获取当前目录的 C/C++ 文件（不递归）
current_dir_files=($(get_cpp_files_in_dir "$SCRIPT_DIR"))
if [ ${#current_dir_files[@]} -eq 0 ]; then
    echo "工作目录内没有 C/C++ 文件。"
else
    echo "当前目录的 C/C++ 文件："
    ask_user "${(F)current_dir_files}"
fi

# 遍历当前目录的所有子目录，并递归获取 C/C++ 文件
for dir in "$SCRIPT_DIR"/*(/); do
    dir_files=($(get_cpp_files_recursive "$dir"))
    # 如果当前目录没有 C/C++ 文件，则跳过
    if [ ${#dir_files[@]} -eq 0 ]; then
        continue
    else
        ask_user "${(F)dir_files}"
    fi
done

脚本执行流程：

当存在配置文件 clang-format-files.txt 时：

  1. 解析配置文件的 +（包含）和 -（排除）规则
  2. 合并所有匹配文件并过滤排除项
  3. 单次交互确认：列出所有目标文件及行数，确认后一次性完成格式化

当不存在配置文件时：

  1. 当前目录处理（非递归）：
    • 扫描当前层级的 C/C++ 文件
    • 首次交互确认：用户确认是否格式化这些文件
  2. 子目录递归处理：
    • 遍历当前目录的每个子目录
    • 对每个子目录执行递归扫描（含所有嵌套子目录）
    • 逐目录交互确认：每个子目录的文件列表单独显示并请求确认

clang-format-files.txt 文件说明：

文件路径前的 + 表示需要格式化后面的文件，执行脚本时会进行询问， - 表示不需要询问格式化后面的文件，执行脚本时会忽略。

  • path/to/file ：匹配普通文件。

  • path/to/directory/* ：匹配 path/to/directory 目录中的所有 C/C++ 相关文件。（需要支持 ** 的 shell，如 zsh）。

  • path/to/directory/**/*：匹配 path/to/directory 目录及其所有子目录中的所有 C/C++ 相关文件（需要支持 ** 的 shell，如 zsh）。

安装和使用 cmake-format

Arch Linux 系统安装

1
sudo pacman -S cmake-format

获取静态链接的 cmake-format

cmake-format 是一个 Python 工具，通常以 Python 包的形式分发。要将其打包为独立的二进制文件，可以使用工具如 pyinstaller。

  1. 安装依赖：

    1
    2
    sudo pacman -S python python-pip
    pip install cmake-format pyinstaller

  2. 将 cmake-format 打包为独立二进制：

    1
    pyinstaller --onefile --collect-all cmakelang $(which cmake-format)

  3. 获取二进制文件： 打包完成后，独立的 cmake-format 可执行文件位于：

    1
    ./dist/cmake-format

    你可以将其复制到项目目录中使用。

注意：pyinstaller 打包时会将动态库（如 libz.so.1）打包到可执行文件中，但这些动态库可能依赖于较新的 GLIBC 特性（如 GLIBC_ABI_DT_RELR）。如果使用可执行程序的系统 GLIBC 版本较旧，就会导致运行失败。

生成自定义格式化规则配置文件：

1
cmake-format --dump-config > .cmake-format

.cmake-format 配置文件内容例子（中文注释）：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
# ----------------------------------
# 影响 CMake 文件解析的选项
# ----------------------------------
with section("parse"):

  # 指定自定义 CMake 函数的结构
  additional_commands = { 'foo': { 'flags': ['BAR', 'BAZ'],
             'kwargs': {'DEPENDS': '*', 'HEADERS': '*', 'SOURCES': '*'}}}

  # 为每个命令覆盖配置（如果可用）
  override_spec = {}

  # 指定变量标签
  vartags = []

  # 指定属性标签
  proptags = []

# -----------------------------
# 影响格式化的选项
# -----------------------------
with section("format"):

  # 完全禁用格式化，使 cmake-format 无效
  disable = False

  # 允许格式化的 CMake 文件的最大宽度
  line_width = 120

  # 缩进使用的空格数
  tab_size = 4

  # 如果为 True，则使用制表符（utf-8 0x09）而不是空格（utf-8 0x20）进行缩进
  use_tabchars = False

  # 如果 <use_tabchars> 为 True，则此变量控制如何处理缩进中的部分制表符
  # 'use-space': 保留为空格
  # 'round-up': 使用一个制表符代替，将列对齐到下一个制表位
  fractional_tab_policy = 'use-space'

  # 如果一个参数组包含超过此数量的子组（位置参数组或关键字参数组），则强制使用垂直布局
  max_subgroups_hwrap = 2

  # 如果一个位置参数组包含超过此数量的参数，则强制使用垂直布局
  max_pargs_hwrap = 6

  # 如果命令行位置组在没有嵌套的情况下占用超过此数量的行，则使布局无效（并嵌套）
  max_rows_cmdline = 2

  # 如果为 True，则在控制语句名称和括号之间添加空格
  separate_ctrl_name_with_space = False

  # 如果为 True，则在函数名称和括号之间添加空格
  separate_fn_name_with_space = False

  # 如果语句被换行到多行，则将右括号单独放在一行
  dangle_parens = False

  # 如果右括号必须单独放在一行，则对齐到以下参考：
  # `prefix`: 语句的开头
  # `prefix-indent`: 语句开头加一个缩进级别
  # `child`: 对齐到参数的列
  dangle_align = 'prefix'

  # 如果语句的拼写长度（包括空格和括号）小于此值，则强制拒绝嵌套布局
  min_prefix_chars = 4

  # 如果语句的拼写长度（包括空格和括号）比制表符宽度大超过此值，则强制拒绝非嵌套布局
  max_prefix_chars = 10

  # 如果候选布局是水平换行但超过此行数，则拒绝该布局
  max_lines_hwrap = 2

  # 输出中使用哪种样式的行尾符
  line_ending = 'unix'

  # 将命令名称格式化为 'lower'（小写）或 'upper'（大写）
  command_case = 'canonical'

  # 将关键字格式化为 'lower'（小写）或 'upper'（大写）
  keyword_case = 'unchanged'

  # 始终换行的命令名称列表
  always_wrap = []

  # 如果为 True，则将已知可排序的参数列表按字典顺序排序
  enable_sort = True

  # 如果为 True，解析器可以推断参数列表是否可排序（无需注释）
  autosort = False

  # 默认情况下，如果 cmake-format 无法将所有内容适配到所需的行宽，它将应用最后一次最激进的尝试
  # 如果此标志为 True，cmake-format 将打印错误，退出并返回非零状态码，且不输出任何内容
  require_valid_layout = False

  # 将布局节点映射到换行决策的字典
  layout_passes = {}

# ------------------------------------------------
# 影响注释重排和格式化的选项
# ------------------------------------------------
with section("markup"):

  # 用于项目符号列表的字符
  bullet_char = '*'

  # 用于枚举列表中数字后的标点符号的字符
  enum_char = '.'

  # 如果启用了注释标记，不要重排每个文件中的第一个注释块
  # 用于保留版权/许可证声明的格式
  first_comment_is_literal = False

  # 如果启用了注释标记，不要重排匹配此正则表达式模式的注释块
  literal_comment_pattern = None

  # 用于匹配注释中预格式化栅栏的正则表达式
  fence_pattern = '^\\s*([`~]{3}[`~]*)(.*)$'

  # 用于匹配注释中标尺的正则表达式
  ruler_pattern = '^\\s*[^\\w\\s]{3}.*[^\\w\\s]{3}$'

  # 如果注释行以此模式开头，则它是前一个参数的显式尾随注释
  explicit_trailing_pattern = '#<'

  # 如果注释行以至少此数量的连续井号开头，则不要删除它们
  hashruler_min_length = 10

  # 如果为 True，则在标尺的第一个井号和其余井号之间插入空格，并将其长度标准化以填充列
  canonicalize_hashrulers = True

  # 启用注释标记解析和重排
  enable_markup = True

# ----------------------------
# 影响代码检查的选项
# ----------------------------
with section("lint"):

  # 禁用的代码检查列表
  disabled_codes = []

  # 描述有效函数名称的正则表达式模式
  function_pattern = '[0-9a-z_]+'

  # 描述有效宏名称的正则表达式模式
  macro_pattern = '[0-9A-Z_]+'

  # 描述具有全局（缓存）作用域的变量名称的正则表达式模式
  global_var_pattern = '[A-Z][0-9A-Z_]+'

  # 描述具有全局作用域（但内部语义）的变量名称的正则表达式模式
  internal_var_pattern = '_[A-Z][0-9A-Z_]+'

  # 描述具有局部作用域的变量名称的正则表达式模式
  local_var_pattern = '[a-z][a-z0-9_]+'

  # 描述私有目录变量名称的正则表达式模式
  private_var_pattern = '_[0-9a-z_]+'

  # 描述公共目录变量名称的正则表达式模式
  public_var_pattern = '[A-Z][0-9A-Z_]+'

  # 描述函数/宏参数和循环变量名称的正则表达式模式
  argument_var_pattern = '[a-z][a-z0-9_]+'

  # 描述函数或宏中使用的关键字名称的正则表达式模式
  keyword_pattern = '[A-Z][0-9A-Z_]+'

  # 在 C0201 启发式算法中，匹配循环中的条件语句数量，以将其视为解析器
  max_conditionals_custom_parser = 2

  # 要求语句之间至少有多少个空行
  min_statement_spacing = 1

  # 要求语句之间最多有多少个空行
  max_statement_spacing = 2
  max_returns = 6
  max_branches = 12
  max_arguments = 5
  max_localvars = 15
  max_statements = 50

# -------------------------------
# 影响文件编码的选项
# -------------------------------
with section("encode"):

  # 如果为 True，则在文件开头发出 Unicode 字节顺序标记（BOM）
  emit_byteorder_mark = False

  # 指定输入文件的编码，默认为 utf-8
  input_encoding = 'utf-8'

  # 指定输出文件的编码，默认为 utf-8
  output_encoding = 'utf-8'

# -------------------------------------
# 其他配置选项
# -------------------------------------
with section("misc"):

  # 包含每个命令配置覆盖的字典，目前仅支持 `command_case`
  per_command = {}