📖 歡迎

歡迎使用 Termony！這是一份專為新手設計的 macOS 環境配置指南，將幫助你從零開始配置開發環境，讓 Termony 在你的 Mac 上能夠順利為OpenHarmony適配各種開源命令行工具。

🎯 適用對象

• ✅ 初次接觸OpenHarmony開發的開發者
• ✅ 需要在 macOS 上配置 Termony 開發環境的用户
• ✅ 遇到環境配置問題的開發者
• ✅ 對命令行不太熟悉的新手用户

⏱️ 預計時間

• 環境配置：15-30 分鐘（取決於網絡速度）
• 完整流程：1-2 小時（包括構建和部署）

📚 如何使用本指南

1. 如果你是新手：建議按照順序閲讀，不要跳過任何步驟
2. 如果你有經驗：可以直接查看"快速開始"章節
3. 如果遇到問題：查看"常見問題與故障排除"章節
4. 如果需要幫助：查看"獲取幫助"章節

🔑 重要提示

• ⚠️ 請按照順序執行：每個步驟都有依賴關係，跳過可能導致後續步驟失敗
• 💡 遇到問題不要慌：大部分問題都有解決方案，查看故障排除章節
• 📝 建議做筆記：記錄你的配置路徑和遇到的問題，方便後續參考

📑 目錄

1. 前置條件檢查 - 檢查你的 Mac 是否滿足要求
2. 快速開始（推薦） - 快速配置環境（適合有經驗的用户）
3. 詳細配置步驟 - 詳細的配置説明（適合新手）
4. Java Runtime 環境檢測與安裝 ⚠️ 簽名工具必需
5. 驗證安裝 - 驗證所有工具是否正確安裝
6. 常見問題與故障排除 - 遇到問題？看這裏
7. 檢查清單 - 配置完成後的檢查清單
8. 術語表 - 專業術語解釋
9. 快速參考 - 常用命令速查表
10. 獲取幫助 - 需要幫助？看這裏

📋 前置條件檢查

在開始配置之前，請確保你的 Mac 滿足以下條件。不要跳過這一步，否則可能導致後續配置失敗。

💻 系統要求

檢查方法：

# 檢查 macOS 版本
sw_vers

# 檢查架構（Apple Silicon 顯示 arm64，Intel 顯示 x86_64）
uname -m

# 檢查磁盤空間（查看可用空間）
df -h /

📦 必需軟件

1. Homebrew（包管理器）

什麼是 Homebrew？

Homebrew 是 macOS 上最流行的包管理器，類似於 Windows 的"應用商店"或 Linux 的 apt/yum。它可以幫你輕鬆安裝和管理各種開發工具，而不需要手動下載和配置。

為什麼需要 Homebrew？

Termony 項目需要很多開發工具（如 cmake、make 等），使用 Homebrew 可以一鍵安裝這些工具，比手動安裝方便得多。

檢查是否已安裝：

打開終端（Terminal.app），輸入以下命令：

brew --version

如果顯示版本號（如 Homebrew 5.0.1）：

• ✅ 説明已安裝，可以跳過安裝步驟
• 繼續下一步：安裝開發工具

如果顯示 "command not found"：

• ❌ 説明未安裝，需要先安裝 Homebrew

安裝 Homebrew：

1. 打開終端（Terminal.app）

   • 可以在"應用程序" → "實用工具"中找到
   • 或者按 ⌘ + 空格，輸入"終端"搜索

2. 複製並粘貼以下命令：

   /bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"

3. 按回車執行，然後：

   • 輸入你的 Mac 密碼（輸入時不會顯示，這是正常的）
   • 按回車確認
   • 等待安裝完成（可能需要 5-10 分鐘，取決於網絡速度）

4. 安裝後配置 PATH（重要！）：

   Apple Silicon Mac (M1/M2/M3)：

   echo 'eval "$(/opt/homebrew/bin/brew shellenv)"' >> ~/.zshrc
   eval "$(/opt/homebrew/bin/brew shellenv)"

   Intel Mac：

   echo 'eval "$(/usr/local/bin/brew shellenv)"' >> ~/.zshrc
   eval "$(/usr/local/bin/brew shellenv)"

   説明：這些命令會將 Homebrew 添加到系統路徑中，讓系統能找到 Homebrew 安裝的工具。

5. 驗證安裝：

   brew --version

   預期輸出：

   Homebrew 5.0.1
   Homebrew/homebrew-core (git revision xxxxx; last commit xxxxx)

   ✅ 如果看到版本號，説明安裝成功！

説明：

可執行brew update進行升級。

2. 檢查 Shell 類型

什麼是 Shell？

