.
├── include/
│   └── project/
│       └── sample_library.hpp    # 對外公開的標頭
├── src/
│   ├── app/
│   │   └── main.cpp              # 可執行程式進入點
│   └── lib/
│       └── sample_library.cpp    # 函式庫實作
├── utils/                        # Shell 腳本工具
├── build/                        # make 時產生，存放物件檔
├── .clang-format
├── .clang-tidy
└── Makefile

建置與執行

若系統已安裝 g++，可使用以下命令：

# 編譯 (預設目標 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

如需覆寫工具或編譯器設定，可在命令前傳入變數，例如：

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/ 底下的腳本快速操作：

./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：

./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 逐一檢查；若要檢查特定檔案，可執行：

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。

Docker

提供的 Dockerfile 會以 Ubuntu 24.04 建立開發環境，安裝 clang、clang-tidy、clang-format 等工具並執行 make install 與 make。可以使用以下指令建置並執行容器：

docker build -t cpp-template .
docker run --rm -it cpp-template

如果需要掛載原始碼以便互動開發，可使用：

docker run --rm -it -v "$(pwd)":/app -w /app cpp-template bash

下一步

在 src/ 新增更多檔案與模組。
依專案需求擴充 Makefile 或 utils 腳本。
若需要不同的編碼規範或靜態分析工具，修改 .clang-format 與 .clang-tidy 即可。

README.md Unescape Escape

cpp-template

目錄結構