Linux Build and Release

2.1 Arch Linux and Docker (for packaging)

Release packages are built inside the container, so the host only needs Docker, Git, and Python 3; Qt and the other build dependencies are in the container. Add your user to the docker group and log in again.

sudo usermod -aG docker $USER

Members of the docker group can perform root-equivalent operations through docker.

To build and develop on Arch Linux directly, install the build tools and Arch's Qt packages. fcitx5-qt provides the Japanese input (fcitx5) plugin that is bundled in the AppImage; without it, that plugin is left out.

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 Other distributions (building the application only)

You can build and develop the application on Ubuntu, Debian, or Fedora as well. Qt 6.7 or later is required; if your distribution's Qt is older, install Qt with the Qt Online Installer.

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

For Qt installed with the Qt Online Installer, pass its location when configuring CMake (Qt 6.11.2 in this example).

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

2.3 Checking the installation

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

5.1 Running the script

Release packages are built in an older Arch Linux container (the Arch Linux Archive as of 2024-07-15: glibc 2.39, Qt 6.7.2).

For a release, first update the version to the release date and commit it (section 6).

./scripts/build-linux-container.sh

• The first run creates the build image (scripts/linux-container/Dockerfile, about 3 GB). Downloads from the Arch Linux Archive are slow and take tens of minutes.
• Inside the container, scripts/build-linux.sh runs as your user. It uses build-container instead of the usual build directory and writes the outputs to the repository root.
• Some keys that signed packages at that time have since expired. The image verifies signatures against the official keyring but does not require the keys to be currently trusted.
• The bundled OpenSSL and libcurl, and the network libraries libcurl uses (nghttp2, nghttp3, ngtcp2, libssh2), are replaced with newer versions, because the versions of that time lack later fixes. Current Arch packages are installed after checking their SHA-256 (scripts/linux-container/packages.sha256) and signatures; curl, whose current package uses newer glibc functions, is rebuilt in the image from the same version's Arch PKGBUILD.
• To update them, download the new packages and their .sig files on your machine, check the signatures with pacman-key --verify, and update packages.sha256. For curl, set CURL_PKGVER and CURL_PKGBUILD_SHA256 (the SHA-256 of the PKGBUILD at the Arch tag) in the Dockerfile; the tag signature is checked with the key in curl-signing-key.asc. First make sure the glibc version a new package needs (the highest GLIBC_ in objdump -T) is 2.38 or lower; rebuild in the image any package that needs more. Changing scripts/linux-container/ makes build-linux-container.sh rebuild the image.

You can also build directly on Arch Linux. Such an AppImage requires the host's glibc version or later (2.43 as of October 2026).

./scripts/build-linux.sh

Both scripts accept these options:

build-linux.sh performs these steps (in the container, the same steps run inside it):

1. Check the required tools (cmake and python3; ninja recommended)
2. Configure CMake and build in Release mode (ShogiBoardQ and Hayanagi)
3. Check the executable, translation files, and the 3- to 13-move collections (one file per move count)
4. Download linuxdeploy, its Qt plugin, and appimagetool (first time only; saved in the build directory). Before running them, check them against the SHA-256 values in build-linux.sh. They are continuous builds that upstream replaces, so a replacement makes the check fail and stop; then review the upstream release digest and changes before updating the values
5. Create the AppDir and generate the AppImage (files needed to run, plus Qt and bundled library license notices)
6. Create the ZIP with the AppImage, puzzle collections, and Hayanagi

The outputs are ShogiBoardQ-linux-x86_64.AppImage and ShogiBoardQ-linux.zip in the repository root. The working directories are AppDir and ShogiBoardQ-linux/ in the build directory.

5.2 Contents of the AppImage

The AppImage contains only the files needed to start and run the application, plus license notices.