Shell 是終端中用來執行命令的程序。macOS 默認使用 zsh，本指南的所有命令都基於 zsh。

檢查當前 Shell：

echo $SHELL

預期輸出：

• ✅ /bin/zsh - 正確，可以繼續
• ❌ /bin/bash - 需要切換（見下方）

如果不是 zsh，切換方法：

chsh -s /bin/zsh

切換後需要重新打開終端才能生效。

🚀 快速開始（推薦）

💡 適合對象：對命令行比較熟悉，希望快速配置環境的用户

⚠️ 新手建議：如果你是第一次配置，建議查看"詳細配置步驟"章節，那裏有更詳細的説明

如果你希望快速配置環境，可以按照以下步驟操作：

步驟 1：安裝 Homebrew（如果未安裝）

/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"

安裝後配置 PATH（Apple Silicon Mac）：

echo 'eval "$(/opt/homebrew/bin/brew shellenv)"' >> ~/.zshrc
eval "$(/opt/homebrew/bin/brew shellenv)"

步驟 2：批量安裝開發工具

brew install --formula wget coreutils make gsed gettext automake cmake pkg-config ncurses

説明：

• --formula 參數可以避免某些包的衝突問題
• 安裝過程可能需要 10-20 分鐘，請耐心等待
• 如果某個工具安裝失敗，查看"常見問題"章節

步驟 3：配置 GNU 工具優先級

# 將 GNU 工具路徑添加到 PATH 前面
echo 'export PATH="/opt/homebrew/opt/coreutils/libexec/gnubin:/opt/homebrew/opt/gnu-sed/libexec/gnubin:/opt/homebrew/opt/make/libexec/gnubin:$PATH"' >> ~/.zshrc

# 使配置立即生效
source ~/.zshrc

為什麼需要這一步？ macOS 自帶的工具是 BSD 版本，而構建腳本需要 GNU 版本。這一步確保系統優先使用 GNU 版本。

步驟 4：驗證安裝

#!/bin/bash
# 開發工具安裝驗證腳本
# 用於檢查必需開發工具是否已正確安裝

echo "=== 開發工具安裝驗證 ==="
echo ""

# 定義要檢查的工具列表
tools=("wget" "make" "gsed" "gettext" "automake" "cmake" "pkg-config")

# 檢查每個工具
for tool in "${tools[@]}"; do
    if command -v $tool &> /dev/null; then
        # 獲取版本信息（取第一行）
        version=$($tool --version 2>&1 | head -1)
        echo "✓ $tool: $version"
    else
        echo "✗ $tool: 未安裝"
    fi
done

# 檢查 coreutils（特殊處理）
echo ""
echo "=== 檢查 coreutils ==="
if brew list coreutils &> /dev/null; then
    cp_path=$(which cp 2>/dev/null)
    if [[ $cp_path == *"/opt/homebrew/bin"* ]] || [[ $cp_path == *"/usr/local/bin"* ]]; then
        echo "✓ coreutils: GNU 版本已安裝 ($cp_path)"
    else
        echo "✓ coreutils: 已安裝（通過 Homebrew），但 PATH 中可能優先使用系統版本"
        echo "  提示：可以通過 'gcp', 'gls' 等命令使用 GNU 版本"
    fi
else
    echo "✗ coreutils: 未安裝"
fi

# 檢查 ncurses（庫文件，沒有可執行文件）
echo ""
echo "=== 檢查 ncurses ==="
if brew list ncurses &> /dev/null; then
    # 檢查庫文件是否存在
    if [ -f "/opt/homebrew/lib/libncurses.dylib" ] || [ -f "/opt/homebrew/lib/libncurses.a" ] || \
       [ -f "/usr/local/lib/libncurses.dylib" ] || [ -f "/usr/local/lib/libncurses.a" ]; then
        echo "✓ ncurses: 庫文件已安裝"
    else
        echo "✓ ncurses: 已安裝（通過 Homebrew）"
    fi
else
    echo "✗ ncurses: 未安裝"
fi

echo ""
echo "=== 檢查 GNU 工具優先級配置 ==="
# 檢查 sed
sed_path=$(which sed 2>/dev/null)
if [[ $sed_path == *"/opt/homebrew/opt/gnu-sed/libexec/gnubin"* ]]; then
    echo "✓ sed: 使用 GNU 版本 ($sed_path)"
else
    echo "⚠ sed: 使用系統版本 ($sed_path)，建議配置 GNU 版本優先級"
fi

# 檢查 make
make_path=$(which make 2>/dev/null)
if [[ $make_path == *"/opt/homebrew/opt/make/libexec/gnubin"* ]]; then
    echo "✓ make: 使用 GNU 版本 ($make_path)"
