Linux 建置與發行

2.1 Arch Linux 與 Docker（製作發行套件時）

用於發行的發行套件在容器中建置，因此本機只需要 Docker、Git 和 Python 3（Qt 等建置所需的軟體在容器中）。請將使用者加入 docker 群組並重新登入。

sudo usermod -aG docker $USER

docker 群組的使用者可以透過 docker 進行相當於 root 的操作。

直接在 Arch Linux 上建置與開發時，安裝建置工具和 Arch 的 Qt 套件。fcitx5-qt 用於將日文輸入（fcitx5）的輸入法外掛程式放進 AppImage；未安裝時不會隨附該外掛程式。

sudo pacman -S --needed base-devel cmake ninja git curl file python fuse2 imagemagick \
  qt6-base qt6-charts qt6-multimedia qt6-svg qt6-tools fcitx5-qt

2.2 其他發行版（僅建置應用程式）

在 Ubuntu、Debian 或 Fedora 上也可以建置與開發應用程式。需要 Qt 6.7 以上，若發行版提供的 Qt 較舊，請使用 Qt Online Installer 安裝 Qt。

Ubuntu / Debian：

sudo apt install build-essential cmake ninja-build git \
  qt6-base-dev qt6-charts-dev qt6-multimedia-dev qt6-tools-dev qt6-tools-dev-tools \
  qt6-l10n-tools libqt6sql6-sqlite libgl1-mesa-dev

Fedora：

sudo dnf install gcc-c++ cmake ninja-build git \
  qt6-qtbase-devel qt6-qtcharts-devel qt6-qtmultimedia-devel qt6-qttools-devel \
  qt6-linguist mesa-libGL-devel

使用 Qt Online Installer 安裝的 Qt 時，在設定 CMake 時指定其位置（範例為 Qt 6.11.2）。

cmake -B build -S . -G Ninja -DCMAKE_BUILD_TYPE=Release \
  -DCMAKE_PREFIX_PATH="$HOME/Qt/6.11.2/gcc_64"

2.3 確認安裝

cmake --version
g++ --version
qmake6 --version

5.1 執行指令碼

用於發行的發行套件在較舊的 Arch Linux（2024 年 7 月 15 日的 Arch Linux Archive；glibc 2.39、Qt 6.7.2）容器中製作。

製作用於發行的發行套件時，請先把版本號改為發行當天的日期並提交（第 6 節）。

./scripts/build-linux-container.sh

• 第一次執行時會建立建置環境映像（scripts/linux-container/Dockerfile，約 3GB）。從 Arch Linux Archive 下載較慢，需要數十分鐘。
• 在容器中以自己的使用者執行 scripts/build-linux.sh。建置目錄與平時的 build 分開，使用 build-container，輸出放在儲存庫根目錄。
• 為當時的套件簽章的金鑰中，有些後來已過期。映像中以官方金鑰圈驗證簽章，但不要求金鑰目前受信任。
• 隨附的 OpenSSL、libcurl 以及 libcurl 使用的網路程式庫（nghttp2、nghttp3、ngtcp2、libssh2）因當時的版本缺少後來的修正，會替換為新版本。目前的 Arch 套件先以 SHA-256（scripts/linux-container/packages.sha256）和簽章驗證後再安裝；目前套件會用到新版 glibc 函式的 curl，則在映像中以同一版本的 Arch PKGBUILD 重新建置。
• 升級版本時，在本機下載新的套件及其 .sig，以 pacman-key --verify 驗證簽章，然後改寫 packages.sha256。curl 則在 Dockerfile 的 CURL_PKGVER、CURL_PKGBUILD_SHA256 中寫入 Arch 標籤處 PKGBUILD 的 SHA-256（標籤的簽章以 curl-signing-key.asc 中的金鑰驗證）。請先確認新套件需要的 glibc 版本（objdump -T 中 GLIBC_ 的最大值）不超過 2.38，超過的套件在映像中重新建置。修改 scripts/linux-container/ 後，build-linux-container.sh 會重新建立映像。

也可以直接在 Arch Linux 上製作。這樣製作的 AppImage 需要本機的 glibc 版本以上（2026 年 10 月時為 2.43）。

./scripts/build-linux.sh

兩個指令碼都可以使用以下選項：

build-linux.sh 依序執行以下處理（在容器中，於容器內執行同樣的處理）：

