A native macOS / windows / Linux database IDE built with Swift and AppKit. Connect to PostgreSQL, MySQL, SQLite, and Redis from a single app with a fast, keyboard-driven interface.
Gridex — Windows Build Guide
Hướng dẫn build Gridex từ source và tạo installer Setup.exe trên Windows, chạy local không phụ thuộc CI.
Yêu cầu môi trường
| Thành phần | Version | Ghi chú |
|---|---|---|
| Windows | 10/11 x64 | |
| Visual Studio 2022+ | 17.x hoặc Build Tools | Phải có workload Desktop development with C++ |
| Windows App SDK | 1.8 | Tự kéo qua NuGet packages.config |
| .NET SDK | 8.0 hoặc mới hơn | Cần cho vpk global tool |
| vcpkg | latest, ở C:\vcpkg |
Project hardcode path này |
| PowerShell | 5.1 (pwsh cũng OK) |
Cài vcpkg deps (1 lần duy nhất)
Project link các lib native qua vcpkg. Cài 1 lần:
Git Bash / MSYS2:
/c/vcpkg/vcpkg.exe install \
sqlite3 libpq libmariadb openssl hiredis libssh2 \
nlohmann-json cpp-httplib \
--triplet x64-windows
PowerShell:
C:\vcpkg\vcpkg.exe install `
sqlite3 libpq libmariadb openssl hiredis libssh2 `
nlohmann-json cpp-httplib `
--triplet x64-windows
CMD:
C:\vcpkg\vcpkg.exe install ^
sqlite3 libpq libmariadb openssl hiredis libssh2 ^
nlohmann-json cpp-httplib ^
--triplet x64-windows
Mỗi shell có cú pháp line-continuation khác nhau: bash dùng
\, PowerShell dùng backtick`, CMD dùng caret^. Hoặc bạn có thể gõ 1 dòng duy nhất không xuống dòng cũng được.
Cấu trúc scripts
Tất cả build scripts nằm ở windows/scripts/:
windows/scripts/
├── install-vpk-tool.ps1 # Cài vpk CLI (Velopack) 1 lần
├── build-unpackaged.ps1 # Build Gridex.exe + bundle runtime DLLs
├── pack-velopack.ps1 # Pack Gridex.exe → Setup.exe
└── build-and-pack.ps1 # One-shot: install + build + pack
Build Setup.exe
Flags bắt buộc cho mọi lệnh
powershell:
-NoProfile: skip load$PROFILEcá nhân — tránh aliases / function overrides ảnh hưởng build.-ExecutionPolicy Bypass: Windows mặc định chặn script.ps1không được ký (policyRestricted/AllSigned). Flag này chỉ áp dụng cho 1 process duy nhất, không cầnSet-ExecutionPolicyglobal.
Cách nhanh nhất — 1 lệnh duy nhất
Git Bash / MSYS2:
cd /e/dev/be/vura
powershell -NoProfile -ExecutionPolicy Bypass -File ./windows/scripts/build-and-pack.ps1 -Version "0.1.12"
PowerShell (5.1 / 7+):
cd E:\dev\be\vura
powershell -NoProfile -ExecutionPolicy Bypass -File .\windows\scripts\build-and-pack.ps1 -Version "0.1.12"
CMD:
cd /d E:\dev\be\vura
powershell -NoProfile -ExecutionPolicy Bypass -File .\windows\scripts\build-and-pack.ps1 -Version "0.1.12"
Script sẽ:
- Cài/update
vpkglobal tool (skip nếu đã có) - Build
Gridex.exeunpackaged, stamp version0.1.12vào About section - Pack thành
Setup.exequa Velopack với metadata version0.1.12
Output: windows/Releases/
Gridex-stable-Setup.exe— installer user-facingGridex-0.1.12-stable-full.nupkg— package Velopackreleases.stable.json,RELEASES-stable— feed manifestsGridex-stable-Portable.zip— bản portable
Cài thử sau khi build
Git Bash / MSYS2:
./windows/Releases/Gridex-stable-Setup.exe
PowerShell:
.\windows\Releases\Gridex-stable-Setup.exe
CMD:
.\windows\Releases\Gridex-stable-Setup.exe
Sau khi cài, mở Settings (Ctrl+Shift+P) → cuộn xuống mục About → phải thấy đúng số version đã pass vào.
Build từng bước (khi debug)
Khi cần iterate nhanh hơn hoặc chỉ build exe mà không pack installer:
Bước 1 — Cài vpk (1 lần)
Git Bash / MSYS2:
powershell -NoProfile -ExecutionPolicy Bypass -File ./windows/scripts/install-vpk-tool.ps1
PowerShell:
powershell -NoProfile -ExecutionPolicy Bypass -File .\windows\scripts\install-vpk-tool.ps1
CMD:
powershell -NoProfile -ExecutionPolicy Bypass -File .\windows\scripts\install-vpk-tool.ps1
Bước 2 — Build Gridex.exe (nhiều lần)
Git Bash / MSYS2:
# Dev build — About section hiện "0.0.0-dev"
powershell -NoProfile -ExecutionPolicy Bypass -File ./windows/scripts/build-unpackaged.ps1
# Build với version cụ thể — About section hiện đúng string
powershell -NoProfile -ExecutionPolicy Bypass -File ./windows/scripts/build-unpackaged.ps1 -Version "0.1.12-test"
PowerShell:
# Dev build — About section hiện "0.0.0-dev"
powershell -NoProfile -ExecutionPolicy Bypass -File .\windows\scripts\build-unpackaged.ps1
# Build với version cụ thể — About section hiện đúng string
powershell -NoProfile -ExecutionPolicy Bypass -File .\windows\scripts\build-unpackaged.ps1 -Version "0.1.12-test"
CMD:
REM Dev build — About section hiện "0.0.0-dev"
powershell -NoProfile -ExecutionPolicy Bypass -File .\windows\scripts\build-unpackaged.ps1
REM Build với version cụ thể — About section hiện đúng string
powershell -NoProfile -ExecutionPolicy Bypass -File .\windows\scripts\build-unpackaged.ps1 -Version "0.1.12-test"
Chạy trực tiếp exe để test nhanh mà không cần cài installer:
Git Bash / MSYS2:
./windows/Gridex/x64/Release/Gridex/Gridex.exe
PowerShell / CMD:
.\windows\Gridex\x64\Release\Gridex\Gridex.exe
Bước 3 — Pack Setup.exe
Git Bash / MSYS2:
powershell -NoProfile -ExecutionPolicy Bypass -File ./windows/scripts/pack-velopack.ps1 -Version "0.1.12-test"
PowerShell:
powershell -NoProfile -ExecutionPolicy Bypass -File .\windows\scripts\pack-velopack.ps1 -Version "0.1.12-test"
CMD:
powershell -NoProfile -ExecutionPolicy Bypass -File .\windows\scripts\pack-velopack.ps1 -Version "0.1.12-test"
Lưu ý: -Version truyền vào pack-velopack.ps1 phải khớp với -Version truyền vào build-unpackaged.ps1, nếu không thì Velopack sẽ in một số, còn About section của app sẽ in số khác. Dùng build-and-pack.ps1 ở trên để tránh trường hợp này.
Version stamping — cách hoạt động
windows/Gridex/GridexVersion.h— include unconditional file generatedwindows/Gridex/GridexVersion.generated.h— auto-generated, gitignored, dobuild-unpackaged.ps1ghi mỗi lần chạy- Có
-Version→#define GRIDEX_VERSION L"0.1.12" - Không
-Version→#define GRIDEX_VERSION L"0.0.0-dev"
- Có
windows/Gridex/SettingsPage.xaml.cpp— đọcGRIDEX_VERSIONvà set vàoVersionTexttext block- CI workflow
.github/workflows/windows-release.ymltự parse version từ git tag (v0.1.12→0.1.12) và forward sang script
Build script chỉ rewrite GridexVersion.generated.h khi nội dung khác → không force recompile vô ích.
Channels (optional)
Mặc định Velopack dùng channel stable. Nếu muốn phát hành kênh riêng (beta/nightly):
Git Bash / MSYS2:
powershell -NoProfile -ExecutionPolicy Bypass -File ./windows/scripts/build-and-pack.ps1 -Version "0.1.12-beta.1" -Channel "beta"
PowerShell:
powershell -NoProfile -ExecutionPolicy Bypass -File .\windows\scripts\build-and-pack.ps1 -Version "0.1.12-beta.1" -Channel "beta"
CMD:
powershell -NoProfile -ExecutionPolicy Bypass -File .\windows\scripts\build-and-pack.ps1 -Version "0.1.12-beta.1" -Channel "beta"
Output sẽ là Gridex-beta-Setup.exe + releases.beta.json — auto-updater phân luồng theo channel.
Troubleshooting
MSBuild.exe not found
Chưa cài VS 2022 với workload C++. Cài từ: https://visualstudio.microsoft.com/downloads/
dotnet SDK not found on PATH
Cài .NET 8 SDK (hoặc mới hơn) từ: https://dot.net/download
running scripts is disabled on this system (SecurityError / UnauthorizedAccess)
Thiếu flag -ExecutionPolicy Bypass trong lệnh powershell. Dùng đúng các lệnh trong README (đã có sẵn flag).
cd: E:devbevura: No such file or directory trong Git Bash
Bash parse \d, \b, \v thành escape sequence → path hỏng. Fix bằng 1 trong 3 cách:
- Forward slash:
cd /e/dev/be/vura - Single quote:
cd 'E:\dev\be\vura' - Escape backslash:
cd E:\\dev\\be\\vura
vpk installed but not on PATH
Thêm %USERPROFILE%\.dotnet\tools vào PATH rồi mở lại terminal.
packages\Microsoft.Web.WebView2...\build\native\Microsoft.Web.WebView2.targets not found
NuGet restore chưa chạy. Script có gọi MSBuild /t:Restore /p:RestorePackagesConfig=true rồi — nếu lỗi, check windows/NuGet.Config còn không.
vcpkg install failed hoặc link lỗi cannot open libpq.lib
Chưa cài đủ vcpkg deps. Xem section "Cài vcpkg deps" ở đầu file.
Gridex.exe crash ngay khi khởi động với MSVCP140.dll not found
Máy thiếu VC++ 2015-2022 Redistributable. Script build-unpackaged.ps1 tự copy CRT DLLs vào output folder → nếu vẫn lỗi thì check VS install path / logs script.
Setup.exe cài xong nhưng About hiện 0.0.0-dev dù pack với -Version 0.1.12
Dùng build-and-pack.ps1 thay vì gọi pack-velopack.ps1 trực tiếp. Trường hợp chạy pack-velopack.ps1 với version khác version lúc build Gridex.exe → xóa windows\Gridex\x64\Release\ rồi build lại đúng thứ tự.
Lỗi pwsh.exe exited with code 9009 trong vcpkg applocal step
Bỏ qua — PowerShell Core chưa cài, vcpkg tự fallback sang powershell.exe ngay sau đó. Không ảnh hưởng build.
Có ký tự lạ [200~ hoặc ~ xuất hiện khi paste
Terminal đang bật bracketed paste mode. Fix: tắt bằng printf '\e[?2004l' (bash) hoặc chuyển sang terminal khác (Windows Terminal thường không bị).
Cleanup
Xoá artifacts sau khi test:
Git Bash / MSYS2:
rm -rf ./windows/Gridex/x64 ./windows/Releases ./windows/Gridex/GridexVersion.generated.h
PowerShell:
Remove-Item -Recurse -Force .\windows\Gridex\x64, .\windows\Releases, .\windows\Gridex\GridexVersion.generated.h -ErrorAction SilentlyContinue
CMD:
rmdir /s /q .\windows\Gridex\x64
rmdir /s /q .\windows\Releases
del /q .\windows\Gridex\GridexVersion.generated.h
CI Release (tham khảo)
CI tự chạy khi push tag matching v*.*.*:
git tag v0.1.12
git push origin v0.1.12
GitHub Actions workflow windows-release.yml sẽ tự build + pack + upload assets lên GitHub Release. Xem chi tiết ở .github/workflows/windows-release.yml.