ShogiBoardQ-linux-x86_64.AppImage
└── (extracted)
    ├── AppRun                          ← starts the app with only the bundled Qt and OpenSSL settings
    ├── shogiboardq.desktop
    ├── shogiboardq.png
    └── usr/
        ├── bin/
        │   ├── ShogiBoardQ             ← executable
        │   ├── qt.conf                 ← Qt plugin location
        │   └── ShogiBoardQ_{ja_JP,en,zh_CN,zh_TW}.qm   ← application translations (4 languages)
        ├── lib/                        ← Qt and dependencies
        ├── plugins/
        │   ├── platforms/libqxcb.so            ← X11
        │   ├── imageformats/libqsvg.so, libqjpeg.so, libqico.so
        │   ├── iconengines/libqsvgicon.so
        │   ├── platforminputcontexts/          ← Japanese input (compose, fcitx5, ibus)
        │   ├── platformthemes/libqxdgdesktopportal.so
        │   ├── sqldrivers/libqsqlite.so        ← tsume history and analysis cache
        │   └── tls/libqopensslbackend.so       ← TLS for CSA network play (OpenSSL)
        └── share/
            ├── applications/, icons/
            ├── ShogiBoardQ/openssl.cnf ← settings the bundled OpenSSL reads (empty; the system's are not read)
            └── licenses/ShogiBoardQ/
                ├── NOTICE*.md, SOURCE_CODE*.md, GPL-3.0.txt, LGPL-3.0.txt
                ├── QT-NOTICES.md, qt/          ← notices of the bundled Qt modules
                ├── QT-SOURCE.json, BUILD.json  ← Qt source record and build version
                └── THIRD-PARTY-NOTICES.md, third-party/   ← notices of the other bundled libraries

• Puzzle collections, the Hayanagi engine for regular games, documentation, and validation records (validation_*.json) are not included. The application does not read them from inside the AppImage and users cannot select files there, so they are shipped only as files outside the AppImage in the ZIP. The Hayanagi used for tsume play is built into the application.
• Qt's own translations placed by linuxdeploy (usr/translations/) are removed. The Japanese and Chinese translations of standard dialogs are built into the executable, and the application translations are read from usr/bin/.
• Unused plugins are not bundled: OpenGL integration (xcbglintegrations) and GIF images. No widget uses OpenGL.
• Of the tls plugins, only the OpenSSL backend (libqopensslbackend.so) is bundled, for the "TLS (encrypted)" connection in CSA network play. libssl and libcrypto are bundled as its dependencies. The app makes no HTTPS or other connections.
• The Qt license notices cover only the bundled Qt modules (qtbase, qtcharts, qtmultimedia, qtsvg, qttranslations, and qtwayland) and the files they refer to (scripts/qt_licenses.py). Notices for modules that are not distributed, such as Qt WebEngine, are left out.
• For the other bundled libraries (about 50 packages such as glib, PulseAudio, OpenSSL, and fcitx5-qt), scripts/bundled_licenses.py looks up each package with pacman, copies the license texts to third-party/, and lists versions, licenses, and source locations in THIRD-PARTY-NOTICES.md. Both lists are shown in “Version Info” as “Third-party licenses in Qt” and “Bundled library licenses”.

5.3 Contents of the ZIP

The ZIP contains the following files. After extracting it, users can select the puzzle collections and Hayanagi right away.

ShogiBoardQ-linux.zip
└── ShogiBoardQ-linux/
    ├── ShogiBoardQ-linux-x86_64.AppImage
    ├── README.md
    ├── LICENSE
    ├── Hayanagi/
    │   ├── hayanagi
    │   ├── book/hayanagi_book.db   ← Hayanagi opening book
    │   └── README.md
    └── data/tsumeshogi/
        ├── tsume_{3,5,7,9,11,13}ply_1000_20261001.txt   ← 6 files (1,000 puzzles each)
        └── README.md

• The puzzle collections are copied unchanged. Their hashes match the audit records built into the application, so verified move counts and solutions are reused when a collection is opened.
• Keep exactly one collection per move count in data/tsumeshogi/ (the repository tracks only the current 20261001 files). The script stops with an error if two files exist for the same move count.
• Hayanagi is stripped before it is added. Its opening book hayanagi_book.db, which the build copies to build/Hayanagi/book/, goes to Hayanagi/book/; Hayanagi reads the book from book/ next to its executable. The ZIP has no docs/, validation_*.json, or licenses/ outside the AppImage; the license notices are inside the AppImage.

Users start the application as follows. In tsume play, they choose a collection in data/tsumeshogi/ with “Open collection…”; to register the engine for regular games, they choose 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 Testing

# Start
./ShogiBoardQ-linux-x86_64.AppImage

# Extract and check the contents (no Hayanagi and no Qt translations inside)
./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

# Required glibc version
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

# Hayanagi in the ZIP answers as a USI engine
unzip -o -q ShogiBoardQ-linux.zip -d /tmp/zipcheck
printf 'usi\nisready\nquit\n' | /tmp/zipcheck/ShogiBoardQ-linux/Hayanagi/hayanagi

# The ZIP has the 12 expected files and is not corrupted
python3 -m zipfile -l ShogiBoardQ-linux.zip
python3 -m zipfile -t ShogiBoardQ-linux.zip

For a container build, the required glibc version should be GLIBC_2.38 or lower. The AppImage uses the system's OpenGL (libEGL, libOpenGL), fontconfig, HarfBuzz, and wayland-client, which desktop systems normally provide.

Test in an environment whose LD_LIBRARY_PATH does not include Qt's lib directory; otherwise system libraries are used and missing files go unnoticed. If possible, also check on another environment such as Ubuntu 24.04: switching among Japanese, English, and Chinese, SVG pieces, piece sounds, saving tsume history, and the license lists in “Version Info”.

Qt is not found

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

Make sure Qt 6.7 or later and the required modules are installed. For Qt from the Qt Online Installer, pass -DCMAKE_PREFIX_PATH. After switching Qt or the CMake generator, start over in a new build directory.

Hayanagi sources are missing

Run git submodule update --init --recursive in the repository root.

The script stops because of multiple collections

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

An older version of a collection remains in data/tsumeshogi/ (the message says that several collections were found for one move count). Delete the unused version so that one file remains per move count.

Qt notice validation fails

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.

Prepare the notices for the same Qt version used for the build (section 4): Qt 6.7.2 in the container, or the version reported by pacman -Q qt6-base on Arch Linux. Do not ship a package after a failed step.

Collecting bundled library notices fails

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)

