“Tài liệu tốt không chỉ giải thích cách hoạt động của mã nguồn, mà còn trình bày rõ ràng lý do tại sao nó được thiết kế như vậy.”
— Technical Writing Standards
INTRODUCTION

Giới thiệu về WinNest

Khi cài đặt phần mềm Windows trên Linux thông qua Wine, người dùng thường gặp phải hiện tượng "xáo trộn Registry" hoặc các thư viện DLL bị đè lên nhau trong một prefix mặc định duy nhất (`~/.wine`). Điều này trực tiếp gây ra lỗi không tương thích giữa các ứng dụng khác nhau.

WinNest ra đời nhằm đóng gói mỗi phần mềm Windows vào một thư mục dữ liệu độc lập hoàn toàn, tự động hóa cấu hình và cung cấp khả năng tích hợp nguyên bản vào môi trường Desktop của Linux.

Đặc trưng thiết kế:

  • Cô lập tuyệt đối: Mỗi phần mềm là một sandbox prefix tách biệt, có cấu hình Registry ảo độc lập.
  • An toàn tiến trình: Nói không với việc ghép chuỗi câu lệnh Shell thô, loại trừ nguy cơ tấn công Injection.
  • Tích hợp Desktop tự động: Tự sinh file phím tắt khởi chạy `.desktop` và đăng ký MIME types để nhấp đúp chạy ứng dụng.
INSTALLATION GUIDE

Thiết lập & Cài đặt hệ thống

Cách cài chính thức cho người dùng cuối là thêm APT repository của WinNest rồi cài bằng trình quản lý gói. Cách này giúp hệ thống tự kéo đúng Wine, wine32, winbind, cabextract và các công cụ desktop cần thiết thay vì để người dùng tự đoán từng gói.

  • Hệ điều hành: Debian, Ubuntu, nonlaOS hoặc distro Debian-like.
  • Kiến trúc: amd64, bật thêm i386 để APT cài được gói wine32:i386.
  • Wine: được khai báo là dependency của gói WinNest, không cần cài thủ công trước nếu dùng repo chính thức.

Cài đặt khuyến nghị bằng APT repository:

Chạy các lệnh sau một lần để thêm repository và cài WinNest:

bash --install
# 1. Bật kiến trúc i386 để APT kéo được wine32 sudo dpkg --add-architecture i386 sudo apt update # 2. Thêm khóa ký gói của WinNest 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. Thêm repository WinNest 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. Cài WinNest và các dependency bắt buộc sudo apt update sudo apt install winnest
Vì sao cần i386?

Nhiều installer Windows vẫn cần lớp Wine 32-bit dù file cài đặt là x64. Nếu thiếu wine32:i386, WinNest có thể báo lỗi dạng syswow64\\ntdll.dll hoặc installer tự thoát.

Build cho maintainer:

Các lệnh này dành cho người đóng gói release, không phải flow chính cho người dùng cuối:

bash --release
# Tạo gói .deb local npm run build:deb -- --build # Tạo metadata repository APT dưới release/apt/ npm run build:apt-repo # Stage repository vào pages/debian/ cho GitHub Pages npm run publish:apt-pages # Cài gói .deb rời để test cục bộ nếu cần sudo dpkg --add-architecture i386 sudo apt update sudo apt install ./release/winnest_0.1.0_amd64.deb

Quy trình phát triển cục bộ:

Nhập các lệnh sau trong thư mục gốc của WinNest:

bash --development
# 1. Cài dependency Node.js cho dev npm install # 2. Kiểm tra kiểu tĩnh TypeScript npm run check # 3. Biên dịch TypeScript sang JavaScript (Thư mục dist/) npm run build # 4. Kiểm tra lỗi Spawning và log với đường dẫn đặc biệt npm run test:path-torture
Lưu ý về Lệnh chạy thử nghiệm

Sau khi chạy biên dịch, bạn có thể gọi trực tiếp file CLI trong quá trình phát triển bằng lệnh:
npm run dev:cli -- doctor (Thay thế `doctor` bằng lệnh bạn muốn test).