Marek Novák
63 lines
3.2 KiB
Markdown
63 lines
3.2 KiB
Markdown
# Nix WSL Wrapper (nix.exe)
|
|
|
|
A robust, transparent Windows executable wrapper designed to intercept native Windows commands and execute them seamlessly inside Nix Subsystem for Linux (WSL). This wrapper is particularly useful for allowing Windows-based MCP servers (like `utensils/mcp-nixos`), IDE integrations, and build tools to run `nix` commands natively on a Windows host without requiring full native Nix compile chains.
|
|
|
|
## Key Features
|
|
* **Clean Architecture & SOLID**: Built in C# using Domain-Driven Design (DDD) to encapsulate domain validation (e.g. `WslTarget`, `NixArguments`).
|
|
* **Deadlock-Free I/O Streaming**: Spawns background threads to redirect standard input, standard output, and standard error without blocking host tools.
|
|
* **Premium CLI UI & Diagnostics**: Integrates `Spectre.Console` to render beautiful diagnostic dashboards, system statuses, and automated validation tests.
|
|
* **Highly Configuration-driven**: Environment variables allow configuring the WSL distribution name, username, and path to the Nix profile.
|
|
|
|
---
|
|
|
|
## Architectural Layout
|
|
* **NixWslWrapper.Core**: The domain layer defining value objects (`WslTarget`, `NixArguments`, `ExecutionResult`) and interfaces (`ICommandExecutor`, `IStreamCopier`).
|
|
* **NixWslWrapper.Infrastructure**: Contains execution strategies (`WslCommandExecutor`), builder patterns (`ProcessBuilder`), and threaded stream piping (`ThreadedStreamCopier`).
|
|
* **NixWslWrapper.Cli**: Presentation layer resolving services via Dependency Injection (`Microsoft.Extensions.DependencyInjection`), handling command forwarding, and presenting styled dashboard visuals with `Spectre.Console`.
|
|
* **NixWslWrapper.Tests**: The testing suite compiling xUnit tests and mock assertions.
|
|
|
|
---
|
|
|
|
## Getting Started
|
|
|
|
### Prerequisites
|
|
1. **WSL2** must be active.
|
|
2. A Linux distribution installed in WSL (e.g. `Debian` or `Ubuntu`).
|
|
3. **Nix Package Manager** installed inside the WSL distribution.
|
|
|
|
### Build and Publish
|
|
Compile the project to a single self-contained executable for Windows:
|
|
```powershell
|
|
dotnet publish src/NixWslWrapper.Cli/NixWslWrapper.Cli.csproj -c Release -r win-x64 --self-contained -p:PublishSingleFile=true -o ./dist
|
|
```
|
|
This will generate `nix.exe` inside the `./dist` folder. Place this executable in your Windows `%PATH%` (e.g., in a WinGet Links directory or your IDE binary directory).
|
|
|
|
---
|
|
|
|
## Configuration
|
|
|
|
Configure the wrapper using the following Windows environment variables:
|
|
|
|
| Environment Variable | Description | Default Value |
|
|
| :--- | :--- | :--- |
|
|
| `NIX_WSL_DISTRO` | Target WSL Linux distribution name. | `Debian` |
|
|
| `NIX_WSL_USER` | The user to execute WSL commands under. | `root` |
|
|
| `NIX_WSL_PROFILE` | Path to the nix-daemon profile script inside WSL. | `/nix/var/nix/profiles/default/etc/profile.d/nix-daemon.sh` |
|
|
|
|
---
|
|
|
|
## Command Flags
|
|
|
|
When running the wrapper, standard arguments are forwarded directly to WSL. Two special flags are intercepted by the wrapper for system administration:
|
|
|
|
* `--wsl-status`: Renders a premium diagnostic panel checking your WSL execution and verifying the Nix version inside your distro.
|
|
* `--wsl-help`: Displays wrapper-specific configuration details.
|
|
|
|
---
|
|
|
|
## Running Tests
|
|
Run the xUnit test suite from the root of the project:
|
|
```powershell
|
|
dotnet test
|
|
```
|