else
    echo "⚠ make: 使用系統版本 ($make_path)，建議配置 GNU 版本優先級"
fi

# 檢查 coreutils (cp)
cp_path=$(which cp 2>/dev/null)
if [[ $cp_path == *"/opt/homebrew/opt/coreutils/libexec/gnubin"* ]]; then
    echo "✓ cp: 使用 GNU 版本 ($cp_path)"
else
    echo "⚠ cp: 使用系統版本 ($cp_path)，建議配置 GNU 版本優先級"
fi

echo ""
echo "=== 驗證完成 ==="
echo ""
echo "如果發現未安裝的工具，請運行："
echo "brew install --formula wget coreutils make gsed gettext automake cmake pkg-config ncurses"
echo ""
echo "如果需要配置 GNU 工具優先級，請運行："
echo 'echo '\''export PATH="/opt/homebrew/opt/coreutils/libexec/gnubin:/opt/homebrew/opt/gnu-sed/libexec/gnubin:/opt/homebrew/opt/make/libexec/gnubin:$PATH"'\'' >> ~/.zshrc'
echo "source ~/.zshrc"

# 運行項目提供的驗證腳本（推薦）
./verify-tools.sh

# 或者手動驗證
cmake --version
make --version

預期結果：

• ✅ 所有工具都顯示版本號 → 配置成功！
• ❌ 某些工具顯示 "command not found" → 查看"常見問題"章節

完成！ 如果所有工具都顯示已安裝，説明環境配置成功。接下來可以繼續：

1. 安裝 Java Runtime（見"Java Runtime 環境檢測與安裝"章節）
2. 配置應用簽名（見"應用簽名配置實戰"章節）
3. 構建 HNP 包（見"HNP 包構建實戰"章節）

📖 詳細配置步驟

💡 適合對象：新手用户，希望瞭解每個步驟的詳細説明

📝 提示：如果你已經通過"快速開始"完成了配置，可以跳過這一章節

如果你希望瞭解每個步驟的詳細説明，或者遇到了問題，可以按照以下詳細步驟操作。建議按照順序閲讀，不要跳過任何步驟。

第一步：安裝 Homebrew

🤔 什麼是 Homebrew？

Homebrew 是 macOS 的包管理器，類似於：

• Windows 的"Microsoft Store"或"Chocolatey"
• Linux 的 apt（Ubuntu）或 yum（CentOS）
• Android 的"Google Play Store"

簡單來説：Homebrew 可以幫你一鍵安裝各種開發工具，而不需要：

• ❌ 手動下載安裝包
• ❌ 手動配置環境變量
• ❌ 手動處理依賴關係

📝 安裝步驟

步驟 1：打開終端

1. 點擊 Dock 中的"終端"圖標，或
2. 按 ⌘ + 空格，輸入"終端"，按回車，或
3. 打開"應用程序" → "實用工具" → "終端"

步驟 2：運行安裝命令

複製以下命令，粘貼到終端中，按回車：

/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"

步驟 3：按照提示操作

安裝過程中會提示你：

1. 輸入密碼：

   Password:

   • 輸入你的 Mac 登錄密碼（輸入時不會顯示，這是正常的）
   • 按回車確認

2. 確認安裝：

   Press RETURN to continue or any other key to abort

   • 按回車繼續，或按其他鍵取消

3. 等待安裝完成：

   • 可能需要 5-10 分鐘（取決於網絡速度）
   • 看到 Installation successful! 表示安裝成功

步驟 4：配置 PATH

安裝完成後，需要配置環境變量，讓系統能找到 Homebrew 安裝的工具。

Apple Silicon Mac (M1/M2/M3)：

echo 'eval "$(/opt/homebrew/bin/brew shellenv)"' >> ~/.zshrc
eval "$(/opt/homebrew/bin/brew shellenv)"

Intel Mac：

echo 'eval "$(/usr/local/bin/brew shellenv)"' >> ~/.zshrc
eval "$(/usr/local/bin/brew shellenv)"

説明：

• echo '...' >> ~/.zshrc：將配置添加到 shell 配置文件
• eval "$(...)"：立即應用配置（不需要重啓終端）

步驟 5：驗證安裝

brew --version

預期輸出：

Homebrew 5.0.1
Homebrew/homebrew-core (git revision xxxxx; last commit xxxxx)

✅ 如果看到版本號，説明安裝成功！

❓ 常見問題

Q1: 安裝時提示權限錯誤

錯誤信息：

Error: Permission denied

解決方案：

• 確保使用管理員賬户（Mac 登錄賬户）
• 不要使用 sudo，Homebrew 不需要管理員權限

