issue/52 代码格式化：机制和效果

.clang-format

@@ -1,66 +1,30 @@
-# Generated from CLion C/C++ Code Style settings
+---
 BasedOnStyle: LLVM
-AccessModifierOffset: -4
-AlignAfterOpenBracket: Align
-# AlignConsecutiveAssignments: None
-AlignOperands: Align
-AllowAllArgumentsOnNextLine: false
-AllowAllConstructorInitializersOnNextLine: false
-AllowAllParametersOfDeclarationOnNextLine: false
-AllowShortBlocksOnASingleLine: Always
-AllowShortCaseLabelsOnASingleLine: false
-AllowShortFunctionsOnASingleLine: All
-AllowShortIfStatementsOnASingleLine: Always
-AllowShortLambdasOnASingleLine: All
-AllowShortLoopsOnASingleLine: true
-AlwaysBreakAfterReturnType: None
-AlwaysBreakTemplateDeclarations: No
-BreakBeforeBraces: Custom
+IndentWidth: 4                        # 缩进宽度，LLVM 默认值为 2，改为 4
+AccessModifierOffset: -4              # public/protected/private 访问控制符相对成员的偏移，与 IndentWidth 配合，LLVM 默认值为 -2
+AlignOperands: AlignAfterOperator     # 双目运算符的行间对齐，LLVM 默认值为 Align，改为带符号一起换行
+BreakBeforeBinaryOperators: All       # 在双目运算符之前换行，LLVM 默认值为 None，改为换行时总是把双目运算符放在行首，包括赋值（=）
+ColumnLimit: 0                        # 列宽限制，LLVM 默认值为 80，改为不限制
+AllowShortBlocksOnASingleLine: Always # 是否允许短块（单个语句的块）不换行，LLVM 默认值为 Never，改为允许
+AllowShortLoopsOnASingleLine: true    # 是否允许短循环不换行，LLVM 默认值为 false，改为允许
+InsertBraces: true                    # 是否在 if/for/while/switch 等语句后插入大括号，LLVM 默认值为 false，改为允许
+BreakBeforeBraces: Custom             # 大括号换行配置，LLVM 默认值为 LLVM，改为自定义以使 BraceWrapping 生效
 BraceWrapping:
   AfterCaseLabel: false
   AfterClass: false
   AfterControlStatement: Never
   AfterEnum: false
   AfterFunction: false
   AfterNamespace: false
+  AfterObjCDeclaration: false
+  AfterStruct: false
   AfterUnion: false
+  AfterExternBlock: false
   BeforeCatch: false
   BeforeElse: false
+  BeforeLambdaBody: false
+  BeforeWhile: false
   IndentBraces: false
-  SplitEmptyFunction: false
+  SplitEmptyFunction: true
   SplitEmptyRecord: true
-BreakBeforeBinaryOperators: None
-BreakBeforeTernaryOperators: true
-BreakConstructorInitializers: BeforeColon
-BreakInheritanceList: BeforeColon
-ColumnLimit: 0
-CompactNamespaces: true
-ContinuationIndentWidth: 4
-IndentCaseLabels: true
-IndentPPDirectives: None
-IndentWidth: 4
-KeepEmptyLinesAtTheStartOfBlocks: true
-MaxEmptyLinesToKeep: 2
-NamespaceIndentation: All
-ObjCSpaceAfterProperty: false
-ObjCSpaceBeforeProtocolList: true
-PointerAlignment: Right
-ReflowComments: false
-SpaceAfterCStyleCast: true
-SpaceAfterLogicalNot: false
-SpaceAfterTemplateKeyword: false
-SpaceBeforeAssignmentOperators: true
-SpaceBeforeCpp11BracedList: false
-SpaceBeforeCtorInitializerColon: true
-SpaceBeforeInheritanceColon: true
-SpaceBeforeParens: ControlStatements
-SpaceBeforeRangeBasedForLoopColon: true
-SpaceInEmptyParentheses: false
-SpacesBeforeTrailingComments: 0
-SpacesInAngles: false
-SpacesInCStyleCastParentheses: false
-SpacesInContainerLiterals: false
-SpacesInParentheses: false
-SpacesInSquareBrackets: false
-TabWidth: 4
-UseTab: Never
+  SplitEmptyNamespace: true

