MH Hung
f55d10ee07
- Add .clang-tidy (analyzer + selected bugprone) and .clang-format (LLVM, 4-space, 100 cols) - Enhance scripts/run-linter.sh to use compile_commands.json when available - Add scripts/setup-hooks.sh pre-commit (format enforcement; advisory tidy) - Update azure-pipelines.yml to export compile_commands and run clang-tidy -p build - Fill docs/linter-setup.md and docs/coding-standards.md for Phase 1 - Add minimal tests in tests/test_main.cpp to ensure CI executes - Rewrite README with Phase 1 workflow
95 lines
3.4 KiB
Markdown
95 lines
3.4 KiB
Markdown
# C++ Linter Template
|
||
|
||
這是一個符合最佳實務、可漸進式導入的 C++ linter 自動化模板。現為 Phase 1：格式嚴格、靜態分析建議不擋流程。
|
||
|
||
## 目標
|
||
- 對舊 C++ 專案導入 `clang-tidy` 與 `clang-format`
|
||
- 提供「先格式、後強化」的漸進策略
|
||
- 內建 Azure DevOps CI/CD 串接與 PR 差異分析
|
||
|
||
## 快速開始（Phase 1）
|
||
|
||
### 1) 安裝工具
|
||
```bash
|
||
# Ubuntu/Debian
|
||
sudo apt install clang-tidy clang-format cmake build-essential
|
||
|
||
# macOS
|
||
brew install llvm cmake
|
||
```
|
||
|
||
### 2) 產出 compile_commands.json（建議）
|
||
```bash
|
||
mkdir -p build && cd build
|
||
cmake .. -DCMAKE_EXPORT_COMPILE_COMMANDS=ON
|
||
cd -
|
||
```
|
||
|
||
### 3) 執行 Linter
|
||
```bash
|
||
# 使用腳本（會自動偵測 build/compile_commands.json）
|
||
./scripts/run-linter.sh
|
||
```
|
||
|
||
### 4) 安裝 Git hooks（建議）
|
||
```bash
|
||
./scripts/setup-hooks.sh
|
||
```
|
||
- pre-commit 會自動 clang-format 已 staged 的 C/C++ 檔並要求你重提一次 commit。
|
||
- clang-tidy 以建議模式執行（不擋提交）。
|
||
|
||
### 5) 建構與執行
|
||
```bash
|
||
mkdir -p build && cd build
|
||
cmake .. -DCMAKE_BUILD_TYPE=Debug
|
||
make -j$(nproc)
|
||
./tests
|
||
./main
|
||
```
|
||
|
||
## Phase 1 政策（建議 → 強制的起點）
|
||
- 格式：以 `.clang-format` 為準；CI 以 `--dry-run --Werror` 強制。
|
||
- 靜態分析：`.clang-tidy` 啟用 `clang-analyzer-*` 與精選 `bugprone-*`；僅回報警告，不讓 CI 失敗。
|
||
- PR：僅分析變更檔案，加速回饋。
|
||
|
||
## CI 流程（Azure Pipelines）
|
||
1. 安裝工具與版本資訊
|
||
2. `clang-format --dry-run --Werror`（不合格式即失敗）
|
||
3. 以 CMake 匯出 `build/compile_commands.json`
|
||
4. `clang-tidy -p build` 掃描（建議模式，不擋流程）
|
||
5. Build 專案與執行 `./tests`、`./main`
|
||
6. PR Job 僅對變更檔案跑 `clang-tidy -p build`
|
||
|
||
## 自定義規則
|
||
- `.clang-tidy`：Phase 1 強調重大缺陷檢查（例如 analyzer、部分 bugprone）。
|
||
- `.clang-format`：基於 LLVM 風格（IndentWidth=4, ColumnLimit=100）。
|
||
|
||
## 文件
|
||
- `docs/linter-setup.md`：本地與 CI 設定流程
|
||
- `docs/coding-standards.md`：編碼與格式規範（Phase 1）
|
||
|
||
## 專案結構
|
||
cpp-linter-template/
|
||
├── .clang-tidy # linter 配置檔（Phase 1）
|
||
├── .clang-format # 格式化配置
|
||
├── azure-pipelines.yml # Azure DevOps CI/CD 配置
|
||
├── CMakeLists.txt # 建構配置（C++98）
|
||
├── README.md # 專案說明（本檔）
|
||
├── docs/ # 文件目錄
|
||
│ ├── linter-setup.md # Linter 設定指南
|
||
│ └── coding-standards.md # 編碼標準（Phase 1）
|
||
├── src/ # 原始碼
|
||
│ ├── main.cpp # 主程式（含測試片段）
|
||
│ ├── utils.cpp # 工具函數
|
||
│ └── utils.h # 標頭檔
|
||
├── tests/ # 測試程式碼
|
||
│ └── test_main.cpp # 最小測試（無框架）
|
||
└── scripts/ # 輔助腳本
|
||
├── run-linter.sh # 本地執行 linter
|
||
└── setup-hooks.sh # 安裝 pre-commit hooks
|
||
|
||
## 後續階段（預覽）
|
||
- Phase 2：對關鍵 tidy 規則轉為失敗門檻（資源管理/未定義行為）。
|
||
- Phase 3：引入 readability/modernize 並在 PR 變更檔上強制。
|
||
- Phase 4：全域強制，警告視為錯誤（需技術債清理完成）。
|