How frankea/whisky works
1. Overall shape
- Whisky is a macOS Swift/SwiftUI application with a shared core library, plus two auxiliary targets: a command-line tool (WhiskyCmd) and a Finder thumbnail extension (WhiskyThumbnail).
- The main architectural boundary is between the UI/app layer in Whisky/ and the domain/runtime layer in WhiskyKit/.
2. Primary runtime responsibility
- The app is a Wine wrapper for macOS: it creates and manages “bottles,” configures them, installs a bundled Wine runtime, and launches Windows programs and games inside those bottles.
- Almost all non-UI logic lives in WhiskyKit, which is reused by the app UI, CLI, and tests.
3. UI layer
- Whisky/Views/ is a large SwiftUI surface split by workflow: setup, bottles, programs, game database, diagnostics, audio, troubleshooting, settings, menus, and common components.
- Whisky/Views/WhiskyApp.swift and AppDelegate.swift are the app entry points; view models such as BottleVM and ProcessesViewModel bridge the UI to the core model/state.
4. Core domain model
- WhiskyKit/Sources/WhiskyKit/Whisky/ contains the central models: Bottle, Program, RunLog, bottle settings/config structs, shortcut creation, legacy import, and launch result types.
- This layer represents the persisted user state and bottle-specific configuration, and it is the main source of truth for the app.
5. Wine execution and environment setup
- WhiskyKit/Sources/WhiskyKit/Wine/ builds the execution environment for Wine, detects GPU/backend capabilities, resolves graphics backend choices, manages Wine processes, and handles registry/environment interactions.
- EnvironmentBuilder, WineEnvironment, WineRegistry, and related types form the launch pipeline from bottle settings to a runnable Windows process.
6. Runtime installation and dependency management
- WhiskyKit/Sources/WhiskyKit/WhiskyWine/ handles downloading, validating, and installing the bundled Whisky Wine runtime.
- Whisky/Utils/DependencyManager.swift, Winetricks.swift, and related setup views coordinate additional dependencies and first-run setup, making the runtime-install path a distinct startup flow.
7. Bottle configuration and per-app overrides
- Bottle configuration is decomposed into separate concerns: graphics, audio, input, launcher, performance, Metal/DXVK/DXMT, cleanup, and Wine-specific settings.
- Program and ProgramOverrides provide per-application overrides so different Windows executables can have different launch behavior inside the same bottle.
8. Game compatibility subsystem
- WhiskyKit/Sources/WhiskyKit/GameDatabase/ loads a curated JSON database of game-specific configurations, matches installed apps to entries, and applies configuration snapshots.
- The UI surfaces this through the GameDB views, letting users preview and apply recommended settings rather than manually tuning bottles.
9. Diagnostics and troubleshooting pipeline
- The diagnostics subsystem classifies crashes and produces redacted exportable reports from logs and prefix state.
- A separate troubleshooting engine in WhiskyKit/Sources/WhiskyKit/Troubleshooting/ drives scripted flows made of checks, preflight collection, and fix applicators; the SwiftUI wizard is just the presentation layer over that engine.
10. Audio and controller support
- Audio has its own subsystem for probing devices, tracking changes, testing output, and diagnosing Wine audio issues.
- Controller support is handled through bottle configuration and diagnostics around input/device setup, reflecting that gamepad/input problems are a first-class concern.
11. Binary/file-format tooling
- WhiskyKit includes PE parsing, icon/resource extraction, ShellLink handling, tar handling, temporary file tracking, and clipboard/process utilities.
- These support file discovery, shortcut creation, icon rendering, and binary inspection rather than being core business logic.
12. Persistence and local data boundaries
- User data is stored locally in macOS container/support locations: bottles, cached runtime files, logs, preferences, and diagnostic history live under the app’s container/support directories.
- Migration support exists for importing bottles from the archived original Whisky bundle identifier, but bottles remain file-system-backed and are not centralized in a server.
13. External services and distribution
- Updates are delivered via Sparkle using a hosted appcast; runtime artifacts and releases are distributed through GitHub-hosted release infrastructure and Homebrew casks/taps.
- Optional telemetry is sent to a third-party analytics service only when enabled, and is limited to a small set of first-run funnel events.
14. Build, test, and packaging structure
- WhiskyKit is a standalone Swift package with extensive unit tests; the app target and extension targets consume it as the shared core.
- CI, release, and packaging scripts assemble the macOS app, runtime assets, docs, and distribution artifacts, while UI tests cover the SwiftUI surface separately from the package tests.
Main entry points: Whisky Domain Model · Wine Wine Runtime · Troubleshooting Troubleshooting · WhiskyApp.swift Whisky
Components 19
App & UI
macOS app, SwiftUI surface, and auxiliary targets.
- Whisky · Main SwiftUI application target and user-facing shell.
Whisky/Views/WhiskyApp.swift - App Delegate · Lifecycle, setup, and app integration glue.
Whisky/AppDelegate.swift - Views · Primary UI workflows for bottles, setup, diagnostics, games, settings, and troubleshooting.
Whisky/Views - View Models · State adapters between SwiftUI and shared core models.
Whisky/View Models - App Utils · UI-adjacent helpers for updates, telemetry, dependency install, launcher detection, and command launching.
Whisky/Utils - WhiskyCmd · Command-line entry point for scripting and automation.
WhiskyCmd/Main.swift - Thumbnail · Finder thumbnail provider for Whisky-related file previews.
WhiskyThumbnail/ThumbnailProvider.swift
WhiskyKit
Shared domain, runtime, and tooling library.
- Domain Model · Bottles, programs, settings, run logs, shortcuts, imports, and launch results.
WhiskyKit/Sources/WhiskyKit/Whisky - Wine Runtime · Builds Wine execution environment, backend selection, registry access, and process management.
WhiskyKit/Sources/WhiskyKit/Wine - WhiskyWine · Downloads, validates, and installs the bundled Whisky Wine runtime.
WhiskyKit/Sources/WhiskyKit/WhiskyWine - Game DB · Loads game-specific configs, matches installed apps, and applies recommended settings.
WhiskyKit/Sources/WhiskyKit/GameDatabase - Troubleshooting · Checks, preflight collection, flow execution, fix application, and history storage.
WhiskyKit/Sources/WhiskyKit/Troubleshooting - Diagnostics · Crash classification, redaction, export, and remediation mapping.
WhiskyKit/Sources/WhiskyKit/Diagnostics - Audio · Audio device monitoring, probing, status tracking, and Wine audio troubleshooting.
WhiskyKit/Sources/WhiskyKit/Audio - Binary Tools · PE parsing, icon/resource extraction, ShellLink handling, tar, temp files, and process/clipboard helpers.
WhiskyKit/Sources/WhiskyKit/PE - Core Utils · Host architecture, Rosetta, terminal integration, and stability diagnostics helpers.
WhiskyKit/Sources/WhiskyKit/Utils - Tests · Shared unit tests for the WhiskyKit package and its subsystems.
WhiskyKit/Tests/WhiskyKitTests
Build & Distribution
CI, packaging, releases, and hosted artifacts.
- CI & Release · Workflows and scripts for build, release, update feeds, scanning, and packaging.
.github/workflows/CI.yml - Dist Pages · Hosted appcast and distribution pages for updates and release metadata.
dist/pages/appcast.xml
Connections 23
- Whisky → App Delegate: boots · App entry initializes lifecycle and services.
- Whisky → Views: hosts · Main window and workflow navigation are built from SwiftUI views.
- Whisky → View Models: binds · View models mediate state between UI and core models.
- Views → View Models: uses · Screens consume shared observable state and actions.
- View Models → Domain Model: reads/writes · UI state is backed by bottles, programs, and settings.
- App Utils → Domain Model: orchestrates · Setup, shortcuts, telemetry, and launch helpers act on core state.
- WhiskyCmd → Domain Model: calls · CLI uses the shared domain and runtime APIs.
- Thumbnail → Binary Tools: renders · Thumbnail generation relies on binary/icon extraction helpers.
- Domain Model → Wine Runtime: launches via · Bottle and program state drive Wine environment setup and execution.
- Domain Model → WhiskyWine: installs · Shared model includes bundled runtime install and version state.
- Domain Model → Game DB: applies · Game configurations can be matched and applied to bottles.
- Domain Model → Troubleshooting: diagnoses · Troubleshooting flows operate on bottle and prefix state.
- Domain Model → Diagnostics: exports · Run logs and crash data feed diagnostic classification and export.
- Domain Model → Audio: configures · Audio settings and device state are part of bottle configuration.
- Wine Runtime → Audio: probes · Wine audio helpers interact with device probing and tests.
- Wine Runtime → Binary Tools: uses · Execution helpers depend on process, file, and binary utilities.
- Troubleshooting → Diagnostics: consumes · Troubleshooting flows use diagnostics and preflight evidence.
- Troubleshooting → Game DB: checks · Some flows validate whether a compatible game configuration exists.
- WhiskyWine → CI & Release: packs · Release automation assembles runtime artifacts and app bundles.
- CI & Release → Dist Pages: publishes · Release workflows generate appcast and hosted distribution pages.
- Tests → Domain Model: covers · Package tests exercise the core domain model and launch behavior.
- Tests → Wine Runtime: covers · Tests validate environment building, GPU detection, and prefix behavior.
- Tests → Troubleshooting: covers · Troubleshooting flows and checks are verified by unit tests.