.github/workflows/build.yml

@@ -0,0 +1,37 @@
+name: Build and test
+on:
+  pull_request:
+  push:
+    paths-ignore:
+      - '**.md'
+      - 'LICENSE'
+
+jobs:
+  build:
+    name: Build
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        type: [debug, release]
+    steps:
+
+    - name: checkout code
+      uses: actions/checkout@v4
+
+    - name: install black
+      run: pip install black
+
+    - name: check format
+      run: python3 scripts/format.py --path src --check
+
+    - name: install xmake
+      uses: xmake-io/github-action-setup-xmake@v1
+      with:
+        xmake-version: latest
+
+    - name: configure xmake
+      run: xmake f -cv
+
+    - name: build with xmake
+      run: xmake build && xmake install

README.md

@@ -1,50 +1,99 @@
 # InfiniCore
 
-InfiniCore是一个跨平台统一编程工具集，为不同芯片平台的功能（包括计算、运行时、通信等）提供统一 C 语言接口。目前支持的芯片包括CPU、英伟达GPU、华为昇腾NPU、寒武纪MLU、摩尔线程GPU、天数智芯GPU、沐曦GPU、曙光DCU、昆仑芯。
+InfiniCore 是一个跨平台统一编程工具集，为不同芯片平台的功能（包括计算、运行时、通信等）提供统一 C 语言接口。目前支持的硬件和后端包括：
 
-## 一、使用说明
+- CPU；
+- CUDA
+  - 英伟达 GPU；
+  - 摩尔线程 GPU；
+  - 天数智芯 GPU；
+  - 沐曦 GPU；
+  - 曙光 DCU；
+- 华为昇腾 NPU；
+- 寒武纪 MLU；
+- 昆仑芯 XPU；
 
-### 1. 配置
+## 配置和使用
 
-#### 查看当前配置
+1. 项目配置
 
-```xmake
-xmake f -v
-```
+   - 查看当前配置
 
-#### 配置 CPU （默认配置）
+     ```shell
+     xmake f -v
+     ```
 
-```xmake
-xmake f -cv
-```
+   - 配置 CPU（默认配置）
 
-#### 配置加速卡
+     ```shell
+     xmake f -cv
+     ```
 
-```xmake
-# 英伟达
-# 可以指定 CUDA 路径， 一般环境变量为 `CUDA_HOME` 或者 `CUDA_ROOT`
-xmake f --nv-gpu=true --cuda=$CUDA_HOME -cv
+   - 配置加速卡
 
-# 寒武纪
-xmake f --cambricon-mlu=true -cv
+     ```shell
+     # 英伟达
+     # 可以指定 CUDA 路径， 一般环境变量为 `CUDA_HOME` 或者 `CUDA_ROOT`
+     xmake f --nv-gpu=true --cuda=$CUDA_HOME -cv
 
-# 华为昇腾
-xmake f --ascend-npu=true -cv
-```
+     # 寒武纪
+     xmake f --cambricon-mlu=true -cv
 
-### 2. 编译安装
+     # 华为昇腾
+     xmake f --ascend-npu=true -cv
+     ```
 
-```xmake
-xmake build && xmake install
-# 默认安装路径为 $HOME/.infini
-```
+2. 编译安装
+
+   默认安装路径为 `$HOME/.infini`。
+
+   ```shell
+   xmake build && xmake install
+   ```
+
+3. 设置环境变量
+
+   按输出提示设置 `INFINI_ROOT` 和 `LD_LIBRARY_PATH` 环境变量。
+
+4. 运行算子测试
 