Q2: 安裝速度很慢

原因：Homebrew 需要從 GitHub 下載文件，如果網絡較慢會影響速度。

解決方案：

• 耐心等待（這是正常的）
• 如果非常慢，可以考慮使用國內鏡像源（見"常見問題與故障排除"章節）

Q3: 提示 "command not found: brew"

原因：PATH 環境變量未正確配置。

解決方案：

1. 重新執行步驟 4 的配置命令
2. 重新打開終端窗口
3. 如果還是不行，檢查你的 Shell 類型（見前置條件檢查）

第二步：安裝開發工具

工具列表説明

Termony 需要以下開發工具：

安裝命令

方法一：批量安裝（推薦）

brew install --formula wget coreutils make gsed gettext automake cmake pkg-config ncurses

方法二：逐個安裝

如果批量安裝遇到問題，可以逐個安裝：

brew install --formula wget
brew install --formula coreutils
brew install --formula make
brew install --formula gsed
brew install --formula gettext
brew install --formula automake
brew install --formula cmake
brew install --formula pkg-config
brew install --formula ncurses

可能遇到的問題

問題 1：CMake 安裝錯誤

如果遇到以下錯誤：

Error: Cask 'cmake' definition is invalid: 'conflicts_with' stanza failed...

解決方案：

# 使用 formula 版本安裝
brew install --formula cmake

問題 2：工具已安裝但版本不對

# 更新所有工具
brew upgrade wget coreutils make gsed gettext automake cmake pkg-config ncurses

問題 3：網絡問題導致下載失敗

# 重試安裝
brew install --formula <工具名>

# 或者使用國內鏡像（見故障排除章節）

第三步：配置 GNU 工具優先級

為什麼需要配置？

macOS 自帶 BSD 版本的工具（如 sed、make、cp），而 Homebrew 安裝的是 GNU 版本。GNU 版本功能更強大、語法更標準，許多構建腳本依賴 GNU 版本。

配置步驟

1. 確定你的 Shell：

   echo $SHELL

   • 如果顯示 /bin/zsh，使用 ~/.zshrc
   • 如果顯示 /bin/bash，使用 ~/.bash_profile

2. 添加環境變量（zsh 用户）：

   echo 'export PATH="/opt/homebrew/opt/coreutils/libexec/gnubin:/opt/homebrew/opt/gnu-sed/libexec/gnubin:/opt/homebrew/opt/make/libexec/gnubin:$PATH"' >> ~/.zshrc

   或者（bash 用户）：

   echo 'export PATH="/opt/homebrew/opt/coreutils/libexec/gnubin:/opt/homebrew/opt/gnu-sed/libexec/gnubin:/opt/homebrew/opt/make/libexec/gnubin:$PATH"' >> ~/.bash_profile

3. 使配置生效：

   source ~/.zshrc  # zsh 用户
   # 或
   source ~/.bash_profile  # bash 用户

4. 驗證配置：

   # 檢查 sed（應該是 GNU sed）
   which sed
   sed --version
   # 應該顯示：sed (GNU sed) 4.9
   
   # 檢查 make（應該是 GNU Make）
   which make
   make --version
   # 應該顯示：GNU Make 4.4.1

配置説明

路徑含義：

• /opt/homebrew/opt/coreutils/libexec/gnubin：GNU coreutils 工具目錄
• /opt/homebrew/opt/gnu-sed/libexec/gnubin：GNU sed 工具目錄
• /opt/homebrew/opt/make/libexec/gnubin：GNU make 工具目錄

配置效果：

• ✅ 系統優先使用 GNU 版本的工具
• ✅ 腳本兼容性更好（符合 Linux/GNU 標準）
• ✅ 功能更強大（支持更多選項）
• ✅ 避免 BSD/GNU 語法差異導致的問題

注意事項：

• 配置後，sed、make、cp 等命令會使用 GNU 版本
• 如果需要使用 BSD 版本，可以使用完整路徑（如 /bin/sed）
• 某些腳本可能依賴 BSD 版本，需要測試兼容性

☕️ Java Runtime 環境檢測與安裝

為什麼需要 Java Runtime？

OpenHarmony 應用的簽名工具 hap-sign-tool.jar 需要 Java Runtime Environment (JRE) 來運行。在構建和簽名 HAP 包時，sign.py 腳本會調用 Java 來執行簽名操作。

檢測 Java Runtime

方法一：檢查 Java 是否已安裝

# 檢查 Java 命令是否可用
which java

# 檢查 Java 版本
java -version

