macOS 建置與發行

2.1 Xcode Command Line Tools

xcode-select --install

2.2 以 Homebrew 安裝相依工具

brew install cmake ninja

2.3 安裝 Qt 6

# 加入 ~/.zshrc（Qt 的安裝路徑請依實際環境修改）
export Qt6_DIR="$HOME/Qt/6.x.x/macos/lib/cmake/Qt6"
export PATH="$HOME/Qt/6.x.x/macos/bin:$PATH"

brew install qt@6

2.4 確認安裝

cmake --version       # 3.16 以上
qmake --version       # Qt 6.x
clang++ --version     # Apple Clang

建置指令碼（建議）

使用 scripts/build-macos.sh，可以一次完成從 Release 建置到程式碼簽章、製作 DMG 的全部步驟：

# 一般建置 + 製作 DMG
./scripts/build-macos.sh

# 建置通用二進位檔（arm64 + x86_64）
./scripts/build-macos.sh --universal

# 清理後建置，不製作 DMG
./scripts/build-macos.sh --clean --skip-dmg

# 尚未準備 Qt 授權文件時的測試用 DMG（不用於發行）
./scripts/build-macos.sh --clean --skip-qt-licenses

# 以 Developer ID 簽章（預設為臨時簽章）
./scripts/build-macos.sh --sign-identity "Developer ID Application: Your Name (TEAMID)"

# 以 Developer ID 簽章，公證 DMG 後再製作 ZIP
export APPLE_ID="your@email.com" APPLE_TEAM_ID="TEAMID" APPLE_APP_PASSWORD="app-specific-password"
./scripts/build-macos.sh --sign-identity "Developer ID Application: Your Name (TEAMID)" --notarize

指令碼會自動執行以下處理：

1. 確認所需工具（cmake、ninja、macdeployqt、codesign、vtool、python3、create-dmg）
2. CMake 設定（指定 CMAKE_OSX_DEPLOYMENT_TARGET）+ Ninja 建置
3. 確認建置產物（.app、執行檔的最低 macOS 版本、.qm 翻譯檔）
4. 以 macdeployqt 打包框架
5. 刪除未使用的 Qt 元件，並將 Qt 二進位檔精簡為 arm64（4.4。使用 --universal 時不精簡為 arm64）+ 驗證
6. 附帶 Qt 授權文件（使用 --skip-qt-licenses 時略過）
7. 對整個應用程式套件進行程式碼簽章 + 以 codesign --verify --deep --strict 驗證
8. 以 create-dmg 製作 DMG（使用 Developer ID 時也對 DMG 簽章）
9. 使用 --notarize 時，對 DMG 進行公證與裝訂 + 驗證
10. 製作包含 DMG、Hayanagi 與詰將棋題集的發行用 ZIP（ShogiBoardQ-macos.zip）（5.2）

關於最低 macOS 版本：如果不指定部署目標（deployment target），建置主機的 macOS 版本就會成為最低支援版本（例：在 macOS 27 上建置後，無法在 macOS 26 上啟動）。指令碼預設指定 26.0，建置後如果執行檔的 minos 不一致就會停止。

關於程式碼簽章：macdeployqt 會改寫二進位檔，因此執行後的應用程式套件只剩連結器簽章，無法通過嚴格的簽章驗證。指令碼在 macdeployqt 之後重新對整個應用程式套件簽章，然後再製作 DMG。

關於 macdeployqt 顯示的 ERROR：會出現 .qm: is not an object file（對翻譯檔執行了 otool）、找不到 ODBC / PostgreSQL / Mimer SQL 驅動程式的相依項目，以及 macdeployqt 本身的簽章錯誤，但都無害。這些驅動程式會在下一步刪除，簽章也會由指令碼重新進行並嚴格驗證。

以下是手動逐一執行指令時的步驟。

3.1 Release 建置

cd /path/to/ShogiBoardQ

# 設定（Release 建置）
cmake -B build -S . -DCMAKE_BUILD_TYPE=Release

# 建置（平行建置）
cmake --build build --config Release -- -j$(sysctl -n hw.ncpu)

使用 Ninja 時（更快）：

