MP-Server/BUILDING.md

Building MacroPad Server

This guide explains how to build standalone executables for MacroPad Server using uv and PyInstaller.

Prerequisites

Install uv

Windows (PowerShell):

irm https://astral.sh/uv/install.ps1 | iex

Linux/macOS:

curl -LsSf https://astral.sh/uv/install.sh | sh

Clone the Repository

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

uv sync

Step 2: Add PyInstaller

uv add --dev pyinstaller

Step 3: Build for Your Platform

Windows

uv run pyinstaller macropad.spec

The executable will be created at: dist\macropad.exe

Linux

# 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

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:

hiddenimports=[
    'missing_module_name',
    # ... existing imports
],

Linux: PySide6 Display Issues

Ensure you have the required Qt libraries:

sudo apt-get install -y \
    libxcb-xinerama0 \
    libxkbcommon-x11-0 \
    libegl1 \
    libxcb-cursor0

Linux: System Tray Issues

For system tray support on Linux:

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:

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)

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

rmdir /s /q build dist

Linux/macOS

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

Remove-Item -Recurse -Force build, dist -ErrorAction SilentlyContinue
uv run pyinstaller macropad.spec

Linux

rm -rf build/ dist/
uv run pyinstaller macropad_linux.spec

macOS

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:

# Keep the executable, remove build intermediates
rm -rf build/

Alternative: Using pip

If you prefer not to use uv:

# 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