# 應該看到類似以下輸出：
# openjdk version "17.0.2" 2022-01-18
# OpenJDK Runtime Environment (build 17.0.2+8-Ubuntu-120.04)
# OpenJDK 64-Bit Server VM (build 17.0.2+8-Ubuntu-120.04, mixed mode, sharing)

方法二：檢查 JAVA_HOME 環境變量

# 檢查 JAVA_HOME 是否設置
echo $JAVA_HOME

# 如果設置了，應該顯示 Java 安裝路徑，例如：
# /Library/Java/JavaVirtualMachines/jdk-17.jdk/Contents/Home

安裝 Java Runtime

方法一：使用 Homebrew 安裝（推薦）

這是最簡單的方式，適合 macOS 用户。

步驟 1：安裝 OpenJDK

# 安裝 OpenJDK（推薦 Java 17 或更高版本）
brew install openjdk@17

# 或者安裝最新版本
brew install openjdk

步驟 2：配置環境變量

安裝完成後，需要配置環境變量：

# 對於 zsh（macOS 默認）
echo 'export PATH="/opt/homebrew/opt/openjdk@17/bin:$PATH"' >> ~/.zshrc
echo 'export JAVA_HOME="/opt/homebrew/opt/openjdk@17"' >> ~/.zshrc

# 使配置立即生效
source ~/.zshrc

步驟 3：驗證安裝

# 檢查 Java 版本
java -version

# 檢查 JAVA_HOME
echo $JAVA_HOME

# 應該看到 Java 版本信息和正確的 JAVA_HOME 路徑

方法二：使用 Oracle JDK（官方版本）

如果你需要 Oracle 官方版本：

1. 訪問 Oracle 官網：

   • 打開 https://www.oracle.com/java/technologies/downloads/
   • 選擇 macOS 版本
   • 下載 JDK 安裝包（.dmg 文件）

2. 安裝 JDK：

   • 雙擊下載的 .dmg 文件
   • 按照安裝嚮導完成安裝

3. 配置環境變量：

   # 查找 Java 安裝路徑
   /usr/libexec/java_home -V
   
   # 設置 JAVA_HOME（替換為實際路徑）
   echo 'export JAVA_HOME=$(/usr/libexec/java_home)' >> ~/.zshrc
   echo 'export PATH="$JAVA_HOME/bin:$PATH"' >> ~/.zshrc
   
   # 使配置生效
   source ~/.zshrc

方法三：使用 Adoptium（Eclipse Temurin）

Adoptium 提供預構建的 OpenJDK 二進制文件：

1. 訪問 Adoptium 官網：

   • 打開 https://adoptium.net/
   • 選擇 macOS 和 Java 版本
   • 下載 .pkg 安裝包

2. 安裝：

   • 雙擊 .pkg 文件
   • 按照安裝嚮導完成安裝

3. 配置環境變量：

   # 查找 Java 安裝路徑
   /usr/libexec/java_home -V
   
   # 設置環境變量
   echo 'export JAVA_HOME=$(/usr/libexec/java_home)' >> ~/.zshrc
   echo 'export PATH="$JAVA_HOME/bin:$PATH"' >> ~/.zshrc
   
   # 使配置生效
   source ~/.zshrc

Java 版本要求

OpenHarmony 簽名工具通常需要：

• 最低版本：Java 8 或更高版本
• 推薦版本：Java 11、Java 17 或 Java 21（LTS 版本）

檢查當前 Java 版本：

java -version 2>&1 | head -1
# 應該顯示類似：openjdk version "17.0.2"

驗證 Java Runtime

完整驗證步驟

# 1. 檢查 Java 命令
which java
# 應該顯示：/opt/homebrew/opt/openjdk@17/bin/java 或類似路徑

# 2. 檢查 Java 版本
java -version
# 應該顯示版本信息

# 3. 檢查 JAVA_HOME
echo $JAVA_HOME
# 應該顯示 Java 安裝目錄

# 4. 測試運行 Java 程序
java -version
# 應該能正常輸出版本信息

# 5. 檢查 Java 編譯器（可選，簽名不需要）
javac -version
# 如果安裝了 JDK，應該顯示編譯器版本

驗證簽名工具可用性

# 檢查 OpenHarmony 簽名工具是否存在
ls -lh /Applications/DevEco-Studio.app/Contents/sdk/default/openharmony/toolchains/lib/hap-sign-tool.jar

# 測試運行簽名工具（會顯示幫助信息）
java -jar /Applications/DevEco-Studio.app/Contents/sdk/default/openharmony/toolchains/lib/hap-sign-tool.jar --help

Java Runtime 常見問題

問題 1：找不到 Java 命令

錯誤信息：