cmake -B build -S . -G Ninja -DCMAKE_BUILD_TYPE=Release
ninja -C build

3.2 確認建置產物

# 確認已產生 .app 套件
ls -la build/ShogiBoardQ.app/

# 確認套件內的結構
find build/ShogiBoardQ.app -type f | head -20

建置後的套件結構：

ShogiBoardQ.app/
├── Contents/
│   ├── Info.plist
│   ├── MacOS/
│   │   ├── ShogiBoardQ              ← 執行檔
│   │   ├── ShogiBoardQ_ja_JP.qm     ← 日文翻譯
│   │   ├── ShogiBoardQ_en.qm        ← 英文翻譯
│   │   ├── ShogiBoardQ_zh_CN.qm     ← 簡體中文翻譯
│   │   ├── ShogiBoardQ_zh_TW.qm     ← 繁體中文翻譯
│   │   └── licenses/                ← 授權文件（簡易版）
│   └── Resources/
│       └── shogiboardq.icns          ← 應用程式圖示

3.3 執行確認

# 啟動建置好的應用程式
open build/ShogiBoardQ.app

4.1 以 macdeployqt 打包 Qt 框架

只有建置的話，Qt 的動態函式庫不會包含在應用程式套件中。使用 macdeployqt 將所需的 Qt 框架與外掛程式複製到套件內。

macdeployqt build/ShogiBoardQ.app -verbose=2

macdeployqt 自動執行的處理：

1. 將相依的 Qt 框架（QtWidgets、QtCharts、QtNetwork、QtMultimedia、QtGui、QtCore 等）複製到 Contents/Frameworks/
2. 將 Qt 外掛程式（platforms/cocoa、imageformats/svg 等）複製到 Contents/PlugIns/
3. 改寫函式庫的 @rpath（install_name_tool）
4. 在 Contents/Resources/ 中產生 qt.conf

4.2 確認打包後的結構

# 確認框架已正確打包
ls build/ShogiBoardQ.app/Contents/Frameworks/

# 確認包含外掛程式
ls build/ShogiBoardQ.app/Contents/PlugIns/

# 確認相依關係中沒有殘留外部路徑
otool -L build/ShogiBoardQ.app/Contents/MacOS/ShogiBoardQ

如果 otool 的輸出中殘留 /usr/local/ 或 /opt/homebrew/ 的路徑，表示打包不完整。

4.3 確認翻譯檔

CMake 的建置後步驟會將 .qm 檔放到 Contents/MacOS/。確認執行 macdeployqt 後檔案仍然存在：

