Distribute as .wsl file instead of .tar.gz (#600)

* wsl-package: create renamed tarball, include manifest

* update all code occurences of nixos-wsl.tar.gz

* update docs

.github/workflows/on_release.yml

@@ -42,7 +42,7 @@ jobs:
 
       - name: Generate Checksums 🔑
         run: |
-          for x in *.{tar.gz,zip}; do
+          for x in *.{wsl,zip}; do
             sha256sum $x > ${x}.sha256
           done
 
@@ -50,8 +50,8 @@ jobs:
         uses: softprops/action-gh-release@v2
         with:
           files: |
-            nixos-wsl.tar.gz
-            nixos-wsl.tar.gz.sha256
+            nixos.wsl
+            nixos.wsl.sha256
             NixOS-WSL-Launcher.zip
             NixOS-WSL-Launcher.zip.sha256
         env:

.github/workflows/run_build.yml

@@ -27,13 +27,13 @@ jobs:
         uses: ./.github/actions/build-wsl-tarball
         with:
           config: default
-          filename: nixos-wsl.tar.gz
+          filename: nixos.wsl
 
       - name: Upload Tarball 📤
         uses: actions/upload-artifact@v4
         with:
           name: tarball
-          path: nixos-wsl.tar.gz
+          path: nixos.wsl
 
   launcher:
     name: Launcher 🛠️

.github/workflows/run_checks.yml

@@ -64,7 +64,7 @@ jobs:
 
       - name: Create dummy tarball
         shell: pwsh
-        run: echo $null >> Launcher\Launcher-Appx\nixos-wsl.tar.gz
+        run: echo $null >> Launcher\Launcher-Appx\nixos.wsl
 
       - name: Run InspectCode 🔍
         shell: pwsh

.github/workflows/run_package.yml

@@ -26,7 +26,7 @@ jobs:
 
       - name: Bundle tarball with launcher 📦
         run: |
-          Copy-Item nixos-wsl.tar.gz Launcher\Launcher\pkg\
+          Copy-Item nixos.wsl Launcher\Launcher\pkg\
 
       - name: Upload Launcher 📤
         uses: actions/upload-artifact@v4

.gitignore

@@ -1,3 +1,4 @@
 result
 result-*
 nixos-wsl*.tar.gz
+nixos.wsl

Launcher/Launcher-Appx/Launcher-Appx.wapproj

@@ -1,5 +1,6 @@
 <?xml version="1.0" encoding="utf-8"?>
-<Project ToolsVersion="15.0" DefaultTargets="Build" xmlns="http://schemas.microsoft.com/developer/msbuild/2003">
+<Project ToolsVersion="15.0" DefaultTargets="Build"
+  xmlns="http://schemas.microsoft.com/developer/msbuild/2003">
   <PropertyGroup Condition="'$(VisualStudioVersion)' == '' or '$(VisualStudioVersion)' &lt; '15.0'">
     <VisualStudioVersion>15.0</VisualStudioVersion>
   </PropertyGroup>
@@ -54,11 +55,12 @@
     <Content Include="Images\Square44x44Logo.targetsize-24_altform-unplated.png" />
     <Content Include="Images\StoreLogo.png" />
     <Content Include="Images\Wide310x150Logo.scale-200.png" />
-    <Content Include="nixos-wsl.tar.gz" />
+    <Content Include="nixos.wsl" />
   </ItemGroup>
   <Import Project="$(WapProjPath)\Microsoft.DesktopBridge.targets" />
   <ItemGroup>
-    <PackageReference Include="Microsoft.Windows.SDK.BuildTools" Version="10.0.22000.197" PrivateAssets="all" />
+    <PackageReference Include="Microsoft.Windows.SDK.BuildTools" Version="10.0.22000.197"
+      PrivateAssets="all" />
   </ItemGroup>
   <ItemGroup>
     <ProjectReference Include="..\Launcher\Launcher.csproj" />

Launcher/Launcher/src/Helpers/InstallationHelper.cs

@@ -62,7 +62,7 @@ public static class InstallationHelper {
     /// </summary>
     /// <returns>the full path to the tarball or null</returns>
     private static string? FindTarball() {
-        const string tarFileName = "nixos-wsl.tar.gz";
+        const string tarFileName = "nixos.wsl";
 
         // Accept a tarball in the current directory when running a debug build
 #if (DEBUG)

README.md

@@ -15,17 +15,13 @@ Run the following from powershell:
 
 1. Enable WSL if you haven't done already:
 
-- ```powershell
-  wsl --install --no-distribution
-  ```
+  - ```powershell
+    wsl --install --no-distribution
+    ```
 
-2. Download `nixos-wsl.tar.gz` from [the latest release](https://github.com/nix-community/NixOS-WSL/releases/latest).
+2. Download `nixos.wsl` from [the latest release](https://github.com/nix-community/NixOS-WSL/releases/latest).
 
-3. Import the tarball into WSL:
-
-- ```powershell
-  wsl --import NixOS $env:USERPROFILE\NixOS nixos-wsl.tar.gz --version 2
-  ```
+3. Double-click the file you just downloaded (requires WSL >= 2.4.4)
 
 4. You can now run NixOS:
 

docs/src/building.md

@@ -22,4 +22,4 @@ nix-build -A nixosConfigurations.default.config.system.build.tarballBuilder && s
 
 ```
 
-The resulting tarball can then be found under `nixos-wsl.tar.gz`.
+The resulting tarball can then be found under `nixos.wsl`.

docs/src/install.md

@@ -7,22 +7,39 @@ Support for older "inbox" versions is best-effort.
 
 ## Install NixOS-WSL
 
-First, [download the latest release](https://github.com/nix-community/NixOS-WSL/releases/latest).
+First, download `nixos.wsl` from [the latest release](https://github.com/nix-community/NixOS-WSL/releases/latest).[^wsl-file]
 
-Then open up a PowerShell and run:
+If you have WSL version 2.4.4 or later installed, you can open (double-click) the .wsl file to install it.
+It is also possible to perform the installation from a PowerShell:
 
 ```powershell
-wsl --import NixOS $env:USERPROFILE\NixOS nixos-wsl.tar.gz --version 2
+wsl --install --from-file nixos.wsl
+```
+
+`nixos.wsl` must be the path to the file you just downloaded if you're running the command in another directory.
+
+You can use the `--name` and `--location` flags to change the name the distro is registered under (default: `NixOS`) and the location of the disk image (default: `%localappdata%\wsl\{some random GUID}`). For a full list of options, refer to `wsl --help`
+
+To open a shell in your NixOS environment, run `wsl -d NixOS`, select NixOS from the profile dropdown in Windows Terminal or run it from your Start Menu. (Adjust the name accordingly if you changed it)
+
+### Older WSL versions
+
+If you have a WSL version older than 2.4.4, you can install NixOS-WSL like this:
+
+Open up a PowerShell and run:
+
+```powershell
+wsl --import NixOS $env:USERPROFILE\NixOS nixos.wsl --version 2
 ```
 
 Or for Command Prompt:
 
 ```cmd
-wsl --import NixOS %USERPROFILE%\NixOS nixos-wsl.tar.gz --version 2
+wsl --import NixOS %USERPROFILE%\NixOS nixos.wsl --version 2
 ```
 
 This sets up a new WSL distribution `NixOS` that is installed in a directory called `NixOS` inside your user directory.
-`nixos-wsl.tar.gz` is the path to the file you downloaded earlier.
+`nixos.wsl` is the path to the file you downloaded earlier.
 You can adjust the installation path and distribution name to your liking.
 
 To get a shell in your NixOS environment, use:
@@ -46,3 +63,5 @@ If you want to make NixOS your default distribution, you can do so with
 ```powershell
 wsl -s NixOS
 ```
+
+[^wsl-file]: That file is called `nixos-wsl.tar.gz` in releases prior to 2411.*

modules/build-tarball.nix

@@ -3,6 +3,16 @@ with builtins; with lib;
 let
   cfg = config.wsl.tarball;
 
+  icon = ../Launcher/Launcher/nixos.ico;
+  iconPath = "/etc/nixos.ico";
+
+  wsl-distribution-conf = pkgs.writeText "wsl-distribution.conf" (
+    generators.toINI { } {
+      oobe.defaultName = "NixOS";
+      shortcut.icon = iconPath;
+    }
+  );
+
   defaultConfig = pkgs.writeText "default-configuration.nix" ''
     # Edit this configuration file to define what should be installed on
     # your system. Help is available in the configuration.nix(5) man page, on
@@ -62,7 +72,8 @@ in
           exit 1
         fi
 
-        out=''${1:-nixos-wsl.tar.gz}
+        # Use .wsl extension to support double-click installs on recent versions of Windows
+        out=''${1:-nixos.wsl}
 
         root=$(mktemp -p "''${TMPDIR:-/tmp}" -d nixos-wsl-tarball.XXXXXXXXXX)
         # FIXME: fails in CI for some reason, but we don't really care because it's CI
@@ -80,6 +91,10 @@ in
         echo "[NixOS-WSL] Adding channel..."
         nixos-enter --root "$root" --command 'HOME=/root nix-channel --add https://github.com/nix-community/NixOS-WSL/archive/refs/heads/main.tar.gz nixos-wsl'
 
+        echo "[NixOS-WSL] Adding wsl-distribution.conf"
+        install -Dm644 ${wsl-distribution-conf} "$root/etc/wsl-distribution.conf"
+        install -Dm644 ${icon} "$root${iconPath}"
+
         echo "[NixOS-WSL] Adding default config..."
         ${if cfg.configPath == null then ''
           install -Dm644 ${defaultConfig} "$root/etc/nixos/configuration.nix"

tests/README.md

@@ -13,8 +13,8 @@ Please note that the tests are not compatible with Windows PowerShell, but requi
 ### Running the Tests
 
 If you haven't already, [install Pester](https://pester.dev/docs/introduction/installation/).  
-The tests require a "default" (formerly "modern") `nixos-wsl.tar.gz` to be present in the current working directory, which can be built with
-`sudo nix run .#nixosConfigurations.default.config.system.build.tarballBuilder -- nixos-wsl.tar.gz`.
+The tests require a "default" `nixos.wsl` to be present in the current working directory, which can be built with
+`sudo nix run .#nixosConfigurations.default.config.system.build.tarballBuilder -- nixos.wsl`.
 
 Once everything is in place, run the test by running the following in PowerShell at the root of this repo:
 

tests/lib/lib.ps1

@@ -47,7 +47,7 @@ class Distro {
 
   [string]FindTarball() {
     # Check if a fresh tarball exists in result, otherwise try one in the current directory
-    $tarball = "./nixos-wsl.tar.gz"
+    $tarball = "./nixos.wsl"
     if (!(Test-Path $tarball)) {
       throw "Could not find the tarball! Run nix build first, or place one in the current directory."
     }