From 60b88eb33a27e5fb33d665a6dab3587c08d9dada Mon Sep 17 00:00:00 2001 From: nzbr Date: Fri, 6 Dec 2024 22:51:03 +0100 Subject: [PATCH] update docs --- README.md | 20 +++++--------------- docs/src/building.md | 2 +- docs/src/install.md | 29 ++++++++++++++++++++++++----- tests/README.md | 4 ++-- 4 files changed, 32 insertions(+), 23 deletions(-) diff --git a/README.md b/README.md index 80bc14c8..9f05174a 100644 --- a/README.md +++ b/README.md @@ -13,23 +13,13 @@ Modules for running NixOS on the Windows Subsystem for Linux 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 - ``` - -4. You can now run NixOS: - -- ```powershell - wsl -d NixOS - ``` +3. Double-click the file you just downloaded (requires WSL >= 2.4.4) For more detailed instructions, [refer to the documentation](https://nix-community.github.io/NixOS-WSL/install.html). diff --git a/docs/src/building.md b/docs/src/building.md index f9153874..603c130e 100644 --- a/docs/src/building.md +++ b/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`. diff --git a/docs/src/install.md b/docs/src/install.md index 017db1a5..b2af5237 100644 --- a/docs/src/install.md +++ b/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.* diff --git a/tests/README.md b/tests/README.md index c91822ca..8693e163 100644 --- a/tests/README.md +++ b/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: