From b5ccc595e0ff3647eb3e5e543e1efe8a3ed7d7fc Mon Sep 17 00:00:00 2001
From: MH Hung <mh.hung1994@gmail.com>
Date: Tue, 23 Sep 2025 13:47:09 +0800
Subject: [PATCH] feat: enhence makefile

---
 Makefile        | 57 +++++++++++++++++++++++++++++++++++++++++++++++--
 README.md       | 33 +++++++++++++++++++++++-----
 utils/format.sh | 17 +++------------
 utils/tidy.sh   | 10 +++++++++
 4 files changed, 96 insertions(+), 21 deletions(-)
 create mode 100755 utils/tidy.sh

diff --git a/Makefile b/Makefile
index 6c60fe5..19e8aeb 100644
--- a/Makefile
+++ b/Makefile
@@ -4,9 +4,13 @@ LDFLAGS :=
 SRC_DIR := src
 BUILD_DIR := build
 TARGET := app
+CLANG_FORMAT ?= clang-format
+CLANG_TIDY ?= clang-tidy
 
 SRCS := $(wildcard $(SRC_DIR)/*.cpp)
 OBJS := $(patsubst $(SRC_DIR)/%.cpp,$(BUILD_DIR)/%.o,$(SRCS))
+HDRS := $(wildcard $(SRC_DIR)/*.h) $(wildcard $(SRC_DIR)/*.hpp)
+FORMAT_SRCS := $(SRCS) $(HDRS)
 
 $(TARGET): $(OBJS)
 	$(CXX) $(OBJS) $(LDFLAGS) -o $@
@@ -17,7 +21,7 @@ $(BUILD_DIR)/%.o: $(SRC_DIR)/%.cpp | $(BUILD_DIR)
 $(BUILD_DIR):
 	mkdir -p $(BUILD_DIR)
 
-.PHONY: clean run format
+.PHONY: clean run format tidy tools install
 
 run: $(TARGET)
 	./$(TARGET)
@@ -26,4 +30,53 @@ clean:
 	rm -rf $(BUILD_DIR) $(TARGET)
 
 format:
-	clang-format -i $(SRCS)
+	@command -v $(CLANG_FORMAT) >/dev/null 2>&1 || { \
+		echo "error: $(CLANG_FORMAT) not found in PATH" >&2; \
+		exit 1; \
+	}
+	@if [ -n "$(strip $(FORMAT_SRCS))" ]; then \
+		$(CLANG_FORMAT) -i $(FORMAT_SRCS); \
+		echo "formatted: $(FORMAT_SRCS)"; \
+	else \
+		echo "warning: no source files found to format"; \
+	fi
+
+tidy:
+	@command -v $(CLANG_TIDY) >/dev/null 2>&1 || { \
+		echo "error: $(CLANG_TIDY) not found in PATH" >&2; \
+		exit 1; \
+	}
+	@if [ -n "$(strip $(SRCS))" ]; then \
+		for src in $(SRCS); do \
+			echo "running clang-tidy on $$src"; \
+			$(CLANG_TIDY) $$src -- $(CXXFLAGS); \
+		done; \
+	else \
+		echo "warning: no source files found for clang-tidy"; \
+	fi
+
+tools:
+	@command -v $(CLANG_FORMAT) >/dev/null 2>&1 && echo "found $(CLANG_FORMAT)" || echo "missing $(CLANG_FORMAT)"
+	@command -v $(CLANG_TIDY) >/dev/null 2>&1 && echo "found $(CLANG_TIDY)" || echo "missing $(CLANG_TIDY)"
+
+install:
+	@missing=""; \
+	if ! command -v $(CLANG_FORMAT) >/dev/null 2>&1; then \
+		missing="$$missing clang-format"; \
+	fi; \
+	if ! command -v $(CLANG_TIDY) >/dev/null 2>&1; then \
+		missing="$$missing clang-tidy"; \
+	fi; \
+	if [ -z "$$missing" ]; then \
+		echo "clang-format and clang-tidy already installed"; \
+	else \
+		echo "missing tools:$$missing"; \
+		if command -v apt-get >/dev/null 2>&1; then \
+			if command -v sudo >/dev/null 2>&1; then SUDO=sudo; else SUDO=; fi; \
+			$$SUDO apt-get update; \
+			$$SUDO apt-get install -y $$missing; \
+		else \
+			echo "error: apt-get not available; install manually:$$missing" >&2; \
+			exit 1; \
+		fi; \
+	fi
diff --git a/README.md b/README.md
index 757d39e..5176a83 100644
--- a/README.md
+++ b/README.md
@@ -5,10 +5,10 @@
 ## 目錄結構
 - `src/`: 主要的 C++ 原始碼，目前包含 `main.cpp`。
 - `build/`: 由 Makefile 自動建立，用來存放編譯後的物件檔。
-- `utils/`: 收錄常用腳本，例如編譯、執行、清理以及格式化。
+- `utils/`: 收錄常用腳本，例如編譯、執行、清理、格式化與 clang-tidy。
 - `.clang-format`: 定義 clang-format 的專案格式規則。
 - `.clang-tidy`: 定義 clang-tidy 的檢查設定。
-- `Makefile`: 管理編譯、執行、清理與格式化等命令。
+- `Makefile`: 管理編譯、執行、清理、格式化與靜態分析等命令。
 
 ## 建置與執行
 若系統已安裝 `g++`，可使用以下命令：
@@ -22,6 +22,25 @@ 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/` 底下的腳本快速操作：
@@ -30,7 +49,8 @@ make clean
 ./utils/build.sh        # 執行 make，接受額外參數
 ./utils/run.sh          # 編譯並執行
 ./utils/clean.sh        # 移除 build/ 與 app
-./utils/format.sh       # 依據 .clang-format 重新排版 src/ 下的檔案
+./utils/format.sh       # 呼叫 make format，可用 CLANG_FORMAT 指定執行檔
+./utils/tidy.sh         # 呼叫 make tidy，可用 CLANG_TIDY 指定執行檔
 ```
 
 如需指定不同的目標或旗標，可直接傳入 `utils/build.sh`：
@@ -40,13 +60,13 @@ make clean
 ```
 
 ## 程式碼格式化
-`utils/format.sh` 會檢查 `clang-format` 是否存在，並對 `src/` 目錄內的 `.cpp/.hpp/.h` 檔案進行格式化。專案提供的 `.clang-format` 以 LLVM 風格為基礎，並設定：
+`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 縮排規則
 
 ## 靜態分析
-`.clang-tidy` 啟用了一些常用的檢查（`bugprone-*`、`clang-analyzer-*`、`modernize-*` 等）。要檢查特定檔案，可執行：
+`.clang-tidy` 啟用了一些常用的檢查（`bugprone-*`、`clang-analyzer-*`、`modernize-*` 等）。可使用 `make tidy` 或 `CLANG_TIDY=/path/to/clang-tidy make tidy` 對 `src/*.cpp` 逐一檢查；若要檢查特定檔案，可執行：
 
 ```bash
 clang-tidy src/main.cpp --
@@ -54,6 +74,9 @@ clang-tidy src/main.cpp --
 
 可視需求調整 `Checks`、`HeaderFilterRegex` 或其他設定來符合專案需求。
 
+## 工具安裝
+`make install` 會檢查是否能找到 `clang-format` 與 `clang-tidy`。若缺少任何一項且系統支援 `apt-get`，會嘗試以 `sudo apt-get update` 與 `sudo apt-get install -y` 安裝所需套件（若沒有 `sudo` 則直接呼叫 `apt-get`）。若環境沒有 `apt-get`，指令會提示手動安裝缺少的工具。
+
 ## 下一步
 - 在 `src/` 新增更多檔案與模組。
 - 依專案需求擴充 Makefile 或 utils 腳本。
diff --git a/utils/format.sh b/utils/format.sh
index ca743fb..9a3301c 100755
--- a/utils/format.sh
+++ b/utils/format.sh
@@ -3,19 +3,8 @@ set -euo pipefail
 
 SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
 PROJECT_ROOT="${SCRIPT_DIR}/.."
-SRC_DIR="${PROJECT_ROOT}/src"
+CLANG_FORMAT_BIN="${CLANG_FORMAT:-clang-format}"
 
-if ! command -v clang-format >/dev/null 2>&1; then
-  echo "error: clang-format is not installed or not in PATH" >&2
-  exit 1
-fi
+cd "${PROJECT_ROOT}"
 
-if [ ! -d "${SRC_DIR}" ]; then
-  echo "warning: src directory not found; nothing to format" >&2
-  exit 0
-fi
-
-find "${SRC_DIR}" -name '*.cpp' -o -name '*.hpp' -o -name '*.h' | while read -r file; do
-  clang-format -i "$file"
-  echo "formatted $file"
-done
+make CLANG_FORMAT="${CLANG_FORMAT_BIN}" format
diff --git a/utils/tidy.sh b/utils/tidy.sh
new file mode 100755
index 0000000..10607c9
--- /dev/null
+++ b/utils/tidy.sh
@@ -0,0 +1,10 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+PROJECT_ROOT="${SCRIPT_DIR}/.."
+CLANG_TIDY_BIN="${CLANG_TIDY:-clang-tidy}"
+
+cd "${PROJECT_ROOT}"
+
+make CLANG_TIDY="${CLANG_TIDY_BIN}" tidy