feat(linter): implement Phase 1 linter automation and docs
- 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
This commit is contained in:
138
README.md
138
README.md
@@ -1,94 +1,94 @@
|
||||
# C++ Linter Template
|
||||
|
||||
這是一個展示如何在 C++ 專案中整合 linter 工具的模板專案。
|
||||
這是一個符合最佳實務、可漸進式導入的 C++ linter 自動化模板。現為 Phase 1：格式嚴格、靜態分析建議不擋流程。
|
||||
|
||||
## 目的
|
||||
- 展示 clang-tidy 在舊 C++ 代碼中的應用
|
||||
- 提供漸進式導入 linter 的範例
|
||||
- Azure DevOps CI/CD 整合範例
|
||||
## 目標
|
||||
- 對舊 C++ 專案導入 `clang-tidy` 與 `clang-format`
|
||||
- 提供「先格式、後強化」的漸進策略
|
||||
- 內建 Azure DevOps CI/CD 串接與 PR 差異分析
|
||||
|
||||
## 快速開始
|
||||
## 快速開始（Phase 1）
|
||||
|
||||
### 1. 本地開發環境設定
|
||||
### 1) 安裝工具
|
||||
```bash
|
||||
# 安裝相依套件 (Ubuntu/Debian)
|
||||
# Ubuntu/Debian
|
||||
sudo apt install clang-tidy clang-format cmake build-essential
|
||||
|
||||
# 安裝相依套件 (macOS)
|
||||
# macOS
|
||||
brew install llvm cmake
|
||||
|
||||
# 克隆專案
|
||||
git clone <your-repo-url>
|
||||
cd cpp-linter-template
|
||||
```
|
||||
|
||||
### 2. 執行 Linter
|
||||
### 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
|
||||
|
||||
# 或手動執行
|
||||
clang-tidy src/*.cpp src/*.h tests/*.cpp --config-file=.clang-tidy
|
||||
```
|
||||
|
||||
### 3. 建構專案
|
||||
### 4) 安裝 Git hooks（建議）
|
||||
```bash
|
||||
mkdir build && cd build
|
||||
cmake ..
|
||||
make
|
||||
./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
|
||||
```
|
||||
|
||||
## Linter 配置說明
|
||||
### 當前採用階段一設定：
|
||||
- 只檢查最關鍵的錯誤
|
||||
- 不會因 linter 警告而中斷 CI
|
||||
- 適合舊代碼逐步改進
|
||||
## 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`
|
||||
|
||||
## 在 Azure DevOps 中使用
|
||||
1. 將此專案推送到 Azure DevOps
|
||||
2. 設定 Pipeline 使用 azure-pipelines.yml
|
||||
3. 建立 Pull Request 時會自動執行 linter
|
||||
## 自定義規則
|
||||
- `.clang-tidy`：Phase 1 強調重大缺陷檢查（例如 analyzer、部分 bugprone）。
|
||||
- `.clang-format`：基於 LLVM 風格（IndentWidth=4, ColumnLimit=100）。
|
||||
|
||||
## 自定義配置
|
||||
編輯 .clang-tidy 檔案來調整檢查規則：
|
||||
```yaml
|
||||
# 增加更多檢查
|
||||
Checks: '-*,clang-analyzer-*,bugprone-*,readability-*'
|
||||
```
|
||||
|
||||
## 檔案說明
|
||||
`.clang-tidy:` Linter 配置檔
|
||||
`.clang-format`: 程式碼格式化配置
|
||||
`azure-pipelines.yml`: Azure DevOps CI/CD 配置
|
||||
`scripts/run-linter.sh`: 本地執行 linter 腳本
|
||||
|
||||
## 注意事項
|
||||
- 此模板使用 C++98 標準，適合舊代碼
|
||||
- Linter 設定較為寬鬆，適合逐步導入
|
||||
- 可以根據團隊需求調整檢查規則
|
||||
## 文件
|
||||
- `docs/linter-setup.md`：本地與 CI 設定流程
|
||||
- `docs/coding-standards.md`：編碼與格式規範（Phase 1）
|
||||
|
||||
## 專案結構
|
||||
cpp-linter-template/
|
||||
├── .clang-tidy # linter 配置檔
|
||||
├── .clang-format # 格式化配置檔
|
||||
├── azure-pipelines.yml # Azure DevOps CI/CD 配置
|
||||
├── CMakeLists.txt # 建構配置
|
||||
├── README.md # 專案說明
|
||||
├── docs/ # 文件目錄
|
||||
│ ├── linter-setup.md # Linter 設定指南
|
||||
│ └── coding-standards.md # 編碼標準
|
||||
├── src/ # 原始碼
|
||||
│ ├── main.cpp # 主程式（含各種測試案例）
|
||||
│ ├── utils.cpp # 工具函數
|
||||
│ └── utils.h # 標頭檔
|
||||
├── tests/ # 測試程式碼
|
||||
│ └── test_main.cpp # 簡單測試
|
||||
└── scripts/ # 輔助腳本
|
||||
├── run-linter.sh # 本地執行 linter
|
||||
└── setup-hooks.sh # 設定 git hooks
|
||||
├── .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：全域強制，警告視為錯誤（需技術債清理完成）。
|
||||
|
||||
Reference in New Issue
Block a user