Windows 建置與發行

2.1 安裝 Visual Studio

安裝 Visual Studio，並選擇以下工作負載：

• 使用 C++ 的桌面開發

這樣會一併安裝 MSVC 編譯器、CMake 與 Ninja。

Community 版可免費用於個人開發與開放原始碼開發。

2.2 安裝 Qt 6

# 加入使用者環境變數（Qt 的安裝路徑請依實際環境修改）
# 例：C:\Qt\6.8.3\msvc2022_64
[Environment]::SetEnvironmentVariable("Qt6_DIR", "C:\Qt\6.8.3\msvc2022_64\lib\cmake\Qt6", "User")
[Environment]::SetEnvironmentVariable("PATH", "C:\Qt\6.8.3\msvc2022_64\bin;$env:PATH", "User")

pip install aqtinstall
aqt install-qt windows desktop 6.8.3 win64_msvc2022_64 -m qtcharts

2.3 安裝 Ninja（建議）

可以使用 Visual Studio 內附的 Ninja，也可以另外安裝：

winget install Ninja-build.Ninja

2.4 確認安裝

在 Developer PowerShell for VS 2022（從開始功能表啟動）中確認：

cmake --version       # 3.16 以上
cl                    # MSVC 編譯器
ninja --version       # Ninja
windeployqt --version # Qt 部署工具

建置指令碼（建議）

使用 scripts/build-windows.ps1，可以一次完成從 Release 建置到製作 ZIP 的所有步驟。

重要：請在 Developer PowerShell for VS 2022 中執行（需要 MSVC 的環境變數）。

# 一般建置 + 製作 ZIP
.\scripts\build-windows.ps1

# 清除後建置，不製作 ZIP
.\scripts\build-windows.ps1 -Clean -SkipZip

# 依版本建置到各自的目錄（發行時）
.\scripts\build-windows.ps1 -BuildDir build\msvc-release-2026.10.07 `
    -DeployDir build\releases\2026.10.07-windows\deploy `
    -ZipPath build\releases\2026.10.07-windows\ShogiBoardQ-windows.zip

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

1. 確認所需工具（cmake、ninja、cl、windeployqt、MSVC 執行階段 DLL 的位置）
2. CMake 設定 + 建置（ShogiBoardQ、shogiboardq-cli、Hayanagi）
3. 確認建置產物（.exe、.qm 翻譯檔、hayanagi.exe 與定跡檔案、每種手數各 1 個檔案的題集）
4. 建立 deploy 目錄 + 放置題集、Hayanagi（含定跡檔案）與 LICENSE + 以 windeployqt 部署 DLL + 加入 qoffscreen.dll + 複製 MSVC 執行階段 DLL + 驗證
5. 製作 ZIP 檔案

如果沒有把 Qt 加入 PATH，請在執行前指定 Qt 的位置（例：Qt 6.11.2）：

$env:PATH = "C:\Qt\6.11.2\msvc2022_64\bin;C:\Qt\Tools\Ninja;$env:PATH"
$env:CMAKE_PREFIX_PATH = "C:\Qt\6.11.2\msvc2022_64"

出現執行原則錯誤時：

Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser

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

3.1 Release 建置

在 Developer PowerShell for VS 2022 中執行：

cd C:\path\to\ShogiBoardQ

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

# 建置
ninja -C build

沒有 Ninja 時（使用 Visual Studio 產生器）：

# 設定
cmake -B build -S .

# Release 建置
cmake --build build --config Release

3.2 確認建置產物

# 確認已產生 exe
# Ninja：
dir build\ShogiBoardQ.exe

# Visual Studio 產生器：
dir build\Release\ShogiBoardQ.exe

# 確認翻譯檔
dir build\*.qm           # Ninja
dir build\Release\*.qm   # VS 產生器

3.3 執行確認

# 啟動建置好的應用程式（需在 PATH 中包含 Qt DLL 的環境下）
.\build\ShogiBoardQ.exe

4.1 建立 deploy 目錄

將 exe、翻譯檔、詰將棋題集、Hayanagi 及其定跡檔案與 LICENSE 複製到發行用目錄：

mkdir deploy, deploy\Hayanagi\book, deploy\data\tsumeshogi
copy build\ShogiBoardQ.exe deploy\
copy build\shogiboardq-cli.exe deploy\
copy build\*.qm deploy\
copy build\Hayanagi\hayanagi.exe deploy\Hayanagi\
copy build\Hayanagi\book\hayanagi_book.db deploy\Hayanagi\book\
copy data\tsumeshogi\tsume_*ply_*.txt deploy\data\tsumeshogi\
copy LICENSE deploy\

