114 lines
4.2 KiB
Markdown
114 lines
4.2 KiB
Markdown
# cpp-template
|
||
|
||
這個專案提供一個簡單的 C++ 樣板，包含基本的目錄結構、Makefile 與開發輔助工具，方便快速開始新專案。
|
||
|
||
## 目錄結構
|
||
```text
|
||
.
|
||
├── include/
|
||
│ └── project/
|
||
│ └── sample_library.hpp # 對外公開的標頭
|
||
├── src/
|
||
│ ├── app/
|
||
│ │ └── main.cpp # 可執行程式進入點
|
||
│ └── lib/
|
||
│ └── sample_library.cpp # 函式庫實作
|
||
├── utils/ # Shell 腳本工具
|
||
├── build/ # make 時產生，存放物件檔
|
||
├── .clang-format
|
||
├── .clang-tidy
|
||
└── Makefile
|
||
```
|
||
|
||
## 建置與執行
|
||
若系統已安裝 `g++`，可使用以下命令：
|
||
|
||
```bash
|
||
# 編譯 (預設目標 app)
|
||
make
|
||
|
||
# 編譯並執行
|
||
make run
|
||
|
||
# 清理 build 及執行檔
|
||
make clean
|
||
|
||
# 以 clang-format 重新排版 src/*.cpp/.hpp/.h
|
||
make format
|
||
|
||
# 以 clang-tidy 檢查所有 src/*.cpp
|
||
make tidy
|
||
|
||
# 確認並安裝 clang-format/clang-tidy（需要 apt 與可能的 sudo）
|
||
make install
|
||
|
||
# 確認 clang-format 與 clang-tidy 是否可用
|
||
make tools
|
||
```
|
||
|
||
如需覆寫工具或編譯器設定，可在命令前傳入變數，例如：
|
||
|
||
```bash
|
||
CLANG_FORMAT=/opt/llvm/bin/clang-format CLANG_TIDY=/opt/llvm/bin/clang-tidy make tidy
|
||
CXX=clang++ CXXFLAGS="-std=c++20 -O3" make
|
||
```
|
||
|
||
也可以透過 `utils/` 底下的腳本快速操作：
|
||
|
||
```bash
|
||
./utils/build.sh # 執行 make，接受額外參數
|
||
./utils/run.sh # 編譯並執行
|
||
./utils/clean.sh # 移除 build/ 與 app
|
||
./utils/format.sh # 呼叫 make format，可用 CLANG_FORMAT 指定執行檔
|
||
./utils/tidy.sh # 呼叫 make tidy，可用 CLANG_TIDY 指定執行檔
|
||
```
|
||
|
||
如需指定不同的目標或旗標，可直接傳入 `utils/build.sh`：
|
||
|
||
```bash
|
||
./utils/build.sh TARGET=my_app CXXFLAGS="-O3 -DNDEBUG"
|
||
```
|
||
|
||
## 程式碼格式化
|
||
`make format` 會確認 `clang-format` 是否可用，再對 `src/` 目錄內的 `.cpp/.hpp/.h` 檔案進行格式化。透過 `CLANG_FORMAT=/path/to/clang-format make format` 或 `CLANG_FORMAT=/path/to/clang-format ./utils/format.sh` 可覆寫預設執行檔。專案提供的 `.clang-format` 以 LLVM 風格為基礎，並設定：
|
||
- C++20 標準
|
||
- 4 空格縮排，最大列寬 100
|
||
- 自訂括號換行與 namespace 縮排規則
|
||
|
||
## 範例程式碼
|
||
`include/project/sample_library.hpp` 與 `src/lib/sample_library.cpp` 呈現一個簡單的 `project::Greeter` 類別與 `generate_sequence` 函式，`.hpp` 只放宣告、`.cpp` 負責實作，示範「公開標頭放在 include/，實作放在 src/」的常見結構。`src/app/main.cpp` 會引入該標頭並呼叫它們，執行 `make run` 即可看到輸出。如果要建立自己的模組，可依此模式建立額外的標頭與來源檔，並依需求放在 `src/lib/`、`src/app/` 或新的子資料夾。
|
||
|
||
## 靜態分析
|
||
`.clang-tidy` 啟用了一些常用的檢查（`bugprone-*`、`clang-analyzer-*`、`modernize-*` 等）。可使用 `make tidy` 或 `CLANG_TIDY=/path/to/clang-tidy make tidy` 對 `src/*.cpp` 逐一檢查；若要檢查特定檔案，可執行：
|
||
|
||
```bash
|
||
clang-tidy -quiet src/app/main.cpp -- -Iinclude
|
||
```
|
||
|
||
可視需求調整 `Checks`、`HeaderFilterRegex` 或其他設定來符合專案需求。
|
||
|
||
## 工具安裝
|
||
`make install` 會檢查是否能找到 `clang-format` 與 `clang-tidy`。若缺少任何一項且系統支援 `apt-get`，會嘗試以 `sudo apt-get update` 與 `sudo apt-get install -y` 安裝所需套件（若沒有 `sudo` 則直接呼叫 `apt-get`）。若環境沒有 `apt-get`，指令會提示手動安裝缺少的工具。
|
||
|
||
## 授權
|
||
此專案使用 [MIT License](LICENSE)。
|
||
|
||
## Docker
|
||
提供的 `Dockerfile` 會以 Ubuntu 24.04 建立開發環境，安裝 `clang`、`clang-tidy`、`clang-format` 等工具並執行 `make install` 與 `make`。可以使用以下指令建置並執行容器：
|
||
|
||
```bash
|
||
docker build -t cpp-template .
|
||
docker run --rm -it cpp-template
|
||
```
|
||
|
||
如果需要掛載原始碼以便互動開發，可使用：
|
||
|
||
```bash
|
||
docker run --rm -it -v "$(pwd)":/app -w /app cpp-template bash
|
||
```
|
||
|
||
## 下一步
|
||
- 在 `src/` 新增更多檔案與模組。
|
||
- 依專案需求擴充 Makefile 或 utils 腳本。
|
||
- 若需要不同的編碼規範或靜態分析工具，修改 `.clang-format` 與 `.clang-tidy` 即可。
|