Commonwealth-Online-Public/host-gui/DEPLOYMENT.md

Commonwealth Online GUI - Deployment Guide

Quick Start - Running the GUI

First Time Setup (Deploy Qt DLLs)

The executable needs Qt6 runtime libraries. Deploy them once:

cd host-gui
deploy.bat

This copies all required Qt6 DLLs and plugins to the Release folder.

Running the Application

After deployment, simply:

# Double-click this file:
build/bin/Release/CommonwealthOnlineHost.exe

# Or run from command line:
cd build/bin/Release
CommonwealthOnlineHost.exe

---

Distribution

To distribute the application to other machines:

Option 1: Copy Entire Folder (Easiest)

Release/
├── CommonwealthOnlineHost.exe
├── Qt6Core.dll
├── Qt6Gui.dll
├── Qt6Widgets.dll
├── Qt6Network.dll
├── Qt6Concurrent.dll
├── Qt6DBus.dll
├── Qt6Xml.dll
└── plugins/
    ├── platforms/
    ├── styles/
    └── imageformats/

Just zip and send this folder - everything needed is included.

Option 2: Use Qt Deployment Tool (Advanced)

Qt provides windeployqt.exe for automatic deployment:

C:\Qt\6.11.1\msvc2022_64\bin\windeployqt.exe build/bin/Release/CommonwealthOnlineHost.exe

---

Requirements for Users

Recipients of the .exe need only:

• Windows 10 or later
• Python 3.9+ (for running the relay server)
• No Visual Studio or Qt installation needed

---

Troubleshooting

"Entry point not found" error

The DLLs weren't deployed. Run:

deploy.bat

"The procedure entry point... could not be located"

Likely a missing or incompatible DLL. Try redeploying:

# Clean old DLLs
del build\bin\Release\*.dll

# Redeploy
deploy.bat

Application window doesn't appear

The GUI may have launched but is hidden. Check:

1. Task Manager for CommonwealthOnlineHost.exe process
2. Try running from command line to see error messages
3. Ensure Python and server directory are accessible

---

Development Build vs Release Build

For Development:

# Just build (DLLs not deployed)
build.bat

For Distribution:

# Build + deploy DLLs
build.bat
deploy.bat

---

Next Steps

1. Test Locally

   • Run CommonwealthOnlineHost.exe
   • Click "Start Server"
   • Run fake_client.py from server folder
   • Verify client appears in table

2. Package for Release

   • Run deploy.bat
   • Zip build/bin/Release/ folder
   • Distribute to users

3. Create Installer (Future Enhancement)

   • Use NSIS or WiX to create .msi installer
   • Automatically handles DLL deployment
   • Adds Start Menu shortcuts
   • Enables uninstall

---

File Locations

host-gui/
├── CMakeLists.txt           # Build configuration
├── build.bat                # Compile application
├── deploy.bat               # Deploy Qt DLLs ← Run this after build.bat
├── check-setup.bat          # Verify prerequisites
├── find-qt.bat              # Locate Qt6 installation
├── README.md                # User guide
├── SETUP.md                 # Setup instructions
├── src/                     # Source code
└── build/
    └── bin/
        └── Release/
            ├── CommonwealthOnlineHost.exe
            ├── Qt6*.dll                    # Runtime libraries
            └── plugins/                    # Qt plugins

---

Creating a Portable Distribution

To create a self-contained package anyone can run:

# Build the application
cd host-gui
build.bat

# Deploy DLLs
deploy.bat

# Create distribution package
mkdir Commonwealth-Online-Host
xcopy /I /E build\bin\Release Commonwealth-Online-Host\
xcopy /I server ..\Commonwealth-Online-Host\server\
copy README.md Commonwealth-Online-Host\README.txt

# Zip and distribute
# Send Commonwealth-Online-Host.zip to users

Users extract and run CommonwealthOnlineHost.exe - no setup needed!

---

Support

If users encounter issues:

1. Ensure deployment completed successfully (see output)
2. Verify Python is installed and in PATH
3. Check that server folder exists next to executable
4. Run from command line to see detailed error messages

---

Performance Notes

• Startup time: <1 second
• Memory usage: ~80-150 MB
• CPU: Minimal (event-driven)
• DLL size: ~100-150 MB total (but only loaded once)

Deploy once, run forever! 🚀