詰將棋題集收錄 3、5、7、9、11、13 手詰各 1 個檔案，共 6 個檔案（data/tsumeshogi/ 中不能殘留相同手數的舊版本；有多個時指令碼會停止）。不收錄 README（根目錄、Hayanagi/、data/tsumeshogi/）。Hayanagi 的定跡檔案 hayanagi_book.db 使用建置時複製到 build/Hayanagi/book/ 的檔案，放入 Hayanagi/book/。Hayanagi 從工作目錄的 book/ 讀取定跡，而 ShogiBoardQ 以引擎所在的目錄作為工作目錄啟動引擎，因此解壓縮 ZIP 後即可直接使用定跡。請不要整個複製原始碼樹或建置資料夾，並在發行前確認 ZIP 中不包含 Hayanagi/source/ 與 licenses/。一般建置產生的 build/licenses/ 也不複製到 Windows 的 ZIP 中。

4.2 以 windeployqt 部署 Qt DLL

windeployqt --release --no-translations --no-system-d3d-compiler --no-opengl-sw --no-compiler-runtime deploy\ShogiBoardQ.exe deploy\shogiboardq-cli.exe

# shogiboardq-cli 使用 offscreen 平台繪製棋盤。windeployqt 不會複製它，因此需要手動加入
copy C:\Qt\6.11.2\msvc2022_64\plugins\platforms\qoffscreen.dll deploy\platforms\

windeployqt 自動執行的處理：

1. 複製相依的 Qt DLL（Qt6Core、Qt6Gui、Qt6Widgets、Qt6Charts、Qt6Network、Qt6Multimedia 等）
2. 複製 Qt 外掛程式（platforms/qwindows.dll、imageformats/ 等）

4.2.1 複製 MSVC 執行階段 DLL

為了在沒有安裝 Visual C++ 可轉散發套件的電腦上也能啟動，將 MSVC 執行階段 DLL（vcruntime140.dll、msvcp140.dll 等）放在與 exe 相同的目錄中。在 Developer PowerShell for VS 中，環境變數 VCToolsRedistDir 指向執行階段所在的位置：

copy "$env:VCToolsRedistDir\x64\Microsoft.VC*.CRT\*.dll" deploy\

Hayanagi\hayanagi.exe 只在自身所在的目錄中尋找 DLL，因此只把它載入的 3 個 DLL（vcruntime140.dll、vcruntime140_1.dll、msvcp140.dll）也放到 Hayanagi\ 中：

foreach ($dll in "vcruntime140.dll", "vcruntime140_1.dll", "msvcp140.dll") {
    copy "$env:VCToolsRedistDir\x64\Microsoft.VC*.CRT\$dll" deploy\Hayanagi\
}

windeployqt 預設附帶的不是 DLL，而是 vc_redist.x64.exe（約 18 MB）。但除非使用者手動執行它，否則執行階段不會被安裝，因此直接附帶 DLL。

4.3 部署後的確認

# 確認目錄結構
tree /F deploy

# 確認必要的 DLL
dir deploy\Qt6Core.dll
dir deploy\Qt6Gui.dll
dir deploy\Qt6Widgets.dll
dir deploy\Qt6Charts.dll
dir deploy\Qt6Network.dll

# 確認 MSVC 執行階段 DLL
dir deploy\vcruntime140.dll
dir deploy\vcruntime140_1.dll
dir deploy\msvcp140.dll

# 確認 platforms 外掛程式
dir deploy\platforms\qwindows.dll
dir deploy\platforms\qoffscreen.dll

# SQLite 驅動程式（用於儲存詰將棋的解題紀錄）
dir deploy\sqldrivers\qsqlite.dll

# Hayanagi、定跡檔案與題集（6 個檔案）
dir deploy\Hayanagi
dir deploy\Hayanagi\book\hayanagi_book.db
dir deploy\data\tsumeshogi

部署後的目錄結構：