• Create the package on Arch Linux with Arch's Qt packages. If the AppImage contains libraries that do not belong to a pacman package, such as Qt from the Qt Online Installer, their package cannot be identified and the script stops.
• No license text for … means that no license text was found for a package. Older repositories may use license fields that are not SPDX expressions; add the upstream expression to LICENSE_OVERRIDES in scripts/bundled_licenses.py. Put texts that a package lacks, such as a notice with the actual copyright line, in scripts/license-texts/<package>/.

docker cannot be used

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

Add your user to the docker group and log in again (sudo usermod -aG docker $USER), or set DOCKER="sudo docker".

linuxdeploy does not start

dlopen(): error loading libfuse.so.2

Install fuse2, or run APPIMAGE_EXTRACT_AND_RUN=1 ./scripts/build-linux.sh.

The AppImage does not start (FUSE)

AppImages require FUSE to run.

Install FUSE 2, or start it with --appimage-extract-and-run.

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

The glibc version is too old

version `GLIBC_2.38' not found

The system's glibc is older than that of the build system. Build release packages in the container (5.1). If that is still too new, use a distribution with a newer glibc (see the glibc note in Requirements).

System libraries are missing

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

Libraries that are not bundled in the AppImage (OpenGL, fontconfig, HarfBuzz, wayland-client) are missing on the system. Example for Ubuntu / Debian:

sudo apt install libegl1 libopengl0 libfontconfig1 libharfbuzz0b libwayland-client0

The xcb platform plugin cannot be loaded

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

X11 libraries are missing. Examples for Ubuntu / Debian, Fedora, and Arch Linux, in that order:

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

Japanese text cannot be entered

The AppImage bundles only the X11 platform plugin, so it runs through XWayland on Wayland desktops. If the QT_IM_MODULE environment variable is not set, no Japanese input plugin is selected. Start it with QT_IM_MODULE=fcitx for fcitx5, or QT_IM_MODULE=ibus for IBus.

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

Translations are not loaded

Check that the .qm files are in usr/bin/, next to the executable.

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