1. 檢查所需工具（cmake、python3；建議使用 ninja）
2. 設定 CMake 並以 Release 方式建置（ShogiBoardQ 與 Hayanagi）
3. 檢查執行檔、翻譯檔，以及 3〜13 手詰的題集（每種手數各 1 個檔案）
4. 下載 linuxdeploy、其 Qt 外掛程式和 appimagetool（僅第一次；儲存在建置目錄中）。執行前與 build-linux.sh 中記錄的 SHA-256 核對。它們都是上游會替換的 continuous 版本，被替換後核對不一致就會停止；此時先確認上游發行的 digest 和變更，再更新這些值
5. 建立 AppDir 並產生 AppImage（執行所需的檔案，以及 Qt 與隨附程式庫的授權文件）
6. 製作包含 AppImage、題集和 Hayanagi 的 ZIP

輸出為儲存庫根目錄下的 ShogiBoardQ-linux-x86_64.AppImage 和 ShogiBoardQ-linux.zip。工作目錄為建置目錄下的 AppDir 和 ShogiBoardQ-linux/。

5.2 AppImage 的內容

AppImage 中只收錄啟動與執行應用程式所需的檔案以及授權文件。

ShogiBoardQ-linux-x86_64.AppImage
└── （解壓縮後）
    ├── AppRun                          ← 只使用隨附的 Qt 和隨附的 OpenSSL 設定啟動
    ├── shogiboardq.desktop
    ├── shogiboardq.png
    └── usr/
        ├── bin/
        │   ├── ShogiBoardQ             ← 執行檔
        │   ├── qt.conf                 ← Qt 外掛程式的位置
        │   └── ShogiBoardQ_{ja_JP,en,zh_CN,zh_TW}.qm   ← 應用程式翻譯（4 種語言）
        ├── lib/                        ← Qt 及其相依程式庫
        ├── plugins/
        │   ├── platforms/libqxcb.so            ← X11
        │   ├── imageformats/libqsvg.so, libqjpeg.so, libqico.so
        │   ├── iconengines/libqsvgicon.so
        │   ├── platforminputcontexts/          ← 日文輸入（compose、fcitx5、ibus）
        │   ├── platformthemes/libqxdgdesktopportal.so
        │   ├── sqldrivers/libqsqlite.so        ← 詰棋作答紀錄與分析快取
        │   └── tls/libqopensslbackend.so       ← 網路對局的 TLS 連線（OpenSSL）
        └── share/
            ├── applications/, icons/
            ├── ShogiBoardQ/openssl.cnf ← 隨附的 OpenSSL 讀取的設定（為空，不讀取系統的設定）
            └── licenses/ShogiBoardQ/
                ├── NOTICE*.md, SOURCE_CODE*.md, GPL-3.0.txt, LGPL-3.0.txt
                ├── QT-NOTICES.md, qt/          ← 隨附的 Qt 模組的文件
                ├── QT-SOURCE.json, BUILD.json  ← Qt 的來源與建置時版本
                └── THIRD-PARTY-NOTICES.md, third-party/   ← Qt 以外隨附程式庫的文件

• 不收錄題集、一般對局用的 Hayanagi、說明文件和題集的驗證紀錄（validation_*.json）。應用程式不會從 AppImage 內部讀取它們，使用者也無法在其中選擇檔案，因此只作為 ZIP 中 AppImage 之外的檔案發行。練習詰棋用的 Hayanagi 已內建於應用程式中。
• 刪除 linuxdeploy 放入的 Qt 標準翻譯（usr/translations/）。標準對話方塊的日文與中文翻譯已內建於執行檔，應用程式的翻譯從 usr/bin/ 讀取。
• 不收錄用不到的外掛程式：OpenGL 整合（xcbglintegrations）和 GIF 圖片。沒有使用 OpenGL 的介面元件。
• tls 外掛程式只收錄 OpenSSL 後端（libqopensslbackend.so），用於 CSA 網路對局的「TLS（加密）」連線。libssl 和 libcrypto 作為其相依程式庫一併收錄。應用程式不進行 HTTPS 等通訊。
• Qt 的授權文件只收錄隨附的 Qt 模組（qtbase、qtcharts、qtmultimedia、qtsvg、qttranslations、qtwayland）及其參照的文件（scripts/qt_licenses.py）。不收錄 WebEngine 等未發行模組的文件。
• 對於 Qt 以外的隨附程式庫（glib、PulseAudio、OpenSSL、fcitx5-qt 等約 50 個套件），scripts/bundled_licenses.py 透過 pacman 查找所屬套件，將授權原文放入 third-party/，並在 THIRD-PARTY-NOTICES.md 中列出版本、授權和原始碼取得位置。兩者分別顯示在「版本資訊」的「Qt 中的第三方授權」和「隨附程式庫的授權」中。

