“Good documentation not only explains how code works, but also clearly details why it was designed that way.”
— Technical Writing Standards
INTRODUCTION

Introduction to WinNest

When installing Windows software on Linux using Wine, users commonly experience "Registry cluttering" or overlapping DLL overrides within a single default prefix (`~/.wine`). This directly leads to compatibility failures between different applications.

WinNest was created to package each Windows program inside a fully independent data directory, automate configuration, and provide native desktop integration into Linux systems.

Core Design Features:

  • Absolute Isolation: Each software runs in a separate prefix sandbox with its own virtual Registry database.
  • Safe Spawning: Avoids raw shell command concatenation, removing command injection attack vectors.
  • Automated Desktop Integration: Generates launch shortcut (`.desktop`) files and registers MIME types for double-click operation.
INSTALLATION GUIDE

Setup & System Installation

The recommended user installation path is the official WinNest APT repository. This lets the package manager install Wine, wine32, winbind, cabextract, and desktop integration tools instead of asking users to guess system packages manually.

  • Operating system: Debian, Ubuntu, nonlaOS, or a Debian-like distribution.
  • Architecture: amd64 with i386 enabled so APT can install wine32:i386.
  • Wine: declared as a WinNest package dependency when using the official repository.

Recommended APT repository install:

Run these commands once to add the repository and install WinNest:

bash --install
# 1. Enable i386 so APT can install wine32 sudo dpkg --add-architecture i386 sudo apt update # 2. Add the WinNest signing key sudo install -d -m 0755 /etc/apt/keyrings curl -fsSL https://winnest.dismon.me/winnest.gpg \ | sudo gpg --dearmor -o /etc/apt/keyrings/winnest.gpg # 3. Add the WinNest repository echo "deb [arch=amd64 signed-by=/etc/apt/keyrings/winnest.gpg] https://winnest.dismon.me/debian stable main" \ | sudo tee /etc/apt/sources.list.d/winnest.list >/dev/null # 4. Install WinNest and required dependencies sudo apt update sudo apt install winnest
Why i386 matters

Many Windows installers still need 32-bit Wine support even when the installer is x64. Without wine32:i386, installs may fail with syswow64\\ntdll.dll errors or exit unexpectedly.

Maintainer release build:

These commands are for release maintainers, not the main end-user install flow:

bash --release
# Build a local .deb package npm run build:deb -- --build # Generate APT repository metadata under release/apt/ npm run build:apt-repo # Stage the repository into pages/debian/ for GitHub Pages npm run publish:apt-pages # Install the standalone .deb locally when testing sudo dpkg --add-architecture i386 sudo apt update sudo apt install ./release/winnest_0.1.0_amd64.deb

Local development process:

Enter the following commands inside the WinNest project root folder:

bash --development
# 1. Install Node.js development dependencies npm install # 2. Run TypeScript static typechecking npm run check # 3. Compile TypeScript to JavaScript (outputs under dist/) npm run build # 4. Test safe spawning and logs against unicode/space paths npm run test:path-torture
Note on Development Execution

After building, you can invoke the CLI wrapper directly during development using:
npm run dev:cli -- doctor (Replace `doctor` with the CLI command you wish to test).