Add BUILDING.md with uv and PyInstaller build instructions

Comprehensive guide covering:
- Installing uv on Windows/Linux/macOS
- Building executables with uv run pyinstaller
- Platform-specific build commands
- Troubleshooting common issues
- Detailed cleanup instructions for build artifacts
- Clean rebuild commands for all platforms
- Alternative pip-based build approach

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

BUILDING.md

@@ -0,0 +1,239 @@
+# Building MacroPad Server
+
+This guide explains how to build standalone executables for MacroPad Server using `uv` and PyInstaller.
+
+## Prerequisites
+
+### Install uv
+
+**Windows (PowerShell):**
+```powershell
+irm https://astral.sh/uv/install.ps1 | iex
+```
+
+**Linux/macOS:**
+```bash
+curl -LsSf https://astral.sh/uv/install.sh | sh
+```
+
+### Clone the Repository
+
+```bash
+git clone https://repo.anhonesthost.net/MacroPad/MP-Server.git
+cd MP-Server
+```
+
+## Building Executables
+
+> **Important:** PyInstaller cannot cross-compile. You must build on the target platform:
+> - Windows executables → build on Windows
+> - Linux executables → build on Linux
+> - macOS executables → build on macOS
+
+### Step 1: Install Dependencies
+
+```bash
+uv sync
+```
+
+### Step 2: Add PyInstaller
+
+```bash
+uv add --dev pyinstaller
+```
+
+### Step 3: Build for Your Platform
+
+#### Windows
+
+```powershell
+uv run pyinstaller macropad.spec
+```
+
+The executable will be created at: `dist\macropad.exe`
+
+#### Linux
+
+```bash
+# Install system dependencies first (Ubuntu/Debian)
+sudo apt-get update
+sudo apt-get install -y libxcb-xinerama0 libxkbcommon-x11-0 libegl1
+
+# Build
+uv run pyinstaller macropad_linux.spec
+```
+
+The executable will be created at: `dist/macropad`
+
+#### macOS
+
+```bash
+uv run pyinstaller macropad_macos.spec
+```
+
+The app bundle will be created at: `dist/MacroPad Server.app`
+
+## Build Output
+
+After a successful build, you'll find the executable in the `dist/` directory:
+
+| Platform | Output |
+|----------|--------|
+| Windows | `dist/macropad.exe` |
+| Linux | `dist/macropad` |
+| macOS | `dist/MacroPad Server.app` |
+
+## Troubleshooting
+
+### Missing Hidden Imports
+
+If you get import errors when running the built executable, you may need to add hidden imports to the `.spec` file:
+
+```python
+hiddenimports=[
+    'missing_module_name',
+    # ... existing imports
+],
+```
+
+### Linux: PySide6 Display Issues
+
+Ensure you have the required Qt libraries:
+
+```bash
+sudo apt-get install -y \
+    libxcb-xinerama0 \
+    libxkbcommon-x11-0 \
+    libegl1 \
+    libxcb-cursor0
+```
+
+### Linux: System Tray Issues
+
+For system tray support on Linux:
+
+```bash
+sudo apt-get install -y \
+    libgtk-3-dev \
+    gir1.2-appindicator3-0.1
+```
+
+### Windows: Antivirus False Positives
+
+PyInstaller executables may trigger antivirus warnings. This is a known issue with PyInstaller-built applications. You may need to add an exception in your antivirus software.
+
+### macOS: Unsigned Application
+
+The built app is unsigned and will trigger Gatekeeper:
+
+1. Right-click the app → Open
+2. Or: `xattr -cr "dist/MacroPad Server.app"`
+
+## Development Builds
+
+For debugging, you can enable console output by editing the `.spec` file:
+
+```python
+exe = EXE(
+    ...
+    console=True,  # Change from False to True
+    ...
+)
+```
+
+## Cleaning Up
+
+PyInstaller creates several directories and files during the build process. Here's how to clean them up:
+
+### Build Artifacts
+
+| Directory/File | Description |
+|----------------|-------------|
+| `build/` | Temporary build files (can be large) |
+| `dist/` | Final executable output |
+| `*.spec` | Spec files (keep these - they're source files) |
+| `__pycache__/` | Python bytecode cache |
+
+### Clean Commands
+
+#### Windows (PowerShell)
+
+```powershell
+# Remove build artifacts
+Remove-Item -Recurse -Force build, dist -ErrorAction SilentlyContinue
+
+# Also clear Python cache (optional)
+Get-ChildItem -Recurse -Directory -Name __pycache__ | Remove-Item -Recurse -Force
+```
+
+#### Windows (Command Prompt)
+
+```cmd
+rmdir /s /q build dist
+```
+
+#### Linux/macOS
+
+```bash
+# Remove build artifacts
+rm -rf build/ dist/
+
+# Also clear Python cache (optional)
+find . -type d -name __pycache__ -exec rm -rf {} + 2>/dev/null
+```
+
+### Clean Rebuild
+
+To perform a completely clean rebuild:
+
+#### Windows (PowerShell)
+
+```powershell
+Remove-Item -Recurse -Force build, dist -ErrorAction SilentlyContinue
+uv run pyinstaller macropad.spec
+```
+
+#### Linux
+
+```bash
+rm -rf build/ dist/
+uv run pyinstaller macropad_linux.spec
+```
+
+#### macOS
+
+```bash
+rm -rf build/ dist/
+uv run pyinstaller macropad_macos.spec
+```
+
+### Space Recovery
+
+The `build/` directory can consume significant disk space (often 500MB+). If you're done testing, remove it:
+
+```bash
+# Keep the executable, remove build intermediates
+rm -rf build/
+```
+
+## Alternative: Using pip
+
+If you prefer not to use uv:
+
+```bash
+# Create virtual environment
+python -m venv .venv
+
+# Activate it
+# Windows:
+.venv\Scripts\activate
+# Linux/macOS:
+source .venv/bin/activate
+
+# Install dependencies
+pip install -e .
+pip install pyinstaller
+
+# Build
+pyinstaller macropad.spec
+```