5.3 ZIP 的內容

ZIP 中放入以下檔案。解壓縮 ZIP 後即可選擇題集和 Hayanagi。

ShogiBoardQ-linux.zip
└── ShogiBoardQ-linux/
    ├── ShogiBoardQ-linux-x86_64.AppImage
    ├── README.md
    ├── LICENSE
    ├── Hayanagi/
    │   ├── hayanagi
    │   ├── book/hayanagi_book.db   ← Hayanagi 的定跡
    │   └── README.md
    └── data/tsumeshogi/
        ├── tsume_{3,5,7,9,11,13}ply_1000_20261001.txt   ← 6 個檔案（各 1,000 題）
        └── README.md

• 題集原樣複製。其雜湊值與應用程式內建的稽核紀錄一致，因此讀取時可以沿用已驗證的手數和手順。
• data/tsumeshogi/ 中每種手數只放 1 個題集檔案（儲存庫只追蹤目前的 20261001 版）。同一手數有多個檔案時，指令碼會報錯並停止。
• Hayanagi 經 strip 後放入。定跡檔案 hayanagi_book.db 由建置複製到 build/Hayanagi/book/，放入 Hayanagi/book/；Hayanagi 從執行檔旁邊的 book/ 讀取定跡。ZIP 中 AppImage 之外不放 docs/、validation_*.json 和 licenses/，授權文件位於 AppImage 內。

使用者依以下方式啟動。在練習詰棋的「開啟題集…」中選擇 data/tsumeshogi/ 中的題集；登錄一般對局用的引擎時選擇 Hayanagi/hayanagi。

unzip ShogiBoardQ-linux.zip
cd ShogiBoardQ-linux
chmod +x ShogiBoardQ-linux-x86_64.AppImage Hayanagi/hayanagi
./ShogiBoardQ-linux-x86_64.AppImage

5.4 執行確認

# 啟動
./ShogiBoardQ-linux-x86_64.AppImage

