<!-- Generated: 2025-06-14 21:30:00 UTC -->

# Build System Documentation

## Overview

Yakety uses CMake 3.20+ as its primary build system with multi-language support (C, C++, Swift). The build system is configured through:

- **Main CMake file**: `CMakeLists.txt` - Primary build configuration
- **Build presets**: `CMakePresets.json` - Platform-specific build configurations
- **Helper modules**: `cmake/` directory with modular build logic
  - `cmake/BuildWhisper.cmake` - Whisper.cpp dependency management
  - `cmake/PlatformSetup.cmake` - Platform-specific libraries and frameworks
  - `cmake/GenerateIcons.cmake` - Asset generation from SVG sources

The system automatically handles whisper.cpp dependency building, model downloading, icon generation, and platform-specific configurations.

## Build Workflows

### Quick Start Commands

**Development builds:**
```bash
# Release build (recommended for development)
cmake --preset release
cmake --build --preset release

# Debug build
cmake --preset debug
cmake --build --preset debug
```

**Windows debugging with Visual Studio:**
```bash
# Only on Windows - enables Visual Studio debugging
cmake --preset vs-debug
cmake --build --preset vs-debug
```

**Distribution packaging:**
```bash
# Build and package for current platform
cmake --build --preset release
cmake --build build --target package

# Platform-specific packages
cmake --build build --target package-macos    # macOS only
cmake --build build --target package-windows  # Windows only

# Upload to server (requires SSH access)
cmake --build build --target upload
```

### Build Targets

The build system generates these executables in `build/bin/`:

- **yakety-cli** - Command-line interface
- **yakety-app** - GUI application (platform-specific bundle)
- **recorder** - Audio recording utility
- **transcribe** - Standalone transcription tool
- **test-*** - Platform-specific test executables (macOS only)

### Asset Generation

Icons are automatically generated from `assets/yakety.svg`:
```bash
# Manual icon regeneration (automatic during build)
cmake --build build --target generate_icons
```

Requires: `rsvg-convert` (librsvg) and `magick` (ImageMagick)

## Platform Setup

### macOS Requirements

- **Xcode Command Line Tools**: Required for Swift compiler
- **macOS 14.0+**: Minimum deployment target
- **Apple Silicon (ARM64)**: Target architecture
- **System frameworks**: Automatically linked
  - CoreFoundation, AppKit, AudioToolbox, AVFoundation
  - Metal frameworks for GPU acceleration

**Dependencies:**
```bash
# Install build tools via Homebrew
brew install librsvg imagemagick ninja cmake
```

### Windows Requirements

- **Visual Studio 2022**: For MSVC compiler and debugging
- **CMake 3.20+**: Build system
- **Ninja**: Fast builds (included in VS2022)
- **Vulkan SDK**: Optional GPU acceleration

**Environment setup:**
- Set VULKAN_SDK environment variable for GPU support
- Use `winvs.bat` script for proper Visual Studio environment

### Windows/WSL Remote Development

For development from macOS to Windows via SSH:

**Setup scripts:**
- `wsl/start-wsl-ssh.bat` - Run as Administrator on Windows
- `wsl/setup-wsl-ssh.sh` - Configure SSH in WSL

**Sync and build workflow:**
```bash
# 1. Sync source files (excludes build directories)
rsync -av --exclude='build/' --exclude='build-debug/' --exclude='whisper.cpp/' \
  . badlogic@192.168.1.21:/mnt/c/workspaces/yakety/

# 2. Configure build
ssh badlogic@192.168.1.21 "cd /mnt/c/workspaces/yakety && \
  /mnt/c/Windows/System32/cmd.exe /c 'cd c:\\workspaces\\yakety && \
  c:\\workspaces\\winvs.bat && cmake --preset release'"

# 3. Build
ssh badlogic@192.168.1.21 "cd /mnt/c/workspaces/yakety && \
  /mnt/c/Windows/System32/cmd.exe /c 'cd c:\\workspaces\\yakety && \
  c:\\workspaces\\winvs.bat && cmake --build --preset release'"

# 4. Run CLI
ssh badlogic@192.168.1.21 "cd /mnt/c/workspaces/yakety && \
  build/bin/yakety-cli.exe"
```

### Linux Requirements (Experimental)

- **GCC/Clang**: C/C++ compiler
- **ALSA/PulseAudio**: Audio system libraries
- **CMake 3.20+**, **Ninja**: Build tools

## Reference

### CMake Presets

From `CMakePresets.json`:

**Configure presets:**
- `release` - Ninja generator, Release build, `build/` directory
- `debug` - Ninja generator, Debug build, `build-debug/` directory  
- `vs-debug` - Visual Studio 2022, Windows-only debugging

**Build presets:**
- `release` - Build release configuration
- `debug` - Build debug configuration
- `vs-debug` - Build Windows VS debug configuration

### Whisper.cpp Integration

Automatic dependency management via `cmake/BuildWhisper.cmake`:

- **Auto-clone**: Downloads whisper.cpp from GitHub if missing
- **Platform optimization**: 
  - macOS: Metal GPU acceleration, ARM64 architecture
  - Windows: Native CPU optimization, optional Vulkan GPU
- **Model download**: Automatically downloads ggml-base-q8_0.bin (110MB)
- **Static linking**: All whisper libraries statically linked

### Code Signing (macOS)

Automatic ad-hoc signing via `cmake/PlatformSetup.cmake`:
```bash
# Manual signing
./sign-app.sh  # Signs and removes quarantine
```

### Troubleshooting

**Whisper.cpp build failures:**
- Verify internet connection for auto-download
- Check disk space (whisper.cpp ~500MB + model ~110MB)
- On Windows: Ensure Visual Studio environment is loaded

**Swift compilation warnings:**
- Incremental compilation disabled via CMAKE_Swift_FLAGS
- Normal for mixed C/Swift projects

**Icon generation failures:**
- Install librsvg: `brew install librsvg` (macOS) or `apt install librsvg2-bin` (Linux)
- Install ImageMagick: `brew install imagemagick` (macOS)

**Windows Vulkan not detected:**
- Install Vulkan SDK and set VULKAN_SDK environment variable
- Restart command prompt after installation

**Linking errors:**
- Clean build directories: `rm -rf build build-debug`
- Rebuild whisper.cpp: `rm -rf whisper.cpp/build`
- On Windows: Match Debug/Release configuration with whisper.cpp