# Building Yemaya Desktop

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](./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:

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

- [Electron Forge Documentation](https://www.electronforge.io/)
- [Code Signing Guide](./CODE_SIGNING.md)
- [Electron Auto-Update](https://www.electronjs.org/docs/latest/api/auto-updater)
