From bf1ce86eef2fcdadd056933ce8ebf4444e0762a7 Mon Sep 17 00:00:00 2001 From: Lukas Jezek Date: Sun, 26 Apr 2026 22:45:33 +0200 Subject: [PATCH 1/3] Add Windows README and install folder to gitignore Co-authored-by: Copilot --- .gitignore | 1 + README.md | 11 ++-- README_WINDOWS.md | 124 ++++++++++++++++++++++++++++++++++++++++++++++ 3 files changed, 133 insertions(+), 3 deletions(-) create mode 100644 README_WINDOWS.md diff --git a/.gitignore b/.gitignore index dbcb10b26..c4a17913c 100644 --- a/.gitignore +++ b/.gitignore @@ -30,6 +30,7 @@ ui_*.h Makefile* *-build-* build +install # QtCreator diff --git a/README.md b/README.md index 3cb84e07f..b19636aa9 100644 --- a/README.md +++ b/README.md @@ -136,11 +136,13 @@ To allow incoming connections, create a firewall rule: --- -## Build QE3 (Qt6 version) +## Build + +### Linux Build QE3 (Qt6 version) ``` git clone https://github.com/Quick-Event/quickbox.git cd quickbox -git sw qe3 +git switch main git submodule update --init --recursive mkdir build cd build @@ -148,7 +150,7 @@ cmake .. -DCMAKE_GENERATOR:STRING=Ninja -DCMAKE_BUILD_TYPE:STRING=Debug -DCMAKE_ cmake --build . cmake --install . --prefix /path/to/install/qe3 ``` -## Run QE3 from QTC (Qt6 version) +### Linux Run QE3 from QTC (Qt6 version) When QE3 is run from QTC (QT Creator), some symlinks must be created to load QML modules. 1. build QE3 manually and run `cmake --install ...` as described in previous chapter. 2. Open `CMakeLists.txt` as project in QTC @@ -162,6 +164,9 @@ ln -s /tmp/qe3/bin/reports reports ln -s /tmp/qe3/bin/translations translations ``` +### Windows Build +See the [README_WINDOWS.md](README_WINDOWS.md) for detailed guide how to get the working running on Windows. + --- ## Contributing diff --git a/README_WINDOWS.md b/README_WINDOWS.md new file mode 100644 index 000000000..93fd21af4 --- /dev/null +++ b/README_WINDOWS.md @@ -0,0 +1,124 @@ +# Building QuickEvent on Windows + +This guide covers building QuickEvent on Windows (including Windows ARM). The build targets x86_64 using MinGW, which runs natively on x64 and via emulation on Windows ARM. + +--- + +## Tools to Install + +### 1. Qt 6.10.x (includes MinGW and CMake) +- Download the Qt Online Installer from https://www.qt.io/download-qt-installer +- In the installer, select: + - **Component**: `Qt 6.10.x → MinGW 64-bit` (`win64_mingw`) + - **Required extra modules**: `Qt Serial Port`, `Qt Multimedia` + - Under **Tools**: ensure `MinGW 13.1.0 64-bit` and `CMake` are checked (they are by default) +- Note your Qt install root (e.g. `C:\Qt` or `C:\dev\Qtx86`) + +> Qt bundles the correct MinGW variant (msvcrt, not ucrt) under `Tools\$MINGW_VER\`. No separate MinGW install is needed. + +### 2. PostgreSQL 17 — x86-64 build required +- **Windows ARM users**: do NOT use `winget` — it may install the ARM64 native version, which cannot be loaded by the x86_64 binary. +- Use Chocolatey (delivers x64): `choco install postgresql17 -y` +- Or download the **Windows x86-64** installer explicitly from https://www.enterprisedb.com/downloads/postgres-postgresql-downloads +- Required for `libpq` headers at build time and DLLs at runtime + +### 3. OpenSSL 3.x — x86-64 build required +- **Windows ARM users**: do NOT use `winget` — it may install the ARM64 native version. +- Use Chocolatey (delivers x64): `choco install openssl.light --version=3.1.4 -y` +- Or download **Win64 OpenSSL** (not Win ARM64) from https://slproweb.com/products/Win32OpenSSL.html +- Required at runtime for Qt's network/SSL support + +--- + +## Build Commands + +Run the following from a **PowerShell** terminal. + +Set `$QT_ROOT` to your Qt install folder. Everything else is derived from it: + +```powershell +$QT_ROOT = "C:\dev\Qtx86" # adjust to your actual Qt install root +$QT_VER = "6.10.3" # adjust to the installed Qt version +$MINGW_VER = "mingw1310_64" +``` + +One-time PATH setup (restart PowerShell after running this): +```powershell +$p = [Environment]::GetEnvironmentVariable("PATH", "User") +[Environment]::SetEnvironmentVariable("PATH", + "$p;$QT_ROOT\Tools\CMake_64\bin;$QT_ROOT\Tools\$MINGW_VER\bin", + "User") +``` + +Configure, build, and install: +```powershell +$env:CC = "$QT_ROOT\Tools\$MINGW_VER\bin\gcc.exe" +$env:CXX = "$QT_ROOT\Tools\$MINGW_VER\bin\g++.exe" + +cmake ` + -S "C:\repos\quickbox" ` + -B "C:\repos\quickbox\build" ` + -G "MinGW Makefiles" ` + -DCMAKE_BUILD_TYPE=Release ` + "-DCMAKE_PREFIX_PATH=$QT_ROOT\$QT_VER\mingw_64" ` + -DCMAKE_INSTALL_PREFIX="C:\repos\quickbox\install" ` + -DUSE_QT6=ON ` + -DMINGW=ON ` + -DQF_BUILD_QML_PLUGINS=ON ` + -DBUILD_TESTING=OFF + +cmake --build "C:\repos\quickbox\build" --parallel +cmake --install "C:\repos\quickbox\build" +``` + +--- + +## After Install — Bundle Dependencies + +After installing, run `windeployqt` to copy Qt plugins and DLLs, then manually copy runtime libraries: + +```powershell +$PG_BIN = "C:\Program Files\PostgreSQL\17\bin" # Update this +$SSL_DIR = "C:\Program Files\OpenSSL" # Update this + + +# Deploy Qt DLLs and plugins +& "$QT_ROOT\$QT_VER\mingw_64\bin\windeployqt.exe" ` + -serialport -multimedia ` + --qmldir "C:\repos\quickbox\install\bin\qml" ` + --qmldir "C:\repos\quickbox\install\bin\reports" ` + "C:\repos\quickbox\install\bin\quickevent.exe" + +# Copy MinGW runtime DLLs +Copy-Item ` + "$QT_ROOT\Tools\$MINGW_VER\bin\libstdc++-6.dll", ` + "$QT_ROOT\Tools\$MINGW_VER\bin\libgcc_s_seh-1.dll", ` + "$QT_ROOT\Tools\$MINGW_VER\bin\libwinpthread-1.dll" ` + "C:\repos\quickbox\install\bin\" + +# Copy PostgreSQL runtime DLLs +Copy-Item ` + "$PG_BIN\libiconv-2.dll", "$PG_BIN\libintl-9.dll", ` + "$PG_BIN\liblz4.dll", "$PG_BIN\zlib1.dll", "$PG_BIN\libpq.dll" ` + "C:\repos\quickbox\install\bin\" + +# Copy OpenSSL runtime DLLs (path may vary by OpenSSL install) +Copy-Item "$SSL_DIR\libssl-3-x64.dll", "$SSL_DIR\libcrypto-3-x64.dll" ` + "C:\repos\quickbox\install\bin\" +``` + +--- + +## Verification + +Run `install\bin\quickevent.exe` — it should launch without any missing DLL errors. Connect to a local SQLite or PostgreSQL database and load an event to verify Qt SQL works end-to-end. + +--- + +## Notes on Windows ARM + +The project has no native ARM64 build support. Building x86_64 with MinGW and running via Windows ARM's built-in x64 emulation is the recommended approach and mirrors the CI configuration exactly. + +**Critical**: An x86_64 emulated process cannot load ARM64 DLLs. On Windows ARM, `winget` may install ARM64-native versions of PostgreSQL and OpenSSL. Use Chocolatey or download explicit x86-64 installers as described above — otherwise the app will fail to start with missing or incompatible DLL errors. + +If ARM64 native support is ever needed, it would require Qt `win64_msvc2022_arm64` and the MSVC ARM64 toolchain — this is currently untested with the project. From 8db99f3e2d183689af68bc8c9f59710feeb3f820 Mon Sep 17 00:00:00 2001 From: Lukas Jezek Date: Mon, 27 Apr 2026 19:34:55 +0200 Subject: [PATCH 2/3] Remove hardcoding of QB_ROOT --- README_WINDOWS.md | 31 +++++++++++++++---------------- 1 file changed, 15 insertions(+), 16 deletions(-) diff --git a/README_WINDOWS.md b/README_WINDOWS.md index 93fd21af4..a9b4a4234 100644 --- a/README_WINDOWS.md +++ b/README_WINDOWS.md @@ -39,7 +39,8 @@ Set `$QT_ROOT` to your Qt install folder. Everything else is derived from it: ```powershell $QT_ROOT = "C:\dev\Qtx86" # adjust to your actual Qt install root $QT_VER = "6.10.3" # adjust to the installed Qt version -$MINGW_VER = "mingw1310_64" +$MINGW_VER = "mingw1310_64" # adjust to the installed Qt version +$QUICKBOX_ROOT = $PWD # adjust to the quickbox repo root if necessary ``` One-time PATH setup (restart PowerShell after running this): @@ -56,19 +57,19 @@ $env:CC = "$QT_ROOT\Tools\$MINGW_VER\bin\gcc.exe" $env:CXX = "$QT_ROOT\Tools\$MINGW_VER\bin\g++.exe" cmake ` - -S "C:\repos\quickbox" ` - -B "C:\repos\quickbox\build" ` + -S "$QUICKBOX_ROOT" ` + -B "$QUICKBOX_ROOT\build" ` -G "MinGW Makefiles" ` -DCMAKE_BUILD_TYPE=Release ` "-DCMAKE_PREFIX_PATH=$QT_ROOT\$QT_VER\mingw_64" ` - -DCMAKE_INSTALL_PREFIX="C:\repos\quickbox\install" ` + -DCMAKE_INSTALL_PREFIX="$QUICKBOX_ROOT\install" ` -DUSE_QT6=ON ` -DMINGW=ON ` -DQF_BUILD_QML_PLUGINS=ON ` -DBUILD_TESTING=OFF -cmake --build "C:\repos\quickbox\build" --parallel -cmake --install "C:\repos\quickbox\build" +cmake --build "$QUICKBOX_ROOT\build" --parallel +cmake --install "$QUICKBOX_ROOT\build" ``` --- @@ -85,26 +86,26 @@ $SSL_DIR = "C:\Program Files\OpenSSL" # Update this # Deploy Qt DLLs and plugins & "$QT_ROOT\$QT_VER\mingw_64\bin\windeployqt.exe" ` -serialport -multimedia ` - --qmldir "C:\repos\quickbox\install\bin\qml" ` - --qmldir "C:\repos\quickbox\install\bin\reports" ` - "C:\repos\quickbox\install\bin\quickevent.exe" + --qmldir "$QUICKBOX_ROOT\install\bin\qml" ` + --qmldir "$QUICKBOX_ROOT\install\bin\reports" ` + "$QUICKBOX_ROOT\install\bin\quickevent.exe" # Copy MinGW runtime DLLs Copy-Item ` "$QT_ROOT\Tools\$MINGW_VER\bin\libstdc++-6.dll", ` "$QT_ROOT\Tools\$MINGW_VER\bin\libgcc_s_seh-1.dll", ` "$QT_ROOT\Tools\$MINGW_VER\bin\libwinpthread-1.dll" ` - "C:\repos\quickbox\install\bin\" + "$QUICKBOX_ROOT\install\bin\" # Copy PostgreSQL runtime DLLs Copy-Item ` "$PG_BIN\libiconv-2.dll", "$PG_BIN\libintl-9.dll", ` "$PG_BIN\liblz4.dll", "$PG_BIN\zlib1.dll", "$PG_BIN\libpq.dll" ` - "C:\repos\quickbox\install\bin\" + "$QUICKBOX_ROOT\install\bin\" # Copy OpenSSL runtime DLLs (path may vary by OpenSSL install) Copy-Item "$SSL_DIR\libssl-3-x64.dll", "$SSL_DIR\libcrypto-3-x64.dll" ` - "C:\repos\quickbox\install\bin\" + "$QUICKBOX_ROOT\install\bin\" ``` --- @@ -117,8 +118,6 @@ Run `install\bin\quickevent.exe` — it should launch without any missing DLL er ## Notes on Windows ARM -The project has no native ARM64 build support. Building x86_64 with MinGW and running via Windows ARM's built-in x64 emulation is the recommended approach and mirrors the CI configuration exactly. +Quickbox currently has no native ARM64 build support. Building x86_64 with MinGW and running via Windows ARM's built-in x64 emulation is the recommended approach and mirrors the CI configuration exactly. -**Critical**: An x86_64 emulated process cannot load ARM64 DLLs. On Windows ARM, `winget` may install ARM64-native versions of PostgreSQL and OpenSSL. Use Chocolatey or download explicit x86-64 installers as described above — otherwise the app will fail to start with missing or incompatible DLL errors. - -If ARM64 native support is ever needed, it would require Qt `win64_msvc2022_arm64` and the MSVC ARM64 toolchain — this is currently untested with the project. +**Critical**: An x86_64 emulated process cannot load ARM64 DLLs. On Windows ARM, `winget` may install ARM64-native versions of PostgreSQL and OpenSSL. Use Chocolatey or download explicit x86-64 installers as described above — otherwise the app will fail to start with missing or incompatible DLL errors. \ No newline at end of file From 7fe90c782f9361b100857f44d498b2e830227bc1 Mon Sep 17 00:00:00 2001 From: Lukas Jezek Date: Mon, 27 Apr 2026 19:39:21 +0200 Subject: [PATCH 3/3] Clarify readme and source of data --- README.md | 2 +- README_WINDOWS.md | 2 ++ 2 files changed, 3 insertions(+), 1 deletion(-) diff --git a/README.md b/README.md index b19636aa9..f9d6e94ff 100644 --- a/README.md +++ b/README.md @@ -165,7 +165,7 @@ ln -s /tmp/qe3/bin/translations translations ``` ### Windows Build -See the [README_WINDOWS.md](README_WINDOWS.md) for detailed guide how to get the working running on Windows. +See the [README_WINDOWS.md](README_WINDOWS.md) for detailed guide how to get the build working on Windows. --- diff --git a/README_WINDOWS.md b/README_WINDOWS.md index a9b4a4234..d3584170e 100644 --- a/README_WINDOWS.md +++ b/README_WINDOWS.md @@ -2,6 +2,8 @@ This guide covers building QuickEvent on Windows (including Windows ARM). The build targets x86_64 using MinGW, which runs natively on x64 and via emulation on Windows ARM. +It is heavily inspired by the `.github\workflows\installer.yml` GitHub workflow. + --- ## Tools to Install