deploy/
├── ShogiBoardQ.exe                ← 執行檔
├── shogiboardq-cli.exe            ← CLI（由 MCP 伺服器呼叫）
├── LICENSE                        ← 授權
├── ShogiBoardQ_ja_JP.qm           ← 日文翻譯
├── ShogiBoardQ_en.qm              ← 英文翻譯
├── ShogiBoardQ_zh_CN.qm           ← 簡體中文翻譯
├── ShogiBoardQ_zh_TW.qm           ← 繁體中文翻譯
├── Qt6Core.dll                    ← Qt Core
├── Qt6Gui.dll                     ← Qt GUI
├── Qt6Widgets.dll                 ← Qt Widgets
├── Qt6Charts.dll                  ← Qt Charts
├── Qt6Network.dll                 ← Qt Network
├── Qt6Multimedia.dll              ← Qt Multimedia（棋子音效）
├── Qt6OpenGL.dll                  ← Qt OpenGL（Charts 相依）
├── Qt6OpenGLWidgets.dll           ← Qt OpenGL Widgets
├── Qt6Svg.dll                     ← Qt SVG（圖示用）
├── Qt6Sql.dll                     ← Qt SQL（解題紀錄）
├── avcodec-61.dll 等              ← FFmpeg（播放棋子音效）
├── vcruntime140.dll               ← MSVC 執行階段
├── vcruntime140_1.dll
├── msvcp140.dll
├── ...                            ← 其他 MSVC 執行階段 DLL（concrt140.dll 等）
├── Hayanagi/
│   ├── hayanagi.exe               ← 用於一般對局的 USI 引擎
│   ├── vcruntime140.dll           ← Hayanagi 用 MSVC 執行階段（僅這 3 個）
│   ├── vcruntime140_1.dll
│   ├── msvcp140.dll
│   └── book/hayanagi_book.db      ← Hayanagi 的定跡
├── data/tsumeshogi/
│   ├── tsume_3ply_1000_*.txt      ← 詰將棋題集（3～13 手詰，各 1,000 題）
│   ├── ...
│   └── tsume_13ply_1000_*.txt
├── platforms/
│   ├── qwindows.dll               ← Windows 平台外掛程式
│   └── qoffscreen.dll             ← shogiboardq-cli 繪製棋盤用
├── sqldrivers/
│   ├── qsqlite.dll                ← SQLite（詰將棋的解題紀錄）
│   └── ...
├── multimedia/
│   ├── ffmpegmediaplugin.dll      ← 播放棋子音效
│   └── windowsmediaplugin.dll
├── imageformats/
│   ├── qsvg.dll                   ← SVG 支援
│   ├── qico.dll                   ← ICO 支援
│   └── ...
├── styles/
│   └── qmodernwindowsstyle.dll    ← Windows 樣式
├── tls/
│   └── qschannelbackend.dll       ← TLS（CSA 網路通訊用）
└── networkinformation/
    └── qnetworklistmanager.dll    ← 網路資訊

由於附帶了 MSVC 執行階段 DLL，使用者的電腦上不需要安裝 Visual C++ 可轉散發套件。

4.4 執行測試

直接從 deploy 資料夾啟動進行測試：

.\deploy\ShogiBoardQ.exe

# CLI（版本與產生棋盤圖片）
.\deploy\shogiboardq-cli.exe version
.\deploy\shogiboardq-cli.exe render-board --sfen startpos --output board.png --overwrite

# Hayanagi（與 ShogiBoardQ 一樣在 Hayanagi 的資料夾中啟動，應回傳 id name Hayanagi … 與
# info string book loaded）
cmd /c "cd deploy\Hayanagi && (echo usi& echo isready& echo quit) | .\hayanagi.exe"

重要：請在 PATH 中不包含 Qt 的 bin 目錄的環境下測試。如果 PATH 中包含 Qt，就會使用系統中的 DLL 而不是 deploy 資料夾中的 DLL，因而無法發現部署遺漏。

4.5 製作 ZIP 檔案

Compress-Archive -Path deploy\* -DestinationPath ShogiBoardQ-windows.zip

5.1 建立標籤

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

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

5.2 以 GitHub CLI 建立 Release

使用 GitHub CLI (gh)：

# 安裝
winget install GitHub.cli

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

建立 Release 並上傳附件：

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

同時發行 macOS 的 DMG 時，加入附件：

gh release create 2026.10.07 `
  --title "ShogiBoardQ 2026.10.07" `
  --notes-file RELEASE_NOTES.md `
  ShogiBoardQ-windows.zip `
  ShogiBoardQ.dmg

