Building Cross Platform

This page focuses on how to run and test the same Aparoksha app across Windows, macOS, and Linux.

Default backend behavior

In normal use, Aparoksha selects the platform backend automatically.

Typical mapping:

• Windows → WINUI
• macOS → APPKIT
• Linux and other non-macOS Unix-like platforms → ADWAITA

That means the simplest command is usually enough:

swift run

Force a backend manually

When testing, debugging, or reproducing bugs, you can force a backend through the APAROKSHA_FRAMEWORK environment variable.

macOS / Linux

APAROKSHA_FRAMEWORK=APPKIT swift run
APAROKSHA_FRAMEWORK=ADWAITA swift run
APAROKSHA_FRAMEWORK=WINUI swift run

Windows PowerShell

$env:APAROKSHA_FRAMEWORK = "WINUI"
swift run

Accepted values

• WINUI
• APPKIT
• ADWAITA

Why manual backend selection matters

This is useful when you want to:

• compare behavior between backends
• isolate a rendering issue
• confirm that platform-specific code paths behave as expected
• test your helper scripts or CI instructions

Platform notes

Linux

The Linux path is tied to libadwaita / GTK and generally expects that those development packages are installed.

You can usually run the Linux backend with:

APAROKSHA_FRAMEWORK=ADWAITA swift run

macOS

On macOS, the most natural starting point is the native macOS backend:

APAROKSHA_FRAMEWORK=APPKIT swift run

If you want to experiment with Adwaita on macOS, install libadwaita through Homebrew first.

Windows

On Windows, use PowerShell and the WinUI backend:

$env:APAROKSHA_FRAMEWORK = "WINUI"
swift run

Suggested testing workflow

If your goal is a real cross-platform app, use this order:

1. make the app work on your primary native platform first
2. keep the shared structure simple
3. test backend-specific behavior one platform at a time
4. avoid assuming visual parity between platforms
5. verify dialogs, navigation, menus, and window sizing separately on each OS

Advanced package strategy

It is possible to control backend packages more directly by reproducing the framework selection logic in your own Package.swift, but this is usually not the best first step.

The umbrella package is easier to maintain while the ecosystem is still moving.

If you need direct backend control anyway, use it only when:

• you need tighter dependency control
• you want to understand the framework internals
• you are contributing to the ecosystem itself