How winapps-org/winapps works
Project Type and Purpose
• WinApps is an open-source integration tool that lets users run Windows applications on a GNU/Linux host by provisioning a Windows VM/container (via Docker, Podman or libvirt) and using FreeRDP to render individual Windows apps seamlessly alongside native Linux applications.
File Structure Analysis
• Top-level:
• README.md, LICENSE.md, CONTRIBUTING.md, docs/ — project documentation.
• bin/winapps — the main CLI entry point.
• setup.sh and install/ — installer scripts for bootstrapping the environment.
• docs/docker.md, docs/libvirt.md — guides for configuring Docker/Podman and libvirt backends.
• compose.yaml — Docker Compose definition for spinning up the VM container.
• default.nix, flake.nix, flake.lock, packages/ — Nix integration and packaging metadata.
• oem/ — optional OEM scripts and registry tweaks (e.g., RDPApps.reg).
Key README Insights
• Underlying mechanism:
1. Provision Windows VM/container with KVM hypervisor.
2. Query installed Windows apps via a scanning script.
3. Generate Linux-side shortcuts (.desktop files) and MIME associations.
4. Launch selected Windows apps over RDP using FreeRDP.
• Supports backends: Docker, Podman, libvirt, manual.
• Configuration: ~/.config/winapps/winapps.conf.
Main Components
a. Host Linux Environment
• Configuration store (~/.config/winapps/).
• CLI tools: bin/winapps, install/, setup.sh.
• Desktop integration: .desktop files, MIME database, Nautilus extension.
• Optional tray UI: WinApps-Launcher (separate package under packages/winapps-launcher).
b. Virtualization Backend Abstraction
• Docker/Podman (compose.yaml, Dockerfiles).
• libvirt (docs/libvirt.md, oem/ scripts).
• Manual mode fallback.
c. Windows VM/Container
• Windows guest OS running RDP server.
• Shared mount of host home (\\tsclient\home).
d. FreeRDP Client
• Invoked by WinApps CLI (xfreerdp or specified FREERDP_COMMAND).
• Streams individual application windows back to the host X11/Wayland session.
e. Application Definition Modules (apps/…)
• Template variables for .desktop generation.
f. External Services & Utilities
• Docker/Podman engine or libvirt/QEMU/KVM.
• Host package dependencies (curl, dialog, freerdp3-x11, iproute2, libnotify-bin, netcat).
Relationships and Data Flows
• The CLI (bin/winapps) reads the user’s config, selects the backend, ensures the Windows VM is running.
• The backend layer (Docker/Podman/libvirt) launches or resumes the Windows VM.
• A scanning script inside the Windows VM collects installed .exe data and returns it to the host.
• When the user clicks a shortcut, the CLI invokes FreeRDP with flags and the target application’s RDP “RemoteApp” UUID.
• FreeRDP establishes an RDP stream to the Windows VM, tunneling the individual app window to the host display.
• The Linux file manager extension (Nautilus integration) uses the generated MIME mappings to dispatch files to Windows apps.
• The optional WinApps Launcher UI communicates with the CLI to start/stop/pause the VM and list installed apps.
Architectural Patterns and Design Principles
• Modular plug-in structure: each application supported under apps/ acts as an independent definition module.
• Backend abstraction: uniform CLI commands regardless of Docker/Podman/libvirt choice.
• Separation of concerns:
• Installer (setup.sh, install/) vs. runtime CLI vs. user config vs. definition modules vs. optional GUI.
• Data flow: config → backend orchestration → VM state → scanning → shortcut generation → RDP launch.
• Idempotent installation: re-running the installer cleans and updates definitions.
• Declarative packaging: Nix flake files under default.nix, flake.nix, packages/ for reproducible installs.