Eve library

Building Yemaya Desktop

Guide

Revision 1

On this page

This document explains how to build installer packages for Yemaya Desktop on Windows, macOS, and Linux.

Prerequisites#

All Platforms#

  • Node.js 20.x or later
  • pnpm 10.x or later
  • Git

Windows#

  • Windows 10/11
  • Visual Studio Build Tools (for native modules)
  • Windows SDK (for code signing)

macOS#

  • macOS 13+ (Ventura or later)
  • Xcode Command Line Tools
  • Apple Developer certificate (for signing/notarization)

Linux#

  • Ubuntu 20.04+ or equivalent
  • rpm, fakeroot, dpkg packages for building installers

Quick Start#

bash
# Clone the repository
git clone https://github.com/yemaya/yemaya.git
cd yemaya

# Install dependencies
pnpm install

# Build the desktop app
cd apps/yemaya/studio-desktop
pnpm build

# Create installer for current platform
pnpm make

Generating Icons#

Before building, generate platform-specific icons from the source SVG:

bash
# Install icon generation dependencies
npm install sharp png-to-ico

# Generate icons
pnpm generate-icons

Required Icon Files#

File Platform Size Description
icon.png All 512x512 Primary application icon
icon.ico Windows Multi Windows icon (16-256px)
icon.icns macOS Multi macOS icon bundle
dmg-background.png macOS 540x380 DMG installer background
installing.gif Windows - Squirrel installer animation

macOS Icon Generation#

On macOS, use iconutil to create .icns:

bash
# Create iconset directory
mkdir icon.iconset

# Copy PNG files with correct names
cp icon-16.png icon.iconset/icon_16x16.png
cp icon-32.png icon.iconset/icon_16x16@2x.png
cp icon-32.png icon.iconset/icon_32x32.png
cp icon-64.png icon.iconset/icon_32x32@2x.png
cp icon-128.png icon.iconset/icon_128x128.png
cp icon-256.png icon.iconset/icon_128x128@2x.png
cp icon-256.png icon.iconset/icon_256x256.png
cp icon-512.png icon.iconset/icon_256x256@2x.png
cp icon-512.png icon.iconset/icon_512x512.png
cp icon-1024.png icon.iconset/icon_512x512@2x.png

# Generate icns
iconutil -c icns icon.iconset -o icon.icns

Build Commands#

Development Build#

bash
# Build for development (no packaging)
pnpm build

# Start the app in development mode
pnpm dev

Package Without Installer#

bash
# Package the app (creates executable but no installer)
pnpm package

Create Installers#

bash
# Build installer for current platform
pnpm make

# Build for specific platform
pnpm make --platform darwin     # macOS
pnpm make --platform win32      # Windows
pnpm make --platform linux      # Linux

# Build for specific architecture
pnpm make --arch x64            # Intel/AMD 64-bit
pnpm make --arch arm64          # Apple Silicon / ARM64

Publish to GitHub Releases#

bash
# Publish to GitHub (requires GITHUB_TOKEN)
pnpm publish

Code Signing#

macOS#

Set these environment variables for code signing and notarization:

bash
export APPLE_ID="your@email.com"
export APPLE_PASSWORD="xxxx-xxxx-xxxx-xxxx"
export APPLE_TEAM_ID="ABCD1234EF"

Verify your signing configuration:

bash
pnpm check-signing

See CODE_SIGNING.md for detailed setup instructions.

Windows#

Set these environment variables for Windows signing:

bash
export WINDOWS_CERTIFICATE_FILE="/path/to/certificate.pfx"
export WINDOWS_CERTIFICATE_PASSWORD="your-password"

CI/CD Build#

The desktop build workflow (.github/workflows/desktop-build.yml) automatically:

  1. Runs on pushes to main that affect desktop code
  2. Tests the application
  3. Builds installers for all platforms in parallel
  4. Uploads build artifacts
  5. Optionally publishes to GitHub Releases

Required Secrets#

Configure these secrets in your GitHub repository:

Secret Description
APPLE_ID Apple ID email for notarization
APPLE_PASSWORD App-specific password for Apple
APPLE_TEAM_ID Apple Developer Team ID
WINDOWS_CERTIFICATE_FILE Base64-encoded .pfx certificate
WINDOWS_CERTIFICATE_PASSWORD Certificate password
GITHUB_TOKEN Auto-provided by GitHub Actions

Manual Release#

Trigger a release build manually:

  1. Go to Actions > Desktop Build
  2. Click "Run workflow"
  3. Enable "Publish release to GitHub"
  4. Click "Run workflow"

Build Output#

After building, find installers in:

text
apps/yemaya/studio-desktop/out/make/
├── squirrel.windows/
│   └── x64/
│       ├── Yemaya-{version} Setup.exe
│       └── yemaya-{version}-full.nupkg
├── dmg/
│   └── Yemaya-{version}-{arch}.dmg
├── zip/
│   └── darwin/
│       └── Yemaya-darwin-{arch}-{version}.zip
├── deb/
│   └── x64/
│       └── yemaya_{version}_amd64.deb
└── rpm/
    └── x64/
        └── yemaya-{version}.x86_64.rpm

Troubleshooting#

Build Fails on Windows#

Native module compilation errors:

  • Install Visual Studio Build Tools
  • Run from "x64 Native Tools Command Prompt"

Signing errors:

  • Verify certificate file path is correct
  • Check certificate password
  • Ensure certificate hasn't expired

Build Fails on macOS#

Signing identity not found:

bash
security find-identity -v -p codesigning

Ensure your Developer ID Application certificate is installed.

Notarization fails:

  • Verify App-Specific Password is correct
  • Check Apple Developer account status
  • Review notarization log for specific issues

"App is damaged" error:

bash
xattr -cr /Applications/Yemaya.app

Build Fails on Linux#

Missing dependencies:

bash
sudo apt-get update
sudo apt-get install -y rpm fakeroot dpkg

Permission errors:

bash
chmod +x node_modules/.bin/*

Performance Tips#

  1. Use caching - CI caches node_modules to speed up builds
  2. Build in parallel - Each platform builds on its own runner
  3. Skip tests for releases - Use --skip-tests flag for production builds
  4. Use ARM runners - Apple Silicon builds are faster on native runners

Additional Resources#