-### 3. 设置环境变量
+   ```shell
+   python test/infiniop/[operator].py [--cpu | --nvidia | --cambricon | --ascend]
+   ```
 
-按输出提示设置 `INFINI_ROOT` 和 `LD_LIBRARY_PATH` 环境变量。
+## 开发指南
 
-### 4. 运行算子测试
+### 代码格式化
 
-```bash
-python test/infiniop/[operator].py [--cpu | --nvidia | --cambricon | --ascend]
+本项目使用 [`scripts/format.py`](/scripts/format.py) 脚本实现代码格式化检查和操作。
+
+使用
+
+```shell
+python scripts/format.py -h
+```
+
+查看脚本帮助信息：
+
+```plaintext
+usage: format.py [-h] [--ref REF] [--path [PATH ...]] [--check] [--c C] [--py PY]
+
+options:
+  -h, --help         show this help message and exit
+  --ref REF          Git reference (commit hash) to compare against.
+  --path [PATH ...]  Files to format or check.
+  --check            Check files without modifying them.
+  --c C              C formatter (default: clang-format-16)
+  --py PY            Python formatter (default: black)
 ```
+
+参数中：
+
+- `ref` 和 `path` 控制格式化的文件范围
+  - 若 `ref` 和 `path` 都为空，格式化当前暂存（git added）的文件；
+  - 否则
+    - 若 `ref` 非空，将比较指定 commit 和当前代码的差异，只格式化修改过的文件；
+    - 若 `path` 非空，可传入多个路径（`--path p0 p1 p2`），只格式化指定路径及其子目录中的文件；
+- 若设置 `--check`，将检查代码是否需要修改格式，不修改文件内容；
+- 通过 `--c` 指定 c/c++ 格式化器，默认为 `clang-format-16`；
+- 通过 `--python` 指定 python 格式化器 `black`；

include/infinicore.h

@@ -6,8 +6,7 @@
 #define __INFINICORE_EXPORT_C__
 #if defined(_WIN32)
 #define __export __declspec(dllexport)
-#elif defined(__GNUC__) &&                                                     \
-    ((__GNUC__ >= 4) || (__GNUC__ == 3 && __GNUC_MINOR__ >= 3))
+#elif defined(__GNUC__) && ((__GNUC__ >= 4) || (__GNUC__ == 3 && __GNUC_MINOR__ >= 3))
 #define __export __attribute__((visibility("default")))
 #else
 #define __export

include/infiniop/ops/causal_softmax.h

@@ -19,5 +19,4 @@ __C __export infiniopStatus_t infiniopCausalSoftmax(infiniopCausalSoftmaxDescrip
 
 __C __export infiniopStatus_t infiniopDestroyCausalSoftmaxDescriptor(infiniopCausalSoftmaxDescriptor_t desc);
 
-
 #endif

include/infiniop/ops/conv.h

@@ -21,5 +21,4 @@ __C __export infiniopStatus_t infiniopConv(infiniopConvDescriptor_t desc, void *
 
 __C __export infiniopStatus_t infiniopDestroyConvDescriptor(infiniopConvDescriptor_t desc);
 
-
 #endif

include/infiniop/ops/random_sample.h

@@ -22,5 +22,4 @@ __C __export infiniopStatus_t infiniopRandomSample(infiniopRandomSampleDescripto
 
 __C __export infiniopStatus_t infiniopDestroyRandomSampleDescriptor(infiniopRandomSampleDescriptor_t desc);
 
-
 #endif

include/infiniop/tensor_descriptor.h

@@ -21,4 +21,4 @@ __C __export infiniopStatus_t infiniopCreateTensorDescriptor(infiniopTensorDescr
 
 __C __export infiniopStatus_t infiniopDestroyTensorDescriptor(infiniopTensorDescriptor_t desc);
 
-#endif// __INFINIOP_TENSOR_DESCRIPTOR__
+#endif // __INFINIOP_TENSOR_DESCRIPTOR__