# 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
```