trainer/BUILD.md

Building RideAware Trainer

Quick Start

Local Development Build

npm run electron:dev

Production Builds

Linux (from Linux)

npm run electron:build:linux

Builds: AppImage, deb, rpm (requires Ubuntu/Debian for deb/rpm)

Windows (from Windows)

npm run electron:build:win

Builds: NSIS installer (.exe)

macOS (from macOS)

npm run electron:build:mac

Builds: DMG, ZIP

Cross-Platform Builds with GitHub Actions

The easiest way to build for all platforms is using GitHub Actions:

Automatic Release Build

git tag v1.0.1
git push origin v1.0.1

This triggers the workflow which:

1. Builds on Windows, macOS, and Linux runners
2. Creates a GitHub Release
3. Uploads all installers (exe, dmg, AppImage, deb, rpm)

Manual Build

Go to: GitHub → Actions → Build and Release → Run workflow

Build Artifacts

After building, files are in the release/ directory:

• Windows: RideAware Trainer Setup 1.0.0.exe
• macOS: RideAware Trainer-1.0.0-arm64.dmg, RideAware Trainer-1.0.0-arm64-mac.zip
• Linux:
  • RideAware Trainer-1.0.0.AppImage (universal)
  • rideaware-trainer_1.0.0_amd64.deb (Debian/Ubuntu)
  • rideaware-trainer-1.0.0.x86_64.rpm (Fedora/RHEL)

Platform Limitations

Building from Linux

• ✅ Linux packages (AppImage always works, deb/rpm need Ubuntu)
• ❌ macOS DMG (requires macOS-specific dependencies)
• ❌ Windows EXE (requires Windows or Wine)

Building from macOS

• ✅ macOS packages (DMG, ZIP)
• ✅ Linux packages (with Docker)
• ❌ Windows EXE (requires Windows or Wine)

Building from Windows

• ✅ Windows packages (EXE)
• ✅ Linux packages (with WSL/Docker)
• ❌ macOS DMG (requires macOS)

Recommendation: Use GitHub Actions for cross-platform builds.

Icon Requirements

Place app icons in the build/ directory:

• build/icon.ico - Windows (256x256)
• build/icon.icns - macOS (1024x1024)
• build/icon.png - Linux (512x512)

Troubleshooting

"dmg-license not found" on Linux

This is expected. Build macOS packages on macOS or use GitHub Actions.

"libcrypt.so.1 not found" on Fedora

Install compatibility package or use GitHub Actions (runs on Ubuntu).

Build hangs on "packaging"

Check available disk space. Electron builds can use 500MB+ per platform.

GitHub Actions Workflow

The workflow file is at .github/workflows/build.yml.

Triggers:

• Push to main branch (builds but doesn't release)
• Push tag starting with v (builds and creates release)
• Manual workflow dispatch
• Pull requests (builds but doesn't release)

Permissions needed:

• Repository Settings → Actions → General → Workflow permissions
• Enable "Read and write permissions"