The operation couldn't be completed. Unable to locate a Java Runtime.
Please visit http://www.java.com for information on installing Java.

解決方案：

1. 使用 Homebrew 安裝 Java：brew install openjdk@17
2. 配置 PATH 環境變量
3. 重新加載 shell 配置：source ~/.zshrc

問題 2：Java 版本不兼容

錯誤信息：

Error: A JNI error has occurred, please check your installation

解決方案：

• 確保使用 Java 8 或更高版本
• 推薦使用 Java 11、17 或 21（LTS 版本）
• 檢查 JAVA_HOME 是否正確設置

問題 3：JAVA_HOME 未設置

錯誤信息：

JAVA_HOME is not set

解決方案：

# 查找 Java 安裝路徑
/usr/libexec/java_home -V

# 設置 JAVA_HOME
echo 'export JAVA_HOME=$(/usr/libexec/java_home)' >> ~/.zshrc
source ~/.zshrc

問題 4：多個 Java 版本衝突

解決方案：

# 查看所有已安裝的 Java 版本
/usr/libexec/java_home -V

# 切換到特定版本
export JAVA_HOME=$(/usr/libexec/java_home -v 17)

# 或者使用 jenv 管理多個 Java 版本
brew install jenv

Java Runtime 驗證清單

在構建和簽名 HAP 包之前，請確認：

• [ ] Java 已安裝（java -version 可以正常運行）
• [ ] Java 版本符合要求（Java 8 或更高，推薦 Java 17）
• [ ] JAVA_HOME 環境變量已設置（echo $JAVA_HOME 顯示路徑）
• [ ] PATH 中包含 Java bin 目錄（which java 顯示路徑）
• [ ] 可以運行 Java 程序（java -version 正常輸出）
• [ ] OpenHarmony 簽名工具可用（hap-sign-tool.jar 存在）

🧪 驗證安裝

方法一：使用驗證腳本（推薦）

項目根目錄提供了驗證腳本 verify-tools.sh：

# 運行驗證腳本
./verify-tools.sh

腳本會檢查：

• ✅ 所有必需工具的安裝狀態
• ✅ 每個工具的版本信息
• ✅ GNU 工具優先級配置
• ✅ 提供安裝和配置建議

預期輸出：

=== 開發工具安裝驗證 ===

✓ wget: GNU Wget 1.25.0
✓ make: GNU Make 4.4.1
✓ gsed: gsed (GNU sed) 4.9
✓ gettext: gettext (GNU gettext-runtime) 0.25
✓ automake: automake (GNU automake) 1.17
✓ cmake: cmake version 4.0.2
✓ pkg-config: 2.4.3

=== 檢查 coreutils ===
✓ coreutils: 已安裝（通過 Homebrew）

=== 檢查 ncurses ===
✓ ncurses: 已安裝（通過 Homebrew）

=== 檢查 GNU 工具優先級配置 ===
✓ sed: 使用 GNU 版本
✓ make: 使用 GNU 版本
✓ cp: 使用 GNU 版本

=== 驗證完成 ===

方法二：手動驗證

如果不想使用腳本，可以手動檢查：

# 檢查各個工具
wget --version
make --version
cmake --version
pkg-config --version
gettext --version
automake --version
gsed --version

# 檢查 GNU 工具優先級
which sed
sed --version  # 應該顯示 GNU sed

which make
make --version  # 應該顯示 GNU Make

which cp
cp --version  # 應該顯示 GNU coreutils

驗證清單

請確認以下所有項目都顯示 ✓：

• [ ] Homebrew 已安裝並可運行
• [ ] wget 已安裝
• [ ] coreutils 已安裝
• [ ] make 已安裝（GNU 版本）
• [ ] gsed 已安裝
• [ ] gettext 已安裝
• [ ] automake 已安裝
• [ ] cmake 已安裝
• [ ] pkg-config 已安裝
• [ ] ncurses 已安裝
• [ ] GNU 工具優先級已配置（sed、make、cp 使用 GNU 版本）
• [ ] Java Runtime 已安裝（java -version 可以正常運行）
• [ ] JAVA_HOME 環境變量已設置

🧯 常見問題與故障排除

問題 1：Homebrew 安裝 CMake 失敗

錯誤信息：

Error: Cask 'cmake' definition is invalid: 'conflicts_with' stanza failed...

原因：Homebrew 5.0+ 版本禁用了 conflicts_with 功能，但某些 cask 定義還在使用它。

解決方案：

# 使用 formula 版本安裝（推薦）
brew install --formula cmake

驗證：

cmake --version
# 應該顯示：cmake version 4.0.2

問題 2：找不到命令（command not found）

症狀：安裝工具後，運行命令時提示 "command not found"