ls build/ShogiBoardQ.app/Contents/MacOS/*.qm   # 4 個（ja_JP / en / zh_CN / zh_TW）

Qt 標準對話方塊的翻譯（qtbase_ja / qtbase_zh_CN / qtbase_zh_TW）內嵌在執行檔的資源中，因此不需要另外的檔案。

4.4 刪除未使用的 Qt 元件（最小組態）

macdeployqt 會依類別放入所有 Qt 外掛程式，並透過虛擬鍵盤外掛程式連帶引入 Qt Quick / QML（約 187MB）。刪除 ShogiBoardQ 不使用的部分，在僅支援 Apple 晶片的發行中還要去除 Qt 的 x86_64 部分（約 89MB，DMG 約 50MB）。

C=build/ShogiBoardQ.app/Contents
rm -rf $C/PlugIns/platforminputcontexts $C/PlugIns/networkinformation \
  $C/PlugIns/multimedia/libffmpegmediaplugin.dylib $C/Frameworks/libav*.dylib $C/Frameworks/libsw*.dylib \
  $C/Frameworks/QtQml*.framework $C/Frameworks/QtQuick.framework $C/Frameworks/QtVirtualKeyboard*.framework
find $C/PlugIns/tls -name '*.dylib' ! -name libqsecuretransportbackend.dylib -delete
find $C/PlugIns/sqldrivers -name '*.dylib' ! -name libqsqlite.dylib -delete
for p in gif wbmp macheif icns tga macjp2; do rm -f $C/PlugIns/imageformats/libq$p.dylib; done

# 將 Qt 精簡為只含 arm64（發行通用二進位檔時不要執行）
find $C -type f \( -perm +111 -o -name '*.dylib' \) | while read -r f; do
  if lipo -archs "$f" 2>/dev/null | grep -q x86_64; then
    lipo "$f" -thin arm64 -output "$f.thin" && chmod "$(stat -f %Lp "$f")" "$f.thin" && mv "$f.thin" "$f"
  fi
done

保留的是 12 個 Qt 框架（Charts、Concurrent、Core、DBus、Gui、Multimedia、Network、OpenGL、OpenGLWidgets、Sql、Svg、Widgets）與 10 個外掛程式（cocoa、macstyle、svgicon、darwin multimedia、sqlite、securetransport、ico / jpeg / tiff / webp）。刪除後要重新對整個應用程式套件簽章（6.4。臨時簽章時為 codesign --force --deep --sign - build/ShogiBoardQ.app）。

啟動後，確認載入的函式庫全部來自套件內：

open build/ShogiBoardQ.app
lsof -p "$(pgrep -x ShogiBoardQ)" | grep -E '/Qt/|homebrew'   # 沒有任何輸出即可

方法 A：macdeployqt 的 -dmg 選項（簡易）

macdeployqt build/ShogiBoardQ.app -dmg

會產生 build/ShogiBoardQ.dmg。方法簡單，但沒有背景圖片，也沒有指向 Applications 資料夾的連結。

方法 B：create-dmg（建議 - 自訂 DMG）

製作外觀美觀、使用者可以拖放到 Applications 資料夾的 DMG。

brew install create-dmg

# 以 macdeployqt 製作應用程式套件（不加 -dmg）
macdeployqt build/ShogiBoardQ.app

# 製作 DMG
create-dmg \
  --volname "ShogiBoardQ" \
  --volicon "resources/icons/shogiboardq.icns" \
  --window-pos 200 120 \
  --window-size 600 400 \
  --icon-size 100 \
  --icon "ShogiBoardQ.app" 150 190 \
  --hide-extension "ShogiBoardQ.app" \
  --app-drop-link 450 190 \
  "ShogiBoardQ.dmg" \
  "build/ShogiBoardQ.app"

方法 C：hdiutil（手動 - 完全控制）

# 建立暫存目錄
mkdir -p dmg_staging
cp -R build/ShogiBoardQ.app dmg_staging/
ln -s /Applications dmg_staging/Applications

# 製作 DMG
hdiutil create -volname "ShogiBoardQ" \
  -srcfolder dmg_staging \
  -ov -format UDZO \
  "ShogiBoardQ.dmg"

# 清理
rm -rf dmg_staging

5.1 驗證 DMG

# 掛載後確認執行
hdiutil attach ShogiBoardQ.dmg
open /Volumes/ShogiBoardQ/ShogiBoardQ.app

# 退出
hdiutil detach /Volumes/ShogiBoardQ

5.2 發行用 ZIP

指令碼在製作 DMG 之後，會在存放庫根目錄製作 ShogiBoardQ-macos.zip。結構與 Linux 版的 ZIP 相同。

ShogiBoardQ-macos/
├── ShogiBoardQ.dmg
├── README.md                      ← resources/platform/README-macos.md
├── LICENSE
├── Hayanagi/
│   ├── hayanagi                   ← 用於一般對局的 USI 引擎（arm64，最低 macOS 版本與應用程式相同）
│   ├── book/hayanagi_book.db      ← Hayanagi 的定跡
│   └── README.md
└── data/tsumeshogi/
    ├── tsume_{3,5,7,9,11,13}ply_1000_YYYYMMDD.txt
    └── README.md

• 題集每種手數只能有 1 個檔案。如果殘留舊版等檔案，指令碼會停止。
• hayanagi 使用對 build/Hayanagi/hayanagi 執行 strip -x 後的檔案，並以與應用程式相同的身分（預設為臨時簽章）重新簽章。
• 定跡檔案 hayanagi_book.db 使用建置時複製到 build/Hayanagi/book/ 的檔案，放入 Hayanagi/book/。Hayanagi 從工作目錄的 book/ 讀取定跡，而 ShogiBoardQ 以引擎所在的目錄作為工作目錄啟動引擎，因此解壓縮後即可直接使用定跡。
• 下載的 hayanagi 會帶有隔離屬性，因此 README 中說明了 xattr -d com.apple.quarantine Hayanagi/hayanagi。

unzip -l ShogiBoardQ-macos.zip
# 確認 Hayanagi 能回應並讀取定跡（與 ShogiBoardQ 一樣在 Hayanagi/ 中啟動）
(cd build/ShogiBoardQ-macos/Hayanagi && (printf 'usi\nisready\nposition startpos\ngo movetime 300\n'; sleep 1.5; echo quit) | ./hayanagi | grep -E 'book|usiok|readyok|bestmove')

6.1 加入 Apple Developer Program

程式碼簽章與公證需要加入 Apple Developer Program（年費 99 美元）。

6.2 取得簽章用憑證

在 Xcode > Settings > Accounts 中建立以下憑證：

• Developer ID Application — 用於對應用程式本身簽章
• Developer ID Installer — 用於對 DMG / pkg 簽章（選用）

6.3 以 macdeployqt 製作附程式碼簽章的應用程式套件

macdeployqt build/ShogiBoardQ.app \
  -sign-for-notarization="Developer ID Application: Your Name (TEAMID)"

使用這個選項時，macdeployqt 會：

1. 打包 Qt 框架與外掛程式
2. 對所有框架、外掛程式與執行檔進行程式碼簽章
3. 啟用 --options=runtime（強化執行階段）

6.4 手動進行程式碼簽章

不使用 macdeployqt 的簽章選項時：

# 遞迴地對套件內的所有二進位檔簽章
codesign --deep --force --verify --verbose \
  --sign "Developer ID Application: Your Name (TEAMID)" \
  --options runtime \
  build/ShogiBoardQ.app

# 驗證簽章
codesign --verify --deep --strict --verbose=2 build/ShogiBoardQ.app

6.5 公證（Notarization）

使用指令碼時，以 --sign-identity 指定 Developer ID 並加上 --notarize，指令碼會將 DMG 提交公證並裝訂，然後再製作發行用 ZIP（3. 建置）。公證未通過時會顯示提交 ID 並停止。以下是手動進行時的步驟。

# 製作 DMG（使用已簽章的應用程式套件）
# ...（依第 5 節的方法製作 DMG）

# 提交公證
xcrun notarytool submit ShogiBoardQ.dmg \
  --apple-id "your@email.com" \
  --team-id "TEAMID" \
  --password "app-specific-password" \
  --wait

# 裝訂（將公證結果嵌入 DMG）
xcrun stapler staple ShogiBoardQ.dmg

# 驗證裝訂
xcrun stapler validate ShogiBoardQ.dmg

注意：--password 使用的不是 Apple 帳號的密碼，而是 App 專用密碼。

6.6 不經公證發行時

不經公證就發行時，下載的應用程式在第一次啟動時會被 Gatekeeper 阻擋。從 macOS 15 開始，無法再透過在 Finder 中按右鍵點一下 → 「打開」來開啟，因此請向使用者說明以下步驟：

1. 開啟應用程式，顯示警告後將其關閉
2. 開啟「系統設定」→「隱私權與安全性」，按一下「強制打開」，並依指示允許

或者在終端機中解除 Gatekeeper 的隔離屬性（沒有顯示「強制打開」時也使用這個方法）：

xattr -cr /Applications/ShogiBoardQ.app

7.1 建立標籤

版本號只在發行當天改為當天的日期（版本號與發行的運作方式，日文）。製作發行套件之前，先修改 CMakeLists.txt 中的 APP_VERSION 並提交，用該提交製作發行套件，然後在同一提交上加上相同版本號的標籤。標籤不加 v。

git tag -a 2026.10.07 -m "ShogiBoardQ 2026.10.07"
git push origin main 2026.10.07

7.2 以 GitHub CLI 建立 Release

使用 GitHub CLI (gh)：

# 安裝
brew install gh

# 登入（僅第一次）
gh auth login

建立 Release 並上傳附件：

gh release create 2026.10.07 \
  --title "ShogiBoardQ 2026.10.07" \
  --notes-file RELEASE_NOTES.md \
  ShogiBoardQ-macos.zip

同時發行 Windows 的 ZIP 時，加入附件：

gh release create 2026.10.07 \
  --title "ShogiBoardQ 2026.10.07" \
  --notes-file RELEASE_NOTES.md \
  ShogiBoardQ-macos.zip \
  ShogiBoardQ-windows.zip

gh release create 2026.10.07 \
  --title "ShogiBoardQ 2026.10.07" \
  --generate-notes \
  ShogiBoardQ-macos.zip

gh release upload 2026.10.07 ShogiBoardQ-macos.zip

7.3 在網頁介面上建立 Release（替代方法）

1. GitHub 存放庫 → Releases → Draft a new release
2. Choose a tag → 輸入新標籤（例：2026.10.07）並建立
3. 輸入 Release title（例：ShogiBoardQ 2026.10.07）
4. 在 Description 中填寫發行說明
5. 將 ShogiBoardQ-macos.zip 拖放到 Attach binaries
6. 按一下 Publish release

7.4 發行說明的寫法（範本）

## ShogiBoardQ 2026.10.07

### 下載

| OS | 檔案 |
|---|---|
| macOS | `ShogiBoardQ-macos.zip` |
| Windows (64-bit) | `ShogiBoardQ-windows.zip` |

### 在 macOS 上啟動

1. 解壓縮 ZIP，打開 `ShogiBoardQ.dmg`
2. 將 ShogiBoardQ.app 拖放到 Applications 資料夾
3. 從 Applications 啟動

> 由於未經 Apple 公證，第一次啟動時會顯示警告而無法開啟。
> 在「系統設定」→「隱私權與安全性」中按一下「強制打開」即可啟動。

### 變更內容

- ...

找不到 Qt

CMake Error: Could not find a package configuration file provided by "Qt6"

明確指定 Qt 的安裝路徑：

cmake -B build -S . -DCMAKE_BUILD_TYPE=Release \
  -DCMAKE_PREFIX_PATH="$HOME/Qt/6.x.x/macos"

找不到 macdeployqt

# 確認 Qt 的安裝路徑
which macdeployqt

# 找不到時，加入 PATH
export PATH="$HOME/Qt/6.x.x/macos/bin:$PATH"

# 使用 Homebrew 時
export PATH="$(brew --prefix qt@6)/bin:$PATH"

macdeployqt 沒有打包 Qt Charts

macdeployqt 有時無法自動偵測到 Qt Charts。這時需要手動複製：

# 確認是否遺漏打包
otool -L build/ShogiBoardQ.app/Contents/MacOS/ShogiBoardQ | grep Charts

# 手動複製（需要時）
cp -R "$HOME/Qt/6.x.x/macos/lib/QtCharts.framework" \
  build/ShogiBoardQ.app/Contents/Frameworks/

# 以 install_name_tool 修正參照路徑
install_name_tool -change \
  @rpath/QtCharts.framework/Versions/A/QtCharts \
  @executable_path/../Frameworks/QtCharts.framework/Versions/A/QtCharts \
  build/ShogiBoardQ.app/Contents/MacOS/ShogiBoardQ

第一次啟動時無法開啟（未經公證時）

向使用者說明以下任一方法：

• 在「系統設定」→「隱私權與安全性」中按一下「強制打開」（僅第一次。從 macOS 15 開始，在 Finder 中按右鍵點一下 → 「打開」無法開啟）
• 在終端機中執行 xattr -cr /Applications/ShogiBoardQ.app

無法載入翻譯

確認套件內存在 .qm 檔：

find build/ShogiBoardQ.app -name "*.qm"

Contents/MacOS/ 中沒有 .qm 檔時，手動複製：

cp build/ShogiBoardQ_{ja_JP,en,zh_CN,zh_TW}.qm build/ShogiBoardQ.app/Contents/MacOS/

製作通用二進位檔（Intel + Apple 晶片）

製作同時支援兩種架構的二進位檔時：

cmake -B build -S . -DCMAKE_BUILD_TYPE=Release \
  -DCMAKE_OSX_ARCHITECTURES="arm64;x86_64"

cmake --build build --config Release

注意：Qt 本身也必須安裝通用二進位檔版本。