gh release create 2026.10.07 `
  --title "ShogiBoardQ 2026.10.07" `
  --generate-notes `
  ShogiBoardQ-windows.zip

5.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-windows.zip 拖放到 Attach binaries
6. 按一下 Publish release

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

## ShogiBoardQ 2026.10.07

### 下載

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

### 在 Windows 上啟動

1. 解壓縮 ZIP 檔案
2. 按兩下 `ShogiBoardQ.exe`

> 第一次啟動時如果顯示「Windows 已保護您的電腦」，
> 請按一下「其他資訊」→「仍要執行」。

### 變更內容

- ...

6.1 取得程式碼簽章憑證

程式碼簽章建議使用 EV（Extended Validation）程式碼簽章憑證。對個人開發者來說，OV（Organization Validation）憑證也是一種選擇。

主要供應商：

• SignPath Foundation（適用於開放原始碼專案，免費）
• DigiCert
• Sectigo
• GlobalSign

6.2 以 signtool 簽章

# 使用 Windows SDK 中的 signtool
signtool sign /fd SHA256 /tr http://timestamp.digicert.com /td SHA256 `
  /f "certificate.pfx" /p "password" `
  deploy\ShogiBoardQ.exe

6.3 不簽章發行時

向使用者說明以下步驟：

1. 下載後，以滑鼠右鍵按一下 ZIP → 內容 → 勾選「解除封鎖」→ 確定
2. 解壓縮後執行 ShogiBoardQ.exe
3. 如果顯示 SmartScreen 警告，按一下「其他資訊」→「仍要執行」

找不到 Qt

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

明確指定 Qt 的安裝路徑：

cmake -B build -S . -G Ninja -DCMAKE_BUILD_TYPE=Release `
  -DCMAKE_PREFIX_PATH="C:\Qt\6.8.3\msvc2022_64"

找不到 cl.exe

沒有使用 Developer PowerShell for VS 2022 時：

# 手動設定 MSVC 環境
# Visual Studio 2022 的情況
& "C:\Program Files\Microsoft Visual Studio\2022\Community\VC\Auxiliary\Build\vcvarsall.bat" x64

或者從開始功能表啟動 Developer PowerShell for VS 2022。

找不到 windeployqt

# 確認 Qt 的安裝路徑，並加入 PATH
$env:PATH = "C:\Qt\6.8.3\msvc2022_64\bin;$env:PATH"

# 確認
windeployqt --version

應用程式無法啟動（DLL 錯誤）

「找不到 Qt6Core.dll」等錯誤

1. 重新執行 windeployqt

2. 確認所有必要的 DLL 都在 deploy 目錄中：

   dir deploy\Qt6Core.dll
   dir deploy\Qt6Gui.dll
   dir deploy\Qt6Widgets.dll
   dir deploy\Qt6Charts.dll
   dir deploy\Qt6Network.dll
   dir deploy\platforms\qwindows.dll

3. 缺少 MSVC 執行階段時：

   • 安裝 Visual C++ 可轉散發套件

Qt Charts 的 DLL 沒有被部署

windeployqt 無法偵測到 Qt Charts 時，手動複製：

copy "C:\Qt\6.8.3\msvc2022_64\bin\Qt6Charts.dll" deploy\
copy "C:\Qt\6.8.3\msvc2022_64\bin\Qt6OpenGL.dll" deploy\
copy "C:\Qt\6.8.3\msvc2022_64\bin\Qt6OpenGLWidgets.dll" deploy\

無法載入翻譯

確認 .qm 檔與 exe 位於同一目錄：

dir deploy\*.qm

沒有時，從建置目錄手動複製：

copy build\ShogiBoardQ_ja_JP.qm deploy\
copy build\ShogiBoardQ_en.qm deploy\
copy build\ShogiBoardQ_zh_CN.qm deploy\
copy build\ShogiBoardQ_zh_TW.qm deploy\

執行原則錯誤（PowerShell 指令碼）

因為這個系統上已停用指令碼執行，所以無法載入 ……

Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser

SmartScreen 警告（未簽章）

向使用者說明：

1. 以滑鼠右鍵按一下 ZIP → 內容 → 勾選解除封鎖 → 確定
2. 先解壓縮 ZIP 再執行
3. 「Windows 已保護您的電腦」→ 其他資訊 → 仍要執行

下載次數增加後，SmartScreen 的信譽會提高，警告會變得不容易出現。