可能原因：

1. PATH 未正確配置
2. 工具未正確安裝
3. Shell 配置未生效

解決方案：

1. 檢查工具是否安裝：

   brew list | grep cmake

2. 檢查 PATH：

   echo $PATH
   # 應該包含 /opt/homebrew/bin

3. 添加 PATH（如果缺失）：

   echo 'export PATH="/opt/homebrew/bin:$PATH"' >> ~/.zshrc
   source ~/.zshrc

4. 檢查工具位置：

   which cmake
   # 應該顯示：/opt/homebrew/bin/cmake

問題 3：GNU 工具優先級未生效

症狀：配置了 PATH，但 sed、make 仍使用系統版本

檢查方法：

which sed
# 如果顯示 /bin/sed，説明使用的是系統版本
# 應該顯示 /opt/homebrew/opt/gnu-sed/libexec/gnubin/sed

解決方案：

1. 確認配置已添加：

   tail -5 ~/.zshrc
   # 應該看到 PATH 配置

2. 重新加載配置：

   source ~/.zshrc

3. 檢查 PATH 順序：

   echo $PATH | tr ':' '\n' | grep -E "(coreutils|gnu-sed|make)"
   # GNU 工具的路徑應該在前面

4. 如果仍未生效，手動設置：

   export PATH="/opt/homebrew/opt/coreutils/libexec/gnubin:/opt/homebrew/opt/gnu-sed/libexec/gnubin:/opt/homebrew/opt/make/libexec/gnubin:$PATH"

問題 4：Homebrew 更新失敗

症狀：運行 brew update 時失敗或很慢

可能原因：

• 網絡連接問題
• 使用了鏡像源但配置不正確
• Homebrew 倉庫損壞

解決方案：

1. 檢查網絡連接：

   ping github.com

2. 切換到官方源（如果使用了鏡像）：

   git -C "/opt/homebrew" remote set-url origin https://github.com/Homebrew/brew

3. 重置更新：

   brew update-reset
   brew update

4. 修復倉庫：

   brew tap --repair

問題 5：安裝工具時網絡超時

症狀：下載工具時超時或失敗

解決方案：

1. 重試安裝：

   brew install --formula <工具名>

2. 使用國內鏡像（如果在中國）：

   # 設置 Homebrew 鏡像（清華大學）
   export HOMEBREW_BREW_GIT_REMOTE="https://mirrors.tuna.tsinghua.edu.cn/git/homebrew/brew.git"
   export HOMEBREW_CORE_GIT_REMOTE="https://mirrors.tuna.tsinghua.edu.cn/git/homebrew/homebrew-core.git"
   
   # 然後重新安裝
   brew install --formula <工具名>

3. 使用代理（如果有）：

   export http_proxy=http://127.0.0.1:7890
   export https_proxy=http://127.0.0.1:7890
   brew install --formula <工具名>

問題 6：磁盤空間不足

症狀：安裝時提示磁盤空間不足

解決方案：

1. 清理 Homebrew 緩存：

   brew cleanup

2. 刪除舊版本：

   brew cleanup --prune=all

3. 檢查磁盤空間：

   df -h

問題 7：權限問題

症狀：安裝或配置時提示權限錯誤

解決方案：

1. 檢查文件權限：

   ls -la ~/.zshrc

2. 修復權限：

   chmod 644 ~/.zshrc

3. 檢查 Homebrew 目錄權限：

   ls -la /opt/homebrew

✅ 檢查清單

在開始使用 Termony 之前，請確認以下所有項目都已完成：

基礎環境

• [ ] macOS 10.15 或更高版本
• [ ] 至少 5GB 可用磁盤空間
• [ ] 網絡連接正常

Homebrew

• [ ] Homebrew 已安裝
• [ ] brew --version 可以正常運行
• [ ] Homebrew 已更新到最新版本（brew update）

開發工具

• [ ] wget 已安裝（wget --version）
• [ ] coreutils 已安裝（brew list coreutils）
• [ ] make 已安裝（make --version）
• [ ] gsed 已安裝（gsed --version）
• [ ] gettext 已安裝（gettext --version）
• [ ] automake 已安裝（automake --version）
• [ ] cmake 已安裝（cmake --version）
• [ ] pkg-config 已安裝（pkg-config --version）
• [ ] ncurses 已安裝（brew list ncurses）

GNU 工具配置

• [ ] PATH 已配置（echo $PATH 包含 GNU 工具路徑）
• [ ] sed 使用 GNU 版本（sed --version 顯示 GNU sed）
• [ ] make 使用 GNU 版本（make --version 顯示 GNU Make）
• [ ] cp 使用 GNU 版本（cp --version 顯示 GNU coreutils）

