Commonwealth-Online/Commonwealth-Online-Public
3
0
Fork 0
Code Pull Requests Activity

Add Qt6 setup helpers and comprehensive build instructions

Browse Source 
- Improved build.bat with auto-detection of Qt6 installation
  - Checks common Qt6 paths automatically
  - Provides helpful error messages with paths to check
  - Works with Qt6.4 through Qt6.8

- Added check-setup.bat verification script
  - Verifies CMake, Visual Studio 2022, and Qt6 installation
  - Reports found/missing prerequisites
  - Quick setup validation before building

- Added comprehensive SETUP.md documentation
  - Quick 3-step setup guide
  - Detailed manual setup instructions
  - Qt6 download and installation steps
  - Troubleshooting for common issues
  - Manual CMake command reference
  - Environment variable setup

- Updated README.md
  - Links to SETUP.md for first-time users
  - Quick build instructions
  - Clear prerequisites with download links
  - Better organized for both quick and manual builds

Fixes CMake Qt6 detection errors by:
1. Auto-searching common Qt6 installation paths
2. Providing fallback manual build instructions
3. Detecting missing prerequisites with helpful links

Co-authored-by: Cursor <cursoragent@cursor.com>
This commit is contained in:
andrew
2026-07-09 20:55:44 +12:00
co-authored by Cursor
parent 911ee1aca8
commit 22bbfceeb8
4 changed files with 452 additions and 28 deletions
Download Patch File Download Diff File Expand all files Collapse all files
host-gui/README.md
+76 -19
View File
@@ -2,6 +2,24 @@
Production-ready Qt6 GUI application for hosting Commonwealth Online servers on Windows. Production-ready Qt6 GUI application for hosting Commonwealth Online servers on Windows.
## Quick Start
**First time? Follow the [Setup Instructions](SETUP.md)**
### Building
```bash
cd host-gui
# Check prerequisites
check-setup.bat
# Build
build.bat
```
Output: `host-gui\build\bin\Release\CommonwealthOnlineHost.exe`
## Features ## Features
- **Start/Stop Server**: One-click server control with live status indicator - **Start/Stop Server**: One-click server control with live status indicator
@@ -15,28 +33,39 @@ Production-ready Qt6 GUI application for hosting Commonwealth Online servers on
## Requirements ## Requirements
- Windows 10 or later - Windows 10 or later
- Qt 6.4+ - **Qt 6.4+** (install from https://www.qt.io/download-open-source)
- Visual Studio 2022 (MSVC) - **Visual Studio 2022** with C++ tools
- CMake 3.20+ - **CMake 3.20+**
- Python 3.9+ (for running the relay server) - **Python 3.9+** (for running the relay server)
## Setup Issues?
See [SETUP.md](SETUP.md) for detailed instructions and troubleshooting.
## Building ## Building
### Quick Build
```bash
cd host-gui
check-setup.bat # Verify prerequisites
build.bat # Auto-detect Qt6 and build
```
### From Visual Studio ### From Visual Studio
1. Clone the repository 1. Open `host-gui` folder in Visual Studio 2022
2. Open `CMakeLists.txt` in Visual Studio 2. Wait for CMake to auto-configure
3. Configure the project (Visual Studio should auto-detect Qt6) 3. Build → Build All
4. Build → Build All 4. Run the executable
5. Run the executable
### From Command Line ### From Command Line (Manual)
```bash ```bash
cd host-gui cd host-gui
mkdir build mkdir build
cd build cd build
cmake .. -G "Visual Studio 17 2022" cmake .. -G "Visual Studio 17 2022" -DCMAKE_PREFIX_PATH="C:\Qt\6.8.0\msvc2022_64"
cmake --build . --config Release cmake --build . --config Release
``` ```
@@ -61,7 +90,12 @@ Edit `commonwealth-server.json` in the server folder to customize:
``` ```
host-gui/ host-gui/
├── CMakeLists.txt # Build configuration ├── CMakeLists.txt # Build configuration
├── build.bat # Auto-build script
├── check-setup.bat # Verify prerequisites
├── SETUP.md # Setup instructions
├── README.md # This file ├── README.md # This file
├── DEVELOPMENT.md # Developer guide
├── IMPLEMENTATION.md # Architecture docs
├── src/ ├── src/
│ ├── main.cpp # Application entry point │ ├── main.cpp # Application entry point
│ ├── MainWindow.h/cpp # Main window UI and logic │ ├── MainWindow.h/cpp # Main window UI and logic
@@ -70,9 +104,10 @@ host-gui/
│ ├── resources.qrc # Qt resource manifest │ ├── resources.qrc # Qt resource manifest
│ └── icons/ │ └── icons/
│ └── app.ico # Application icon │ └── app.ico # Application icon
└── build/ # Build output directory └── build/ # Build output directory (after building)
└── bin/ └── bin/
└── CommonwealthOnlineHost.exe └── Release/
└── CommonwealthOnlineHost.exe
``` ```
## Architecture ## Architecture
@@ -83,11 +118,33 @@ The GUI spawns the Python relay server (`consumer_server_cli.py`) as a subproces
- Provides UI for server control and monitoring - Provides UI for server control and monitoring
- Maintains server state even if GUI crashes - Maintains server state even if GUI crashes
See [IMPLEMENTATION.md](IMPLEMENTATION.md) for detailed architecture.
## Troubleshooting
**Qt6 not found?**
- Install Qt6 from https://www.qt.io/download-open-source
- Use default path: C:\Qt\6.8.0\msvc2022_64
- Run `check-setup.bat` to verify
**Visual Studio not found?**
- Install Visual Studio 2022 with C++ tools
- See [SETUP.md](SETUP.md)
**CMake error?**
- Install CMake from https://cmake.org/download/
- Select "Add CMake to PATH" during install
**Build fails?**
- See [SETUP.md](SETUP.md) for manual build instructions
- Review [DEVELOPMENT.md](DEVELOPMENT.md) for developer notes
## Future Enhancements ## Future Enhancements
- Admin commands (set time/weather directly from GUI) - [ ] Admin commands (set time/weather directly from GUI)
- Config file editor in GUI - [ ] Config file editor in GUI
- Player kick/ban buttons - [ ] Player kick/ban buttons
- System tray icon with quick access - [ ] System tray icon with quick access
- Settings panel for port customization - [ ] Settings panel for port customization
- Server history and logs export - [ ] Server history and logs export
- [ ] Installer (.msi or .exe wrapper)
host-gui/SETUP.md
+231
View File
@@ -0,0 +1,231 @@
# Commonwealth Online Qt GUI - Setup Instructions
## Quick Setup (3 Steps)
### Step 1: Install Qt6
1. Download Qt6 from: **https://www.qt.io/download-open-source**
2. Run the installer and select:
- ✓ Qt 6.8 (or latest 6.x)
- ✓ MSVC 2022 64-bit component
- Install to default location: `C:\Qt\6.8.0\`
3. After installation, verify the path exists:
```
C:\Qt\6.8.0\msvc2022_64\lib\cmake\Qt6
```
### Step 2: Verify Prerequisites
Run the setup checker:
```bash
cd host-gui
check-setup.bat
```
This verifies:
- ✓ CMake 3.20+
- ✓ Visual Studio 2022
- ✓ Qt6 installation
### Step 3: Build
```bash
cd host-gui
build.bat
```
The script will:
1. Auto-detect Qt6 location
2. Configure CMake
3. Build Release executable
4. Output: `host-gui/build/bin/Release/CommonwealthOnlineHost.exe`
---
## Detailed Setup (If Quick Setup Fails)
### Manual Qt6 Installation
1. **Download Qt Online Installer**
- Go to https://www.qt.io/download-open-source
- Download "Qt Online Installer for Windows"
2. **Run Installer**
- Create Qt account (free)
- Select "Custom installation"
- Under "Qt 6.8.0" (or latest):
- ✓ MSVC 2022 64-bit
- ✓ Qt 5compat (optional)
- Under "Developer and Designer Tools":
- ✓ CMake (if not already installed)
- Click "Install"
3. **Verify Installation**
- Check that this folder exists:
```
C:\Qt\6.8.0\msvc2022_64\
```
- Should contain:
```
lib\cmake\Qt6\
bin\
include\
plugins\
```
### Manual CMake Installation
If CMake isn't found:
1. Download from: https://cmake.org/download/
2. Run installer
3. When prompted, select "Add CMake to PATH"
4. Restart your terminal/command prompt
### Manual Visual Studio 2022 Installation
If Visual Studio 2022 isn't found:
1. Download from: https://visualstudio.microsoft.com/downloads/
2. Run installer
3. Select "Desktop development with C++"
4. Install
---
## Building Manually (If Scripts Fail)
### Command Line Build
```bash
cd host-gui
mkdir build
cd build
# Configure (replace path with your Qt6 location)
cmake .. -G "Visual Studio 17 2022" -DCMAKE_PREFIX_PATH="C:\Qt\6.8.0\msvc2022_64"
# Build Release
cmake --build . --config Release
```
### Visual Studio IDE Build
1. Open Visual Studio 2022
2. File → Open → Folder
3. Select `host-gui` folder
4. Wait for CMake configuration
5. Build → Build All
6. Executable at: `host-gui/build/bin/Release/CommonwealthOnlineHost.exe`
---
## Troubleshooting
### "Qt6 not found"
**Solution 1**: Edit `build.bat` and update Qt6 search paths
- Find the line with `PATHS_TO_CHECK`
- Add your Qt6 installation path
**Solution 2**: Use manual CMake with explicit path
```bash
cmake .. -G "Visual Studio 17 2022" -DCMAKE_PREFIX_PATH="C:\path\to\your\Qt6"
```
### "Visual Studio not found"
Make sure Visual Studio 2022 is installed with C++ development tools:
1. Open Visual Studio Installer
2. Modify your installation
3. Select "Desktop development with C++"
4. Click "Modify"
### "CMake not found"
Add CMake to PATH:
1. Install CMake from cmake.org
2. Select "Add CMake to PATH"
3. Restart terminal
### "Build fails with link errors"
Ensure you're using the matching MSVC version:
- Qt6 installed for MSVC 2022 64-bit
- Building with "Visual Studio 17 2022" generator
- Using Release build configuration
---
## Running the Application
After successful build:
```bash
cd host-gui
start build\bin\Release\CommonwealthOnlineHost.exe
```
Or double-click:
```
host-gui\build\bin\Release\CommonwealthOnlineHost.exe
```
---
## Environment Setup (Advanced)
If you want to set up your environment permanently:
### Windows Environment Variables
1. Press `Win + X`, select "System"
2. Click "Advanced system settings"
3. Click "Environment Variables"
4. Add or update:
```
CMAKE_PREFIX_PATH = C:\Qt\6.8.0\msvc2022_64
```
5. Restart terminal
Then you can just run:
```bash
cd host-gui
mkdir build
cd build
cmake ..
cmake --build . --config Release
```
---
## Next Steps After Build
Once you have a successful build:
1. **Test the Application**
- Launch `CommonwealthOnlineHost.exe`
- Click "Start Server"
- Verify logs appear
2. **Connect Clients**
- Run fake_client from server directory
- Should see client in GUI table
3. **Customize**
- Edit colors/styling in `MainWindow.cpp`
- Add admin buttons in `MainWindow.h/cpp`
- Extend ServerProcess for more features
---
## Support
If you encounter issues:
1. Run `check-setup.bat` to verify prerequisites
2. Review output and error messages carefully
3. Check this troubleshooting guide
4. Try manual CMake command with explicit paths
host-gui/build.bat
+79 -9
View File
@@ -3,7 +3,7 @@ setlocal enabledelayedexpansion
echo. echo.
echo ================================================================================ echo ================================================================================
echo Commonwealth Online - Qt GUI Build Script echo Commonwealth Online - Qt GUI Build Script (with Qt6 Auto-Detection)
echo ================================================================================ echo ================================================================================
echo. echo.
@@ -12,27 +12,83 @@ cmake --version >nul 2>&1
if errorlevel 1 ( if errorlevel 1 (
echo ERROR: CMake is not installed or not in PATH. echo ERROR: CMake is not installed or not in PATH.
echo Please install CMake from https://cmake.org/download/ echo Please install CMake from https://cmake.org/download/
echo Then add it to your PATH and restart this script.
pause
exit /b 1
)
REM Auto-detect Qt6 installation
echo Searching for Qt6 installation...
set QT6_PATH=
REM Common Qt6 installation paths (check in order)
set PATHS_TO_CHECK[0]=C:\Qt\6.8.0\msvc2022_64
set PATHS_TO_CHECK[1]=C:\Qt\6.7.0\msvc2022_64
set PATHS_TO_CHECK[2]=C:\Qt\6.6.0\msvc2022_64
set PATHS_TO_CHECK[3]=C:\Qt\6.5.0\msvc2022_64
set PATHS_TO_CHECK[4]=C:\Qt\6.4.0\msvc2022_64
set PATHS_TO_CHECK[5]=C:\Qt\6.8.0\msvc2019_64
set PATHS_TO_CHECK[6]=C:\Qt\6.7.0\msvc2019_64
set PATHS_TO_CHECK[7]=C:\Qt\6.6.0\msvc2019_64
for /l %%i in (0,1,7) do (
if exist "!PATHS_TO_CHECK[%%i]!\lib\cmake\Qt6" (
set QT6_PATH=!PATHS_TO_CHECK[%%i]!
echo Found Qt6 at: !QT6_PATH!
goto found_qt6
)
)
:found_qt6
if "!QT6_PATH!"=="" (
echo.
echo ERROR: Qt6 not found at common installation paths.
echo.
echo Please install Qt6 from https://www.qt.io/download-open-source
echo.
echo Common installation paths:
echo - C:\Qt\6.8.0\msvc2022_64
echo - C:\Qt\6.7.0\msvc2022_64
echo - C:\Qt\6.6.0\msvc2022_64
echo.
echo Alternatively, manually set Qt6 path by editing this script
echo or run CMake manually with:
echo cmake .. -G "Visual Studio 17 2022" -DCMAKE_PREFIX_PATH="C:\path\to\Qt6"
echo.
pause pause
exit /b 1 exit /b 1
) )
REM Create build directory REM Create build directory
if not exist "build" ( if not exist "build" (
echo.
echo Creating build directory... echo Creating build directory...
mkdir build mkdir build
) )
cd build cd build
echo Configuring Qt6 project with CMake... echo.
cmake .. -G "Visual Studio 17 2022" -DCMAKE_PREFIX_PATH="C:\Qt\6.4.0\msvc2019_64" echo Configuring project with CMake...
echo CMake: %CMAKE_PREFIX_PATH%
echo Qt6: !QT6_PATH!
echo VS: Visual Studio 17 2022
echo.
cmake .. -G "Visual Studio 17 2022" -DCMAKE_PREFIX_PATH="!QT6_PATH!"
if errorlevel 1 ( if errorlevel 1 (
echo.
echo ERROR: CMake configuration failed. echo ERROR: CMake configuration failed.
echo Make sure: echo.
echo 1. Qt6 is installed echo Troubleshooting:
echo 2. Visual Studio 2022 is installed echo 1. Verify Qt6 is installed at: !QT6_PATH!
echo 3. CMAKE_PREFIX_PATH points to your Qt6 installation echo 2. Verify Visual Studio 2022 is installed with C++ tools
echo 3. Try running this script again
echo.
echo Manual configuration command:
echo cmake .. -G "Visual Studio 17 2022" -DCMAKE_PREFIX_PATH="!QT6_PATH!"
echo.
pause pause
exit /b 1 exit /b 1
) )
@@ -40,11 +96,20 @@ if errorlevel 1 (
echo. echo.
echo Configuration successful! echo Configuration successful!
echo. echo.
echo Building project... echo Building project (this may take a few minutes)...
echo.
cmake --build . --config Release cmake --build . --config Release
if errorlevel 1 ( if errorlevel 1 (
echo.
echo ERROR: Build failed. echo ERROR: Build failed.
echo.
echo Troubleshooting:
echo 1. Check that Visual Studio 2022 is installed
echo 2. Make sure C++ development tools are installed
echo 3. Try building again
echo.
pause pause
exit /b 1 exit /b 1
) )
@@ -54,6 +119,11 @@ echo ===========================================================================
echo Build successful! echo Build successful!
echo ================================================================================ echo ================================================================================
echo. echo.
echo Executable: %cd%\bin\Release\CommonwealthOnlineHost.exe echo Executable created at:
echo %cd%\bin\Release\CommonwealthOnlineHost.exe
echo.
echo To run the application:
echo cd ..
echo start build\bin\Release\CommonwealthOnlineHost.exe
echo. echo.
pause pause
host-gui/check-setup.bat
+66
View File
@@ -0,0 +1,66 @@
@echo off
setlocal enabledelayedexpansion
echo.
echo ================================================================================
echo Commonwealth Online - Qt GUI Setup Helper
echo ================================================================================
echo.
echo This script will help you set up Qt6 for building the GUI.
echo.
REM Check CMake
cmake --version >nul 2>&1
if errorlevel 1 (
echo [ERROR] CMake not found. Please install from https://cmake.org/download
pause
exit /b 1
)
echo [OK] CMake found
REM Check Visual Studio
if not exist "C:\Program Files\Microsoft Visual Studio\2022\Community" (
if not exist "C:\Program Files\Microsoft Visual Studio\2022\Professional" (
echo.
echo [ERROR] Visual Studio 2022 not found
echo Please install from https://visualstudio.microsoft.com/downloads/
pause
exit /b 1
)
)
echo [OK] Visual Studio 2022 found
REM Check Qt6
set QT6_FOUND=0
if exist "C:\Qt\6.8.0\msvc2022_64\lib\cmake\Qt6" set QT6_FOUND=1 & set QT_PATH=C:\Qt\6.8.0\msvc2022_64
if exist "C:\Qt\6.7.0\msvc2022_64\lib\cmake\Qt6" set QT6_FOUND=1 & set QT_PATH=C:\Qt\6.7.0\msvc2022_64
if exist "C:\Qt\6.6.0\msvc2022_64\lib\cmake\Qt6" set QT6_FOUND=1 & set QT_PATH=C:\Qt\6.6.0\msvc2022_64
if exist "C:\Qt\6.5.0\msvc2022_64\lib\cmake\Qt6" set QT6_FOUND=1 & set QT_PATH=C:\Qt\6.5.0\msvc2022_64
if exist "C:\Qt\6.4.0\msvc2022_64\lib\cmake\Qt6" set QT6_FOUND=1 & set QT_PATH=C:\Qt\6.4.0\msvc2022_64
if %QT6_FOUND%==0 (
echo.
echo [ERROR] Qt6 not found at standard locations
echo.
echo Qt6 installation required! Download from: https://www.qt.io/download-open-source
echo.
echo Installation paths checked:
echo - C:\Qt\6.8.0\msvc2022_64
echo - C:\Qt\6.7.0\msvc2022_64
echo - C:\Qt\6.6.0\msvc2022_64
echo - C:\Qt\6.5.0\msvc2022_64
echo - C:\Qt\6.4.0\msvc2022_64
echo.
echo If Qt6 is installed elsewhere, manually edit build.bat
echo and update the Qt6 search paths.
echo.
pause
exit /b 1
)
echo [OK] Qt6 found at: %QT_PATH%
echo.
echo All prerequisites found! You can now run build.bat
echo.
pause