# 解壓縮並確認內容（不含 Hayanagi 和 Qt 標準翻譯）
./ShogiBoardQ-linux-x86_64.AppImage --appimage-extract
ls squashfs-root/usr/bin/ squashfs-root/usr/plugins/*/
ls squashfs-root/usr/share/licenses/ShogiBoardQ/THIRD-PARTY-NOTICES.md
test ! -e squashfs-root/usr/bin/hayanagi && test ! -e squashfs-root/usr/translations && echo OK

# 所需的 glibc 版本
find squashfs-root/usr -type f \( -name '*.so*' -o -name ShogiBoardQ \) -exec objdump -T {} + 2>/dev/null \
  | grep -o 'GLIBC_[0-9.]*' | sort -uV | tail -1

# ZIP 中的 Hayanagi 能作為 USI 引擎回應
unzip -o -q ShogiBoardQ-linux.zip -d /tmp/zipcheck
printf 'usi\nisready\nquit\n' | /tmp/zipcheck/ShogiBoardQ-linux/Hayanagi/hayanagi

# ZIP 由預期的 12 個檔案組成且沒有損毀
python3 -m zipfile -l ShogiBoardQ-linux.zip
python3 -m zipfile -t ShogiBoardQ-linux.zip

在容器中建置時，所需的 glibc 版本應為 GLIBC_2.38 以下。AppImage 使用系統中的 OpenGL（libEGL、libOpenGL）、fontconfig、HarfBuzz 和 wayland-client（一般桌面環境中已安裝）。

請在 LD_LIBRARY_PATH 不包含 Qt 的 lib 目錄的環境中確認，否則會使用系統中的程式庫，無法發現遺漏的檔案。如有可能，也請在 Ubuntu 24.04 等其他環境中確認日文、英文、中文的切換、SVG 棋子、棋子音效、詰棋紀錄的儲存，以及「版本資訊」中的授權清單。

找不到 Qt

Could not find a package configuration file provided by "Qt6"

確認已安裝 Qt 6.7 以上和所需模組。使用 Qt Online Installer 的 Qt 時，以 -DCMAKE_PREFIX_PATH 指定。更換 Qt 或 CMake 產生器後，請在新的 build 目錄中重新開始。

缺少 Hayanagi 的原始碼

在儲存庫根目錄執行 git submodule update --init --recursive。

因存在多個題集而停止

==> ERROR: 5手詰の問題集が複数あります: data/tsumeshogi/tsume_5ply_1000_20260926.txt data/tsumeshogi/tsume_5ply_1000_20261001.txt

data/tsumeshogi/ 中殘留了舊版題集（訊息表示同一手數找到了多個題集）。請刪除不用的版本，使每種手數只剩 1 個檔案。

Qt 文件的驗證失敗

Qt license preparation failed: Qt version mismatch: build=6.7.2, source=6.11.2
Qt license preparation failed: Qt notices are missing. See docs/dev/qt-licensing.md; set SHOGIBOARDQ_QT_LICENSE_DIR to prepared matching notices.

請準備與建置所用 Qt 同版本的文件（第 4 節）：容器中為 Qt 6.7.2，直接在 Arch Linux 上建置時為 pacman -Q qt6-base 所示的版本。不要忽略失敗而繼續發行。

收集隨附程式庫的文件時停止

Bundled library notices failed: Bundled library notices need pacman (Arch Linux); other distributions are not supported yet
Bundled library notices failed: Cannot find the system file of lib/libQt6Core.so.6
Bundled library notices failed: No license text for bundled package fcitx5-qt (GPL)

• 請在 Arch Linux 上使用 Arch 的 Qt 套件製作發行套件。若 AppImage 中含有不屬於 pacman 套件的程式庫（例如透過 Qt Online Installer 安裝的 Qt），就無法確定其所屬套件，指令碼會停止。
• No license text for … 表示有套件找不到授權原文。較舊的套件庫中，授權欄位可能不是 SPDX 運算式，請在 scripts/bundled_licenses.py 的 LICENSE_OVERRIDES 中加入上游的寫法。套件中沒有的文件（例如附有實際著作權聲明的原文）放在 scripts/license-texts/<套件名稱>/ 中。

無法使用 docker

permission denied while trying to connect to the docker API at unix:///var/run/docker.sock

將使用者加入 docker 群組並重新登入（sudo usermod -aG docker $USER），或指定環境變數 DOCKER="sudo docker"。

linuxdeploy 無法啟動

dlopen(): error loading libfuse.so.2

安裝 fuse2，或以 APPIMAGE_EXTRACT_AND_RUN=1 ./scripts/build-linux.sh 執行。

AppImage 無法啟動（FUSE）

AppImages require FUSE to run.

安裝 FUSE 2，或加上 --appimage-extract-and-run 啟動。

./ShogiBoardQ-linux-x86_64.AppImage --appimage-extract-and-run

glibc 版本不足

version `GLIBC_2.38' not found

執行系統的 glibc 比建置環境舊。用於發行的發行套件請在容器中建置（5.1）。仍然不足時，請在 glibc 較新的發行版上使用（參閱前提條件中關於 glibc 的說明）。

找不到系統程式庫

error while loading shared libraries: libOpenGL.so.0: cannot open shared object file: No such file or directory

系統中缺少 AppImage 不隨附的程式庫（OpenGL、fontconfig、HarfBuzz、wayland-client）。Ubuntu / Debian 的範例：

sudo apt install libegl1 libopengl0 libfontconfig1 libharfbuzz0b libwayland-client0

無法載入 xcb 平台外掛程式

qt.qpa.plugin: Could not load the Qt platform plugin "xcb"

缺少 X11 相關的程式庫。以下依序為 Ubuntu / Debian、Fedora、Arch Linux 的範例：

sudo apt install libxcb-cursor0 libxcb-xinerama0
sudo dnf install xcb-util-cursor xcb-util-wm xcb-util-keysyms
sudo pacman -S xcb-util-cursor xcb-util-wm xcb-util-keysyms

無法輸入日文

AppImage 只隨附 X11 平台外掛程式，因此在 Wayland 桌面上也會透過 XWayland 執行。未設定環境變數 QT_IM_MODULE 時，不會選用日文輸入法外掛程式。使用 fcitx5 時請加上 QT_IM_MODULE=fcitx，使用 IBus 時請加上 QT_IM_MODULE=ibus 啟動。

QT_IM_MODULE=fcitx ./ShogiBoardQ-linux-x86_64.AppImage

無法載入翻譯

確認 .qm 檔案位於執行檔所在的 usr/bin/ 中。

./ShogiBoardQ-linux-x86_64.AppImage --appimage-extract
ls squashfs-root/usr/bin/*.qm