驗證

• [ ] 運行 ./verify-tools.sh 所有檢查通過
• [ ] 所有工具版本符合要求
• [ ] 沒有錯誤或警告信息

工具詳細説明

wget - 命令行下載工具

用途：從網絡下載文件，支持 HTTP、HTTPS、FTP 協議

常用命令：

wget https://example.com/file.zip              # 下載文件
wget -c https://example.com/file.zip           # 斷點續傳
wget -O output.zip https://example.com/file.zip  # 指定輸出文件名

驗證：

wget --version
# 輸出：GNU Wget 1.25.0

coreutils - GNU 核心工具集

用途：提供標準 Unix 命令的 GNU 版本（cp, ls, mv, rm, cat 等）

説明：macOS 自帶 BSD 版本，GNU 版本功能更強大、語法更標準

常用命令：

cp file1 file2        # 複製文件（GNU 版本）
ls -lh               # 列出文件（GNU 版本）
mv file1 file2       # 移動文件（GNU 版本）

驗證：

cp --version
# 輸出：cp (GNU coreutils) 9.7

make - 構建工具

用途：根據 Makefile 執行構建任務

常用命令：

make                    # 執行默認目標
make -C build-hnp       # 在指定目錄執行 make
make clean              # 清理構建產物
make -j4                # 並行構建（4 個任務）

驗證：

make --version
# 輸出：GNU Make 4.4.1

gsed (GNU sed) - 文本處理工具

用途：流式文本編輯器，用於文本替換、刪除、插入等操作

常用命令：

sed 's/old/new/g' file.txt              # 替換文本
sed -i 's/old/new/g' file.txt           # 原地修改文件
sed -n '10,20p' file.txt                # 打印第 10-20 行

驗證：

sed --version
# 輸出：sed (GNU sed) 4.9

BSD vs GNU 差異：

• BSD sed：sed -i '' 's/old/new/g' file（需要空字符串）
• GNU sed：sed -i 's/old/new/g' file（不需要空字符串）

gettext - 國際化工具

用途：國際化（i18n）工具集，用於多語言支持

常用命令：

xgettext source.c -o messages.po         # 提取可翻譯字符串
msgfmt messages.po -o messages.mo       # 編譯翻譯文件

驗證：

gettext --version
# 輸出：gettext (GNU gettext-runtime) 0.25

automake - 自動生成 Makefile

用途：自動生成符合 GNU 標準的 Makefile

説明：通常與 autoconf 一起使用，用於生成構建系統

驗證：

automake --version
# 輸出：automake (GNU automake) 1.17

cmake - 跨平台構建系統

用途：跨平台構建系統生成器，用於管理 C/C++ 項目構建

常用命令：

cmake .                                  # 在當前目錄配置
cmake -B build                           # 在 build 目錄配置
cmake --build build                      # 構建項目
cmake --install build                    # 安裝

驗證：

cmake --version
# 輸出：cmake version 4.0.2

在項目中使用：

cmake_minimum_required(VERSION 3.5.0)
project(Termony)

pkg-config - 包配置工具

用途：查找已安裝庫的編譯和鏈接標誌

常用命令：

pkg-config --cflags freetype2            # 獲取編譯標誌
pkg-config --libs freetype2               # 獲取鏈接標誌
pkg-config --modversion freetype2         # 獲取版本號

驗證：

pkg-config --version
# 輸出：2.4.3

在 CMake 中使用：

find_package(PkgConfig REQUIRED)
pkg_check_modules(FREETYPE REQUIRED freetype2)

ncurses - 終端界面庫

用途：終端界面庫，用於創建文本模式的用户界面

説明：這是庫文件，沒有直接的可執行文件，主要用於編程

驗證：

brew list ncurses
# 應該顯示已安裝的文件列表

在 CMake 中使用：

find_package(Curses REQUIRED)
target_link_libraries(target ${CURSES_LIBRARIES})

📚 術語表

為了方便新手理解，這裏解釋一些專業術語：

🔍 快速參考

常用命令速查表

重要文件路徑

環境變量

快捷鍵

💬 獲取幫助

如果遇到問題，可以：

1. 查看項目文檔：

   • docs/ 目錄下的文檔
   • 項目 README.md 文件

2. 運行驗證腳本：

   ./verify-tools.sh

3. 檢查工具版本：

   <工具名> --version

4. 搜索問題：

   • 在"常見問題與故障排除"章節查找
   • 使用搜索引擎搜索錯誤信息

5. 獲取社區幫助：

   • 提交 Issue 到項目倉庫
   • 在項目討論區提問