Contents
Requirements and setup
Install Visual Studio 2022 with the Desktop development with C++ workload, Git, CMake 3.16 or later, Ninja, and Python 3. Use Developer PowerShell for VS 2022 with the x64 toolchain enabled.
Install a Qt 6.7 or later MSVC desktop kit matching your compiler architecture. Required modules are Widgets, Charts, Network, Concurrent, Multimedia, Sql, and LinguistTools. Include Qt Charts, Qt Multimedia, Qt SVG, and the SQLite plugin in your Qt installation.
The examples use the official Qt 6.7.3 MSVC 2022 64-bit SDK. Set these paths to your installed kit:
$env:CMAKE_PREFIX_PATH = "C:\Qt\6.7.3\msvc2022_64"
$env:PATH = "C:\Qt\6.7.3\msvc2022_64\bin;" + $env:PATH
cmake --version
cl
windeployqt --version
python --versionKeep the compiler, Qt DLLs, and application on the same architecture. The packaging script uses the Visual C++ runtime supplied by the Visual Studio developer environment.
Get the source and build
Clone the repository with its Hayanagi submodule. An ordinary clone without submodules is incomplete.
git clone --recurse-submodules https://github.com/hnakada123/ShogiBoardQ.git
cd ShogiBoardQFor an existing checkout, initialize the recorded submodule version with git submodule update --init --recursive.
cmake -B build -S . -G Ninja -DCMAKE_BUILD_TYPE=Release
cmake --build build --parallel
.\build\ShogiBoardQ.exeThese commands build for local development. If you use the Visual Studio generator instead of Ninja, select Release when building and use the executable in build\Release. Start with a separate build directory when changing generators.
To enable and run the test suite:
cmake -B build -S . -DBUILD_TESTING=ON
cmake --build build --parallel
ctest --test-dir build --output-on-failureLicense notices
The Windows ZIP does not contain an external licenses/ folder, Qt source archives, or Hayanagi/source/. Building it does not require downloading the Qt sources or running scripts/qt_licenses.py; those steps prepare the license documents bundled in the Linux and macOS packages.
Windows users get the license information from the application and the ZIP:
- About dialog: shows the Qt version in use and at build time, the Qt copyright notice, the GPL and LGPL texts, and how to obtain the corresponding sources. These documents (
resources/licenses/, such asNOTICE.mdandSOURCE_CODE.md) are built into the executable and shown in the UI language, so they can be read offline. LICENSE: the GPL-3.0 license of ShogiBoardQ, placed at the root of the ZIP.
Attach only the runnable ZIP to a GitHub Release. Do not attach Qt source archives or source/build metadata separately. The repository's Qt distribution notes (Japanese) describe the packaging policy for each platform.
Create a ZIP package
Run the distribution script from Developer PowerShell:
.\scripts\build-windows.ps1The script builds Release, uses windeployqt, copies all four application translations (ja_JP, en, zh_CN, zh_TW) and the Visual C++ runtime, and checks the Qt DLLs and SQLite plugin. It produces deploy\ and ShogiBoardQ-windows.zip in the repository root.
The ZIP contains:
ShogiBoardQ.exeandshogiboardq-cli.exe(the command-line tool used by the MCP server), with the Qt DLLs and plugins.platforms\qoffscreen.dllis added for the CLI's board rendering, becausewindeployqtdoes not copy it.Hayanagi\hayanagi.exe, the USI engine for normal games, with its opening bookHayanagi\book\hayanagi_book.db(the copy the build places inbuild\Hayanagi\book\) and only the three runtime DLLs it loads (vcruntime140.dll,vcruntime140_1.dll,msvcp140.dll).- The six tsume collections in
data\tsumeshogi\(3 to 13 moves, one file each). The script stops ifdata/tsumeshogi/holds more than one file for the same number of moves. - The root
LICENSE. README files,Hayanagi/source/, and an externallicenses/folder are not included.
Use -SkipZip to prepare only the deploy folder or -Help to show the options. -BuildDir, -DeployDir, and -ZipPath change the build directory, deploy folder, and ZIP path (defaults: build, deploy, ShogiBoardQ-windows.zip), for example to build each release in its own folder:
.\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.zipExtract the ZIP into an empty folder on a Windows machine without the development SDK and run ShogiBoardQ.exe. Check language switching, pieces, sound, and tsume progress. Also run shogiboardq-cli.exe version, and check that cmd /c "cd Hayanagi && (echo usi& echo isready& echo quit) | .\hayanagi.exe" answers with id name Hayanagi and info string book loaded. Hayanagi reads the book from book\ in its working directory; ShogiBoardQ starts each engine in the engine's own folder, so the book is used as extracted. Distribute the complete folder; the executable alone does not contain Qt.
Code signing
If you sign your Windows release, sign the executables in the deploy folder (ShogiBoardQ.exe, shogiboardq-cli.exe, and Hayanagi\hayanagi.exe) before creating the final ZIP. The repository's release workflow uses SignTool from the Windows SDK with a certificate supplied through repository secrets, signs and verifies every executable, then packages the signed files.
Configure the workflow's Windows certificate, password, and timestamp settings in repository secrets. Keep certificates and passwords out of source control. Test the final signed archive, not only the executable in the build directory.
Publish on GitHub Releases
The repository includes a release workflow that builds all three platforms, prepares bundled license documents, and uploads only the Linux, macOS, and Windows ZIPs. Checksums and the SBOM remain in the CI artifact release-verification; Qt sources, source guides, build metadata, and CI logs are not release attachments.
The release version is the release date (YYYY.MM.DD, for example 2026.10.07). Update APP_VERSION in CMakeLists.txt only on the day of a release: commit the change before building the packages, build them from that commit, and tag that commit with the same version, without a leading v. Use the version in the release name as well. For a second release on the same day, add a fourth number, as in 2026.10.07.1. See Versioning and releases (Japanese).
The workflow starts automatically only for tags beginning with v, so pushing a release tag does not start it. Maintainers with push access can run it from the Actions tab: enter a tag or branch, and leave Publish off (the default) to only build and verify the packages, or turn it on to attach them to the release for that tag, replacing its existing files. Its Windows job attaches ShogiBoardQ-windows.zip, the same name as a manual release. Releases are still created by hand because the workflow's Linux job cannot create the Linux package yet (see the Linux build guide).
For a manual release, open the repository's Releases page and create a release for the intended tag. Attach only the tested ZIP. Select the package by its exact filename instead of uploading the entire working directory. The license information is built into the application, with LICENSE in the ZIP.
Troubleshooting
- The compiler or Windows SDK cannot be found: open Developer PowerShell and confirm that the Desktop development with C++ workload is installed.
- Qt6Config.cmake or Qt Charts is missing: check the kit path and install the required modules. Do not mix MinGW and MSVC Qt libraries.
- Hayanagi source files are missing: run
git submodule update --init --recursive. - windeployqt is not found: add the selected Qt kit's
bindirectory toPATH. - A DLL or plugin is missing on another PC: distribute the entire deploy folder and inspect the packaging log. Check
sqldrivers\qsqlite.dllif puzzle history is unavailable. - PowerShell blocks the script: review your execution policy and the script before enabling it under your system's policy.