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