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 のパッケージを scripts/linux-container/packages.sha256 の SHA-256 と署名で確かめて入れ、新しい glibc の関数を使う curl は同じ版の Arch の PKGBUILD でイメージの中で作り直す。
• 版を上げるときは、手元で新しいパッケージと .sig を取得して pacman-key --verify で署名を確かめ、packages.sha256 を書き換える。curl は Arch のタグの PKGBUILD の SHA-256 を Dockerfile の CURL_PKGVER・CURL_PKGBUILD_SHA256 に書く（タグの署名は 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 の外部ファイルとしてだけ配布する。詰将棋対局の Hayanagi はアプリ本体に組み込まれている。
• linuxdeploy が配置する Qt 標準の翻訳（usr/translations/）は使わないので削除する。標準ダイアログの日本語・中国語訳は実行ファイルに内蔵し、アプリの翻訳は usr/bin/ から読む。
• 使わないプラグイン（OpenGL 連携の xcbglintegrations、GIF 画像）は入れない。OpenGL を使う画面部品がないため。
• tls は、CSA 通信対局の「TLS（暗号化）」接続に使う OpenSSL バックエンド（libqopensslbackend.so）だけを入れる。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 には次のファイルを配置する。問題集と Hayanagi は、ZIP を展開すればすぐファイル選択できる。

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ファイルだけ置く（git で追跡しているのは現行の20261001版）。同じ手数のファイルが複数あると、スクリプトはエラーで止まる。
• Hayanagi は strip してから配置する。定跡 hayanagi_book.db はビルドで build/Hayanagi/book/ にコピーされたものを Hayanagi/book/ に置く。Hayanagi は実行ファイルの横の book/ から定跡を読む。ZIP の外部ファイルには 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 をシステムのものを使う（通常のデスクトップには入っている）。

Qt の lib ディレクトリを LD_LIBRARY_PATH に含めない環境で確かめる。含まれているとシステムのライブラリが使われ、同梱漏れに気づけない。できれば 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 のQt は 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 パッケージを使って作る。Qt Online Installer の Qt など、pacman のパッケージに含まれないライブラリが AppImage に入ると、元のパッケージを特定できずに止まる。
• 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